accessibility-audit

Audit for the users who hit the wall, not for the checklist: someone on a keyboard who cannot reach the button, a screen-reader user who hears "button button", a low-vision user who cannot read grey-on-white hints. Automated checks catch at most a third of real barriers; the rest come from reading the code and walking the flows. Prefer fixing semantics over adding ARIA; the first rule of ARIA is not to use it when native HTML already does the job.

Step 1: Scope and method

Identify what is being audited (components in a diff, a page, a whole flow) and pick the method:

• Running app available: audit in the browser. Use the webapp-testing skill's Playwright setup and inject axe-core for the automated pass, then do the manual keyboard walk below.
• Code only: review the markup and interaction logic directly. State that contrast and reading-order findings are provisional until seen rendered.

For the automated pass with Playwright:

await page.goto(url);
await page.addScriptTag({ url: "https://cdn.jsdelivr.net/npm/axe-core@4/axe.min.js" });
const results = await page.evaluate(() => axe.run());
// results.violations: id, impact, nodes[].html, nodes[].target

Treat axe output as a floor, not the audit.

Step 2: The manual pass

Work through these in order of user impact:

Keyboard

• Every interactive element reachable with Tab, operable with Enter/Space, in an order that follows the visual flow. No focus traps except intentional ones (modals) that also release on Escape.
• Focus visible at every stop (WCAG 2.2 requires it not be fully obscured). No outline: none without a replacement.
• After actions that move context (opening a modal, deleting a list item, route change in a SPA): focus is placed deliberately, not dropped to <body>.

Semantics and names

• Native elements for native jobs: <button> not <div onClick>, <a href> for navigation, <label for> on every form control. A clickable div needs role, tabindex, and key handlers to equal a button; flag it and recommend the element instead.
• Every control has an accessible name that matches its visible label; icon-only buttons have aria-label. Images: informative ones have real alt, decorative ones have alt="".
• Headings form an outline (one h1, no skipped levels used for styling). Landmarks (main, nav) present once each.