Web Interface Guidelines

Concise rules for building accessible, fast, delightful UIs. Use MUST/SHOULD/NEVER to guide decisions and reviews.

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

Area	Top MUST checks
Keyboard	Full keyboard support per WAI-ARIA APG; visible focus rings; manage focus (trap/move/return)
Forms	No paste blocking; loading buttons keep label + spinner; inline errors + focus first error
Navigation	URL reflects state; links are links; back/forward restores scroll
Motion	Respect prefers-reduced-motion; animate transform/opacity only; animations interruptible
Layout	Respect safe areas; avoid unwanted scrollbars; verify mobile/laptop/ultra-wide
Content	Accurate labels; skip link + proper headings; resilient to long user content
Performance	Measure reliably; batch layout reads/writes; prevent CLS from images

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&nbsp;MB
```
,
```
⌘&nbsp;+&nbsp;K
```
,
```
Vercel&nbsp;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

tsx

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

web-interface-guidelines

NPX Install

Tags

SKILL.md Content

Web Interface Guidelines

How to apply

Quick reference

Interactions

Animation

Layout

Content & accessibility

Performance

Design

Example: loading submit button with inline error focus

Common mistakes

Red flags