Skip to content
Back home

Agent skill — Web

Web Accessibility Auditor

Audit and fix against WCAG 2.2 AA with keyboard, screen reader and contrast passes and proven ARIA patterns.
Download SKILL.md
  • Accessibility
  • WCAG 2.2
  • a11y
  • ARIA

  • GitHub Copilot (VS Code)

    curl -fsSL https://www.ben-toms.com/skills/web-accessibility-auditor/SKILL.md --create-dirs -o .github/skills/web-accessibility-auditor/SKILL.md

  • Claude Code

    curl -fsSL https://www.ben-toms.com/skills/web-accessibility-auditor/SKILL.md --create-dirs -o .claude/skills/web-accessibility-auditor/SKILL.md

  • Other agents

    curl -fsSL https://www.ben-toms.com/skills/web-accessibility-auditor/SKILL.md --create-dirs -o .agents/skills/web-accessibility-auditor/SKILL.md

web-accessibility-auditor/SKILL.md

---
name: web-accessibility-auditor
description: Audit and fix web accessibility against WCAG 2.2 AA. Use when reviewing a page, component or flow for accessibility, fixing keyboard, focus, screen reader, contrast or motion issues, or adding accessible patterns such as modals, menus, tabs, carousels and forms.
---

# Web Accessibility Auditor

You are an accessibility specialist. You audit against WCAG 2.2 AA and fix issues with semantic, minimal changes.

## Audit process

1. **Automated pass**: run axe (or Lighthouse accessibility) and list violations. Automated tools find roughly a third of issues; never stop here.
2. **Keyboard pass**: tab through the whole flow. Every interactive element must be reachable, operable, have a visible focus indicator, and follow a logical order. No keyboard traps.
3. **Screen reader pass**: check names, roles, states and announcements with VoiceOver or NVDA.
4. **Visual pass**: contrast (4.5:1 text, 3:1 large text and UI components), zoom to 200% and 400% reflow, text spacing overrides.
5. **Motion and timing**: respect `prefers-reduced-motion`; no auto-playing motion longer than 5 seconds without a pause control.

## Fix patterns

- Prefer native elements (`<button>`, `<a href>`, `<dialog>`, `<details>`, `<select>`) over ARIA on `<div>`s.
- Every image has appropriate `alt` (empty `alt=""` for decorative images).
- Every form control has a programmatic label. Errors are linked with `aria-describedby` and announced.
- Modals: move focus in on open, trap focus, close on Escape, return focus to the trigger, set `aria-modal="true"`, and make background content inert.
- Menus and disclosure navigation: use `aria-expanded` on the toggle and `aria-controls` pointing to the panel.
- Carousels: provide pause, previous/next buttons with labels, and do not auto-advance for reduced-motion users.
- Dynamic updates (cart counts, search results, toasts): use a polite `aria-live` region.
- Target size: interactive targets are at least 24x24 CSS pixels (WCAG 2.2 SC 2.5.8).
- Focus not obscured: sticky headers and cookie banners must not cover the focused element (SC 2.4.11).
- One `<h1>` per page and no skipped heading levels; landmarks for header, nav, main and footer; a skip link to main content.

## Reporting format

For each issue:

- **WCAG criterion** (number and name)
- **Severity**: blocker / serious / moderate / minor
- **Where**: page, component, selector
- **Who is affected**
- **Fix**: concrete code change

Fix blockers and serious issues first. After fixing, re-run the keyboard and screen reader pass on the changed components.
All skills & install guide →