Web interface guidelines review
When to use
- Reviewing a PR that adds or modifies UI components.
- Auditing an existing UI surface for token discipline, contrast, focus handling, and a11y.
- Writing or reviewing design specs that propose new components.
- After a Figma → code handoff, before merging.
When NOT to use
- Pure backend / non-UI PRs (skill won't fire on a server-route change).
- No carve-out for a missing token layer: only section 6 skips without one.
- Prototype code explicitly labeled as throwaway.
The review checklist
Apply each section in order. Stop and flag at the first failure in each section.
1. Contrast: APCA-preferred, WCAG cross-check
- Primary model is APCA Lc. Verify the foreground color hits its declared Lc target (typically 90 fluent body, 75 body minimum, 60 secondary, 45 large display, 30 spot, 15 non-text — see apca-contrast).
- WCAG 2.2 AA is a cross-check, not the primary. Verify the pair also meets 4.5:1 (normal) / 3:1 (large or non-text) per wcag-contrast. Sizes are in points, not pixels (18 pt ≈ 24 CSS px; 14 pt bold ≈ 18.67 CSS px).
- Flag any review that cites WCAG as the only model — APCA catches real perceptual failures WCAG misses.
- Flag hardcoded hex in source: every contrast-bound color resolves from a token (role families content / surface / border — see token-naming-conventions).
2. Typography: atomic classes from the scale
- Atomic typography classes. One Tailwind / utility class binds font-family + size + lh + tracking + weight — e.g.
body-md,heading-lg. No à-la-carte composition (text-sm font-medium tracking-tight). - Sizes come from the type scale. Every rendered font-size matches a step from the system's modular scale (1.067 → 1.618 family). Flag arbitrary px like
text-[13px]— outside the scale. - Line-height per role. UI text uses
lh-ui(× 1.20 + grid snap); paragraph body useslh-prose(× 1.50 + grid snap). See line-height-grid. - Body text never below 14 pt (≈ 18.67 CSS px); UI labels usable down to 12 CSS px for non-fluent content (badges, metadata) but never below 10 px.
3. Spacing + sizing: token-driven
- Padding, gap, margin values are tokens from the spacing scale (
padding-*/space-*/gap-*), not raw px. See spacing-system. - Component heights come from the system's per-density curated ladder. See component-sizing-principles.
- Interactive heights ≥ 24 CSS px per WCAG 2.5.8 (AA, Target Size Minimum). Rungs below that floor are non-interactive only; whether a ladder's smallest rung is additionally reserved is owned by
component-sizing-principles. - Flag inconsistent rung mixing in the same UI surface (
sm+mdbuttons side by side reads as a typo, not a hierarchy).
4. Action labels: verb-noun
- Buttons that perform an action use verb-noun ("Save changes", "Send invitation", "Open settings"). Never "Click here!", "Submit", or "OK" alone.
- Links that navigate use destination-descriptive text ("Browse all results", not "Click here"). WCAG 2.4.4.
- Flag tone drift: marketing exclamation marks, hedging ("might want to"), emoji in interactive labels.
5. Link vs button
- Links go places. Buttons do things. Navigating or changing the URL is an
<a>/<Link>; triggering an action is a<button>. - Flag
<button>usingwindow.location.href = …orrouter.push(…)— that's a link. - Flag
<a>withonClickdoing in-place mutation andhref="#"— that's a button. - Use the framework's router (
<Link>,useRouter) for SPA navigation; never rawwindow.locationreassignment.
6. Focus + keyboard
- Focus-visible always. Every interactive element has a visible focus ring on
:focus-visible. The default Tailwind reset suppresses outlines; the system must re-add them. - Focus ring contract: 3:1 against both the control and the adjacent surface — 1.4.11, AA. The ≥ 2 px perimeter is 2.4.13, AAA: an enhancement, never an AA failure. A well-formed system's focus token satisfies both.
- Keyboard reachability: every interactive control is tabbable; tab order matches visual order.
- Escape closes overlays: dialogs, popovers, dropdowns close on Escape.
7. Forms
- Every form control has a programmatic label (
<label>,aria-label, oraria-labelledby). Placeholders are NOT labels — they vanish on focus. - Search inputs use
type="search"; emailstype="email"; numberstype="number"with sensibleinputmode. Mobile keyboard semantics depend on the type. - Forms submit on Enter (a
<form>wrapper with a submit handler, not a<button onClick>that ignores Enter). - Required fields marked both visually (asterisk + legend) and programmatically (
requiredoraria-required).
8. Icons + non-text content
- Decorative icons get
aria-hidden="true"and no accessible name. - Functional icons (icon-only buttons) get an accessible name via
aria-label("Search", "Close dialog"). - Icon sizes come from the curated ladder (e.g. 12, 16, 24, 32, 40, 48), paired with the control's rung per
component-sizing-principles. No arbitrarysize={14}.
9. Motion
- Honor
prefers-reduced-motion: reduce— reduce animation distance and easing, or remove non-essential motion entirely. - Transitions on color, transform, and opacity only; never
width,height,top,left(they trigger layout). State changes: motion-continuity. - Durations from a token (
duration-fast/duration-default/duration-slow), not arbitrarymsvalues.
10. Token discipline
- No raw hex, no raw px, no raw rem in source. Every value resolves from a token (a text role token,
padding-md,radius-lg, etc.). - Component tokens reference semantic / color-mode tokens, never primitives directly (see
token-naming-conventionsfor the two chain shapes). - Flag inline
style={{ … }}carrying values that should be tokens; the only exception is values genuinely computed at runtime.
How to phrase findings
- One finding per comment. Bundling unrelated issues makes them hard to track.
- Cite the rule + the source (WCAG SC, WIG section, the relevant skill name).
- Show the fix, not just the rule. "Replace
style={{ color: '#666' }}withclassName=\"text-secondary\"" beats "use the design tokens." - Quote the offending line verbatim before the critique.
Verification
After completing a review:
- Every finding cites a rule. No vibes-based "this feels off."
- Every finding has a fix. Fixless findings get rejected.
- Sections applied in order. Contrast and a11y come before token discipline; don't lead with cosmetic findings.
- No bundled comments.
- Skills cross-referenced. Contrast findings cite
apca-contrast/wcag-contrast; size findings citetype-scale/component-sizing-principles.
Cross-references
- REQUIRED BACKGROUND: contrast — apca-contrast, wcag-contrast; typography — type-scale, line-height-grid; spacing — spacing-system, component-sizing-principles; tokens — token-naming-conventions, dtcg-format.
- UI-string voice: brand-voice-review.
Sources
- Vercel Web Interface Guidelines — the WIG canon.
- Material Design 3 — alternate canon for cross-checks.
- Radix UI documentation — accessible-component reference.
- WCAG 2.2 Recommendation — the legal baseline.
- System-specific review layers (e.g. udts-review, incubating) compose on top of this generic lens.