Web Interface Guidelines Checklist for LLMs & vibe coders!

Distilled from Vercel's https://github.com/vercel-labs/web-interface-guidelines

Interactions

• [ ] Keyboard works everywhere (WAI-ARIA patterns)
• [ ] Clear focus rings (:focus-visible)
• [ ] Manage focus (traps, move, return)
• [ ] Match visual & hit targets (≥24px desktop, ≥44px mobile)
• [ ] Mobile input font ≥16px
• [ ] Never disable zoom
• [ ] Hydration-safe inputs
• [ ] Never block paste
• [ ] Loading buttons show indicator + original label
• [ ] Minimum loading duration (150-300ms delay, 300-500ms min)
• [ ] URL as state (shareable, refreshable)
• [ ] Optimistic updates with rollback
• [ ] Ellipsis for further input & loading states
• [ ] Confirm destructive actions
• [ ] touch-action: manipulation on controls
• [ ] Set webkit-tap-highlight-color
• [ ] Generous hit targets, predictable interactions
• [ ] Delay first tooltip, no delay for peers
• [ ] overscroll-behavior: contain in modals/drawers
• [ ] Scroll positions persist on Back/Forward
• [ ] Autofocus single input on desktop (rarely mobile)
• [ ] No dead zones - interactive looks interactive
• [ ] Deep-link everything (filters, tabs, panels)
• [ ] Clean drag interactions (disable selection, use inert)
• [ ] Links are <a> or <Link> (not buttons/divs)
• [ ] Announce async updates (aria-live)
• [ ] Locale-aware keyboard shortcuts

Animations

• [ ] Honor prefers-reduced-motion
• [ ] Prefer CSS > Web Animations API > JS libraries
• [ ] GPU-accelerated properties (transform, opacity)
• [ ] Animate only for clarity or delight
• [ ] Easing fits the subject
• [ ] Interruptible by user input
• [ ] Input-driven, not autoplay
• [ ] Correct transform origin
• [ ] Never transition: all (explicit properties only)
• [ ] SVG transforms on <g> wrappers with transform-box: fill-box

Layout

• [ ] Optical alignment (±1px adjustments)
• [ ] Deliberate alignment (grid, baseline, edge, center)
• [ ] Balance contrast in text/icon lockups
• [ ] Test mobile, laptop, ultra-wide
• [ ] Respect safe areas (notches, insets)
• [ ] No excessive scrollbars
• [ ] Let browser size things (flex/grid over JS)

Content

• [ ] Inline help first, tooltips last
• [ ] Stable skeletons mirror final content
• [ ] Accurate <title> reflects context
• [ ] No dead ends (next step or recovery)
• [ ] Design all states (empty, sparse, dense, error)
• [ ] Curly quotes (" ")
• [ ] Avoid widows/orphans
• [ ] Tabular numbers for comparisons
• [ ] Redundant status cues (not color alone)
• [ ] Icons have text labels
• [ ] Accessible names exist even if labels hidden
• [ ] Use ellipsis character … not ...
• [ ] scroll-margin-top on headings
• [ ] Handle short, average, long content
• [ ] Locale-aware formats (dates, numbers, currency)
• [ ] Language via Accept-Language, not IP/GPS
• [ ] Accurate aria-label, aria-hidden
• [ ] Icon-only buttons have aria-label
• [ ] Semantics before ARIA (native elements first)
• [ ] Hierarchical <h1–h6> + skip link
• [ ] Brand resources from logo right-click
• [ ] Non-breaking spaces for glued terms ( , ⁠)

Forms

• [ ] Enter submits (single input or last control)
• [ ] Textarea: ⌘/⌃+Enter submits, Enter = new line
• [ ] Every control has <label> or association
• [ ] Label clicks focus control
• [ ] Submit enabled until in-flight (spinner + idempotency key)
• [ ] Don't block typing (validate, don't restrict)
• [ ] Don't pre-disable submit (surface validation)
• [ ] No dead zones on checkboxes/radios
• [ ] Errors next to fields, focus first error on submit
• [ ] Set autocomplete & meaningful name
• [ ] Disable spellcheck for emails, codes, usernames
• [ ] Correct type & inputmode
• [ ] Placeholders end with ellipsis, show example
• [ ] Warn before navigation with unsaved changes
• [ ] Password manager & 2FA compatible
• [ ] Don't trigger password managers for non-auth
• [ ] Trim trailing whitespace from input
• [ ] Set background-color & color on <select>

Performance

• [ ] Test iOS Low Power Mode & macOS Safari
• [ ] Disable extensions when profiling
• [ ] Track re-renders (React DevTools, React Scan)
• [ ] Throttle CPU/network when profiling
• [ ] Minimize layout work (batch reads/writes)
• [ ] POST/PATCH/DELETE <500ms
• [ ] Prefer uncontrolled inputs, cheap controlled loops
• [ ] Virtualize large lists
• [ ] Preload above-fold images, lazy-load rest
• [ ] Set explicit image dimensions (no CLS)
• [ ] <link rel="preconnect"> for asset/CDN domains
• [ ] Preload critical fonts
• [ ] Subset fonts (unicode-range)
• [ ] Expensive work in Web Workers

Design

• [ ] Layered shadows (ambient + direct)
• [ ] Crisp borders + shadows
• [ ] Nested radii (child ≤ parent, concentric)
• [ ] Hue consistency on non-neutral backgrounds
• [ ] Color-blind-friendly chart palettes
• [ ] Prefer APCA over WCAG 2 for contrast
• [ ] Interactions increase contrast
• [ ] Set <meta name="theme-color">
• [ ] Set color-scheme: dark on <html> for dark themes
• [ ] Animate wrapper, not text node (or translateZ(0))
• [ ] Avoid gradient banding (use background images)

Copywriting (Vercel-specific)

• [ ] Active voice
• [ ] Headings/buttons: Title Case (Chicago)
• [ ] Marketing pages: sentence case
• [ ] Clear & concise
• [ ] Prefer & over and
• [ ] Action-oriented language
• [ ] Keep nouns consistent
• [ ] Second person, no first person
• [ ] Consistent placeholders (YOUR_API_TOKEN_HERE, 0123456789)
• [ ] Numerals for counts
• [ ] Consistent currency (0 or 2 decimals, never mix)
• [ ] Space between numbers & units (10 MB, use  )
• [ ] Default to positive language
• [ ] Error messages guide the exit
• [ ] Avoid ambiguity (specific labels)