Accessibility Auditor

When to use

Use when the user asks for an accessibility audit, WCAG compliance check, an a11y review of a component, page, or PR, or reports that assistive-technology users are hitting problems. Also use during pre-launch reviews of user-facing UI when accessibility is in scope.

Default target is WCAG 2.2 Level AA unless the user names another standard. Section 508 and EN 301 549 both map closely to WCAG AA, so the same procedure applies — note the mapping in the report.

Inputs to gather

• Scope: whole app, specific routes, or a component library. Get concrete URLs or file paths.
• Tech stack: framework, component library, CSS approach. Fixes must be idiomatic to the codebase.
• Whether a running dev/staging URL exists for runtime scanning, or whether this is code-only analysis.
• Brand color constraints (affects contrast remediation options).
• Known assistive-tech targets and any prior audit to diff against.

Procedure

1. If a URL is available, run automated scanners first and treat results as a floor, not the audit:
   • npx @axe-core/cli <url>
   • npx pa11y <url> --standard WCAG2AA
   • npx lighthouse <url> --only-categories=accessibility
   • Automated tools catch roughly 30-40% of real-world issues; the manual passes below find the rest.
2. Static code pass. Grep for high-yield patterns:
   • <img without alt= (missing attribute, not empty value, is the violation).
   • Click handlers on div/span instead of button; <button> inside forms missing type (defaults to submit).
   • tabindex greater than 0 (breaks focus order); outline: none or outline: 0 with no replacement :focus-visible style.
   • aria-label on non-interactive elements; redundant roles on native elements; aria-hidden="true" on focusable elements.
   • State attributes (aria-expanded, aria-selected, aria-checked) missing from custom disclosure, tab, and toggle widgets.
   • Inputs without programmatically associated labels; placeholder used as the only label.
   • Heading-level skips, multiple h1, missing main/nav landmarks, missing lang on html.
3. Keyboard pass on the primary user flow. Tab through the page and verify:
   • Visible focus indicator on every interactive element (2.4.7).
   • Focus never fully hidden behind sticky headers or overlays (2.4.11, new in 2.2).
   • No keyboard traps; a skip link exists and works.
   • Focus moves into opened dialogs, Escape closes them, and focus returns to the trigger on close.
4. Contrast pass. Compute ratios, do not eyeball:
   • 4.5:1 for normal text; 3:1 for large text (24px+, or 18.66px+ bold).
   • 3:1 for UI component boundaries and meaningful graphics (1.4.11).
   • Placeholder text is NOT exempt; disabled controls are.
   • Check hover, focus, error, and selected states, not just resting states.
5. WCAG 2.2-specific checks that older tooling misses:
   • Pointer targets at least 24x24 CSS px or adequately spaced (2.5.8).
   • Drag operations have a single-pointer alternative (2.5.7).
   • Help mechanisms appear in a consistent location across pages (3.2.6).
   • Previously entered data is not re-requested in the same flow (3.3.7).
   • Login does not require a cognitive function test — transcribing a code with no paste-enabled alternative or passkey option fails 3.3.8.
6. Screen-reader semantics review:
   • Accessible names compute correctly and include the visible label text (2.5.3).
   • Async updates announce via a pre-existing aria-live="polite" region.
   • Form errors are linked with aria-describedby and announced on submit.
   • Motion and autoplaying animation respect prefers-reduced-motion.
7. Triage every finding by user impact, not tool severity: Blocker (an AT user cannot complete the task), Serious (major barrier with a workaround), Moderate, Minor. Map each finding to its WCAG success criterion number and level.
8. Write the fix for each finding as an exact code change in the project's idiom. Decision point: if the violation originates inside a third-party component library, do not fork it — document the upstream issue and provide a wrapper or configuration mitigation instead.

Output format

### Summary
Counts by severity, the top 3 systemic themes, one-line overall risk statement.

### Findings (ordered by severity)
[BLOCKER|SERIOUS|MODERATE|MINOR] Title — WCAG <SC number> (Level A/AA)
- Location: file path, selector, or URL
- Affected users: who is blocked and how
- Evidence: what was observed (tool output, computed ratio, keyboard behavior)
- Fix: exact code diff or snippet
- Verify: the specific re-test that proves it is resolved

### Not verified
Items that require a real screen reader or real-device pass, listed explicitly.

Quality checklist

• Every finding cites a specific WCAG 2.2 success criterion and level.
• Every fix is a concrete code change, never "consider improving".
• Contrast values are computed numbers included in the finding, with the colors that produced them.
• One systemic root cause equals one finding with an instance count, not N duplicate findings.
• The keyboard path for the primary flow is described step by step.
• Fixes were checked against the framework in use (no raw-DOM patches for a component-based codebase).
• Anything not actually tested (e.g. VoiceOver behavior) is listed under Not verified rather than silently assumed.

Common pitfalls

• Reaching for aria-label and role to patch everything. The first rule of ARIA: prefer native elements and visible text; ARIA changes the accessibility tree, not behavior.
• role="button" on a div without also adding tabindex="0" and Enter/Space key handling — the role alone fixes nothing.
• Flagging decorative images for empty alt. alt="" is correct for decoration; a MISSING alt attribute is the violation.
• Counting axe "incomplete/needs review" results as violations without manually verifying them — false positives destroy report credibility.
• Missing visual-order violations: CSS order, flex-direction: row-reverse, or grid placement that diverges from DOM order breaks 2.4.3 even though every scanner passes it.
• Adding an aria-live region in the same render that inserts the message — the region must already exist in the DOM before its content changes, or nothing is announced.
• Fixing contrast by darkening text on one component when the color comes from a shared design token — patch the token, then re-scan everything that uses it.
• Auditing only default states. Error states, loading states, empty states, and open overlays hide most contrast and focus bugs.