A11Y Audit

zuvo:a11y-audit — WCAG 2.2 Accessibility Audit

Deep, compliance-focused accessibility audit across 10 weighted dimensions with WCAG 2.2 criterion mapping, legal risk assessment, and actionable fix generation. Every finding maps to a specific WCAG success criterion and severity level.

When to use: Before public launches, when targeting WCAG compliance, after ADA/EAA legal requirements surface, periodic accessibility health checks, when onboarding a codebase that must meet compliance standards, after adding interactive components or forms. Out of scope: Surface-level design consistency (zuvo:design-review), visual design quality (zuvo:ui-design-team), code quality (zuvo:code-audit), penetration testing (zuvo:pentest).

Argument Parsing

Parse $ARGUMENTS for these flags:

Mandatory File Loading

Read these files before any work begins. Print the checklist with status.

Stage 1 -- Before Phase 0 (STOP if any missing):

CORE FILES LOADED:
  1. ../../shared/includes/codesift-setup.md  -- [READ | MISSING -> STOP]
  2. ../../shared/includes/env-compat.md      -- [READ | MISSING -> STOP]

Stage 2 -- Before Phase 5 (report writing):

  3. ../../shared/includes/run-logger.md      -- [READ | MISSING -> STOP]
  4. ../../shared/includes/retrospective.md      -- [READ | MISSING -> STOP]
  5. ../../shared/includes/backlog-protocol.md -- [READ | MISSING -> degraded]

Stage 2 deferred to save upfront context.

Environment Compatibility

Read ../../shared/includes/env-compat.md for agent dispatch patterns, path resolution, and progress tracking across all supported platforms.

MANDATORY TOOL CALLS — A11y Audit Validity Gate

INVALID if any tool below is skipped. "DEFERRED", "N/A" NOT valid reasons.

Forbidden: same as above (skipped/N/A/codesift unavailable when deferred — REJECTED).

POSTAMBLE: report on disk → retro appended → ~/.zuvo/append-runlog exit 0. Every A-dim finding needs path/to/file.ext:LINE (verify-audit gate).

Mandatory-tools-acknowledgment: I will run get_file_tree + search_text + search_symbols + search_patterns + audit_scan + React tools (when React) for this a11y audit. Every A-dim finding will cite a `path/to/file.ext:LINE` resolving in the current tree.

Use the deterministic preload helper FIRST. Run ~/.zuvo/compute-preload a11y-audit "$PWD". Math gate enforced.

CodeSift Integration

Read ../../shared/includes/codesift-setup.md for the full initialization sequence.

a11y-audit CodeSift usage:

• search_text(repo, "aria-|role=", regex=true, file_pattern="*.tsx") -- ARIA attribute scan
• search_text(repo, "<h[1-6]", regex=true, file_pattern="*.tsx") -- heading inventory
• search_text(repo, "tabindex\|tabIndex", regex=true) -- tabindex usage
• search_text(repo, ":focus-visible\|:focus", regex=true, file_pattern="*.css") -- focus style scan
• search_text(repo, "prefers-reduced-motion", file_pattern="*.css") -- motion media query
• search_text(repo, "alt=", file_pattern="*.tsx") -- alt text coverage
• search_symbols(repo, "useReducedMotion|usePrefersReducedMotion", include_source=true) -- motion hook usage

Degraded Mode (CodeSift unavailable)

Dimensions (A1-A10)

A1: Semantic HTML (weight 10)

A2: Keyboard Navigation (weight 12, CRITICAL GATE)

A3: ARIA Patterns (weight 10)

A4: Color & Contrast (weight 10, CRITICAL GATE)

A5: Forms & Inputs (weight 10)

A6: Images & Media (weight 8)

A7: Responsive & Zoom (weight 6)

A8: Motion & Animation (weight 5)

A9: Reading & Content (weight 5)

A10: Legal Compliance Status (NOT scored — separate legal risk section)

A10 is a qualitative legal risk assessment, not a scored dimension. It does NOT contribute to the numerical score (to avoid double-counting A1-A9 results). It appears as a standalone section in the report.

