---

name: design description: UI/UX design guidelines for interactions, animation, layout, accessibility, and visual design. Use when building UI components, designing user experiences, or implementing user-facing features.

Design System Guidelines

Follow Apple, Linear, and Vercel as design inspirations. Ask yourself "How would Apple, Linear, or Vercel design this?"

When designing React components, also use the compound-components skill to build the components.

Interactions

Keyboard

• MUST: Full keyboard support per WAI-ARIA APG
• MUST: Visible focus rings (:focus-visible; group with :focus-within)
• MUST: Manage focus (trap, move, and return) per APG patterns

Targets & Input

• MUST: Hit target >=24px (mobile >=44px). If visual <24px, expand hit area
• MUST: Mobile <input> font-size >=16px or set:

  <meta
    name="viewport"
    content="width=device-width, initial-scale=1, maximum-scale=1, viewport-fit=cover"
  />
  

• NEVER: Disable browser zoom
• MUST: touch-action: manipulation to prevent double-tap zoom; set -webkit-tap-highlight-color to match design

Inputs & Forms

• MUST: Hydration-safe inputs (no lost focus/value)
• NEVER: Block paste in <input>/<textarea>
• MUST: Loading buttons show spinner and keep original label
• MUST: Enter submits focused text input. In <textarea>, Cmd/Ctrl+Enter submits; Enter adds newline
• MUST: Keep submit enabled until request starts; then disable, show spinner, use idempotency key
• MUST: Don't block typing; accept free text and validate after
• MUST: Allow submitting incomplete forms to surface validation
• MUST: Errors inline next to fields; on submit, focus first error
• MUST: autocomplete + meaningful name; correct type and inputmode
• SHOULD: Disable spellcheck for emails/codes/usernames
• SHOULD: Placeholders end with ellipsis and show example pattern (eg, +1 (123) 456-7890, sk-012345...)
• MUST: Warn on unsaved changes before navigation
• MUST: Compatible with password managers & 2FA; allow pasting one-time codes
• MUST: Trim values to handle text expansion trailing spaces
• MUST: No dead zones on checkboxes/radios; label+control share one generous hit target

State & Navigation

• MUST: URL reflects state (deep-link filters/tabs/pagination/expanded panels). Prefer libs like nuqs
• MUST: Back/Forward restores scroll
• MUST: Links are links--use <a>/<Link> for navigation (support Cmd/Ctrl/middle-click)

Feedback

• SHOULD: Optimistic UI; reconcile on response; on failure show error and rollback or offer Undo
• MUST: Confirm destructive actions or provide Undo window
• MUST: Use polite aria-live for toasts/inline validation
• SHOULD: Ellipsis (...) for options that open follow-ups (eg, "Rename...")

Touch/Drag/Scroll

• MUST: Design forgiving interactions (generous targets, clear affordances; avoid finickiness)
• MUST: Delay first tooltip in a group; subsequent peers no delay
• MUST: Intentional overscroll-behavior: contain in modals/drawers
• MUST: During drag, disable text selection and set inert on dragged element/containers
• MUST: No "dead-looking" interactive zones--if it looks clickable, it is

Autofocus

• SHOULD: Autofocus on desktop when there's a single primary input; rarely on mobile (to avoid layout shift)

Animation

• MUST: Honor prefers-reduced-motion (provide reduced variant)
• SHOULD: Prefer CSS > Web Animations API > JS libraries
• MUST: Animate compositor-friendly props (transform, opacity); avoid layout/repaint props (top/left/width/height)
• SHOULD: Animate only to clarify cause/effect or add deliberate delight
• SHOULD: Choose easing to match the change (size/distance/trigger)
• MUST: Animations are interruptible and input-driven (avoid autoplay)
• MUST: Correct transform-origin (motion starts where it "physically" should)

Layout

• SHOULD: Optical alignment; adjust by +/-1px when perception beats geometry
• MUST: Deliberate alignment to grid/baseline/edges/optical centers--no accidental placement
• SHOULD: Balance icon/text lockups (stroke/weight/size/spacing/color)
• MUST: Verify mobile, laptop, ultra-wide (simulate ultra-wide at 50% zoom)
• MUST: Respect safe areas (use env(safe-area-inset-*))
• MUST: Avoid unwanted scrollbars; fix overflows

Content & Accessibility

• SHOULD: Inline help first; tooltips last resort
• MUST: Skeletons mirror final content to avoid layout shift
• MUST: <title> matches current context
• MUST: No dead ends; always offer next step/recovery
• MUST: Design empty/sparse/dense/error states
• SHOULD: Curly quotes (" "); avoid widows/orphans
• MUST: Tabular numbers for comparisons (font-variant-numeric: tabular-nums or a monospace font)
• MUST: Redundant status cues (not color-only); icons have text labels
• MUST: Don't ship the schema--visuals may omit labels but accessible names still exist
• MUST: Use the ellipsis character ... (not ..)
• MUST: scroll-margin-top on headings for anchored links; include a "Skip to content" link; hierarchical <h1-h6>
• MUST: Resilient to user-generated content (short/avg/very long)
• MUST: Locale-aware dates/times/numbers/currency
• MUST: Accurate names (aria-label), decorative elements aria-hidden, verify in the Accessibility Tree
• MUST: Icon-only buttons have descriptive aria-label
• MUST: Prefer native semantics (button, a, label, table) before ARIA
• SHOULD: Right-clicking the nav logo surfaces brand assets
• MUST: Use non-breaking spaces to glue terms: 10 MB, Cmd + K, Vercel SDK

Visual Design

• SHOULD: Layered shadows (ambient + direct)
• SHOULD: Crisp edges via semi-transparent borders + shadows
• SHOULD: Nested radii: child <= parent; concentric
• SHOULD: Hue consistency: tint borders/shadows/text toward bg hue
• MUST: Accessible charts (color-blind-friendly palettes)
• MUST: Meet contrast--prefer APCA over WCAG 2
• MUST: Increase contrast on :hover/:active/:focus
• SHOULD: Match browser UI to bg
• SHOULD: Avoid gradient banding (use masks when needed)

Performance (UX)

• SHOULD: Test iOS Low Power Mode and macOS Safari
• MUST: Mutations (POST/PATCH/DELETE) target <500 ms
• MUST: Preload only above-the-fold images; lazy-load the rest
• MUST: Prevent CLS from images (explicit dimensions or reserved space)