web-interface-guidelines

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

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, return) per APG patterns
• •NEVER: outline: none without visible focus replacement

Targets & Input

• •MUST: Hit target ≥24px (mobile ≥44px); if visual <24px, expand hit area
• •MUST: Mobile <input> font-size ≥16px to prevent iOS zoom
• •NEVER: Disable browser zoom (user-scalable=no, maximum-scale=1)
• •MUST: touch-action: manipulation to prevent double-tap zoom
• •SHOULD: Set -webkit-tap-highlight-color to match design

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 input; in <textarea>, ⌘/Ctrl+Enter submits
• •MUST: Keep submit enabled until request starts; then disable with spinner
• •MUST: Accept free text, validate after—don't block typing
• •MUST: Allow incomplete form submission 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 … and show example pattern
• •MUST: Warn on unsaved changes before navigation
• •MUST: Compatible with password managers & 2FA; allow pasting codes
• •MUST: Trim values to handle text expansion trailing spaces
• •MUST: No dead zones on checkboxes/radios; label+control share one hit target

State & Navigation

• •MUST: URL reflects state (deep-link filters/tabs/pagination/expanded panels)
• •MUST: Back/Forward restores scroll position
• •MUST: Links use <a> or <Link> for navigation (support Cmd/Ctrl/middle-click)
• •NEVER: Use <button> or <div> for navigation

Feedback

• •SHOULD: Optimistic UI; reconcile on response; on failure 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 opening follow-ups ("Rename…") and loading states ("Loading…")

Touch & Drag

• •MUST: Generous targets, clear affordances; avoid finicky interactions
• •MUST: Delay first tooltip; subsequent peers instant
• •MUST: overscroll-behavior: contain in modals/drawers
• •MUST: During drag, disable text selection and set inert on dragged elements
• •MUST: If it looks clickable, it must be clickable

Autofocus

• •SHOULD: Autofocus on desktop with single primary input; rarely on mobile

Animation

• •MUST: Honor prefers-reduced-motion (provide reduced variant or disable)
• •SHOULD: Prefer CSS > Web Animations API > JS libraries
• •MUST: Animate compositor-friendly props (transform, opacity) only
• •NEVER: Animate layout props (top, left, width, height)
• •NEVER: transition: all—list properties explicitly
• •SHOULD: Animate only to clarify cause/effect or add deliberate delight
• •SHOULD: Choose easing to match the change (size/distance/trigger)
• •MUST: Animations interruptible and input-driven (no autoplay)
• •MUST: Correct transform-origin (motion starts where it "physically" should)
• •MUST: SVG transforms on <g> wrapper with transform-box: fill-box

Layout

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

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 (text-wrap: balance)
• •MUST: font-variant-numeric: tabular-nums for number comparisons
• •MUST: Redundant status cues (not color-only); icons have text labels
• •MUST: Accessible names exist even when visuals omit labels
• •MUST: Use … character (not ...)
• •MUST: scroll-margin-top on headings; "Skip to content" link; hierarchical <h1–h6>
• •MUST: Resilient to user-generated content (short/avg/very long)
• •MUST: Locale-aware dates/times/numbers (Intl.DateTimeFormat, Intl.NumberFormat)
• •MUST: Accurate aria-label; decorative elements aria-hidden
• •MUST: Icon-only buttons have descriptive aria-label
• •MUST: Prefer native semantics (button, a, label, table) before ARIA
• •MUST: Non-breaking spaces: 10 MB, ⌘ K, brand names

Content Handling

• •MUST: Text containers handle long content (truncate, line-clamp-*, break-words)
• •MUST: Flex children need min-w-0 to allow truncation
• •MUST: Handle empty states—no broken UI for empty strings/arrays

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 reflows/repaints
• •MUST: Mutations (POST/PATCH/DELETE) target <500ms
• •SHOULD: Prefer uncontrolled inputs; controlled inputs cheap per keystroke
• •MUST: Virtualize large lists (>50 items)
• •MUST: Preload above-fold images; lazy-load the rest
• •MUST: Prevent CLS (explicit image dimensions)
• •SHOULD: <link rel="preconnect"> for CDN domains
• •SHOULD: Critical fonts: <link rel="preload"> with font-display: swap

Dark Mode & Theming

• •MUST: color-scheme: dark on <html> for dark themes
• •SHOULD: <meta name="theme-color"> matches page background
• •MUST: Native <select>: explicit background-color and color (Windows fix)

Hydration

• •MUST: Inputs with value need onChange (or use defaultValue)
• •SHOULD: Guard date/time rendering against hydration mismatch

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 dark color gradient banding (use background images when needed)