# a11y-audit

> Drop-in accessibility audit skill for AI coding agents. WCAG 2.1 AA
> compliance scanning with template-aware page sampling, shared-template
> detection, remediation hints, and progress tracking.

## What this skill does

- Scans web projects for WCAG 2.1 AA accessibility violations using axe-core
- Discovers site structure via sitemap.xml (or HTML crawl fallback)
- Classifies pages into template groups and selects representatives
- Produces structured reports with prioritized findings and fix guidance
- Tracks progress between audits (delta comparison)
- Auto-installs its own dependencies (axe-core, Puppeteer)

## How to use

Install: copy `a11y-audit/` into `.claude/skills/` (Claude Code) or
your agent's skills directory.

Prompt: "Run an accessibility audit on this project."

Or run scripts directly:

- `scripts/discover.js --url <base-url>`: discover pages and select representatives
- `scripts/scan.js --urls <url-list>`: scan pages with axe-core
- `scripts/report.js --input <scan.json>`: generate markdown + JSON report

## Key files

- [Assistant Guide](https://skilla11y.dev/.well-known/assistant-guide.txt): bounded assistant install, audit execution, and maintenance instructions
- [SKILL.md](https://github.com/snapsynapse/skill-a11y-audit/blob/main/a11y-audit/SKILL.md): core skill instructions
- [scripts](https://github.com/snapsynapse/skill-a11y-audit/tree/main/a11y-audit/scripts): discover.js, scan.js, report.js, bootstrap-context.js, plan-issues.js
- [output contract](https://github.com/snapsynapse/skill-a11y-audit/blob/main/a11y-audit/references/output-contract.md): report format specification
- [output schema](https://github.com/snapsynapse/skill-a11y-audit/blob/main/a11y-audit/references/output-schema.json): JSON output schema
- [sample output](https://github.com/snapsynapse/skill-a11y-audit/tree/main/a11y-audit/assets/sample-output): example report from a real site audit
- [CHANGELOG](https://github.com/snapsynapse/skill-a11y-audit/blob/main/a11y-audit/CHANGELOG.md): version history
- [MANIFEST](https://github.com/snapsynapse/skill-a11y-audit/blob/main/a11y-audit/MANIFEST.yaml): bundle inventory

## Report sections

1. Executive Summary (severity counts)
2. Findings by Rule (violation details, WCAG mapping)
3. Quick Fixes (one-liner remediation per rule)
4. Color Contrast Details (exact ratios and selectors)
5. WCAG 2.1 AA Compliance Matrix (50 success criteria)
6. Delta from Previous Audit (fixed, new, changed)
7. Remediation Priority (ranked by severity)
8. Sampling Strategy (template groups and coverage)
9. Shared Template Patterns (which groups share issues)

## Output modes

- `markdown`: report only
- `markdown+json`: report + machine-readable data
- `markdown+issues`: report + GitHub/GitLab/Linear/Jira tickets

## Compatibility

- Claude Code (tested, primary target)
- OpenAI Codex (tested, partial)
- Any agent that reads markdown skill files