---
name: web-accessibility-audit
description: "Audit and fix WCAG 2.2 AA issues: ARIA, colour contrast, keyboard nav, and screen reader support. Runs an axe-core-style accessibility audit, identifies WCAG 2.2 AA violations, and auto-generates ARIA attributes, focus traps, skip-nav links, and alt text. Works on React, Vue, or plain HTML."
license: MPL-2.0
---

# Web Accessibility Auditor

Web Accessibility Auditor scans your rendered UI for WCAG 2.2 AA violations and proposes concrete fixes — generated ARIA attributes, focus management, skip links, and alt text — that you can apply directly to source. It's built for frontend engineers and QA testers who need to ship compliant interfaces in React, Vue, or plain HTML without manually cross-referencing success criteria.

## When to use it

- Before a release, to catch contrast failures, missing form labels, and broken keyboard order that visual QA misses.
- When wiring up a custom widget (modal, dropdown, tab set, carousel) and you need correct `role`, `aria-*`, and focus-trap behavior.
- During a legacy remediation pass where you need a prioritized list of violations mapped to specific WCAG 2.2 success criteria.
- In CI, as a gate that fails the build when new AA-level violations are introduced.

## How it works

The auditor runs an axe-core-style rule engine against the live DOM (via a headless Chromium render) so it evaluates computed styles and the actual accessibility tree, not just static markup. Each finding includes the failing selector, the WCAG 2.2 criterion (e.g., 1.4.3 Contrast, 2.4.7 Focus Visible, 4.1.2 Name/Role/Value, plus 2.2 additions like 2.4.11 Focus Not Obscured), an impact rating, and a suggested patch.

Remediations are framework-aware: for React it emits JSX with proper `aria-label`/`aria-labelledby` and `useRef` + `onKeyDown` focus traps; for Vue it uses `:aria-*` bindings and `ref`s; for plain HTML it inserts attributes and a `<a class="skip-nav" href="#main">` link. Contrast fixes suggest the nearest passing foreground/background hex values for the required 4.5:1 (or 3:1 for large text) ratio.

## Example

```bash
curl -fsSL --create-dirs -o ~/.claude/skills/web-accessibility-audit/SKILL.md https://claudeskil.com/skills/web-accessibility-audit/SKILL.md

# Audit a running app and emit a report
a11y-audit http://localhost:5173 --standard wcag22aa --format json > report.json

# Audit source files and write fixes in place
a11y-audit ./src --framework react --fix --rules contrast,aria,keyboard
```

```json
{ "ignore": ["color-contrast"], "level": "AA", "failOn": "serious" }
```

## Tips & gotchas

- Audit the *rendered* app, not raw files, whenever possible — contrast and focus order depend on computed CSS that static analysis can't see.
- Auto-generated alt text describes the image content but can't infer intent. Review decorative images: they should get `alt=""`, not a description.
- Focus traps are only emitted for elements the tool recognizes as dialogs. Add `role="dialog"` first if your modal is a bare `<div>`.
- `--fix` rewrites source; run it on a clean working tree so the diff is reviewable.

## FAQ

**Does it cover WCAG 2.2 specifically, or just 2.1?** It targets 2.2 AA, including the new criteria such as Focus Not Obscured (2.4.11) and Dragging Movements (2.5.7). You can pin `--standard wcag21aa` if you're not yet on 2.2.

**Can it catch keyboard-only issues?** Yes — it simulates tab traversal to flag unreachable controls, illogical tab order, and missing visible focus indicators, then suggests `tabindex` and `:focus-visible` fixes.

**Will it replace a manual audit?** No. Automated rules catch roughly a third to half of issues; semantics, meaningful alt text, and logical flow still need human review.