Accessibility Audit Workflow

Accessibility Audit Workflow

Quick Start

Task Progress:
- [ ] Step 1: Read accessibility requirements from rules and specs
- [ ] Step 2: Automated scan — run axe-core or similar on all pages/components
- [ ] Step 3: Manual audit — load references/manual-audit-checklist.md
- [ ] Step 4: Catalog findings by severity (critical/major/minor)
- [ ] Step 5: Fix critical and major findings
- [ ] Step 6: Verify fixes with re-scan and manual check

Progressive Disclosure

• Main skill file (this): Workflow steps, automated scan, fix process, DoD.
• references/manual-audit-checklist.md: Detailed WCAG requirements matrix, per-category manual criteria, severity cataloging rubric. Load during Step 3.

Step 1: Read Accessibility Requirements

From project component rules (Accessibility section):

• All animations: wrap in prefers-reduced-motion media query AND check user's reduced motion setting.
• Color contrast: >= 4.5:1 for text (WCAG AA).
• Interactive elements: keyboard focusable with visible focus indicator.
• Dynamic content changes: use aria-live regions.
• Support high contrast mode.

For the full WCAG requirements matrix, load references/manual-audit-checklist.md.

For external library docs and current best practices, follow the project's tooling hierarchy.

Step 2: Automated Scan

• Install and run @axe-core/vue, vitest-axe, or Playwright's @axe-core/playwright on all pages and key components.
• Run against: main routes, key components (if testable in isolation).
• Capture all violations. Map to WCAG criteria (e.g., 1.1.1, 1.4.3, 2.1.1, 4.1.2).
• Document: rule ID, description, impact, elements affected, WCAG level.

Step 3: Manual Audit

Load references/manual-audit-checklist.md and work through each category:

1. Keyboard navigation
2. Color contrast
3. ARIA attributes
4. Reduced motion
5. Screen reader
6. High contrast mode

The reference file provides the specific criteria, DevTools settings, and pass/fail conditions for each.

Step 4: Catalog Findings

Use the severity rubric in references/manual-audit-checklist.md to assign severity. Produce a findings table: ID, severity, WCAG criterion, description, location, fix suggestion. Prioritize critical first, then major. Minor can be batched.

Step 5: Fix Critical and Major Findings

• Implement fixes following project component and quality requirements.
• Use semantic HTML where possible (<button>, <a>, <nav>, <main>).
• Add aria-* attributes for custom components.
• Verify prefers-reduced-motion is respected by enabling the media query in DevTools and confirming animations are disabled or simplified.
• Add or fix focus styles. Use design tokens for focus ring.
• Verify reduced-motion behavior in tests.

Step 6: Verify Fixes

• Re-run automated scan. No critical or major violations.
• Manual keyboard and screen reader check on fixed areas.
• Run full test suite and confirm 0 failures to verify no regressions.
• Document remaining minor findings for future backlog.

Required Agent Delegation

You MUST spawn these agents via the Task tool (subagent_type: "generalPurpose") at the appropriate points:

• hatch3r-a11y-auditor — MUST spawn to perform the full WCAG AA compliance audit autonomously. Provide the list of surfaces/components to audit and the current violation list.

Related Rules

• Rule: hatch3r-browser-verification — follow this rule for live browser-based accessibility testing

Error Handling

• No automated scanner available: If axe-core, Lighthouse, or equivalent is not installed, report the gap and proceed with manual checklist-only audit. Do not skip the audit.
• Scanner produces false positives: Cross-reference automated findings against manual inspection. Mark confirmed false positives with justification and exclude from the violation count.
• Component renders differently across browsers: Test in at least two browser engines (Chromium + Firefox or Safari). Document browser-specific a11y gaps with reproduction steps.

Definition of Done

• No critical a11y violations
• WCAG AA compliance on all audited surfaces
• Reduced motion respected (prefers-reduced-motion + user setting)
• Keyboard navigation complete with visible focus
• Color contrast >= 4.5:1 for text
• ARIA live regions for dynamic content
• Automated scan clean for critical/major
• Manual verification completed