Make the whole task accessible
Build and verify semantics, keyboard use, focus, contrast, reflow, and meaningful feedback.
Why this matters
Picture someone completing your form with only a keyboard, or with a screen reader reading each step aloud. Can they find the task, understand it, do it, and recover if it fails? That is the test.
Use your project's applicable standard. This guide uses WCAG 2.2 Level AA — the shared web accessibility rules, middle conformance level — as its baseline. A checklist or automated scan alone does not prove you pass.
What to understand
Use headings for structure, links to go somewhere, buttons to do something, and labeled inputs to collect answers. A styled div gives you none of that built-in behavior.
Add ARIA — extra attributes that describe states and relationships to assistive tech — only when native HTML cannot say it. ARIA does not add keyboard behavior for you.
For tabs, menus, comboboxes, and dialogs, follow the established keyboard pattern. Ask your agent: "which ARIA Authoring Practices Guide pattern fits this widget?"
Watch for
- A styled
divstanding in for a link, button, or labeled input. - ARIA added without the keyboard behavior it doesn't provide.
- Focus moved on routine updates instead of kept stable.
- A sticky header covering visible focus, or focus fully hidden.
- Status carried by color alone with no text or shape to back it.
- Dragging with no alternative, or paste and password managers blocked without a justified alternative.
Strong default
Begin with native semantics and the established APG keyboard pattern. Keep focus visible and logical, put error text next to the field and connect it in code, announce routine confirmations politely and reserve assertive announcements for urgent problems.
When this doesn't apply
Automation doesn't prove the task works, and a checklist doesn't prove you pass. 44 × 44 CSS pixels is a comfortable touch target, not the AA minimum. Criterion 2.4.11 is about focus not being fully hidden; Focus Appearance is 2.4.13 at AAA. Check the WCAG 2.2 criteria and target-size explanation.
In practice
Tab through the flow yourself. Does focus order — the path your keyboard highlight follows — feel logical? Can you always see it? Does a sticky header cover it? Can you skip past repeated navigation?
For a modal, focus moves inside on open, stays inside while open, and lands somewhere sensible on close. If its trigger is gone, pick a logical spot. Do not move focus on routine updates.
Put error text next to the field, connect it in code, and announce important outcomes. A polite status region fits routine confirmations. Save assertive announcements for urgent problems.
| Check | WCAG 2.2 AA reference point |
|---|---|
| Text contrast | At least 4.5:1 for ordinary text; 3:1 for large text as defined. |
| Meaningful non-text contrast | At least 3:1 for needed controls and states against nearby colors, with exceptions. |
| Pointer target size | At least 24 × 24 CSS pixels, or a qualifying spacing or equivalent-control exception. |
| Text enlargement | Text at 200% loses no content or function. |
| Reflow | Vertically scrolling pages work at 320 CSS pixels wide, except content needing two dimensions. |
Support text-spacing changes, themes, reduced motion, and forced colors where they apply. Do not rely on color alone for status. Offer an alternative to dragging. Do not block password managers or pasting without a justified accessible alternative.
Give images an alternative that matches their job. Decorative images can be empty. Instructional diagrams need the same meaning in nearby text. If you teach with audio or video, add captions and transcripts.
Automation catches some contrast, naming, and structure issues. It cannot judge the whole task or prove nothing blocks someone. Replay one real task with a keyboard and a relevant screen reader, then recheck after fixes.
Note the route, browser, input method, size, state, and what you saw. Say what you did not check.
Verify
One real task replayed with keyboard and a relevant screen reader, at 200% text and 320 CSS pixels reflow. Route, browser, input method, size, state, and what you saw noted — plus what you did not check.
Related skills
Ask your agent to run $craft for interface review and $states for recovery behavior.
Last updated on