accessibility-audit

name	accessibility-audit
description	Run a WCAG accessibility audit on UI changes at Stage 6b. Uses axe-core, pa11y, or Lighthouse to check affected pages and components. Produces pipeline/accessibility-report.md and writes the stage-06b gate. Use when a change touched frontend UI. Skip (with audit_skipped_reason) for backend-only or doc-only changes.

Accessibility audit

Use this skill at Stage 6b (after QA) when the change touched UI. Audits the affected pages/components for WCAG violations using axe-core, pa11y, or Lighthouse. Produces pipeline/accessibility-report.md and writes pipeline/gates/stage-06b.json.

When to use

• Frontend changes shipped at Stage 4 (new component, modified flow, redesigned page).
• Updates to forms, inputs, dialogs, navigation, or anything keyboard/screen-reader-relevant.
• New routes/pages added to the app.

When to skip (with audit_skipped_reason set)

• Backend-only changes (no UI surface).
• Doc-only changes.
• Internal tools with no public/customer surface AND no a11y commitment in the brief.

Procedure

1. Identify what to audit

Read pipeline/brief.md and pipeline/design-spec.md for the scope. Cross-reference with the Stage 4 PR summaries (pipeline/pr-frontend.md) to find:

• Specific routes / page URLs.
• Specific React/Vue/Svelte components.
• Any flows the brief flagged as keyboard-only or screen-reader-critical.

If the change has no UI surface, write the gate with audit_skipped_reason: "<reason>", status: "PASS", all violations zero, and move on.

2. Pick a method

Tool	Best for	Output shape
axe-core (via @axe-core/cli or programmatic)	Most thorough; integrates with Playwright/Cypress	JSON with violations grouped by impact
pa11y	Quick CLI sweep of URLs	HTML/JSON report per page
Lighthouse (a11y audit)	Holistic page score (covers perf + a11y)	JSON with categories.accessibility.audits
Manual (screen reader walkthrough)	Custom interactions Playwright/cypress-axe miss	Notes in the report

In order of recommendation: axe-core programmatic (deepest) → Lighthouse CI (CI-friendly) → pa11y (simplest standalone) → manual (only when automated tools can't reach the flow).

3. Run the audit

axe-core via @axe-core/cli:

npx @axe-core/cli https://localhost:3000/account/notifications \
  --tags wcag2a,wcag2aa --save axe-report.json

pa11y:

pa11y --standard WCAG2AA https://localhost:3000/account/notifications \
  --reporter json > pa11y-report.json

Lighthouse:

npx lighthouse https://localhost:3000/account/notifications \
  --only-categories=accessibility --output=json > lh.json

If the app has a Storybook, audit there first — covers components in isolation including states (loading/error/empty) that are easy to miss in route-level audits.

4. Triage the findings

Group by impact:

• Critical: breaks access entirely (missing alt text on actionable images, form inputs with no label, keyboard traps).
• Serious: severely impairs access (color-contrast violations, missing ARIA roles on custom controls, focus order broken).
• Moderate: impairs but workarounds exist (low-contrast borders, decorative icons not hidden from screen readers).
• Minor: friction (duplicate IDs, redundant ARIA attributes).

Critical and serious findings must be fixed before sign-off. Push back to the frontend dev as a FAIL with the specific finding listed in blockers[].

Moderate and minor can ship — record as WARN in the gate so they're tracked for follow-up.

5. Write the report and gate

pipeline/accessibility-report.md:

# Accessibility Audit — <feature title>

## Audit method: axe-core (via @axe-core/cli)
## WCAG level: AA

## Components/routes audited
- /account/notifications
- /account/notifications/sms-verify
- <NotificationToggle> (Storybook)

## Findings

### Critical (0)
None.

### Serious (1)
- **Color contrast** on `<NotificationToggle>` off-state (3.8:1, requires 4.5:1)
  - Fix: bump off-state border color from #aaa to #767676.

### Moderate (1)
- **Form label association** on the phone-number input — implicit label via wrapping `<label>` works but explicit `for` is recommended.

### Minor (0)
None.

## Reproducer
Raw findings: `<path or URL to axe-report.json>`

pipeline/gates/stage-06b.json:

{
  "stage": "stage-06b",
  "workstream": "qa",
  "status": "FAIL",
  "track": "<track>",
  "timestamp": "<ISO-8601>",
  "blockers": ["Color contrast violation on <NotificationToggle> off-state"],
  "warnings": [],
  "audit_method": "axe-core",
  "wcag_level": "AA",
  "violations": { "critical": 0, "serious": 1, "moderate": 1, "minor": 0 },
  "components_audited": ["/account/notifications", "<NotificationToggle>"],
  "audit_skipped_reason": null,
  "wcag_findings_url": "pipeline/axe-report.json"
}

6. PASS / WARN / FAIL decision

Critical	Serious	Moderate	Minor	Status
0	0	0	0	PASS
0	0	≥1	≥0	WARN (or PASS — your call; record in warnings[])
≥1	*	*	*	FAIL
*	≥1	*	*	FAIL

When status is FAIL, name the specific frontend dev who needs to fix in assigned_retry_to if your project tracks that.

Gotchas

• Storybook in isolation passes but the route fails. Components-in-isolation don't always carry the right ARIA context. Always audit BOTH the component and the route that contains it.
• Color-contrast checks need real colors. Computed CSS in tests may differ from production (different theme, dynamic states). If you're auditing component snapshots, use Playwright with a real browser, not jsdom.
• Manual audits miss state. Hover, focus, disabled, loading, and error states all have a11y requirements. Walk through each.
• A "PASS" doesn't mean "accessible." It means "no automated violations." Real accessibility requires user testing with assistive tech users — out of scope here, but flag in the report if the feature warrants it.