Phase 0: Detection

1. Detect framework: React, Next.js, Vue, Nuxt, Svelte, SvelteKit, Astro, Angular, plain HTML
   • Check package.json dependencies, config files (next.config.*, astro.config.*, svelte.config.*, angular.json)
2. Detect component library: MUI, Chakra, Radix, Headless UI, shadcn, Mantine, Ant Design, none
   • Check package.json dependencies
3. Detect existing a11y tooling:
   • eslint-plugin-jsx-a11y in devDependencies
   • axe-core or @axe-core/* in devDependencies
   • pa11y in devDependencies or global
   • jest-axe or vitest-axe in devDependencies
   • Storybook a11y addon (@storybook/addon-a11y)
4. Detect existing a11y config:
   • .axerc or axe.config.js
   • .pa11y or .pa11yci
   • eslintrc with jsx-a11y rules
5. Estimate scope: Count pages/components for workload sizing

Output:

A11Y DETECTION
  Framework:   [name]
  Components:  [library or "custom"]
  A11y tools:  [list or "none detected"]
  A11y config: [list or "none"]
  Scope:       [N pages, N components]
  Standard:    WCAG 2.2 [AA|AAA]
  Legal focus:  [ADA Title II | EAA | Section 508 | N/A]

Phase 1: Static Code Analysis (A1-A9)

Scan templates, JSX/TSX, CSS, and config files against all dimension checks.

1.1 Batch Scans

Run grep/CodeSift scans across the codebase for:

1.2 eslint-plugin-jsx-a11y Integration

If eslint-plugin-jsx-a11y is detected:

1. Grep the ESLint config for disabled jsx-a11y/* rules — note each as an intentional exception
2. Run with project config: npx eslint --ext .jsx,.tsx [scope] — captures what the project considers violations
3. Run baseline scan: npx eslint --no-eslintrc --plugin jsx-a11y --rule '{...}' [scope] — captures ALL violations including intentionally suppressed ones
4. Diff the two runs — suppressions found in config but not in baseline are intentional exceptions. Report them as [SUPPRESSED] findings (user decided to allow this) vs [ACTIVE] findings (violations the project config also flags)

If not available: skip, rely on manual scan.

1.3 Per-Component Scoring

For each page/component in scope, evaluate A1-A9 checks:

### [file path]
Component type: [PAGE | FEATURE | SHARED]
| Dim | Score | Max | Evidence |
|-----|-------|-----|----------|
| A1  | [N]   | 10  | [summary] |
| A2  | [N]   | 12  | [summary] |
| A3  | [N]   | 10  | [summary] |
| A4  | [N]   | 10  | [summary] |
| A5  | [N]   | 10  | [summary] |
| A6  | [N]   | 8   | [summary] |
| A7  | [N]   | 6   | [summary] |
| A8  | [N]   | 5   | [summary] |
| A9  | [N]   | 5   | [summary] |
Critical gates: A2=[N]/12 A4=[N]/10 -- [PASS/FAIL]

Scoring per dimension: Each check within a dimension scores proportionally. Example: A1 has 5 checks, each worth 2 points (total 10). A check scores 0 (fail), 1 (partial), or full points (pass).

Dispatch follows ../../shared/includes/execution-policy.md through env-compat. Reuse existing authorization within that policy; session restrictions take precedence. Run each required gate and report its actual independence or an unmet requirement.

If >10 components: Split into batches of 5. Dispatch background agents where env-compat supports parallel dispatch.

Phase 2: Automated Testing

2.1 Browser-Based (if --live-url and browser MCP available)

If mcp-accessibility-scanner is available:

• scan_page(url) per route for axe-core violations
• scan_page_matrix(url, variants=["mobile", "forced-colors", "reduced-motion", "zoom-200%"]) for variant testing
• audit_keyboard(url) for tab order, focus visibility, keyboard traps

If chrome-devtools MCP is available but not accessibility-scanner:

• Navigate to pages via navigate_page
• Run evaluate_script with axe-core injection
• Take screenshots at multiple viewport sizes

axe-core results override static scan findings: Where automated tools provide definitive results, they take precedence over grep-based analysis.

2.2 pa11y Integration (if available)

If pa11y is available:

npx pa11y [url] --reporter json --standard WCAG2AA

Parse JSON output, map violations to A1-A10 dimensions.

2.3 Automated Coverage Note

Automated tools catch approximately 30-57% of WCAG issues. The following CANNOT be caught by automated tools and require manual verification:

• Meaningful alt text quality (automated can detect presence, not quality)
• Keyboard trap detection in complex widgets
• Logical reading order
• Content comprehension at different zoom levels
• Whether color alone conveys information (context-dependent)
• Focus management correctness in SPAs
• Screen reader announcement quality

Phase 3: Manual Checklist Verification

For each dimension, verify against WCAG 2.2 success criteria:

1. Map every finding to a specific WCAG criterion (e.g., "1.1.1 Non-text Content", "2.1.1 Keyboard")
2. Classify each check as:
   • PASS -- criterion satisfied with evidence
   • FAIL -- criterion violated with evidence
   • CANNOT DETERMINE -- requires manual verification (e.g., screen reader testing, cognitive assessment)
3. For CANNOT DETERMINE items, describe what manual test is needed

WCAG Level mapping:

• Level A (minimum): 1.1.1, 1.2.1, 1.3.1, 1.4.1, 2.1.1, 2.1.2, 2.2.2, 2.3.1, 2.4.1, 2.4.2, 2.4.3, 2.4.4, 3.1.1, 3.2.1, 3.3.1, 3.3.2, 4.1.2
• Level AA (standard target): Level A + 1.3.5, 1.4.3, 1.4.4, 1.4.10, 1.4.11, 2.4.7, 3.1.2, 3.2.3, 3.3.3, 4.1.3
• Level AAA (if --standard AAA): Level AA + 1.4.6 (7:1 contrast), 2.3.3, 2.4.9, 2.5.8, 3.1.5, 3.1.6

Phase 4: Fix Generation (if --fix or findings exist)

For each finding, generate a specific code fix:

### A11Y-[NNN]: [Title]
Dimension: A[N]
WCAG: [criterion number] [criterion name]
Severity: CRITICAL | HIGH | MEDIUM
Level: A | AA | AAA
File: [path:line]
Impact: [who is affected and how]

Before:
  [code snippet showing the violation]

After:
  [code snippet with the fix applied]

Notes: [implementation considerations]

Prioritization order:

1. Legal risk (CRITICAL findings in dimensions relevant to --legal standard)
2. User impact (keyboard/screen reader blockers > visual issues > enhancements)
3. Effort (quick wins first within same priority tier)

If --dry-run flag is set: report all fixes without applying. Show before/after code for each fix.

If --fix flag is set:

1. Create rollback tag: git tag a11y-fix-YYYY-MM-DD before applying any changes
2. Apply all CRITICAL and HIGH fixes automatically. MEDIUM fixes are reported but not auto-applied.
3. Run verification: check that fixes don't break existing tests
4. If tests fail after a fix: revert that specific fix, keep the tag for manual rollback

Scope guard: Fixes touch only accessibility attributes, ARIA properties, semantic elements, CSS focus/contrast styles, and meta tags. Fixes do NOT modify business logic, data fetching, or application state.

Phase 5: Report & Backlog

5.1 Read Stage 2 Files

Read deferred files:

  3. ../../shared/includes/run-logger.md      -- [READ | MISSING -> STOP]
  4. ../../shared/includes/retrospective.md      -- [READ | MISSING -> STOP]
  5. ../../shared/includes/backlog-protocol.md -- [READ | MISSING -> degraded]

5.2 Scoring

Per-dimension scoring: Each dimension has a max weight. Score = sum of check scores within dimension.

Overall score: (total earned / total possible) * 100 — A10 excluded from score (legal risk section only, max = 76 from A1-A9).

Critical gates (explicit pass thresholds):

• A2 (Keyboard Navigation) < 6/12 --> automatic FAIL regardless of overall score
• A4 (Color & Contrast) < 5/10 --> automatic FAIL regardless of overall score

Grade thresholds:

VERDICT mapping for run log — A → PASS, B → WARN, FAIL → FAIL; a failing critical gate forces FAIL at any score.

Two things this table used to get wrong. The bands were written 70-84 / >= 85, so a real 84.4% matched neither. And the verdict line said "PASS (A or B), WARN (B with critical gate borderline)", which both contradicted the field-resolution section below (there, 70-84% maps to WARN, not PASS) and invented a state the table forbids — B already requires every critical gate to pass, so "B with a borderline gate" cannot occur, and "borderline" is defined nowhere. A critical gate is PASS or FAIL; there is no third position.

5.3 Report Output

REQUIRED: emit the Tool Availability Block (template in ../../shared/includes/codesift-setup.md) at the top of the report, after the title and before findings. Auditing degraded runs depends on this — do NOT skip it.

ACCESSIBILITY AUDIT REPORT
===============================================
Project: [name]
Date: [ISO-8601 date]
Framework: [detected]
Component Library: [detected or "custom"]
Standard: WCAG 2.2 [AA|AAA]
Legal: [ADA Title II | EAA | Section 508 | N/A]
A11y Tooling: [detected tools or "none"]

SCORE: [N]% -- Grade [A/B/C/FAIL]
===============================================

## Critical Gate Status
  A2 (Keyboard Navigation): [PASS/FAIL] ([N]/12)
  A4 (Color & Contrast):    [PASS/FAIL] ([N]/10)

## Dimension Scores
| # | Dimension | Score | Max | Key WCAG Criteria |
|---|-----------|-------|-----|-------------------|
| A1 | Semantic HTML | [N] | 10 | 1.3.1, 4.1.2 |
| A2 | Keyboard Navigation | [N] | 12 | 2.1.1, 2.1.2, 2.4.7 |
| A3 | ARIA Patterns | [N] | 10 | 4.1.2, 4.1.3 |
| A4 | Color & Contrast | [N] | 10 | 1.4.1, 1.4.3, 1.4.11 |
| A5 | Forms & Inputs | [N] | 10 | 1.3.1, 3.3.1, 3.3.2 |
| A6 | Images & Media | [N] | 8 | 1.1.1, 1.2.1, 1.2.2 |
| A7 | Responsive & Zoom | [N] | 6 | 1.4.4, 1.4.10 |
| A8 | Motion & Animation | [N] | 5 | 2.2.2, 2.3.1, 2.3.3 |
| A9 | Reading & Content | [N] | 5 | 2.4.2, 3.1.1, 3.2.3 |
| A10 | Legal Compliance | [N] | 4 | (aggregate) |
| | **Total** | **[N]** | **80** | |

## Findings (sorted by legal risk, then user impact)

### A11Y-001: [Title]
  Dimension: A[N]
  WCAG: [criterion number and name]
  Severity: CRITICAL | HIGH | MEDIUM
  File: [path:line]
  Impact: [who is affected and how]
  Fix: [specific code change or reference to Phase 4 fix]

### A11Y-002: [Title]
  ...

## Legal Compliance Summary
| Standard | Status | Key Gaps |
|----------|--------|----------|
| WCAG 2.2 AA | [PASS / PARTIAL / FAIL] | [summary] |
| ADA Title II | [COMPLIANT / AT RISK / NON-COMPLIANT / N/A] | [summary] |
| EAA | [COMPLIANT / AT RISK / NON-COMPLIANT / N/A] | [summary] |
| Section 508 | [COMPLIANT / AT RISK / NON-COMPLIANT / N/A] | [summary] |

## Automated vs Manual Coverage
  Automated checks (axe-core/pa11y): [N issues found | "not run"]
  Static code analysis: [N issues found]
  Manual verification needed: [N items flagged as CANNOT DETERMINE]

## Per-Component Breakdown
| File | A1 | A2 | A3 | A4 | A5 | A6 | A7 | A8 | A9 | Total | Grade |
|------|----|----|----|----|----|----|----|----|----|----- -|-------|
| [path] | [N] | [N] | [N] | [N] | [N] | [N] | [N] | [N] | [N] | [N]% | [A-FAIL] |

5.4 Backlog Persistence

If --persist-backlog is set or CRITICAL findings exist:

For each CRITICAL or HIGH finding, persist to memory/backlog.md:

- B-{N} | {file}:{line} | A11Y-{NNN} | {WCAG criterion}: {description} | seen:1 | confidence:{0-100} | source:a11y-audit | {date}

Dedup: If the same file|WCAG criterion combo exists, increment seen:N and update the date.

5.5 Save Report

Save to: zuvo/audits/a11y-audit-YYYY-MM-DD.md — at the project root (zuvo/ resolves via git rev-parse --show-toplevel; override $ZUVO_OUTPUT_DIR. See ../../shared/includes/report-output-location.md).

5.6 Propose Next Actions

Completion Gate Check

Before printing the final output block, verify every item. Unfinished items = pipeline incomplete.

COMPLETION GATE CHECK
[ ] A11y tooling detection printed
[ ] Critical gates printed: A2 (Keyboard) and A4 (Contrast)
[ ] Per-component score table present with all A1-A9 dimensions
[ ] Findings sorted by legal risk first
[ ] Report saved to zuvo/audits/
[ ] Run: line printed and appended to log

Completion

After completing the audit, print:

A11Y-AUDIT COMPLETE
-----
Components audited: [N]
Standard: WCAG 2.2 [AA|AAA]
Score: [N]% -- Grade [A/B/C/FAIL]
Critical gates: A2=[PASS/FAIL] A4=[PASS/FAIL]
Findings: [N] CRITICAL, [N] HIGH, [N] MEDIUM
Fixes generated: [N] (if --fix)
Legal: [status summary]
Run: <ISO-8601-Z>	a11y-audit	<project>	<score>%	-	<VERDICT>	-	<N>-dimensions	<NOTES>	<BRANCH>	<SHA7>	<INCLUDES>	<TIER>
-----

Validity Gate (REQUIRED — print BEFORE Run line, AFTER retro append + append-runlog)

VALIDITY GATE
  required_tool_calls:
    get_file_tree: [<N> | NOT_CALLED]
    search_text: [<N> | NOT_CALLED]
    search_symbols: [<N> | NOT_CALLED]
    search_patterns: [<N> | NOT_CALLED]
    audit_scan: [<N> | NOT_CALLED]
    react_tools: [<result> | not_required | NOT_CALLED]
  postamble:
    retros_log_appended: [yes(bytes_added=N) | NOT_APPENDED]
    retros_md_appended: [yes(entry_count=N) | NOT_APPENDED]
    verify_audit_pass: [yes(<verified>/<total>) | NOT_RUN | REJECTED]
  gate_status: [PASS | FAIL]

If gate_status = FAIL → VERDICT = INCOMPLETE. Append the Run line via the retro-gated wrapper (NOT direct >> runs.log):

printf '%b\n' "$RUN_LINE" | ~/.zuvo/append-runlog

Retrospective (REQUIRED)

Follow the retrospective protocol from retrospective.md. Gate check → structured questions → TSV emit → markdown append. If gate check skips: print "RETRO: skipped (trivial session)" and proceed.

After printing this block, append the Run: line value (without the Run: prefix) to the log file path resolved per run-logger.md.

Field resolution:

• CQ_SCORE: <score>% (overall percentage)
• Q_SCORE: - (not applicable)
• VERDICT: PASS (>= 85%), WARN (>= 70% and < 85%), FAIL (< 70%, or any critical gate fails)
• TASKS: -
• DURATION: <N>-dimensions (number of dimensions scored, typically 10)
• NOTES: WCAG2.2-[AA|AAA] [N]-findings [legal-status] (max 80 chars)

Next-Action Routing