Audits UI code for WCAG 2.1 AA compliance including semantics, keyboard navigation, color contrast, and ARIA usage.

When to Use

Invoke with /accessibility-audit when:

Building or reviewing user-facing UI components
Preparing for an accessibility compliance review
Fixing reported accessibility issues
Ensuring inclusive design for all users
Before launching a new feature with UI changes

Process

Phase 1: Identify UI Framework

Determine the UI technology:

Web: React, Vue, Angular, Svelte, plain HTML
Mobile: React Native, Flutter, native iOS/Android
Desktop: Electron, Tauri, native desktop

Adapt checks to the framework's accessibility patterns.

Phase 2: Semantic Structure

Check that UI elements convey meaning:

HTML Semantics (Web)

Use semantic elements (<nav>, <main>, <article>, <button>) instead of generic <div>/<span>
Heading hierarchy is logical (h1 → h2 → h3, no skipping levels)
Lists use <ul>/<ol>/<dl> not styled divs
Forms have associated <label> elements
Tables have <thead>, <th>, and scope attributes for data tables
Landmarks are used correctly (one <main>, navigation in <nav>)

Component Semantics (All frameworks)

Interactive elements are focusable and have accessible names
Custom components expose correct roles to assistive technology
Decorative elements are hidden from screen readers (aria-hidden, empty alt)

Verify full keyboard operability:

Tab order: logical, follows visual layout, no keyboard traps
Focus visibility: all interactive elements have visible focus indicators
Interactive elements: all clickable elements are reachable and operable via keyboard
Custom widgets: keyboard patterns follow WAI-ARIA Authoring Practices
- Modals: trap focus, Escape to close
- Dropdowns: Arrow keys to navigate, Enter to select, Escape to close
- Tabs: Arrow keys to switch, Tab to move to content
- Sliders: Arrow keys to adjust
Skip links: "Skip to main content" link for long navigation
No mouse-only interactions: hover-only tooltips, drag-only sorting

Phase 4: Visual Accessibility

Check visual design compliance:

Color & Contrast

Text contrast ratio ≥ 4.5:1 (normal text) or ≥ 3:1 (large text, 18px+ or 14px+ bold)
UI component contrast ≥ 3:1 against adjacent colors
Information is not conveyed by color alone (add icons, patterns, or text)
Focus indicators have sufficient contrast

Typography & Layout

Text can be resized to 200% without loss of content
No horizontal scrolling at 320px viewport width (responsive)
Line height ≥ 1.5, paragraph spacing ≥ 2x font size
Touch targets ≥ 44x44px (mobile)

Motion & Animation

Respect prefers-reduced-motion media query
No auto-playing animations longer than 5 seconds without pause control
No content that flashes more than 3 times per second

Phase 5: ARIA Usage

Audit ARIA implementation:

First rule of ARIA: Don't use ARIA if native HTML can do it
Correct roles: ARIA roles match the element's purpose
Required properties: ARIA roles have all required properties (e.g., role="slider" needs aria-valuenow)
Live regions: dynamic content updates announced with aria-live
Labels: interactive elements have aria-label or aria-labelledby when visible text is insufficient
States: toggle states use aria-pressed, aria-expanded, aria-selected correctly
No conflicting ARIA: ARIA attributes don't conflict with native semantics

Phase 6: Content Accessibility

Check content is accessible:

Images: all <img> have alt text (descriptive for content, empty for decorative)
Forms: error messages are programmatically associated with inputs
Links: link text is descriptive (no "click here" or "read more" without context)
Language: lang attribute set on <html> and on elements in different languages
Timeouts: users are warned before timeouts and can extend them

Output Format

# Accessibility Audit Report

## Compliance Level
[Current WCAG 2.1 AA compliance estimate: Non-compliant / Partially / Mostly / Fully]

## Critical Issues (A-level violations)
| # | WCAG Criterion | Location | Issue | Fix |
|---|---------------|----------|-------|-----|
| 1 | 1.1.1 Non-text Content | file:line | Image missing alt text | Add descriptive alt |

## Major Issues (AA-level violations)
| # | WCAG Criterion | Location | Issue | Fix |
|---|---------------|----------|-------|-----|

## Minor Issues (Best practices)
| # | Category | Location | Issue | Fix |
|---|----------|----------|-------|-----|

## Component Checklist
| Component | Keyboard | Screen Reader | Contrast | Status |
|-----------|----------|--------------|----------|--------|
| Navigation | ✅/❌ | ✅/❌ | ✅/❌ | Pass/Fail |

## Recommendations
1. [Highest impact fix]
2. ...

Notes

This audit covers WCAG 2.1 AA level — AAA is aspirational and not required for most projects
For mobile apps, apply the equivalent platform accessibility guidelines alongside WCAG
Static code analysis catches structural issues but manual testing with screen readers is still recommended
Non-UI projects (APIs, CLIs, libraries) do not need this audit

Edit this page on GitHub

Accessibility Audit