Accessibility Audit Agent

    WCAG 2.1 Level AA compliance audit across 4 categories — Perceivable, Operable, Understandable, Robust — with automatic fixes for issues found.

    Free & open4 dimensionsInstall in 30 seconds

    What This Agent Does

    Audits and fixes any web page or component against WCAG 2.1 Level AA criteria across four categories: Perceivable (images, contrast, text resize), Operable (keyboard access, focus management, touch targets), Understandable (labels, error handling, consistency), and Robust (semantic HTML, ARIA, landmarks).

    Includes component-specific requirements for common UI patterns like navigation, accordions, forms, and content pages. Also provides a color contrast quick reference for verifying common element combinations against your design tokens.

    References & Sources

    What You Get

    • Perceivable (9 checks) — alt text, color contrast (4.5:1 normal, 3:1 large text), non-text contrast, text resize, sensory independence
    • Operable (9 checks) — keyboard access, focus order, focus indicators, keyboard traps, skip links, touch targets
    • Understandable (6 checks) — page language, form labels, error messages, consistent navigation
    • Robust (5 checks) — semantic HTML, ARIA landmarks, valid ARIA attributes, custom component roles, live regions

    Install

    Choose your preferred installation method. Both put the agent rule in the right place for Claude Code to discover automatically.

    Copy the rule below and save it as .claude/rules/accessibility-a11y.md in your project root.

    .claude/rules/accessibility-a11y.md
    # Accessibility Audit Agent Rules

When asked to audit accessibility, check WCAG compliance, or improve accessible design, follow these rules. Accessibility is a design constraint, not a post-hoc audit -- every component should ship accessible.

## Compliance Target

**WCAG 2.1 Level AA** as the minimum standard. Level AAA where practical without degrading the design.

## How to Run an Accessibility Audit

1. Identify the target page(s) or component(s)
2. Check against each WCAG 2.1 AA criterion in the checklist below
3. Test keyboard navigation flow
4. Verify screen reader compatibility (semantic HTML, ARIA)
5. Check color contrast ratios
6. Output an accessibility scorecard

## Audit Checklist by Category

### Perceivable (WCAG 1.x)

| Check | Criterion | How to Verify |
|---|---|---|
| P1 | All images have meaningful alt text | Check every `<img>`, image component, and SVG for `alt` or `aria-label` |
| P2 | Decorative images have empty alt (`alt=""`) | Images that add no information should be hidden from screen readers |
| P3 | Color is not the only means of conveying information | Check charts, status indicators, links -- all need non-color signals |
| P4 | Text contrast ratio >= 4.5:1 (normal text) | Use contrast checker against your design token colors |
| P5 | Text contrast ratio >= 3:1 (large text, 18px+ or 14px+ bold) | Large headings and bold text |
| P6 | Non-text contrast >= 3:1 (UI components, icons) | Buttons, icons, form borders, focus indicators |
| P7 | Text can be resized to 200% without loss of content | Test with browser zoom |
| P8 | No content relies solely on sensory characteristics | "Click the red button" or "see the chart on the right" fails |
| P9 | Video/audio has captions or transcripts (if applicable) | Check if video or audio elements exist |

### Operable (WCAG 2.x)

| Check | Criterion | How to Verify |
|---|---|---|
| O1 | All interactive elements are keyboard accessible | Tab through the entire page -- every button, link, and form field must be reachable |
| O2 | Focus order is logical (top-to-bottom, left-to-right) | Tab order matches visual order |
| O3 | Focus indicators are visible | Every focused element has a visible outline or ring |
| O4 | No keyboard traps | Can Tab into and out of every component (modals, dropdowns, accordions) |
| O5 | Skip-to-content link is present | First focusable element on the page should be a "Skip to main content" link |
| O6 | No content flashes more than 3 times per second | Check animations and transitions |
| O7 | Page has a descriptive `<title>` | Check the page's metadata |
| O8 | Link purpose is clear from text (or text + context) | No "click here" or "read more" without context |
| O9 | Touch targets are at least 44x44 CSS pixels | Mobile buttons and links |

### Understandable (WCAG 3.x)

| Check | Criterion | How to Verify |
|---|---|---|
| U1 | Page language is set (`<html lang="en">`) | Check root layout |
| U2 | Form inputs have associated labels | Every `<input>` has a `<label>` with `htmlFor` (or `for`) |
| U3 | Error messages identify the field and describe the error | Form validation messages are specific |
| U4 | Error prevention for important actions | Confirmation before destructive actions |
| U5 | Consistent navigation across pages | Nav/footer structure is identical on all pages |
| U6 | Consistent identification of UI components | Same component looks and behaves the same everywhere |

### Robust (WCAG 4.x)

