Web Design Guidelines Skill
Purpose
Audit interface code against a concise MUST/SHOULD/NEVER rule set covering interaction, animation, layout, accessibility, performance, and theming.
When to use
Use this skill as a pre-merge gate on user-facing UI. Use impeccable-ui.md for design direction and craft; use this for conformance.
Inputs
- the pages or components under review
- target breakpoints and browsers
- framework and whether the app hydrates
- any product-specific interaction requirements
Output
Return:
- findings grouped as interactions, animation, layout, content and accessibility, performance, theming, hydration
- each finding labelled MUST / SHOULD / NEVER, with the element and the corrected code
- an explicit statement of what was not checked
Constraints
- Keyboard — full support per WAI-ARIA APG; visible
:focus-visible rings; managed focus (trap, move, return); never outline: none without a replacement
- Targets — hit target ≥24px, ≥44px on mobile; mobile
<input> font-size ≥16px to prevent iOS zoom; never disable browser zoom; touch-action: manipulation
- Forms — never block paste; keep submit enabled until the request starts, then spinner with the original label; accept free text and validate after; allow incomplete submission to surface validation; errors inline with focus moved to the first one;
autocomplete plus correct type and inputmode; warn on unsaved changes; label and control share one hit target
- State — URL reflects filters, tabs, pagination, expanded panels; Back/Forward restores scroll; navigation uses
<a>/<Link>, never <div onClick>
- Feedback — confirm destructive actions or offer Undo; polite
aria-live for toasts; optimistic UI reconciled on response
- Animation — honor
prefers-reduced-motion; animate only transform and opacity; never animate layout props; never transition: all; animations interruptible, no autoplay; correct transform-origin
- Layout — deliberate alignment, optical ±1px where perception beats geometry; verify mobile, laptop, and ultra-wide; respect
env(safe-area-inset-*); no unwanted scrollbars
- Content and a11y — no dead ends; design empty, sparse, dense, and error states; skeletons mirror final content;
tabular-nums for compared numbers; status cues never colour-only; icon-only buttons carry aria-label; native semantics before ARIA; resilient to short and very long user content; locale-aware dates and numbers via Intl
- Content handling — text containers truncate or clamp; flex children need
min-w-0; empty strings and arrays must not break layout
- Performance — virtualize lists over 50 items; preload above-fold images and lazy-load the rest; explicit image dimensions to prevent CLS; mutations target under 500ms; batch layout reads and writes; profile with throttling
- Theming —
color-scheme: dark on <html>; <meta name="theme-color"> matches background; native <select> needs explicit colours on Windows
- Hydration — inputs with
value need onChange or defaultValue; guard date rendering against mismatch
- Contrast — meet it, preferring APCA over WCAG 2; increase contrast on hover, active, and focus
Examples
- Audit a checkout flow before release
- Verify a data table's keyboard, truncation, and empty-state behavior
- Check a themed dashboard for dark-mode and hydration defects
1---2name: web-design-guidelines3description: Audit interface code against a concise MUST/SHOULD/NEVER rule set covering interaction, animation, layout, accessibility, performance, and theming. Use this skill as a pre-merge gate on user-facing UI.4---56# Web Design Guidelines Skill78## Purpose9Audit interface code against a concise MUST/SHOULD/NEVER rule set covering interaction, animation, layout, accessibility, performance, and theming.1011## When to use12Use this skill as a pre-merge gate on user-facing UI. Use `impeccable-ui.md` for design direction and craft; use this for conformance.1314## Inputs15- the pages or components under review16- target breakpoints and browsers17- framework and whether the app hydrates18- any product-specific interaction requirements1920## Output21Return:22- findings grouped as interactions, animation, layout, content and accessibility, performance, theming, hydration23- each finding labelled MUST / SHOULD / NEVER, with the element and the corrected code24- an explicit statement of what was not checked2526## Constraints27- **Keyboard** — full support per WAI-ARIA APG; visible `:focus-visible` rings; managed focus (trap, move, return); never `outline: none` without a replacement28- **Targets** — hit target ≥24px, ≥44px on mobile; mobile `<input>` font-size ≥16px to prevent iOS zoom; never disable browser zoom; `touch-action: manipulation`29- **Forms** — never block paste; keep submit enabled until the request starts, then spinner with the original label; accept free text and validate after; allow incomplete submission to surface validation; errors inline with focus moved to the first one; `autocomplete` plus correct `type` and `inputmode`; warn on unsaved changes; label and control share one hit target30- **State** — URL reflects filters, tabs, pagination, expanded panels; Back/Forward restores scroll; navigation uses `<a>`/`<Link>`, never `<div onClick>`31- **Feedback** — confirm destructive actions or offer Undo; polite `aria-live` for toasts; optimistic UI reconciled on response32- **Animation** — honor `prefers-reduced-motion`; animate only `transform` and `opacity`; never animate layout props; never `transition: all`; animations interruptible, no autoplay; correct `transform-origin`33- **Layout** — deliberate alignment, optical ±1px where perception beats geometry; verify mobile, laptop, and ultra-wide; respect `env(safe-area-inset-*)`; no unwanted scrollbars34- **Content and a11y** — no dead ends; design empty, sparse, dense, and error states; skeletons mirror final content; `tabular-nums` for compared numbers; status cues never colour-only; icon-only buttons carry `aria-label`; native semantics before ARIA; resilient to short and very long user content; locale-aware dates and numbers via `Intl`35- **Content handling** — text containers truncate or clamp; flex children need `min-w-0`; empty strings and arrays must not break layout36- **Performance** — virtualize lists over 50 items; preload above-fold images and lazy-load the rest; explicit image dimensions to prevent CLS; mutations target under 500ms; batch layout reads and writes; profile with throttling37- **Theming** — `color-scheme: dark` on `<html>`; `<meta name="theme-color">` matches background; native `<select>` needs explicit colours on Windows38- **Hydration** — inputs with `value` need `onChange` or `defaultValue`; guard date rendering against mismatch39- **Contrast** — meet it, preferring APCA over WCAG 2; increase contrast on hover, active, and focus4041## Examples42- Audit a checkout flow before release43- Verify a data table's keyboard, truncation, and empty-state behavior44- Check a themed dashboard for dark-mode and hydration defects
10xequity