Accessibility Auditor

Analyze applications for WCAG 2.2 AA compliance and produce actionable audit reports.

Audit Workflow

┌─────────────────────────────────────────────────────────────┐
│                        INPUTS                               │
├─────────────────┬─────────────────┬─────────────────────────┤
│ Code            │ Tool Output     │ Tester Findings         │
│ (HTML, React,   │ (axe, Light-    │ (manual testing         │
│ RN, SwiftUI)    │ house, etc.)    │ reports)                │
└────────┬────────┴────────┬────────┴────────┬────────────────┘
         │                 │                 │
         └─────────────────┼─────────────────┘
                           ▼
              ┌────────────────────────┐
              │   ANALYSIS PROCESS     │
              │  • Map to WCAG 2.2 AA  │
              │  • Classify severity   │
              │  • Identify patterns   │
              │  • Note remediation    │
              └───────────┬────────────┘
                          ▼
              ┌────────────────────────┐
              │     AUDIT REPORT       │
              │  Structured for        │
              │  implementation agent  │
              └────────────────────────┘

WCAG 2.2 AA Quick Reference

The Four Principles (POUR)

Principle	Meaning	Key Questions
Perceivable	Users can perceive content	Can everyone see/hear/read it?
Operable	Users can interact	Can everyone navigate and use controls?
Understandable	Users can comprehend	Is content and UI predictable and clear?
Robust	Works with assistive tech	Does it work with screen readers, etc.?

Compliance Levels

• A: Minimum (basic access)
• AA: Standard (legal requirement in most jurisdictions) ← Target
• AAA: Enhanced (not typically required)

Severity Classification

Use this scale for all findings:

Severity	Definition	Example	Priority
Critical	Blocks access entirely	No keyboard navigation, missing alt text on key images	P0 — Fix immediately
Serious	Major barrier, workaround difficult	Poor contrast, form errors not announced	P1 — Fix before release
Moderate	Barrier exists, workaround possible	Focus order confusing, missing skip links	P2 — Fix soon
Minor	Inconvenience, not a barrier	Redundant alt text, minor heading hierarchy issues	P3 — Fix when able

Severity Decision Tree

Can the user complete the task?
├── No → Is there a workaround?
│        ├── No → CRITICAL
│        └── Yes, but difficult → SERIOUS
└── Yes → Is the experience degraded?
          ├── Significantly → MODERATE
          └── Slightly → MINOR

Audit Report Template

Use this structure for all audit reports:

# Accessibility Audit Report

## Summary
| Metric | Count |
|--------|-------|
| Critical | X |
| Serious | X |
| Moderate | X |
| Minor | X |
| **Total Issues** | X |

**Overall Assessment**: [Pass / Fail / Conditional Pass]
**WCAG Version**: 2.2 AA
**Platform**: [Web / iOS / Android / React Native]
**Audit Date**: [Date]
**Auditor**: [Agent/Human]

## Critical Issues

### [Issue ID]: [Brief Title]
- **WCAG Criterion**: [X.X.X Name]
- **Severity**: Critical
- **Location**: [File/Component/Screen]
- **Description**: [What's wrong]
- **Impact**: [Who is affected and how]
- **Code Sample** (if applicable):

[Problematic code]

- **Remediation**: [How to fix]
- **Remediation Code** (if applicable):

[Fixed code]

[Repeat for each critical issue]

## Serious Issues
[Same structure]

## Moderate Issues
[Same structure]

## Minor Issues
[Same structure]

## Passed Criteria
[List WCAG criteria that were checked and passed]

## Out of Scope
[Anything not tested and why]

## Recommendations
[Overall recommendations beyond specific fixes]

## Testing Methodology
- **Automated Tools**: [List tools used]
- **Manual Testing**: [Describe manual checks]
- **Assistive Tech Tested**: [Screen readers, etc.]

Analysis Process

Step 1: Identify Input Type

Input	Analysis Approach
Code	Static analysis against WCAG criteria
Automated tool output	Map findings to WCAG, verify, remove false positives
Tester findings	Standardize format, map to WCAG, classify severity
Mixed	Synthesize all sources, deduplicate

Step 2: Map to WCAG 2.2 AA

Every finding must map to a specific WCAG criterion:

• Reference: references/wcag-22-aa.md

If a finding doesn't map to WCAG AA, classify as:

• Best Practice (not WCAG, but recommended)
• AAA (beyond AA requirement)
• Platform-Specific (HIG, Material guidelines)

Step 3: Classify Severity

Use the severity definitions above. Be consistent:

• Same issue type = same severity across report
• Document reasoning for edge cases

Step 4: Identify Patterns

Look for systemic issues:

• Same problem across multiple components
• Root cause analysis (e.g., missing design system support)
• Note in recommendations section

Step 5: Specify Remediation

Every issue needs actionable remediation:

• Specific enough for implementation agent to execute
• Include code samples when analyzing code
• Reference platform-specific solutions

Code Analysis Checklist

Quick checklist for code review. Details in references/code-analysis.md.

HTML/React/Web

• Images have meaningful alt text (or empty for decorative)
• Form inputs have associated labels
• Heading hierarchy is logical (h1 → h2 → h3)
• Color contrast meets 4.5:1 (text) / 3:1 (large text, UI)
• Focus is visible and logical
• Interactive elements are keyboard accessible
• ARIA used correctly (or native HTML preferred)
• Skip link present
• Language declared
• Error messages associated with inputs

React Native

• accessibilityLabel on touchables/images
• accessibilityRole set correctly
• accessibilityHint for non-obvious actions
• accessibilityState for toggles/selections
• Focus order logical
• Touch targets ≥44pt
• Announcements for dynamic content

SwiftUI / iOS

• accessibilityLabel on custom views
• accessibilityValue for state
• accessibilityHint for actions
• accessibilityElement(children:) grouping
• VoiceOver navigation order
• Dynamic Type support
• Sufficient contrast

Interpreting Tool Output

Common Tools

Tool	Strength	Limitation
axe	Comprehensive, low false positives	Can't test keyboard nav, focus order
Lighthouse	Quick overview, integrated	Less detailed than axe
WAVE	Visual overlay helpful	Can be noisy
Accessibility Inspector (iOS)	Native iOS testing	Manual process
Android Accessibility Scanner	Native Android testing	Limited depth

Tool Output Processing

1. Import findings from tool
2. Remove false positives (verify each finding)
3. Map to WCAG criterion (tools don't always specify)
4. Classify severity (tool severity often inaccurate)
5. Add context (location, impact, remediation)
6. Deduplicate (same issue across pages/components)

Processing Tester Findings

Manual tester reports may need standardization:

1. Normalize format to audit report structure
2. Map to WCAG if tester didn't specify
3. Classify severity using consistent scale
4. Add technical detail if tester provided only description
5. Verify reproducibility if unclear
6. Request clarification if finding is ambiguous

See references/tester-findings.md for interpretation guide.

---

References:

• references/wcag-22-aa.md — Full WCAG 2.2 AA criteria for auditing
• references/code-analysis.md — Platform-specific code analysis patterns
• references/common-issues.md — Frequently found issues with quick fixes
• references/tester-findings.md — Interpreting manual test results