| Check | Criterion | How to Verify |
|---|---|---|
| R1 | Valid, semantic HTML | Correct heading hierarchy (H1 -> H2 -> H3, no skipping) |
| R2 | ARIA landmarks are correct | `<main>`, `<nav>`, `<header>`, `<footer>`, `<aside>` used appropriately |
| R3 | ARIA attributes are valid and complete | No `aria-labelledby` pointing to missing IDs |
| R4 | Custom components have appropriate ARIA roles | Accordions, tabs, modals have correct roles and states |
| R5 | Status messages use `aria-live` regions | Dynamic content updates announced to screen readers |

## Component-Specific Requirements

### Navigation
- All nav links keyboard accessible
- Current page indicated with `aria-current="page"`
- Mobile menu toggle has `aria-expanded` state
- Menu items announced correctly to screen readers

### Accordion / FAQ
- Each trigger has `aria-expanded` (true/false)
- Content region has `aria-labelledby` pointing to trigger
- Keyboard: Enter/Space to toggle, optionally Arrow keys to navigate between items
- Role: `button` for triggers

### Footer
- Contains `<footer>` landmark
- Link sections use heading or `aria-label` for screen reader navigation
- External links indicate they open in new window (if applicable)

### Forms
- Every field has a visible `<label>`
- Required fields indicated with `aria-required="true"` AND visual indicator
- Error messages linked with `aria-describedby`
- Submit button has clear, descriptive text

### Blog/Content Pages
- Heading hierarchy flows correctly (no jumps from H2 to H4)
- Code blocks have language annotation for screen readers
- Tables have `<caption>` or `aria-label` describing the table's purpose
- Tables use `<th>` for header cells with `scope` attribute

## Color Contrast Quick Reference

Verify these common element combinations against your design tokens:

| Element | Foreground | Background | Must Meet |
|---|---|---|---|
| Body text | Primary text color | Page background | 4.5:1 |
| Muted/secondary text | Muted text color | Page background | 4.5:1 |
| Primary buttons | Button text color | Button background | 4.5:1 |
| Links | Link color | Page background | 4.5:1 |
| Card text | Card text color | Card background | 4.5:1 |

## Accessibility Audit Output Format

```
## Accessibility Audit -- [Page URL or Component Name]
**Date:** [Date] | **Standard:** WCAG 2.1 AA | **Issues found:** [N]

### Summary
| Category | Pass | Warning | Fail |
|---|---|---|---|
| Perceivable | [N] | [N] | [N] |
| Operable | [N] | [N] | [N] |
| Understandable | [N] | [N] | [N] |
| Robust | [N] | [N] | [N] |

### Critical Issues (WCAG Failures)
| Check | Issue | Location | Fix |
|---|---|---|---|
| [P4] | [Contrast ratio 3.2:1 on muted text] | [Component:line] | [Increase contrast or change color] |

### Warnings (Should Fix)
| Check | Issue | Location | Fix |
|---|---|---|---|
| [O8] | ["Read more" link without context] | [Component:line] | [Add aria-label or visible context] |

### Keyboard Navigation Flow
[Description of tab order, any traps or missing focus indicators]

### Screen Reader Compatibility
[Key findings from semantic HTML and ARIA review]

### Top 3 Fixes
1. [Fix + impact + file:line]
2. [Fix + impact + file:line]
3. [Fix + impact + file:line]
```

---

## Out of Scope

This agent focuses on WCAG 2.1 AA compliance. The following are not covered:

- Visual design decisions and aesthetics
- Content readability, voice, and tone
- SEO-specific heading hierarchy optimization
- Performance and Core Web Vitals optimization
- Color palette or design system changes (flag issues, recommend fixes within existing system)

    Usage

    Once installed, open your project in Claude Code and ask:

    Run an accessibility audit on /contact and fix any WCAG failures

    Claude Code will follow the scoring rubric, check every dimension, and output a structured scorecard with pass/fail per check and prioritized fix recommendations.

    Works Great With

    Audit43 checks6 dim

    Google SEO Compliance Agent

    43 checks across 6 dimensions based on Google Search Central's official guidelines. Audits any page, scores it to 100, and fixes what it finds.

    Technical

    Performance & Core Web Vitals Agent

    Audits page speed, Core Web Vitals (LCP, CLS, INP), bundle size, and optimization opportunities — then applies fixes to bring you within budget.

    Audit68 checks7 dim

    Content QA Audit Agent

    68 checks across 7 dimensions: Technical SEO, Linking, E-E-A-T, Anti-Slop, AI Extraction, Schema, and AI Access. Scores your page and fixes what fails.

    Need a Custom Agent?

    We build custom Claude Code agent rules tailored to your team's workflows, content standards, and tech stack.

    Get in touch