Accessibility basics

Apply to any new or changed screen, panel, dialog, form or control, and when reviewing a screen from real screenshots. Pair it with ui-review-checklist.

Ground rules

• Fix problems in your own components or theme file; do not patch a vendored design system in place.
• Colours come only from design tokens. If a token pair fails contrast, propose a different existing token, not a new hardcoded colour.
• Check light and dark, and phone width (about 375 px).

Checklist

1. Contrast. Body text about 4.5:1 against its background, large text and meaningful icons about 3:1. Measure in both themes, including muted text, placeholders, disabled-looking text and text on coloured badges.
2. Never colour alone. A status (error, done, waiting) also shows an icon, a word or a shape. Test by imagining the screen in greyscale.
3. Keyboard. Every action is reachable with Tab, in an order that matches the visual order. Enter or Space activates buttons; Escape closes panels and dialogs.
4. Focus. A visible focus ring on every interactive element, in both themes, never removed without a replacement. Opening a panel moves focus inside it; closing returns focus to the control that opened it. Dialogs keep focus inside while open.
5. Real controls. button for actions, a for navigation, input/select/textarea for data. A clickable div is a defect unless it has a role, tabindex and key handling, and even then prefer the real element.
6. Names. Every icon-only button has an accessible name (aria-label or visible text). Every input has a label tied to it, not only a placeholder. Meaningful images have alt text; decorative ones are hidden from assistive tech.
7. Structure. One h1 per screen, headings in order, lists as lists, landmarks (header, nav, main) present. The page title says where the user is ("Billing · Settings").
8. Touch targets. Tappable areas at least 44 by 44 px on the phone layout, with space between neighbours so a thumb does not hit two.
9. Zoom and reflow. At 375 px and at 200% zoom nothing is cut off, overlaps, or needs sideways scrolling (wide tables may scroll inside their own box). Text sizes are relative, not fixed tiny values.
10. Motion. Respect prefers-reduced-motion: no essential information only in animation, no auto-moving content that cannot be paused.
11. Live changes. Toasts, "saved" messages and errors that appear without a focus change are announced (role="status" for polite, role="alert" for urgent). Do not announce every background refresh.
12. Copy. Short, concrete, one action per button. Links and buttons say what happens ("Download invoice"), not "Click here".

Focus check: name the control that holds focus

In the focus check, first name which control holds focus (by its label or visible text), then say whether a visible ring is on THAT control. Reviewers often report a missing ring on the wrong element, for example on the email field when focus is actually on the "Show password" button beside it.

How to test

• Tab through the screen without a mouse, in both themes.
• Screenshot light and dark at desktop and 375 px (a headless browser works) on a local or staging build.
• Read the DOM of controls you doubt for role, name and state.
• Use test data only; keep real customer data, emails and keys out of screenshots.

How to report

One finding per problem, ranked by what it costs the user. Each has:

• Where: screen, element by its visible text, file.
• What: what is wrong, with a screenshot or measured value (for example "3.1:1 in dark").
• Why it matters: who is blocked (keyboard user, low vision, phone thumb) and what they cannot do.
• Fix: the smallest change, naming the existing token or component to use.

End with what you checked and what you could not check. Agreed fixes become tasks with acceptance criteria that cover both themes and phone width.