# Craft Checklist (Detailed)

Final polish sweep for pre-release sign-off. Run after the rule-based CRITICAL/HIGH passes; it carries only the built-UI details no rule file encodes. Anything already owned by a rule (`rules/interaction-*`, `forms-*`, `a11y-*`, `nav-*`, `layout-*`, `perf-*`, `rules/states-*`, `dark-i18n-*`) is not repeated here, so a craft finding never duplicates a rule finding. Visual direction, motion, SEO, and deep typography belong to sibling skills and are pointed to, not restated.

## Contents
- Legibility and typography → sibling
- Keyboard, focus, and targets
- Forms and input behaviour
- Navigation and feedback
- Resilience and layout
- Performance
- Accessibility and theming
- Motion → sibling
- Visual direction and SEO → sibling

## Legibility and typography

Surface type defects are the `type-` rules; punctuation, OpenType, pairing, brand, and display type are the `typography-audit` skill. Not duplicated here.

## Keyboard, focus, and targets
- Buttons/links need a `hover:` state; hover/active/focus more prominent than rest. Set `-webkit-tap-highlight-color` on controls.
- `scroll-margin-top` on heading anchors for in-page links.
- `autoFocus` sparingly: desktop only, single primary input.
- Decorative layers (glows, gradients) get `pointer-events: none`.
- If it looks clickable, it must be clickable; remove dead zones between items. Avoid text selection during drag (`inert` or disable selection).
- Nested menus have a forgiving pointer corridor so moving diagonally into a submenu does not close it.
- Multi-key shortcuts tolerate release-order mistakes where the app owns the chord handling; don't cancel a chord the instant the first key lifts.
- Movable controls with natural stops (carousels, sliders, drawers) snap to valid positions after release, not halfway states.

## Forms and input behaviour
- Enter submits; textarea uses Cmd/Ctrl+Enter.
- Hydration-safe (no lost focus/value after hydration).
- Disable spellcheck for emails/codes/usernames; `autocomplete="off"` on non-auth fields to avoid password-manager triggers; keep password managers and one-time codes working.
- Allow incomplete submission to surface validation; keep submit enabled until the request starts, then disable with a spinner and keep the original label.
- Checkboxes/radios: label + control share one hit target (no dead zones).
- Placeholders end with `…` and show an example pattern.
- Warn before navigation with unsaved changes (`beforeunload` or router guard).
- Input affix hit targets are `forms-input-affix-hit-target`; not duplicated here.

## Navigation and feedback
- Preserve URL state; Back/Forward restores scroll.
- Supporting chrome (sidebars, tabs, secondary bars) recedes beneath the current task; keep shared header actions in consistent slots across comparable screens; prefer compact tab groups over full-width bars at equal state.
- Confirm destructive actions or provide undo.
- Spinners/skeletons: show-delay 150-300ms, min duration 300-500ms (avoid flicker).
- Preserve user position: filters, route changes, pagination, list updates, and Back/Forward keep scroll position or restore the equivalent item in view.
- Context menus open with stable action placement relative to the cursor, and never put a destructive action under the current cursor after the menu appears.
- Tooltips delay on first hover, but neighbouring tooltips in the same group switch instantly once the first tooltip is open.

## Resilience and layout
- `overscroll-behavior: none` on `html` for app shells; `contain` in modals and drawers. Document sites keep pull-to-refresh.
- Stress test with long labels, one-word values, dense rows, empty lists, and one-item lists. The UI should not only survive the populated demo state.
- Added or removed list rows preserve subjective position: content around the changed row should not jump unless the action is explicitly a reorder or navigation.
- If the same object appears across two views, preserve object permanence through the transition when practical: keep position, thumbnail, title, or shape continuous instead of replacing it with an unrelated hard cut.

## Performance
- No layout reads in render (`getBoundingClientRect`, `offsetHeight`); batch DOM reads/writes.
- `will-change` sparingly; avoid heavy blur and excessive video autoplay.

## Accessibility and theming
- Disabled-control tooltips and interactive hover-tooltips are `a11y-disabled-control-tooltip` and `a11y-tooltip-no-interactive`; not duplicated here.
- HTML illustrations (inline SVG, CSS art) need an accessible name, same as `<img>`.
- No animation during theme switches; set `color-scheme` and `<meta name="theme-color">`. Native `<select>`: explicit `background-color` and `color` (Windows dark mode fix).
- Guard hydration for date/time; `value` inputs require `onChange`; `suppressHydrationWarning` only where needed (dates, theme).

## Motion → sibling

Timing, easing, springs, gestures, and transform/opacity-only animation belong to the `ui-animation` skill. Route motion findings there for the fix.

## Visual direction and SEO → sibling

- Visual-direction polish (matching box-shadows to references, concentric border radius, optical alignment of icons/text, image outlines on light backgrounds, the fundamentals→visual→polish quality pyramid) belongs to this skill's Direction and Build modes, not to a built-UI defect check.
- SEO metadata, canonical/OG tags, and dynamic OG images belong to the `seo` skill.