Accessibility Auditor

Audit for the people affected, not for a scanner score. Automated tools catch roughly a third of real barriers.

When to use

Component and page review, remediation planning, VPAT/compliance preparation, design-system checks, EAA/Section 508 questions.

Do not use for: native mobile a11y APIs (different criteria) or PDF remediation.

Workflow

1. Run the automated pass first

python3 scripts/a11y_lint.py page.html --level AA --format md

It catches missing alt text, unlabelled controls, heading skips, duplicate ids, missing lang, tabindex > 0, invalid ARIA and low-contrast inline styles. Everything it reports is a real defect; everything it misses may still be one.

2. Semantics — the foundation

Most a11y bugs are a <div> doing a real element's job.

Landmarks: one <main>, plus <header>, <nav>, <footer>, <aside>. Label duplicates: <nav aria-label="Breadcrumb">. Headings form an outline — exactly one <h1>, never skip a level for styling.

First rule of ARIA: don't use ARIA. A native element beats role + tabindex + key handlers every time. Bad ARIA is worse than none.

3. Keyboard operability (WCAG 2.1.1, 2.4.3, 2.4.7, 2.4.11)

Test with the mouse unplugged. Tab through the whole page.

• Everything interactive is reachable and activatable by keyboard.
• Focus order matches visual order. Never tabindex greater than 0.
• Focus indicator is always visible: minimum 3:1 against the adjacent colour, at least 2 px thick. Never outline: none without a replacement.
• Focus is never obscured by a sticky header or cookie banner (2.4.11, new in 2.2).
• No keyboard trap: you can always Tab and Shift+Tab out.
• A "Skip to main content" link is the first focusable element.
• Modals: move focus in on open, trap it inside, close on Escape, return focus to the trigger on close, and mark background content inert.
• Menus/comboboxes: arrow keys move within, Tab moves out — follow the ARIA Authoring Practices pattern for the widget you are building.

4. Text alternatives and media

Never start alt text with "image of". Never leave alt off — a missing attribute makes screen readers read the filename.

5. Forms (1.3.1, 3.3.1–3.3.4)

• Every input has a programmatically associated <label for>. Placeholder is not a label — it disappears on input and usually fails contrast.
• Group related controls with <fieldset> + <legend>.
• Errors: identify the field in text, describe how to fix it, associate via aria-describedby, and announce with a live region. Never colour alone.
• Mark invalid fields with aria-invalid="true".
• Use correct type and autocomplete tokens (1.3.5).
• Required fields marked in text or required, not by an unexplained asterisk.
• Do not disable the submit button until valid — users get no feedback why.

6. Colour, contrast, motion

7. Dynamic content

Announce async changes with a live region: aria-live="polite" for status, "assertive" only for errors that must interrupt. The container must exist in the DOM before the content is injected. Route changes in SPAs must move focus to the new page heading and update the document title — otherwise screen-reader users have no idea anything happened.

8. Report

Sort by severity: Blocker (a user group cannot complete the task) → Serious → Moderate → Minor. Each finding: criterion (number + name), location, who is affected and how, current code, fixed code, effort.

Worked example

<div class="btn" onclick="submitForm()">
  <img src="check.svg"> Submit
</div>
<span style="color:#e74c3c">Please fix the errors above</span>

A-01 · Blocker · 2.1.1 Keyboard — a <div> is not focusable or activatable by keyboard. Keyboard and screen-reader users cannot submit the form at all.

A-02 · Serious · 1.1.1 Non-text Content — the icon has no alt; screen readers announce "check.svg".

A-03 · Serious · 4.1.3 Status Messages — the error text is injected without a live region and is never announced.

A-04 · Moderate · 1.4.1 Use of Colour — the error is conveyed by red text alone, with 3.1:1 contrast on white (fails 1.4.3).

Fixed

<button type="submit" class="btn">
  <img src="check.svg" alt="" aria-hidden="true"> Submit
</button>

<div role="alert" class="form-error">
  <svg aria-hidden="true" focusable="false"><!-- warning icon --></svg>
  <strong>Error:</strong> Please fix the 2 errors listed above.
</div>

.form-error uses #c0392b on #fff (5.9:1), carries an icon and the word "Error", and role="alert" announces it on insertion.

Quality checklist

• Every finding cites a numbered WCAG 2.2 success criterion
• Impact described in terms of a real user, not "fails the scanner"
• Full keyboard walkthrough performed, not just the automated scan
• Focus visibility, order and trapping verified
• Native elements preferred over ARIA in every fix
• Contrast ratios computed, not eyeballed
• Fixed code snippet supplied for each finding
• Findings prioritised by severity, with an effort estimate
• Screen-reader testing recommended (NVDA/JAWS on Windows, VoiceOver on macOS/iOS)