Accessibility

Accessibility in practice

Most barriers are created by replacing something the platform already made accessible. The cheapest accessible component is the one you did not rebuild.

When this fires

While building or changing any interactive UI, and when turning an audit finding into a fix. It does not fire to prove a screen is accessible — that is accessibility-verification, and it needs a keyboard and a screen reader, not a code read.

Procedure

1. Use the native element first. button, a[href], input, label, select, details,

dialog, table. Each arrives with a role, keyboard behaviour, focus handling and state reporting you would otherwise have to write and maintain. A div with a click handler has none of it. If the project already has an accessible component for this, reuse that instead.

1. Get the structure right before the styling. One h1 per view, headings in descending order

with none skipped, real landmarks (header, nav, main, footer), lists marked up as lists, a unique page title per route. Screen reader users navigate by these; they are the table of contents, not decoration.

1. Give every control a name that matches its visible label. Visible text is the name where

possible; label[for] for inputs; an aria-label only for controls with no visible text, such as an icon button. When there is visible text, the accessible name must contain it — a button reading "Save" named "Submit form" breaks voice control.

1. Walk the keyboard path yourself. Tab reaches everything interactive, in DOM order; Enter and

Space operate it; Escape closes what opened; focus never gets stuck. Do not use positive tabindex — fix the DOM order instead. Composite widgets (menus, tabs, grids) take one Tab stop and move internally with arrow keys.

1. Keep focus visible and unobscured. Never delete an outline without shipping a replacement.

Style :focus-visible so it survives sticky headers, overflow clipping and dark backgrounds, and check that a sticky bar or cookie banner does not cover the focused element.

1. Move focus deliberately when the view changes. Opening a dialog moves focus into it and traps

it there; closing returns focus to the element that opened it; a client-side route change moves focus to the new heading or main region. Focus left behind on a removed node goes to body, and the user loses their place silently.

1. Choose colours that carry the contrast. 4.5:1 for body text, 3:1 for large text and for the

boundaries of controls, focus rings and meaningful graphics. Check hover, active, selected and error states too, and text sitting over images or gradients. Never let colour alone carry meaning — pair it with text, an icon or a pattern.

1. Make forms explain themselves programmatically. Associate the error with its field

(aria-describedby), mark the field invalid (aria-invalid), and write error text that says what is wrong and how to fix it. Use autocomplete tokens on personal-data fields. Do not make people re-enter information they already gave you in the same flow, and do not block paste in password or one-time-code fields.

1. Announce what changes without a page load. A status message needs a live region that already

exists in the DOM before it updates — aria-live="polite" for status, role="alert" for errors. Announce once, keep it short, and do not wire a live region to something that updates constantly.

1. Respect the user's settings. Honour prefers-reduced-motion by removing movement, not by

speeding it up. Respect prefers-color-scheme and prefers-reduced-transparency where the design uses them. Never disable zoom in the viewport meta tag.

1. Cover the WCAG 2.2 additions that bite hardest. Any drag interaction needs a single-pointer

alternative (click or button). Interactive targets are at least 24×24 CSS px unless spaced or inline in a sentence. Help links stay in the same relative place across pages.

1. Add ARIA last, and as little as possible. No ARIA beats wrong ARIA: an incorrect role

silently overrides the real one. Never put aria-hidden on anything focusable, and never invent role/state combinations — copy an established pattern and keep its keyboard contract intact.

1. Stop and ask before changing shared surfaces. A contrast fix that alters a brand token, or a

markup change inside a shared design-system component, affects screens you are not looking at. Propose the change with the reason; do not push it through on your own authority.

Checklist

• [ ] Every interactive element is a native control or reuses an existing accessible component
• [ ] Heading order and landmarks make sense read alone, with no skipped levels
• [ ] Every control has a name, and it contains the visible label text
• [ ] Tab reaches everything, in a sensible order, with no trap and no positive tabindex
• [ ] Focus is always visible and never covered by sticky or overlaying chrome
• [ ] Dialog and route changes move focus, and closing returns it
• [ ] Text and control boundaries meet contrast in every state, including over imagery
• [ ] Errors are associated with their fields and readable without colour
• [ ] Dynamic messages land in a live region that existed beforehand
• [ ] Reduced motion honoured; zoom not disabled
• [ ] Drag interactions have a click alternative; targets are 24×24 CSS px or spaced
• [ ] ARIA added only where a native element could not do the job

Failure handling

• The component is a third-party widget you cannot change — say so, record the specific barrier,

and look for a documented accessible mode or a replacement. Do not paper over it with ARIA that describes behaviour the widget does not have.

• The fix needs a design decision (a token fails contrast, a layout has no room for a 24px

target) — name the conflict and the options, and let the design owner choose. Do not quietly ship a visual change to satisfy a checker.

• A pattern has no obvious accessible form — look up the established pattern for it rather than

inventing roles. If the project pins a component library, check that library's current accessibility API before assuming what it supports.

• A checker passes but the interaction still feels wrong — trust the interaction. Automated rules

cannot see whether a name is meaningful or an order is logical.

Evidence to report

Name the elements changed and why: which control became a button, which name was added, where focus now moves, which token changed and its measured ratio before and after. State plainly that these are implementation changes — they are unverified until someone drives the keyboard and a screen reader. Hand the claim to accessibility-verification; do not call it conformant here.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nahid-sparktales
• Source: nahid-sparktales/agent-dispatcher
• License: MIT

Install and usage instructions live in the source repository linked above.