Web Interface Guidelines
Review files for compliance with Web Interface Guidelines.
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)
- Destructive actions need confirmation modal or undo window—never immediate
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)
Touch & Interaction
touch-action: manipulation (prevents double-tap zoom delay)-webkit-tap-highlight-color set intentionallyoverscroll-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
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 zoomonPaste with preventDefaulttransition: alloutline-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.
1---2name: web-design-guidelines-43description: Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".4license: MIT5---6
7# Web Interface Guidelines
8
9Review files for compliance with Web Interface Guidelines.
10
11Read files, check against rules below. Output concise but comprehensive—sacrifice grammar for brevity. High signal-to-noise.
12
13## Rules
14
15### Accessibility
16
17- Icon-only buttons need `aria-label`
18- Form controls need `<label>` or `aria-label`
19- Interactive elements need keyboard handlers (`onKeyDown`/`onKeyUp`)
20- `<button>` for actions, `<a>`/`<Link>` for navigation (not `<div onClick>`)
21- Images need `alt` (or `alt=""` if decorative)
22- Decorative icons need `aria-hidden="true"`
23- Async updates (toasts, validation) need `aria-live="polite"`
24- Use semantic HTML (`<button>`, `<a>`, `<label>`, `<table>`) before ARIA
25- Headings hierarchical `<h1>`–`<h6>`; include skip link for main content
26- `scroll-margin-top` on heading anchors
27
28### Focus States
29
30- Interactive elements need visible focus: `focus-visible:ring-*` or equivalent
31- Never `outline-none` / `outline: none` without focus replacement
32- Use `:focus-visible` over `:focus` (avoid focus ring on click)
33- Group focus with `:focus-within` for compound controls
34
35### Forms
36
37- Inputs need `autocomplete` and meaningful `name`
38- Use correct `type` (`email`, `tel`, `url`, `number`) and `inputmode`
39- Never block paste (`onPaste` + `preventDefault`)
40- Labels clickable (`htmlFor` or wrapping control)
41- Disable spellcheck on emails, codes, usernames (`spellCheck={false}`)
42- Checkboxes/radios: label + control share single hit target (no dead zones)
43- Submit button stays enabled until request starts; spinner during request
44- Errors inline next to fields; focus first error on submit
45- Placeholders end with `…` and show example pattern
46- `autocomplete="off"` on non-auth fields to avoid password manager triggers
47- Warn before navigation with unsaved changes (`beforeunload` or router guard)
48
49### Animation
50
51- Honor `prefers-reduced-motion` (provide reduced variant or disable)
52- Animate `transform`/`opacity` only (compositor-friendly)
53- Never `transition: all`—list properties explicitly
54- Set correct `transform-origin`
55- SVG: transforms on `<g>` wrapper with `transform-box: fill-box; transform-origin: center`
56- Animations interruptible—respond to user input mid-animation
57
58### Typography
59
60- `…` not `...`
61- Curly quotes `"` `"` not straight `"`
62- Non-breaking spaces: `10 MB`, `⌘ K`, brand names
63- Loading states end with `…`: `"Loading…"`, `"Saving…"`
64- `font-variant-numeric: tabular-nums` for number columns/comparisons
65- Use `text-wrap: balance` or `text-pretty` on headings (prevents widows)
66
67### Content Handling
68
69- Text containers handle long content: `truncate`, `line-clamp-*`, or `break-words`
70- Flex children need `min-w-0` to allow text truncation
71- Handle empty states—don't render broken UI for empty strings/arrays
72- User-generated content: anticipate short, average, and very long inputs
73
74### Images
75
76- `<img>` needs explicit `width` and `height` (prevents CLS)
77- Below-fold images: `loading="lazy"`
78- Above-fold critical images: `priority` or `fetchpriority="high"`
79
80### Performance
81
82- Large lists (>50 items): virtualize (`virtua`, `content-visibility: auto`)
83- No layout reads in render (`getBoundingClientRect`, `offsetHeight`, `offsetWidth`, `scrollTop`)
84- Batch DOM reads/writes; avoid interleaving
85- Prefer uncontrolled inputs; controlled inputs must be cheap per keystroke
86- Add `<link rel="preconnect">` for CDN/asset domains
87- Critical fonts: `<link rel="preload" as="font">` with `font-display: swap`
88
89### Navigation & State
90
91- URL reflects state—filters, tabs, pagination, expanded panels in query params
92- Links use `<a>`/`<Link>` (Cmd/Ctrl+click, middle-click support)
93- Deep-link all stateful UI (if uses `useState`, consider URL sync)
94- Destructive actions need confirmation modal or undo window—never immediate
95
96### Dark Mode & Theming
97
98- `color-scheme: dark` on `<html>` for dark themes (fixes scrollbar, inputs)
99- `<meta name="theme-color">` matches page background
100- Native `<select>`: explicit `background-color` and `color` (Windows dark mode)
101
102### Touch & Interaction
103
104- `touch-action: manipulation` (prevents double-tap zoom delay)
105- `-webkit-tap-highlight-color` set intentionally
106- `overscroll-behavior: contain` in modals/drawers/sheets
107- During drag: disable text selection, `inert` on dragged elements
108- `autoFocus` sparingly—desktop only, single primary input; avoid on mobile
109
110### Safe Areas & Layout
111
112- Full-bleed layouts need `env(safe-area-inset-*)` for notches
113- Avoid unwanted scrollbars: `overflow-x-hidden` on containers, fix content overflow
114- Flex/grid over JS measurement for layout
115
116### Locale & i18n
117
118- Dates/times: use `Intl.DateTimeFormat` not hardcoded formats
119- Numbers/currency: use `Intl.NumberFormat` not hardcoded formats
120- Detect language via `Accept-Language` / `navigator.languages`, not IP
121
122### Hydration Safety
123
124- Inputs with `value` need `onChange` (or use `defaultValue` for uncontrolled)
125- Date/time rendering: guard against hydration mismatch (server vs client)
126- `suppressHydrationWarning` only where truly needed
127
128### Hover & Interactive States
129
130- Buttons/links need `hover:` state (visual feedback)
131- Interactive states increase contrast: hover/active/focus more prominent than rest
132
133### Content & Copy
134
135- Active voice: "Install the CLI" not "The CLI will be installed"
136- Title Case for headings/buttons (Chicago style)
137- Numerals for counts: "8 deployments" not "eight"
138- Specific button labels: "Save API Key" not "Continue"
139- Error messages include fix/next step, not just problem
140- Second person; avoid first person
141- `&` over "and" where space-constrained
142
143### Anti-patterns (flag these)
144
145- `user-scalable=no` or `maximum-scale=1` disabling zoom
146- `onPaste` with `preventDefault`
147- `transition: all`
148- `outline-none` without focus-visible replacement
149- Inline `onClick` navigation without `<a>`
150- `<div>` or `<span>` with click handlers (should be `<button>`)
151- Images without dimensions
152- Large arrays `.map()` without virtualization
153- Form inputs without labels
154- Icon buttons without `aria-label`
155- Hardcoded date/number formats (use `Intl.*`)
156- `autoFocus` without clear justification
157
158## Output Format
159
160Group by file. Use `file:line` format (VS Code clickable). Terse findings.
161
162```text
163## src/Button.tsx
164
165src/Button.tsx:42 - icon button missing aria-label
166src/Button.tsx:18 - input lacks label
167src/Button.tsx:55 - animation missing prefers-reduced-motion
168src/Button.tsx:67 - transition: all → list properties
169
170## src/Modal.tsx
171
172src/Modal.tsx:12 - missing overscroll-behavior: contain
173src/Modal.tsx:34 - "..." → "…"
174
175## src/Card.tsx
176
177✓ pass
178```
179
180State issue + location. Skip explanation unless fix non-obvious. No preamble.
majiayu000