Web Design Guidelines

Web Interface Guidelines

Review files for compliance with Web Interface Guidelines.

How It Works

1. Read the guidelines from #[[file:references/guideline.md]] 2. Read the specified files (or prompt user for files/pattern) 3. Check against all rules in the guidelines 4. Output findings in the terse file:line format

Guidelines Reference

All rules and output format instructions are in:

#[[file:references/guideline.md]]

The guidelines cover:

• Accessibility (ARIA, semantic HTML, keyboard navigation)
• Focus states and keyboard interaction
• Forms (autocomplete, validation, labels)
• Animation (reduced motion, performance)
• Typography (proper characters, number formatting)
• Content handling (overflow, empty states)
• Images (dimensions, lazy loading)
• Performance (virtualization, DOM reads)
• Navigation & state (URL sync, deep linking)
• Touch & interaction (tap delays, safe areas)
• Dark mode & theming
• Locale & i18n
• Hydration safety
• Common anti-patterns to flag

Usage

When a user provides a file or pattern argument:

1. Read the guidelines from references/guideline.md 2. Read the specified files 3. Apply all rules from the guidelines 4. Output findings using the format specified in the guidelines

If no files specified, ask the user which files to review.

Output Format

Follow the format in the guidelines:

• Group findings by file
• Use file:line format (VS Code clickable)
• Terse, high signal-to-noise
• State issue + location
• Skip explanation unless fix is non-obvious

Web Interface Guidelines

Review these files for compliance: $ARGUMENTS

Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise.

Rules

Accessibility

• Icon-only buttons need aria-label
• Form controls need <label> or aria-label
• Interactive elements need keyboard handlers (onKeyDown/onKeyUp)
• <button> for actions, <a>/<Link> for navigation (not <div onClick>)
• Images need alt (or alt="" if decorative)
• Decorative icons need aria-hidden="true"
• Async updates (toasts, validation) need aria-live="polite"
• Use semantic HTML (<button>, <a>, <label>, <table>) before ARIA
• Headings hierarchical <h1>–<h6>; include skip link for main content
• scroll-margin-top on heading anchors

Focus States

• Interactive elements need visible focus: focus-visible:ring-* or equivalent
• Never outline-none / outline: none without focus replacement
• Use :focus-visible over :focus (avoid focus ring on click)
• Group focus with :focus-within for compound controls

Forms

• Inputs need autocomplete and meaningful name
• Use correct type (email, tel, url, number) and inputmode
• Never block paste (onPaste + preventDefault)
• Labels clickable (htmlFor or wrapping control)
• Disable spellcheck on emails, codes, usernames (spellCheck={false})
• Checkboxes/radios: label + control share single hit target (no dead zones)
• Submit button stays enabled until request starts; spinner during request
• Errors inline next to fields; focus first error on submit
• Placeholders end with … and show example pattern
• autocomplete="off" on non-auth fields to avoid password manager triggers
• Warn before navigation with unsaved changes (beforeunload or router guard)

Animation

• Honor prefers-reduced-motion (provide reduced variant or disable)
• Animate transform/opacity only (compositor-friendly)
• Never transition: all—list properties explicitly
• Set correct transform-origin
• SVG: transforms on <g> wrapper with transform-box: fill-box; transform-origin: center
• Animations interruptible—respond to user input mid-animation

Typography

• … not ...
• Curly quotes " " not straight "
• Non-breaking spaces: 10 MB, ⌘ K, brand names
• Loading states end with …: "Loading…", "Saving…"
• font-variant-numeric: tabular-nums for number columns/comparisons
• Use text-wrap: balance or text-pretty on headings (prevents widows)

Content Handling

• Text containers handle long content: truncate, line-clamp-*, or break-words
• Flex children need min-w-0 to allow text truncation
• Handle empty states—don't render broken UI for empty strings/arrays
• User-generated content: anticipate short, average, and very long inputs

Images

• <img> needs explicit width and height (prevents CLS)
• Below-fold images: loading="lazy"
• Above-fold critical images: priority or fetchpriority="high"

Performance

• Large lists (>50 items): virtualize (virtua, content-visibility: auto)
• No layout reads in render (getBoundingClientRect, offsetHeight, offsetWidth, scrollTop)
• Batch DOM reads/writes; avoid interleaving
• Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
• Add <link rel="preconnect"> for CDN/asset domains
• Critical fonts: <link rel="preload" as="font"> with font-display: swap

Navigation & State

• URL reflects state—filters, tabs, pagination, expanded panels in query params
• Links use <a>/<Link> (Cmd/Ctrl+click, middle-click support)
• Deep-link all stateful UI (if uses useState, consider URL sync via nuqs or similar)
• Destructive actions need confirmation modal or undo window—never immediate

Touch & Interaction

• touch-action: manipulation (prevents double-tap zoom delay)
• -webkit-tap-highlight-color set intentionally
• overscroll-behavior: contain in modals/drawers/sheets
• During drag: disable text selection, inert on dragged elements
• autoFocus sparingly—desktop only, single primary input; avoid on mobile

Safe Areas & Layout

• Full-bleed layouts need env(safe-area-inset-*) for notches
• Avoid unwanted scrollbars: overflow-x-hidden on containers, fix content overflow
• Flex/grid over JS measurement for layout

Dark Mode & Theming

• color-scheme: dark on <html> for dark themes (fixes scrollbar, inputs)
• <meta name="theme-color"> matches page background
• Native <select>: explicit background-color and color (Windows dark mode)

Locale & i18n

• Dates/times: use Intl.DateTimeFormat not hardcoded formats
• Numbers/currency: use Intl.NumberFormat not hardcoded formats
• Detect language via Accept-Language / navigator.languages, not IP

Hydration Safety

• Inputs with value need onChange (or use defaultValue for uncontrolled)
• Date/time rendering: guard against hydration mismatch (server vs client)
• suppressHydrationWarning only where truly needed

Hover & Interactive States

• Buttons/links need hover: state (visual feedback)
• Interactive states increase contrast: hover/active/focus more prominent than rest

Content & Copy

• Active voice: "Install the CLI" not "The CLI will be installed"
• Title Case for headings/buttons (Chicago style)
• Numerals for counts: "8 deployments" not "eight"
• Specific button labels: "Save API Key" not "Continue"
• Error messages include fix/next step, not just problem
• Second person; avoid first person
• & over "and" where space-constrained

Anti-patterns (flag these)

• user-scalable=no or maximum-scale=1 disabling zoom
• onPaste with preventDefault
• transition: all
• outline-none without focus-visible replacement
• Inline onClick navigation without <a>
• <div> or <span> with click handlers (should be <button>)
• Images without dimensions
• Large arrays .map() without virtualization
• Form inputs without labels
• Icon buttons without aria-label
• Hardcoded date/number formats (use Intl.*)
• autoFocus without clear justification

Output Format

Group by file. Use file:line format (VS Code clickable). Terse findings.

## src/Button.tsx

src/Button.tsx:42 - icon button missing aria-label
src/Button.tsx:18 - input lacks label
src/Button.tsx:55 - animation missing prefers-reduced-motion
src/Button.tsx:67 - transition: all → list properties

## src/Modal.tsx

src/Modal.tsx:12 - missing overscroll-behavior: contain
src/Modal.tsx:34 - "..." → "…"

## src/Card.tsx

✓ pass

State issue + location. Skip explanation unless fix non-obvious. No preamble.