arbazkhan971 A11y — Accessibility Testing & Auditing
Activate When
- User invokes
/godmode:a11y - User says "check accessibility," "is this accessible?", "WCAG compliance"
- Pre-ship quality gate during
/godmode:shipworkflow - After UI changes, component library updates, or design system modifications
- When building forms, navigation, modals, or interactive widgets
- Code review flags missing ARIA attributes or semantic HTML issues
Workflow
Step 1: Define Audit Scope
Determine which pages, components, or flows to audit:
A11Y AUDIT SCOPE:
Target: <page/component/entire app>
WCAG level: <AA (default) | AAA>
Step 2: Automated Tool Scanning
Run automated accessibility scanners in sequence:
Axe-core Analysis
# Install if needed
npm install --save-dev @axe-core/cli
Pa11y Scanning
# Install if needed
npm install --save-dev pa11y pa11y-ci
Lighthouse Accessibility Audit
# Run Lighthouse accessibility category
npx lighthouse <url> --only-categories=accessibility --output=json --output-path=./a11y-report.json
AUTOMATED SCAN RESULTS:
Axe findings: <N> violations, <N> incomplete, <N> passes
Pa11y findings: <N> errors, <N> warnings, <N> notices
Step 3: WCAG 2.1 Compliance Checklist
Systematic check against WCAG 2.1 principles:
Perceivable (WCAG 1.x)
CHECK — Can all users perceive the content?
1.1 Text Alternatives:
Operable (WCAG 2.x)
CHECK — Can all users operate the interface?
2.1 Keyboard Accessible:
Understandable (WCAG 3.x)
CHECK — Can all users understand the content?
3.1 Readable:
Robust (WCAG 4.x)
CHECK — Does the content work with assistive technologies?
4.1 Compatible:
Step 4: Color Contrast Deep Dive
Analyze every foreground/background color combination:
COLOR CONTRAST ANALYSIS:
| Element | FG | BG | Ratio | Result |
Tools for color contrast:
# Using color-contrast-checker
npx color-contrast-checker --fg "#999" --bg "#fff"
Step 5: Keyboard Navigation Audit
Test every interactive flow using keyboard only:
KEYBOARD NAVIGATION AUDIT:
Flow: <user flow being tested>
Test these common keyboard patterns:
KEYBOARD PATTERNS:
| Component | Expected Keyboard Behavior |
Step 6: Screen Reader Testing
Verify content is announced correctly:
SCREEN READER AUDIT:
Screen reader: <VoiceOver (macOS) / NVDA (Windows) / JAWS / TalkBack (Android)>
Browser: <Safari / Chrome / Firefox>
ARIA live region checklist:
- [ ] Toast notifications use aria-live="polite" or role="status"
- [ ] Error alerts use aria-live="assertive" or role="alert"
- [ ] Loading states announced with aria-busy="true"
Step 7: Findings Report
For each issue found:
### FINDING <N>: <Title>
**Severity:** CRITICAL | HIGH | MEDIUM | LOW
**WCAG criterion:** <number> — <name> (Level <A/AA/AAA>)
Impact: <Who is affected and how — specific disability/assistive technology>
Remediation:
<!-- The accessible fix -->
<fixed code>
Verification: <How to confirm the fix — tool command or manual test>
Severity definitions:
- **CRITICAL**: Complete blocker for assistive technology users.
Missing form labels, keyboard traps, no alt text on functional images.
IF Lighthouse a11y score < 90: treat as NEEDS REMEDIATION.
WHEN axe reports > 0 critical violations: block deployment.
IF contrast ratio < 4.5:1 for normal text: flag as HIGH severity.
WHEN keyboard trap detected: flag as CRITICAL, fix before any other issue.
```bash
# Run full automated a11y scan pipeline
npx axe-core/cli http://localhost:3000 --exit
npx pa11y-ci --config .pa11yci.json
npx lighthouse http://localhost:3000 --only-categories=accessibility --output=json
AUTO-FIXABLE ISSUES:
1. Add missing alt="" to decorative images
2. Associate orphaned labels with inputs via for/id
3. Add aria-label to icon-only buttons
4. Fix heading hierarchy gaps
5. Add lang attribute to <html>
6. Add skip navigation link
7. Wrap form error messages in aria-live region
8. Add role="presentation" to layout tables
For each auto-fix:
FIX <N>: <description>
File: <path>
Before: <original code>
After: <fixed code>
WCAG: <criterion satisfied>
Step 9: Accessibility Report
| ACCESSIBILITY AUDIT — <target> |
| WCAG Level: <AA/AAA> |
| Automated Scores: |
| Axe: <N> violations |
| Pa11y: <N> errors |
| MUST FIX before shipping: |
| 1. <CRITICAL/HIGH finding> |
| 2. <CRITICAL/HIGH finding> |
| SHOULD FIX: |
| 3. <MEDIUM finding> |
| 4. <MEDIUM finding> |
Verdicts:
- PASS: 0 CRITICAL/HIGH findings. Lighthouse score >= 90. Color contrast >= 4.5:1 normal text, >= 3:1 large text (18px+).
AUTO-DETECT SEQUENCE:
1. Scan package.json / requirements.txt for framework:
- React/Next.js → check for jsx/tsx files, component patterns
- Vue → check for .vue files
- Angular → check for angular.json
- Vanilla → check for .html files
2. Detect UI library:
- grep for '@mui', 'antd', '@chakra-ui', 'tailwind', 'bootstrap'
3. Detect existing a11y tooling:
- Check devDependencies for axe-core, pa11y, jest-axe, cypress-axe
- Check for .pa11yci.json, .axe config files
4. Detect existing a11y patterns:
- grep for 'aria-', 'role=', 'alt=', 'sr-only', 'visually-hidden'
- grep for 'prefers-reduced-motion' in CSS/SCSS
5. Detect testing infrastructure:
- Storybook? → can use @storybook/addon-a11y
- Jest? → can use jest-axe
- Playwright/Cypress? → can use axe integration
6. Count components and pages in scope automatically
HARD RULES
Never ask to continue. Loop autonomously until zero CRITICAL/HIGH violations or budget exhausted.
MECHANICAL CONSTRAINTS — NON-NEGOTIABLE:
1. NEVER skip the manual checklist even if automated tools report 0 violations.
Automated tools catch 30-40% of issues. The checklist catches the rest.
2. NEVER mark PASS if any CRITICAL finding exists — regardless of Lighthouse score.
3. NEVER auto-fix without verifying the fix does not break existing functionality.
4. git commit BEFORE running verify — if verify reveals regression, revert the commit.
5. Every finding MUST include: severity, WCAG criterion, location, evidence, remediation.
6. Log all findings in TSV format for tracking:
SEVERITY\tWCAG\tLOCATION\tTOOL\tDESCRIPTION
7. Color contrast failures are ALWAYS HIGH or CRITICAL — no exceptions.
8. Keyboard traps are ALWAYS CRITICAL — no exceptions.
9. If auto-fix changes > 10 files, split into separate commits per concern.
10. Re-run automated scans AFTER applying fixes to confirm zero regressions.
Output Format
A11Y AUDIT REPORT:
| Pages audited | <N> |
|--|--|
| Components audited | <N> |
| Total violations | <N> |
| Critical | <N> (keyboard traps, no alt) |
| High | <N> (contrast, missing labels) |
| Medium | <N> (aria improvements) |
| Low | <N> (best practice suggestions) |
| Auto-fixed | <N> |
| Manual review | <N> |
| WCAG level | A | AA | AAA |
| Verdict | PASS | NEEDS REMEDIATION |
TSV Logging
timestamp skill page severity wcag element tool description status
2026-03-20T14:00:00Z a11y /home CRITICAL 2.1.2 .modal manual keyboard trap in modal fixed
2026-03-20T14:01:00Z a11y /form HIGH 1.4.3 .label axe contrast ratio 3.2:1 < 4.5:1 fixed
Quality Targets
- Target: >90% Lighthouse accessibility score
- Target: 0 critical WCAG 2.1 AA violations
- Target: <2s time-to-interactive for assistive tech
- Color contrast ratio: >=4.5:1 for normal text, >=3:1 for large text
Success Criteria
After EACH accessibility fix:
1. MEASURE: Re-run axe-core and manual check on the fixed component.
2. COMPARE: Did the violation count decrease? Did any new violations appear?
3. DECIDE:
- KEEP if: target violation fixed AND no new violations introduced
- DISCARD if: fix introduced new violations OR broke existing functionality
4. COMMIT kept changes. Revert discarded changes before fixing the next issue.
## Keep/Discard
KEEP if: improvement verified. DISCARD if: regression or no change. Revert discards immediately.
## Stop Conditions
STOP when ANY of these are true: