a11y-audit

a11y-audit is a WCAG 2.2 AA accessibility auditing workflow for coding agents. It combines source analysis, Playwright + axe-core, stateful journeys, design-token checks, baselines, and CI while keeping human judgment in the loop.

Instead of returning an unordered list of violations, a11y-audit organizes findings by what should happen next:

• Safe to fix now — changes an agent can make after you approve them.
• Needs your decision — issues that depend on product, content, or design intent.
• Test it yourself — checks that need a person, a browser, or assistive technology. Automated tools can only evaluate part of WCAG, so each report identifies the media, interaction, and cross-page checks that still require separate review.

Quick start

For demo purposes, the repository includes intentionally inaccessible fixtures. This allows you to run the complete source-audit workflow without setting up another application:

git clone https://github.com/kicobi/a11y-skill.git
cd a11y-skill
python3 .agents/skills/a11y-audit/scripts/cli.py audit \
  --path .agents/skills/a11y-audit/fixtures/html-basic \
  --output-dir /tmp/a11y-audit-demo

Open /tmp/a11y-audit-demo/report.md for the full actionable report or /tmp/a11y-audit-demo/summary.md for the compact CI/PR view. This example is source-only and requires no package installation.

How to install it

Claude.ai

Download a11y-audit.skill from the latest release, then upload it in Claude.ai under Settings → Skills.

Codex

Clone this repository, then copy the skill into the standard user-level skills directory:

git clone https://github.com/kicobi/a11y-skill.git
mkdir -p ~/.agents/skills
cp -R a11y-skill/.agents/skills/a11y-audit ~/.agents/skills/

Restart Codex after installing it. For a project-scoped installation, copy the directory to <project>/.agents/skills/a11y-audit instead.

Claude Code

From a cloned checkout:

mkdir -p ~/.claude/skills
cp -R .agents/skills/a11y-audit ~/.claude/skills/

During development, ./scripts/install-user.sh symlinks the current checkout into ~/.claude/skills/a11y-audit; pass --copy if you prefer a snapshot.

Use with an agent

The skill is designed to trigger on accessibility work and responds to natural requests:

Run an accessibility audit on this project.
Audit the source and http://localhost:3000/settings.
Check this pull request for accessibility regressions.

After a run, use one of the next actions listed in the report:

apply the safe fixes
walk me through the decisions
give me the checklist
save the baseline
run the CI check

The agent pauses before editing source, works decision-dependent findings one at a time, and keeps manual testing separate from automated claims.

Run directly

Run the public orchestrator from the repository root. Python 3.8 or newer is enough for the default source-only audit.

Audit source code:

python3 .agents/skills/a11y-audit/scripts/cli.py audit \
  --path src \
  --output-dir .artifacts/a11y/latest

The source scanner uses its portable regex engine by default. To opt into syntax-aware parsing for HTML, JSX/TSX, Vue, Angular, and Svelte, add --static-engine parser. Repositories with generated, vendored, or unsupported syntax can supply a versioned exclusion file; exclusions are counted in the report rather than hidden:

python3 .agents/skills/a11y-audit/scripts/cli.py audit \
  --path src \
  --static-engine parser \
  --static-config .a11y/static.config.json \
  --output-dir .artifacts/a11y/latest

The static configuration reference documents the exclusion format and fail-closed parser behavior.

Audit a running page. This also needs Node.js and npm; Playwright, Chromium, axe-core, and YAML support are installed into the skill's private cache on first use:

python3 .agents/skills/a11y-audit/scripts/cli.py audit \
  --url http://localhost:3000 \
  --output-dir .artifacts/a11y/latest

For a repeatable full audit, keep the existing inputs in one project file:

{
  "format": "a11y-audit-project-v1",
  "defaults": {
    "path": "..",
    "url": "http://localhost:3000",
    "static_engine": "parser",
    "runtime_config": "runtime.config.json",
    "journey_config": "journey.config.yaml",
    "token_file": "tokens.json",
    "status_file": "status.json",
    "baseline_file": "baseline.json"
  },
  "audit": {
    "mode": "full",
    "output_dir": "../.artifacts/a11y/latest"
  },
  "ci": {
    "changed_files": "changed-files.txt",
    "output_dir": "../.artifacts/a11y/ci",
    "exit_codes": true
  }
}

Save it as .a11y/audit.json, then run:

python3 .agents/skills/a11y-audit/scripts/cli.py audit \
  --config .a11y/audit.json

Paths in the file resolve from its directory, and explicit CLI options override configured values. The CLI does not discover project files automatically. See the project configuration reference for the complete schema, precedence rules, CI policy, and artifact provenance.

Every audit writes a portable artifact package containing report.md, report.json, summary.md, manifest.json, raw scanner output, copied and redacted inputs, and any captured evidence.

How it works

1. Collect evidence. The orchestrator can inspect source files, rendered pages, interaction journeys, and supported design-token files.
2. Normalize findings. Results carry WCAG mappings, impact, confidence, evidence sources, and source locations when they can be established reliably, including optional verified source-map locations from instrumented builds.
3. Route the work. Findings are separated into safe changes, decisions that require intent, and tests that require a person.
4. Package the result. Each run produces reviewable artifacts that can be promoted to a baseline or summarized for CI and pull requests.

The public interface is small: use audit for local work, ci for regression checks, and promote-baseline to save a reviewed report without scanning again. The lower-level scanners remain available for fixtures and debugging.

What it checks

• Source code for issues such as missing image alternatives, unlabeled controls, clickable non-interactive elements, unsafe focus styles, positive tabindex, redundant ARIA, and selected contrast problems.
• Rendered pages with Playwright and axe-core's WCAG 2.2 A/AA and best-practice rules.
• Interaction states such as modals, validation, and route changes through repeatable journey files.
• Supported design-token JSON—including explicit DTCG color and multi-file Style Dictionary manifests—for contrast pairs, focus indicators, and color-only semantic states.
• Regressions against a saved baseline, including waivers, stable fingerprints, changed-file scoping, and deterministic CI exit codes.

For exact coverage boundaries, configuration formats, and advanced commands, read the detailed skill documentation, token input schema, and WCAG coverage matrix.

Baselines and CI

Promote a reviewed report to the regression baseline without scanning again:

python3 .agents/skills/a11y-audit/scripts/cli.py promote-baseline \
  --report .artifacts/a11y/latest/report.json \
  --baseline-file .a11y/baseline.json

Then run the CI/PR workflow against it:

python3 .agents/skills/a11y-audit/scripts/cli.py ci \
  --config .a11y/audit.json

With a baseline, the default CI policy blocks new findings that are serious or critical and have high-confidence source mapping. Manual findings remain non-blocking unless you opt in.

Requirements and limits

• Python 3.8+ for static scans, token scans, triage, reports, baselines, and CI.
• Node.js 22.12+ or 24+ and npm for parser-backed static scans; Node.js 22+ for runtime/stateful browser scans. CI verifies these workflows on Node.js 22 and 24 LTS.
• Network access on the first parser- or browser-backed run so pinned dependencies (and Chromium for browser scans) can be installed.
• Real assistive-technology testing is still required; automated checks cover only part of accessibility work.
• This project does not certify legal compliance with WCAG, ADA, Section 508, EN 301 549, or the EAA.

Develop the skill

The editable source of truth is .agents/skills/a11y-audit. Packaged .skill files are release artifacts; do not edit them directly.

Run the fast regression suite and syntax checks from the repository root:

python3 .agents/skills/a11y-audit/fixtures/run_fixtures.py
python3 .agents/skills/a11y-audit/scripts/a11y_scan.py \
  .agents/skills/a11y-audit/fixtures/html-basic \
  --quiet \
  --output /tmp/a11y-static.json
node --check .agents/skills/a11y-audit/scripts/a11y_runtime.js
node --check .agents/skills/a11y-audit/scripts/a11y_stateful.js
node --check .agents/skills/a11y-audit/scripts/a11y_parser.js

Run python3 .agents/skills/a11y-audit/fixtures/run_fixtures.py --live-runtime to include parser adapters, real Chromium, and axe-core checks. The first run installs the pinned dependencies; later runs reuse the cache.

Build the release archive with:

bash scripts/pack.sh dist/a11y-audit.skill

See AGENTS.md for contribution constraints, PLAN.md for milestone status, docs/trd.md for the product requirements, and decisions/ for architecture decisions.

Background

The case study Transforming accessibility flags into action describes the product rationale behind fix-autonomy triage and the lessons that shaped the workflow.

License

MIT © 2026 Colin Lewis.