Tools · Accessibility

The design-system
a11y checklist.

Twenty-six checks across five layers — token, component, composition, motion, distribution. Tick each item as you verify it in your system; progress saves to your browser; export to markdown when you're done. The contrast checker lives inside the token generator.

Checks: 25
Layers: 05
Saves to: Browser
Export: MD

The wrong question

Is this pair AA?

Most a11y tooling answers a single question: does this color combination pass WCAG 2.1? Useful in isolation, useless as a system-level safeguard. You can have an entire palette of compliant pairs and still ship an inaccessible product because the question stops at the pair.

The right question

Where will my system fail in production?

The interesting failures live in component states, composition rules, motion preferences, and the pipeline that lets regressions reach main. Five layers, each with the specific questions that catch real-world a11y debt before users do.

Progress

0 / 250%

Token audit

Component audit

Composition audit

Motion audit

Distribution audit

01Audit layer0 / 5

Token audit

The foundation. If color tokens fail at the surface level, every component built on them inherits the problem. Audit happens once, before component work.

Does every text-on-surface pair pass APCA Lc 75 (body) or Lc 60 (display)?
WCAG 2.1's 4.5:1 ratio is a poor predictor of real-world readability. APCA, used in WCAG 3 drafts, models how actual humans perceive contrast — small text needs more contrast than large.
Verify
Run the token generator's contrast matrix on every (text, surface) pair. Fail rows highlighted automatically.
Do interactive tokens (hover / active / focus) still pass at AA?
Most palette tools test the default state and call it done. Hover variants are typically 5–10% darker — easy to drop below threshold without noticing.
Verify
For every interactive component variant, contrast-test the hover/active/focus colors against their backgrounds.
Are dark-mode pairs at parity with light mode?
Common failure: a brand color works in light mode but reads thin against the dark canvas. Or text-muted in dark mode is a different OKLCH L value than it should be.
Verify
Run the contrast matrix in both modes. Compare the two tables side-by-side.
Is the palette legible to the eight color-vision conditions?
Protanopia, deuteranopia, tritanopia plus the three weak forms and achromatopsia. Bigger risk than contrast: relying on red/green to signal status when those collapse for ~5% of users.
Verify
Token-generator preview has a CB simulation overlay. Verify every status indicator stays distinguishable when filtered.
Are status colors backed by icon + text, not color alone?
Color-only information is the most-cited WCAG SC 1.4.1 violation. Token-level rule: every status token (success / warning / error) gets a co-token for its icon and a content guideline mandating text.
Verify
Audit every status surface in the system. Each one must carry icon AND text AND color.

02Audit layer0 / 6

Component audit

Every component, every state. The default render is the easy case; failure modes live in focus, disabled, error, and loading variants. Most a11y bugs ship here.

Does every interactive element have a visible focus indicator at 3:1 contrast?
The browser default is fine for inputs. Custom buttons, links styled as buttons, and clickable cards typically suppress it without restoring an equivalent. WCAG 2.2 SC 2.4.11 makes the indicator mandatory.
Verify
Tab through every component story in Storybook. Every stop must be visible. Use brand-color outlines globally via :focus-visible.
Is every hit target ≥ 24×24 CSS px (WCAG 2.2 SC 2.5.8)?
WCAG 2.1's 44×44 was a guideline; 2.2 raised the floor to a 24×24 mandate at Level AA. Icon buttons, tag pills, and table-row clickable areas commonly fail.
Verify
Audit every clickable element under 32px. Add padding or a wrapper to reach the threshold.
Are disabled states distinguishable by non-color cues?
opacity-50 on a disabled button is invisible to screen readers. The actual contract is aria-disabled='true' plus an explanatory aria-label.
Verify
Inspect every disabled state. Confirm aria-disabled + explanation, not just opacity.
Do error states announce themselves to assistive tech?
Visual error styling is the easy half. The hard half: aria-invalid='true' on the input, aria-describedby pointing at the error text, and a live region if the error appears dynamically.
Verify
VoiceOver or NVDA must announce the error on submission, not just on visual focus.
Are loading skeletons exposed as such, not as content?
A pulsing gray rect read aloud sounds nonsensical. Loading regions need aria-busy='true', aria-live='polite', and a screen-reader-only 'Loading' label.
Verify
Trigger each loading state with a screen reader on. Loading should announce; settled content should announce when ready.
Do icon buttons carry an accessible label?
An icon without text is a button without a name. Screen readers say 'button' with no context. Every icon-only button needs aria-label; every icon next to text gets aria-hidden.
Verify
Grep for icon-only buttons. Every one must have aria-label.

03Audit layer0 / 5

Composition audit

Page-level structure. Components can each be perfect in isolation and still produce an inaccessible page when assembled. Headings, landmarks, focus order, form labels.

