Prevent new accessibility barriers across large web estates.
Open, self-hosted regression evidence for maintainers and coding agents. Template-aware sampling, stable findings, and legacy-friendly CI.
Authenticated scan inputs support cookies and local storage with explicit URL/readiness assertions. Discovery remains unauthenticated; deterministic journeys remain future work.
v3.2.0 requires Node.js 22.12.0 or later and uses Puppeteer 25.10.0. Read the release notes. GitHub installs fetch main; the Action examples pin this release.
Strict accessibility gates are hard to adopt when a site already has debt. skill-a11y-audit discovers representative templates, preserves selector-level evidence, and can block only newly introduced findings instead of demanding a perfect first run.
Historical run on the EveryAILaw sitemap, recorded before v3.
Why skill-a11y-audit?
Framework tests cover components and enterprise platforms cover full programs. skill-a11y-audit occupies the repository-native middle: deterministic evidence across large public sites without a hosted dashboard or a zero-violation prerequisite.
Template-aware sampling
Large sites have hundreds of pages but only a handful of distinct templates. The skill identifies your templates, scans representatives from each group, and maps every violation to the template it affects. Fix one component; resolve issues across hundreds of pages.
Legacy-friendly regression gates
Review and commit the current findings as an accepted baseline, then fail CI only when a change introduces a new rule, route, and selector fingerprint. Existing debt stays visible without blocking adoption.
Portable process boundary
Invoke discovery, changed-surface selection, scanning, and reporting through one versioned JSON request. Existing CI runners and agent systems can consume the native artifacts without adopting a vendor-specific orchestration layer.
Where it fits
This is deliberately narrower than an accessibility-agent suite and lighter than an enterprise monitoring platform. It handles the repository-native regression layer between them.
| Layer | Best for | What this project adds |
|---|---|---|
| Storybook, Playwright, axe | Components, states, and authored test journeys | Site-wide route discovery and deterministic template representatives |
| Accessibility agent suites | Guidance, remediation, standards research, and broad orchestration | A small executable evidence pipeline they can invoke without recreating scan logic |
| Enterprise platforms | Hosted monitoring, dashboards, manual programs, and organizational reporting | Open, self-hosted artifacts and CI policy stored with the repository |
Best fit: public sites, documentation systems, government information services, static generators, and content estates with many URLs generated by shared templates.
Adopt the gate without fixing everything first
A baseline is an explicit record of accepted findings; it is not a claim that they are harmless. Review it, commit it, and let CI reject only newly introduced rule, route, and selector fingerprints.
1. Create a reviewed baseline
Replace: TARGET_URL → reachable URL approved for this audit.
Customize
node a11y-audit/scripts/scan.js \ --urls TARGET_URL \ --write-baseline .a11y-audit/baseline.json
Create or update this file only after reviewing the current findings.
2. Block new barriers
Replace: TARGET_URL → reachable URL approved for this audit.
Customize
node a11y-audit/scripts/scan.js \ --urls TARGET_URL \ --baseline .a11y-audit/baseline.json \ --fail-on new
The scan reports accepted, new, and resolved findings and guards axe-core version drift.
3. Reuse the GitHub Action
Replace: BUILD_DIR → repository-relative directory containing the built site.
Customize
- uses: snapsynapse/skill-a11y-audit/.github/actions/scan@v3.2.0
with:
serve-path: BUILD_DIR
discover-url: http://127.0.0.1:8088/
discover-group-map: .a11y-audit/route-group-map.json
surface-map: .a11y-audit/surface-map.json
changed-base: ${{ github.event.pull_request.base.sha }}
changed-head: ${{ github.event.pull_request.head.sha }}
baseline: .a11y-audit/baseline.json
fail-on: new
Fetch full Git history before supplying base and head SHAs. The workflow starter includes that checkout setting. Reviewed route patterns group flat or irregular sites, and a schema-v2 ownership map can include the directly changed page when it already appears in discovery. Unsafe route grouping scans every discovered URL. Unsafe ownership, missing history, and shared-code rules retain the complete representative plan.
Install
Requires Node.js 22.12.0 or later. The v3 Action defaults to Node 22.
Upgrading from v2
Upgrade Node before installing or scanning. The managed graph pins Puppeteer 25.10.0 and removes extract-zip. Existing stale skill-local Puppeteer is replaced through the committed lockfile. Project and global fallback packages need their own dependency review.
axe-core stays at 4.12.1. Review any changed findings before updating an accepted baseline. Browser installation downloads the matching Chrome; PUPPETEER_SKIP_DOWNLOAD=true requires that browser already available in the configured cache.
Options are listed from simplest to most manual. The reviewed assistant acquisition uses a plain-text, hash-pinned GuideCheck guide your assistant verifies and you approve before anything runs. Guide 0.3.17 uses release-specific source acquisition and passes local verification. Verify the hosted result and exact guide hash before use.
1. Reviewed assistant install
Literal
Fetch and verify https://skilla11y.dev/.well-known/assistant-guide.txt with GuideCheck (https://guidecheck.org/verify), report the achieved level and SHA-256, then follow its acquisition action with my approval.
Guide 0.3.17 passes local GuideCheck 0.7.0 and current 0.7.1 evaluation at Level 3. Local evaluation is not hosted acceptance; verify the deployed guide and report its exact hash before use. The guide clones source without registering an agent-client skill. Use the Skills CLI for registration. Every action requires approval. Read and verify the guide before use.
2. Interactive install (recommended)
Literal
npx skills add \ snapsynapse/skill-a11y-audit \ --skill a11y-audit
The open Skills CLI detects supported agents and lets you choose project or global scope. Review the source, then select Claude Code, Codex, or another supported agent.
Try without installing
Literal
npx skills use \ snapsynapse/skill-a11y-audit \ --skill a11y-audit
The CLI prepares a temporary skill invocation and leaves no persistent project installation.
3. Choose an agent
Literal
# Claude Code, current project npx skills add \ snapsynapse/skill-a11y-audit \ --skill a11y-audit \ --agent claude-code \ --yes # Codex, current project npx skills add \ snapsynapse/skill-a11y-audit \ --skill a11y-audit \ --agent codex \ --yes
Add --global to make the skill available across projects.
4. Manual fallback
Claude project: .claude/skills/a11y-audit/ Claude personal: ~/.claude/skills/a11y-audit/ Codex project: .agents/skills/a11y-audit/ Codex personal: ~/.agents/skills/a11y-audit/
Copy the repository's a11y-audit/ folder to one of these supported locations.
Then: ask your coding agent
Literal
Run an accessibility audit on this project.
The skill runs discover → scan → report automatically.
5. Run from a repository clone
Replace: TARGET_URL → reachable URL approved for this audit.
Customize
node a11y-audit/scripts/discover.js \ --url TARGET_URL \ --output /tmp/discover.json node a11y-audit/scripts/scan.js \ --discover /tmp/discover.json \ --root . --summary \ --output /tmp/scan.json node a11y-audit/scripts/report.js \ --input /tmp/scan.json \ --output-dir ./audits
These paths assume the repository is cloned locally. Each script writes JSON the next step reads.
External runners can instead invoke scripts/run-audit.js with one reviewed JSON request. Read the interoperability contract.
For automation, the experimental --contract posix-json-v1 adapter mode emits one terminal JSON result and keeps operational failures distinct from gate outcomes. Existing commands keep their defaults. Read the opt-in CLI contract.
Sample output
A structured markdown report plus versioned JSON. Configure output_mode in .a11y-audit/PROJECT_CONTEXT.md; direct report.js runs write both files. The excerpt below is illustrative and abridged, not a verbatim report.
## Executive Summary Pages scanned: 22 of 746 · Template groups: 16 Violations: 3 · Severity: 2 serious, 1 moderate Baseline: 27 accepted · 1 new · 2 resolved ## Findings by Rule Rule Impact Instances Affects color-contrast serious 6 regulation/*, requires/* aria-required-attr serious 2 nav, footer landmark-one-main moderate 1 homepage ## Shared Template Patterns Shared issues on regulation/*, requires/*: color-contrast → Fix the shared build template once → resolves across 116 pages.
What it does not claim
Not certification
Automated evidence does not prove WCAG or legal conformance. Reports identify manual checks that still require people and assistive technology.
Not an automatic fixer
The project preserves an auditor/fixer boundary. It reports evidence and remediation guidance but does not modify application source.
Not hosted monitoring
Artifacts and policy stay in your repository. Use an enterprise platform when you need dashboards, organizational workflows, or managed manual testing.