Accessibility Audit

​

Overview

​

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 — keyboard, contrast, ARIA, reduced motion, screen reader
- [ ] 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

​

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

​

WCAG AA Standards

​

Step 2: Automated Scan

• @axe-core/vue, vitest-axe, or Playwright’s @axe-core/playwright
• 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)

• Rule ID
• Description
• Impact (critical/serious/moderate/minor)
• Elements affected
• WCAG level (A/AA/AAA)

​

Step 3: Manual Audit

​

Keyboard Navigation

• Tab through all interactive elements
• Ensure logical order, no focus traps
• All buttons, links, inputs, custom controls focusable
• Visible focus indicator (outline or ring) - no outline: none without replacement
• Escape closes modals/dropdowns
• Enter/Space activates buttons

​

Color Contrast

• Check text vs background: ≥ 4.5:1 for normal text, ≥ 3:1 for large text
• Use DevTools or contrast checker
• Test with design tokens - ensure no ad-hoc colors fail

​

ARIA Attributes

• aria-label or aria-labelledby for icon-only buttons, custom controls
• aria-live="polite" or aria-live="assertive" for dynamic state changes, notifications
• role correct for custom widgets (button, link, tab, etc.)
• aria-expanded, aria-selected, aria-hidden where appropriate

​

Reduced Motion

• Test with prefers-reduced-motion: reduce (DevTools → Rendering → Emulate CSS media)
• Verify animations are disabled or simplified
• Check user’s reduced motion setting
• No motion-dependent information (per WCAG 2.1)

​

Screen Reader

• Test with NVDA, VoiceOver, or similar
• Verify announcements for dynamic content
• Dynamic state, errors, and success messages announced
• Form labels associated, error messages linked via aria-describedby or aria-errormessage

​

High Contrast Mode

• Verify user-configurable high contrast theme works (if applicable)
• No loss of information

​

Step 4: Catalog Findings

• ID
• Severity
• WCAG criterion
• Description
• Location
• Fix suggestion

​

Step 5: Fix Critical and Major Findings

• Use semantic HTML where possible (<button>, <a>, <nav>, <main>)
• Add aria-* attributes for custom components
• Ensure prefers-reduced-motion respected in CSS and JS
• Add or fix focus styles using 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 to ensure no regressions
• Document remaining minor findings for future backlog

​

Required Agent Delegation

• 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 Skills

• Visual Refactor - Includes accessibility requirements for UI changes
• QA Validation - For end-to-end validation including accessibility

​

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