Is there exactly one h1 per page, with no skipped heading levels?
Screen readers use heading levels to build an outline. h1 → h3 breaks the outline. Multiple h1s split it.
Verify
Browser accessibility tree inspector or axe DevTools extension on every template.
Does the page have landmark regions: header, nav, main, footer?
Landmarks let screen-reader users jump between page regions. Wrapping everything in <div> defeats the navigation shortcuts.
Verify
Confirm one <main> per page and named landmarks for header / nav / footer.
Are form labels associated with their inputs?
<label for='email'> + <input id='email'>, OR a wrapping label. Placeholders are not labels — they disappear on focus and have poor contrast.
Verify
Every form input must have a programmatic label. aria-label is the fallback for icon-only inputs; aria-labelledby for grouped labels.
Is the tab order logical and uninterrupted?
Tab order follows DOM. CSS reordering with flex-direction reverse or `order:` breaks the visual-keyboard mapping. Modals must trap focus.
Verify
Tab through every page. Visual and keyboard order must match. Open modals trap; closed modals restore focus.
Are dialogs and menus announced as such?
Without role='dialog' + aria-modal='true' + a labelled title, a modal reads as 'a region.' Radix Dialog handles this; custom modals usually don't.
Verify
Open every dialog with a screen reader. It must announce 'dialog' + the title, and tab must trap inside.

04Audit layer0 / 4

Motion audit

Reduce-motion preferences and safe defaults. Often skipped because motion gets added at the component level after the audit. Tokenize the motion policy at the system level.

Does every animation honor prefers-reduced-motion?
Vestibular disorders are triggered by motion. The OS preference is the user's request; honor it everywhere, not just in marketing animations.
Verify
Token the motion policy (--motion-fast, --motion-slow) to 0ms inside the prefers-reduced-motion media query. Every animation reads from these tokens.
Does no content flash more than 3 times per second?
WCAG 2.1 SC 2.3.1. Flashing is a seizure trigger for users with photosensitive epilepsy. Includes loading states and error indicators.
Verify
Inspect every animation under 0.33s duration. None should fully toggle visibility more than 3×/second.
Does autoplay video / audio respect user preference?
Autoplay with sound was banned by browsers years ago; autoplay without sound still violates user expectation. Provide pause + don't autoplay above 5s.
Verify
Every media component defaults autoPlay={false} and exposes pause / mute prominently.
Are parallax / scroll-driven effects skippable?
Even at non-flashing speeds, scroll-jacking and large translations cause motion sickness. Provide a fallback that disables, not just slows.
Verify
Test every scroll-driven section with prefers-reduced-motion on. The effect should disappear, not slow down.

05Audit layer0 / 5

Distribution audit

Keeping regressions out. A11y audited once is a11y broken next sprint. This category is the pipeline that prevents the system from drifting.

Is axe-core (or equivalent) running on every PR?
Automated testing catches ~30% of issues — the deterministic ones. axe-playwright + a Storybook a11y addon catches most regressions before review.
Verify
CI workflow includes an a11y job. PR fails if new violations introduced. Existing violations grandfathered with explicit annotations.
Does every component story include an a11y assertion?
Storybook's a11y addon gives per-story violation reports. The discipline: every new story includes a 'play' function that exercises a11y states.
Verify
Audit a sample of stories. Each one runs an axe scan on render.
Is the a11y review explicit in PR templates?
Reviewers default to checking what they can see. A11y is invisible by default. The PR template needs a checklist: tested with keyboard? Screen-reader announces? Focus restored on close?
Verify
Read the PR template. It surfaces the three a11y questions reviewers most commonly skip.
Is there a deprecation policy for inaccessible components?
Sometimes a component ships with known issues. The policy decides whether you ship with a deprecation tag or block the merge. Without one, you'll ship and forget.
Verify
Open the governance doc. Find the 'a11y exceptions' section. It exists and has owners.
Are a11y bug reports treated as bugs, not feature requests?
A11y issues often filed as 'enhancements'. Wrong category. They block users. Same SLA as functional bugs.
Verify
Pull recent a11y-tagged issues. Their priority labels should match other bugs of equivalent severity.

Where to go next.

Each layer of the checklist has a longer-form companion piece on the site. The token generator carries the contrast matrix; the accessibility foundation covers the first-principles; the playbook puts the work in chronological order.

The design-system
a11y checklist.

Is this pair AA?

Where will my system fail in production?

Token audit

Component audit

Composition audit

Motion audit

Distribution audit

Where to go next.

Token Generator

Accessibility foundations

Playbook · Foundations first

The design-system
a11y checklist.

Is this pair AA?

Where will my system fail in production?

Token audit

Component audit

Composition audit

Motion audit

Distribution audit

Where to go next.

Token Generator

Accessibility foundations

Playbook · Foundations first

The design-system a11y checklist.

Is this pair AA?

Where will my system fail in production?

Token audit

Component audit

Composition audit

Motion audit

Distribution audit

Where to go next.

Token Generator

Accessibility foundations

Playbook · Foundations first

The design-system a11y checklist.

Is this pair AA?

Where will my system fail in production?

Token audit

Component audit

Composition audit

Motion audit

Distribution audit

Where to go next.

Token Generator

Accessibility foundations

Playbook · Foundations first

The design-system
a11y checklist.

The design-system
a11y checklist.