Marcus Andrey Study
Ler em português Library

Framework · Design systems · 4 min read

Component accessibility checklist

The WCAG 2.2 success criteria a single component can meet or fail, grouped by the four principles, so every component ships with a tested accessibility contract instead of waiting for a screen-by-screen audit.

PPerceivable

Text alternatives, relationships in code, contrast, no colour-only state, zoom and reflow.

1.1.1 · 1.3.1 · 1.4.3 · 1.4.11
OOperable

Keyboard, no trap, logical order, visible focus, label in name, target size.

2.1.1 · 2.4.7 · 2.5.8
UUnderstandable

Visible labels and hints, errors in words and linked to the field.

3.3.1 · 3.3.2
RRobust

Name, role and state read correctly; results announced without moving focus.

4.1.2 · 4.1.3

Every state × light and dark × keyboard, screen reader, 200%, 320 px = one accessibility contract

The WCAG 2.2 criteria a component can meet on its own, grouped by the four principles and tested in every state.

Use it when

  • A new component is ready for review and you need a pass or fail before release.
  • A product team asks whether "the design system is accessible", and you want an answer per component, not a promise.
  • An audit finds the same issue on many screens, and you suspect it comes from one component.

How to use it

  1. Start from native HTML and its pattern. Check that the component renders the real element (<button>, <input>, <dialog>) and, for widgets, follows its WAI-ARIA Authoring Practices pattern. Note the pattern's link. Output: the element, the pattern, or "no pattern, HTML covers it".
  2. Go through the criteria that apply. Use the list in the template, one line per criterion. Skip the ones that can't apply to this component and say why (a Divider has no keyboard behaviour). Output: a list of criteria, each marked applies or not.
  3. Test each one in every state. Default, hover, focus, pressed, disabled, loading, error, in light and dark mode. Contrast and focus visibility often pass at rest and fail in one state. Output: pass, fail or "product owns" per criterion.
  4. Test with real tools, not only a scanner. Keyboard only, a screen reader (VoiceOver on Mac and iOS, NVDA on Windows), 200% zoom and a 320 px wide viewport. Automated checks catch some issues; keyboard and screen reader catch the rest. Output: notes on what you heard and where focus went.
  5. Split guarantee from responsibility. For each criterion, decide whether the component guarantees it or the product has to do something (write a good label, not hide the focus ring under a sticky header). Output: the two-column accessibility contract for the doc page.
  6. Make failures release blockers. A bug in a component ships to every screen that uses it. Log it with the criterion number and fix it before the next minor. Output: an issue per failure, linked from the doc page.

Worked example

Harbour's Text field, before the 3.2 release at Tidewater:

Criterion What we checked Result
1.3.1 Info and Relationships Label linked with for; hint and error linked with aria-describedby Component guarantees
1.4.3 Contrast (Minimum) Label, value, hint and error text at 4.5:1 in both modes Pass, except hint in dark mode (fixed)
1.4.11 Non-text Contrast Field border and focus ring at 3:1 against the background Pass
2.4.7 Focus Visible Focus ring in every state, including error Pass
2.4.11 Focus Not Obscured (Minimum) A focused field isn't hidden by the sticky booking bar Product owns
3.3.1 Error Identification Error in words, with aria-invalid="true" Component guarantees
3.3.2 Labels or Instructions Visible label; placeholder never used as label Component guarantees, if the product passes a label
4.1.2 Name, Role, Value Screen reader reads "Departure port, edit text, required" Pass

One failure (hint contrast in dark mode) became a patch. One criterion moved to the doc page as the product's job.

Watch out for

  • Testing the default state only. Disabled, error and dark mode are where contrast fails.
  • Trusting the scanner. Automated tools don't know whether focus moved into a dialog or whether the error is read with the field.
  • Claiming the whole page. Criteria like 2.4.1 Bypass Blocks or 1.3.2 Meaningful Sequence depend on the page. Put them in "product owns", don't mark them as passed.
  • ARIA that promises behaviour. A role like menu or tab tells a screen reader to expect arrow keys. If you didn't build them, remove the role.

Template

Copy this into the component's review issue and fill one line per criterion.

Component: ...          Version: ...
Element / APG pattern: ...
States tested: default, hover, focus, pressed, disabled, loading, error | light, dark

Perceivable
[ ] 1.1.1 Non-text Content: icons and images have a text alternative or are hidden
[ ] 1.3.1 Info and Relationships: label, hint, error, headings exposed in code
[ ] 1.4.1 Use of Color: state is not shown by colour alone
[ ] 1.4.3 Contrast (Minimum): text 4.5:1 (large text 3:1) in every state
[ ] 1.4.4 Resize Text: works at 200%
[ ] 1.4.10 Reflow: works at 320 px wide without sideways scrolling
[ ] 1.4.11 Non-text Contrast: borders, icons, focus ring 3:1
Operable
[ ] 2.1.1 Keyboard: everything works with the keyboard
[ ] 2.1.2 No Keyboard Trap: focus can always leave (Escape for dialogs)
[ ] 2.4.3 Focus Order: Tab order follows the reading order
[ ] 2.4.7 Focus Visible: focus ring in every state
[ ] 2.4.11 Focus Not Obscured (Minimum): product owns, note any sticky parts
[ ] 2.5.3 Label in Name: the visible label is part of the accessible name
[ ] 2.5.7 Dragging Movements: anything draggable also works without dragging
[ ] 2.5.8 Target Size (Minimum): 24 x 24 px or enough spacing
Understandable
[ ] 3.3.1 Error Identification: error in words, linked to the field
[ ] 3.3.2 Labels or Instructions: visible label, hint where needed
Robust
[ ] 4.1.2 Name, Role, Value: screen reader reads name, role and state
[ ] 4.1.3 Status Messages: results announced without moving focus

Tested with: keyboard / VoiceOver / NVDA / 200% / 320 px
The component guarantees: ...
The product owns: ...
Source
Web Content Accessibility Guidelines (WCAG) 2.2, W3C Recommendation (October 2023). WAI-ARIA Authoring Practices Guide (W3C WAI)
Where to find it
Design Systems in Practice: Accessible components › The accessibility contract

"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close