Web Interface Guidelines

How to apply

• Prioritize MUST items first; NEVER items are hard constraints.
• When reviewing, scan each section and confirm every MUST is satisfied or consciously justified.
• If a guideline conflicts with product requirements, surface the conflict explicitly.

Quick reference

Interactions

• Keyboard
  • MUST: Full keyboard support per WAI-ARIA APG patterns
  • 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:
    html

    <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 (behavior)
  • 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 (e.g.,

    +1 (123) 456-7890

    ,

    sk-012345…

    )
  • MUST: Warn on unsaved changes before navigation
  • MUST: Compatible with password managers and 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 (e.g., "Rename…") and loading states (e.g., "Loading…")
• 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 (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 mono like Geist Mono)
• 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

  …

• 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

  ,

  ⌘ + K

  ,

  Vercel SDK

Performance

• SHOULD: Test iOS Low Power Mode and macOS Safari
• MUST: Measure reliably (disable extensions that skew runtime)
• MUST: Track and minimize re-renders (React DevTools/React Scan)
• MUST: Profile with CPU/network throttling
• MUST: Batch layout reads/writes; avoid unnecessary reflows/repaints
• MUST: Mutations (

  POST/PATCH/DELETE

  ) target < 500 ms
• SHOULD: Prefer uncontrolled inputs; make controlled loops cheap (keystroke cost)
• MUST: Virtualize large lists (e.g., virtua)
• MUST: Preload only above-the-fold images; lazy-load the rest
• MUST: Prevent CLS from images (explicit dimensions or reserved space)

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)

Example: loading submit button with inline error focus

type Props = {
  pending: boolean;
  errorId?: string;
};

export function SubmitButton({ pending, errorId }: Props) {
  return (
    <button
      type="submit"
      aria-describedby={errorId}
      aria-busy={pending}
      disabled={pending}
    >
      {pending ? (
        <span aria-live="polite">
          <span className="spinner" aria-hidden="true" />
          Saving…
        </span>
      ) : (
        "Save"
      )}
    </button>
  );
}

Common mistakes

• Missing focus management in dialogs/drawers (no trap/return)
• Blocking paste in inputs or disabling zoom on mobile
• Loading states that replace labels instead of adding a spinner
• Links implemented as buttons (breaks Cmd/Ctrl/middle-click)
• Animating layout properties instead of

  transform

  /

  opacity

• Shipping icons without accessible labels or text alternatives

Red flags

• Keyboard users cannot reach or activate every interactive element
• Forms fail when autofill or password managers are used
• Scroll position is lost on back/forward
• CLS occurs when images load
• Motion plays for users who prefer reduced motion