|
| 1 | +Concise rules for building accessible, fast, delightful UIs Use MUST/SHOULD/NEVER to guide decisions |
| 2 | + |
| 3 | +## Interactions |
| 4 | + |
| 5 | +- Keyboard |
| 6 | + - MUST: Full keyboard support per [WAI-ARIA APG](https://www.w3.org/WAI/ARIA/apg/patterns/) |
| 7 | + - MUST: Visible focus rings (`:focus-visible`; group with `:focus-within`) |
| 8 | + - MUST: Manage focus (trap, move, and return) per APG patterns |
| 9 | +- Targets & input |
| 10 | + - MUST: Hit target ≥24px (mobile ≥44px) If visual <24px, expand hit area |
| 11 | + - MUST: Mobile `<input>` font-size ≥16px or set: |
| 12 | + ```html |
| 13 | + <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover"> |
| 14 | + ``` |
| 15 | + - NEVER: Disable browser zoom |
| 16 | + - MUST: `touch-action: manipulation` to prevent double-tap zoom; set `-webkit-tap-highlight-color` to match design |
| 17 | +- Inputs & forms (behavior) |
| 18 | + - MUST: Hydration-safe inputs (no lost focus/value) |
| 19 | + - NEVER: Block paste in `<input>/<textarea>` |
| 20 | + - MUST: Loading buttons show spinner and keep original label |
| 21 | + - MUST: Enter submits focused text input In `<textarea>`, ⌘/Ctrl+Enter submits; Enter adds newline |
| 22 | + - MUST: Keep submit enabled until request starts; then disable, show spinner, use idempotency key |
| 23 | + - MUST: Don't block typing; accept free text and validate after |
| 24 | + - MUST: Allow submitting incomplete forms to surface validation |
| 25 | + - MUST: Errors inline next to fields; on submit, focus first error |
| 26 | + - MUST: `autocomplete` + meaningful `name`; correct `type` and `inputmode` |
| 27 | + - SHOULD: Disable spellcheck for emails/codes/usernames |
| 28 | + - SHOULD: Placeholders end with ellipsis and show example pattern (eg, `+1 (123) 456-7890`, `sk-012345…`) |
| 29 | + - MUST: Warn on unsaved changes before navigation |
| 30 | + - MUST: Compatible with password managers & 2FA; allow pasting one-time codes |
| 31 | + - MUST: Trim values to handle text expansion trailing spaces |
| 32 | + - MUST: No dead zones on checkboxes/radios; label+control share one generous hit target |
| 33 | +- State & navigation |
| 34 | + - MUST: URL reflects state (deep-link filters/tabs/pagination/expanded panels) Prefer libs like [nuqs](https://nuqs.dev) |
| 35 | + - MUST: Back/Forward restores scroll |
| 36 | + - MUST: Links are links—use `<a>/<Link>` for navigation (support Cmd/Ctrl/middle-click) |
| 37 | +- Feedback |
| 38 | + - SHOULD: Optimistic UI; reconcile on response; on failure show error and rollback or offer Undo |
| 39 | + - MUST: Confirm destructive actions or provide Undo window |
| 40 | + - MUST: Use polite `aria-live` for toasts/inline validation |
| 41 | + - SHOULD: Ellipsis (`…`) for options that open follow-ups (eg, "Rename…") and loading states (eg, "Loading…", "Saving…", "Generating…") |
| 42 | +- Touch/drag/scroll |
| 43 | + - MUST: Design forgiving interactions (generous targets, clear affordances; avoid finickiness) |
| 44 | + - MUST: Delay first tooltip in a group; subsequent peers no delay |
| 45 | + - MUST: Intentional `overscroll-behavior: contain` in modals/drawers |
| 46 | + - MUST: During drag, disable text selection and set `inert` on dragged element/containers |
| 47 | + - MUST: No "dead-looking" interactive zones—if it looks clickable, it is |
| 48 | +- Autofocus |
| 49 | + - SHOULD: Autofocus on desktop when there's a single primary input; rarely on mobile (to avoid layout shift) |
| 50 | + |
| 51 | +## Animation |
| 52 | + |
| 53 | +- MUST: Honor `prefers-reduced-motion` (provide reduced variant) |
| 54 | +- SHOULD: Prefer CSS > Web Animations API > JS libraries |
| 55 | +- MUST: Animate compositor-friendly props (`transform`, `opacity`); avoid layout/repaint props (`top/left/width/height`) |
| 56 | +- SHOULD: Animate only to clarify cause/effect or add deliberate delight |
| 57 | +- SHOULD: Choose easing to match the change (size/distance/trigger) |
| 58 | +- MUST: Animations are interruptible and input-driven (avoid autoplay) |
| 59 | +- MUST: Correct `transform-origin` (motion starts where it "physically" should) |
| 60 | + |
| 61 | +## Layout |
| 62 | + |
| 63 | +- SHOULD: Optical alignment; adjust by ±1px when perception beats geometry |
| 64 | +- MUST: Deliberate alignment to grid/baseline/edges/optical centers—no accidental placement |
| 65 | +- SHOULD: Balance icon/text lockups (stroke/weight/size/spacing/color) |
| 66 | +- MUST: Verify mobile, laptop, ultra-wide (simulate ultra-wide at 50% zoom) |
| 67 | +- MUST: Respect safe areas (use env(safe-area-inset-*)) |
| 68 | +- MUST: Avoid unwanted scrollbars; fix overflows |
| 69 | + |
| 70 | +## Content & Accessibility |
| 71 | + |
| 72 | +- SHOULD: Inline help first; tooltips last resort |
| 73 | +- MUST: Skeletons mirror final content to avoid layout shift |
| 74 | +- MUST: `<title>` matches current context |
| 75 | +- MUST: No dead ends; always offer next step/recovery |
| 76 | +- MUST: Design empty/sparse/dense/error states |
| 77 | +- SHOULD: Curly quotes (" "); avoid widows/orphans |
| 78 | +- MUST: Tabular numbers for comparisons (`font-variant-numeric: tabular-nums` or a mono like Geist Mono) |
| 79 | +- MUST: Redundant status cues (not color-only); icons have text labels |
| 80 | +- MUST: Don't ship the schema—visuals may omit labels but accessible names still exist |
| 81 | +- MUST: Use the ellipsis character `…` (not ``) |
| 82 | +- MUST: `scroll-margin-top` on headings for anchored links; include a "Skip to content" link; hierarchical `<h1–h6>` |
| 83 | +- MUST: Resilient to user-generated content (short/avg/very long) |
| 84 | +- MUST: Locale-aware dates/times/numbers/currency |
| 85 | +- MUST: Accurate names (`aria-label`), decorative elements `aria-hidden`, verify in the Accessibility Tree |
| 86 | +- MUST: Icon-only buttons have descriptive `aria-label` |
| 87 | +- MUST: Prefer native semantics (`button`, `a`, `label`, `table`) before ARIA |
| 88 | +- SHOULD: Right-clicking the nav logo surfaces brand assets |
| 89 | +- MUST: Use non-breaking spaces to glue terms: `10 MB`, `⌘ + K`, `Vercel SDK` |
| 90 | + |
| 91 | +## Performance |
| 92 | + |
| 93 | +- SHOULD: Test iOS Low Power Mode and macOS Safari |
| 94 | +- MUST: Measure reliably (disable extensions that skew runtime) |
| 95 | +- MUST: Track and minimize re-renders (React DevTools/React Scan) |
| 96 | +- MUST: Profile with CPU/network throttling |
| 97 | +- MUST: Batch layout reads/writes; avoid unnecessary reflows/repaints |
| 98 | +- MUST: Mutations (`POST/PATCH/DELETE`) target <500 ms |
| 99 | +- SHOULD: Prefer uncontrolled inputs; make controlled loops cheap (keystroke cost) |
| 100 | +- MUST: Virtualize large lists (eg, `virtua`) |
| 101 | +- MUST: Preload only above-the-fold images; lazy-load the rest |
| 102 | +- MUST: Prevent CLS from images (explicit dimensions or reserved space) |
| 103 | + |
| 104 | +## Design |
| 105 | + |
| 106 | +- SHOULD: Layered shadows (ambient + direct) |
| 107 | +- SHOULD: Crisp edges via semi-transparent borders + shadows |
| 108 | +- SHOULD: Nested radii: child ≤ parent; concentric |
| 109 | +- SHOULD: Hue consistency: tint borders/shadows/text toward bg hue |
| 110 | +- MUST: Accessible charts (color-blind-friendly palettes) |
| 111 | +- MUST: Meet contrast—prefer [APCA](https://apcacontrast.com/) over WCAG 2 |
| 112 | +- MUST: Increase contrast on `:hover/:active/:focus` |
| 113 | +- SHOULD: Match browser UI to bg |
| 114 | +- SHOULD: Avoid gradient banding (use masks when needed) |
| 115 | + |
0 commit comments