accessibility-audit

Accessibility Audit

Scope

Evaluates keyboard accessibility, screen-reader semantics, color contrast, and common WCAG 2.1 AA rules for web and native UIs. Optional — include in a plan when a UI surface is created or modified AND accessibility compliance is required.

Audit Dimensions

Automated (axe-core)

npx @axe-core/cli http://localhost:3000/target-route \
  --save e2e-evidence/vgN-axe.json \
  --tags wcag2a,wcag2aa

PASS criterion: [.violations[] | select(.impact=="serious" or .impact=="critical")] | length == 0

Keyboard navigation

• Tab through the page — focus visible at every stop?
• All interactive elements reachable without a mouse?
• Focus order matches visual order?
• Skip-to-content link present and functional?

Screen-reader semantics

• Every form field has an associated <label> or aria-label
• Every icon-only button has aria-label
• Heading hierarchy is sequential (no jumps from h1 to h4)
• Landmarks present: <header>, <main>, <nav>, <footer>
• Live regions use aria-live where dynamic updates occur

Color contrast

• Text meets 4.5:1 for normal, 3:1 for large (≥18pt or ≥14pt bold)
• UI controls meet 3:1 against adjacent colors
• Focus indicators visible (≥3:1 contrast against background)

Evidence Capture

Dimension	Tool	File
axe-core	@axe-core/cli	e2e-evidence/vgN-axe.json
Keyboard	Manual sequence via agent-browser	e2e-evidence/vgN-keyboard.md (text trace + screenshots per stop)
Screen reader	VoiceOver / NVDA announcement transcript	e2e-evidence/vgN-sr-transcript.md
Contrast	Browser DevTools or axe-core output (included)	e2e-evidence/vgN-axe.json

Gate Integration

Accessibility gates use web-validation as the base platform skill with this additional PASS rule:

<validation_gate id="VG-N" blocking="true" platform="web"
                 protocol="functional-validation"
                 platform_skill="web-validation"
                 verdict_by="gate-validation-discipline">
  ...
  <pass_criteria>
    [normal UI criteria]
    AND axe violations with impact in (serious, critical) == 0
    AND every interactive element reachable via Tab (see vgN-keyboard.md)
    AND heading hierarchy sequential (no h1 → h4 skips)
  </pass_criteria>
  <review>
    jq -e '[.violations[] | select(.impact=="serious" or .impact=="critical")] | length == 0' e2e-evidence/vgN-axe.json
    Read tool: vgN-keyboard.md — verify Tab trace reaches every control
  </review>
</validation_gate>

Common Failures

Finding	Typical cause	Fix
color-contrast violation	Gray-on-white text	Darken text or use bolder weight
label missing	Input without <label> or aria-label	Add label; use htmlFor
button-name missing	Icon button with no text	Add aria-label or sr-only text
heading-order	h1 followed by h4	Fix heading levels to be sequential
no-skip-link	Missing "Skip to main content"	Add skip link as first focusable element

Rules

1. Run axe-core in every gate that touches UI
2. Walk Tab order manually — axe cannot verify focus flow
3. Verify screen-reader announcements on critical flows (login, form submit)
4. Zero-tolerance on serious + critical violations
5. Document intentional AA-non-compliance in <open_questions> with rationale

Security Policy

Axe reports may include source HTML snippets. Treat as evidence; store in gitignored e2e-evidence/.