# A11Y Audit > Run deterministic accessibility audits and regression gates on web projects, especially large sites with many routes and shared templates. Combines axe-core and optional Lighthouse with template-aware sampling, stable finding fingerprints, accepted baselines, standards evidence mapping (WCAG 2.1 AA default, WCAG 2.2 AA, EN 301 549), manual check guidance, and structured reporting. Output is configurable: markdown report only, markdown plus machine-readable JSON, or markdown plus issue tracker integration. Use this skill whenever the user mentions "accessibility audit", "a11y audit", "WCAG audit", "accessibility check", "compliance scan", "accessibility baseline", "new accessibility regressions", or asks to check a web project for accessibility issues. Also trigger when the user wants evidence for WCAG conformance review or mapping to a specific standard (WCAG 2.2, EN 301 549 / European Accessibility Act, CAN-ASC-6.2, ADA/AODA). - Skill: `snapsynapse/a11y-audit` (Agent Skill, multi-file: 75 files) - Install (CLI): `npx skillmds@latest add snapsynapse/a11y-audit` - Raw SKILL.md: https://api.skillmd.com/api/skills/snapsynapse/a11y-audit/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: snapsynapse (https://skillmd.com/u/snapsynapse) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/snapsynapse/a11y-audit --- # Accessibility Audit ## Architecture This skill operates as a single layer. It reads the project environment, runs automated accessibility tools, maps findings to compliance standards, and produces output in a configurable format. No external skill dependency is required. Store project-specific audit state in the target workspace, not in the installed skill directory. Default path: `.a11y-audit/PROJECT_CONTEXT.md` at the workspace root. When that file exists, use it for project-specific configuration: output mode, additional compliance standards, issue tracker settings, route lists, color palettes, and cross-references to existing documentation. When absent, use WCAG 2.1 AA as the sole standard, `markdown` as the output mode, and generic defaults for everything else. Use `references/project-context-template.md` as the canonical schema for that file, including minimal and `markdown+issues` examples. Prefer bundled helpers over ad hoc generation when they fit: - `scripts/bootstrap-context.js` creates a workspace-local `.a11y-audit/PROJECT_CONTEXT.md` from simple inputs. - `scripts/scan.js` runs reusable axe-based scans and records optional Lighthouse execution intent. Use `--summary` to reduce output size (keeps full violation detail, strips node data from passes/inapplicable). - `scripts/report.js` generates the markdown report and JSON data file from scan.js output. Handles the WCAG evidence matrix, violation aggregation, and color-contrast detail extraction deterministically. - `scripts/discover.js` identifies template groups on large sites and selects representative pages for scanning. Reads sitemap.xml first, falls back to HTML navigation crawl. Outputs a scan plan with template groups and a ready-to-use URL list for scan.js. Discovery is same-origin by default; use `--allow-cross-origin-sitemaps` only after the user approves sitemap-declared cross-origin targets. For flat or irregular route structures, use a reviewed route-group map instead of relying on path depth. Read `references/route-grouping.md` when authoring or reviewing that map. - `scripts/select-changed-surfaces.js` maps an explicit project-owned source-prefix map to exact discovery groups. It narrows an existing plan only if every changed path maps safely. Schema-v2 maps can also include the exact changed page when a reviewed source-to-route transform resolves to an already discovered same-origin URL. Otherwise it preserves the full representative sample and records the fallback reason. Read `references/changed-surfaces.md` when configuring or reviewing this path. - `scripts/run-audit.js` is the vendor-neutral process adapter for external agent systems and CI runners that need one JSON request to compose discovery, selection, scanning, and report generation. Read `references/interoperability.md` when configuring that boundary. For the opt-in terminal JSON and exit-status pilot, read `references/cli-contract.md` before selecting `--contract posix-json-v1`. ### Dependencies Requires Node.js 22.12.0 or later. Run `node --version` before scanning; upgrade unsupported runtimes before dependency installation. The managed bundle pins Puppeteer 25.10.0. For browser cache, skip-download, and v3 migration instructions, read `references/runtime-compatibility.md`. scan.js requires `axe-core` and `puppeteer`. It resolves these in order: 1. **Skill-local** `deps/` directory (sibling to `scripts/`) 2. **Target project** `node_modules/` (and common workspace subdirs) 3. **Global** npm modules If either package is not found anywhere, scan.js **auto-installs the complete scanner dependency set** to the skill-local `deps/` directory in one operation. An existing skill-local Puppeteer that differs from the pinned release also triggers this install, so old managed browser packages are replaced. The default versions use the committed lockfile through `npm ci`; a deliberate `--axe-version` override installs both requested versions without rewriting the committed manifests. Installs make three bounded attempts with backoff and omit npm audit and funding network calls. The `deps/node_modules/` directory is gitignored. The same lockfile pins `http-server` for the reusable Action. When `serve-path` is set, the Action completes `npm ci` before starting the local server and its readiness clock; registry time cannot be misreported as server startup failure. Each attempt defaults to 120000 milliseconds. Raise it with `--install-timeout-ms ` or `A11Y_AUDIT_INSTALL_TIMEOUT_MS` on a slow runner. Timeout diagnostics name the dependency set, elapsed time, limit, and setting; non-zero npm exits remain distinct. Because `scan.js` may auto-install missing dependencies or replace stale skill-local Puppeteer, ask before invoking scan.js when that installation scope has not already been authorized. Include browser downloads in that scope. The bundled scanner supports Puppeteer only. Treat `--browser` as a fixed option, not a user-controlled package installer. **Version pinning and delta integrity.** axe-core rule sets and browser behavior change between releases, so scan.js pins both axe-core and Puppeteer auto-installs to validated versions (`--axe-version ` overrides axe-core deliberately). Every scan records the resolved `axe_version` and `browser_version` in its output JSON, report.js carries `axe_version` into the audit JSON, and the Delta from Previous Audit section flags comparisons where the two audits ran different axe-core versions; rule-set drift between versions must not be presented as site regressions or fixes. When a project-resolved axe-core wins the dependency lookup, its version is recorded the same way. Supplying only one dependency at project level does not suppress installation of the missing package: the complete pinned set is installed skill-locally and used together. ### Platform-Specific References - If running in Claude Code, read `references/claude-code.md` for `.claude/launch.json` handling and Preview tool usage. - If running in Codex, read `references/codex.md` for workspace-local state handling and execution assumptions. - `references/output-contract.md` and `references/output-schema.json` are encoded in `scripts/report.js`. Read them only when modifying the report script. - Read `references/issue-trackers.md` only when `output_mode` is `markdown+issues`. - If the user wants to operationalize recurring audits in CI, start from `assets/ci/github-actions/accessibility-audit.yml`. The upstream Action is exercised as a real consumer and checked with actionlint and zizmor. Discovery is sitemap-first; set `discover-no-sitemap: true` in the Action when a served build must be crawled from `discover-url` instead, then adapt the inputs without copying its implementation into the target repo. For pull-request scope reduction, copy the route-group and ownership-map examples, supply `changed-base` and `changed-head`, and retain both discovery and selection artifacts. - Prefer `scripts/plan-issues.js` before live ticket creation when you need a safe review and deduplication pass. **The skill does not modify source code.** It is an auditor, not a fixer. Findings are reported with remediation guidance; the user decides what to act on. ### Output Modes The skill supports three output modes, configured via the `output_mode` field in `.a11y-audit/PROJECT_CONTEXT.md`: | Mode | Output | Use Case | |------|--------|----------| | `markdown` | Markdown report only | Human review, documentation | | `markdown+json` | Markdown report + JSON data file | CI integration, dashboards, trend tracking | | `markdown+issues` | Markdown report + issue tracker tickets | Active remediation workflow | On first run, if no `output_mode` is set in `.a11y-audit/PROJECT_CONTEXT.md`, ask the user which mode they prefer and persist their choice by appending an `## Output Configuration` section to that file. If no context file exists, create it at the default path following `references/project-context-template.md`. Prefer `scripts/bootstrap-context.js` for first-run context creation when a simple generated file is sufficient. The `markdown+json` mode writes a companion file alongside the report: `audit-YYYY-MM-DD.json` containing the raw axe-core results, Lighthouse scores, and the evidence matrix as structured data. This file is machine-readable and can be consumed by CI pipelines, dashboards, or trend-tracking tools. The `markdown+issues` mode requires additional configuration in the context file (see Phase 6). ### Regression Gate Use `--fail-on major` when the acceptance bar is zero current critical or serious standards findings. This mode evaluates the complete current scan, so an accepted baseline cannot suppress an existing major finding. Moderate, minor, and explicitly best-practice-only findings remain visible and nonblocking. A best-practice tag does not downgrade a rule that also carries a WCAG, EN 301 549, Section 508, or unrecognized tag. Best-practice-only status requires the explicit `best-practice` tag and otherwise only axe `cat.*` tags. Unknown violation impact and critical, serious, or unknown-impact axe `incomplete` candidates produce an inconclusive nonzero result. Moderate and minor incomplete candidates remain advisory. An automated pass applies only to the scanned scope and does not establish full conformance. In major mode, a requested URL that returns an HTTP error or non-HTML response is missing required coverage. The scanner records the page error and an inconclusive gate instead of auditing the error payload as if it were the requested page. Existing modes retain their established response behavior. In the evidence matrix, confirmed violations take precedence as `Fail`; an axe `incomplete` candidate takes precedence over automated passes as `Needs review`. Do not show an unqualified pass for a criterion with unresolved incomplete evidence. For an established site with existing accessibility debt, prefer an accepted baseline over an all-or-nothing gate: ```bash # Create a baseline only after reviewing the current findings. node a11y-audit/scripts/scan.js \ --urls http://127.0.0.1:3000/ \ --write-baseline .a11y-audit/baseline.json # Fail only when the current scan introduces a finding outside it. node a11y-audit/scripts/scan.js \ --urls http://127.0.0.1:3000/ \ --baseline .a11y-audit/baseline.json \ --fail-on new ``` The scanner fingerprints each finding from its axe rule, normalized route, and normalized axe target. Baselines record the axe-core version; version mismatches stop comparison unless deliberately overridden. Never refresh a baseline automatically in CI. Review and commit baseline changes as an explicit acceptance decision. --- ## Pipeline An accessibility audit moves through six phases. Each phase produces data the next phase consumes. Phases 1-4 always run. Phase 5 produces output based on the configured output mode. Phase 6 runs only in `markdown+issues` mode and requires explicit user confirmation. The user can request a partial run. Common patterns: - "Quick scan": Phases 1-2 only, results summarized in conversation - "Full audit": Phases 1-5, output per configured mode - "Audit with issues": Phases 1-6, report plus tracker tickets ### Phase 1 -- Environment Discovery **Purpose:** Understand the project before scanning. 1. Read `.a11y-audit/PROJECT_CONTEXT.md` if it exists (standards, routes, output mode, labels). If absent, create it via `scripts/bootstrap-context.js` or from `references/project-context-template.md`. 2. Read `package.json` for tech stack, existing a11y tooling, and available browser automation (`puppeteer` / `playwright`). 3. Build a scannable URL list from router config or HTML file glob. For sites with many pages (>15 routes), prefer `scripts/discover.js` to classify pages into template groups and select representatives. Review the scan plan with the user before proceeding to Phase 2. 4. Confirm a dev server is reachable. Check `.claude/launch.json` and platform-specific references for launch hints. If the app starts on a different URL than expected, switch to the live URL, record the mismatch, and update the context file. 5. Confirm Node.js 22.12.0 or later and installation authority for missing dependencies, stale managed Puppeteer replacement, and browser downloads. **Output:** Structured summary reported to the user before proceeding. ### Phase 2 -- Automated Scanning **Purpose:** Run automated accessibility checks against live pages. **Prerequisite:** A running dev server (or production URL provided by the user). #### axe-core Scanning Prefer the bundled `scripts/scan.js` before writing a throwaway scan script. Use an ad hoc script only when the workspace needs behavior that the bundled script does not yet support. The reusable scanner should: 1. Imports `puppeteer` and `axe-core` 2. Launches a headless browser 3. For each target URL: a. Navigates to the page b. Waits for network idle (`waitUntil: 'networkidle0'`) c. Injects axe-core: reads the axe-core source file from `node_modules/axe-core/axe.min.js` and injects it via `page.evaluate()` d. Runs the audit: `page.evaluate(() => axe.run())` e. Collects the results JSON 4. Closes the browser 5. Writes raw results to JSON Example invocation: ```bash node a11y-audit/scripts/scan.js \ --root . \ --discover /tmp/a11y-discover.json \ --output /tmp/a11y-scan.json \ --summary ``` **Adapt to the project.** If dependencies live in a frontend subdirectory, point `--root` at the workspace root; the bundled script already checks common frontend paths. If that still fails, fall back to an ad hoc script or run from the frontend directory directly. **Common mistake:** Do not use `require()` in an ES module project. Check `package.json` for `"type": "module"`. If present, use `import` syntax and the `__dirname` workaround in any ad hoc script. If absent, `require()` is fine. **Playwright alternative:** The bundled scanner accepts Puppeteer only. If a separately scoped audit uses an existing Playwright installation, write a project-local adapter and disclose that it is outside the validated bundled scanner path. Keep the installed skill and its pinned manifest intact. #### Lighthouse Scanning Run Lighthouse CLI against each target URL: ```bash npx lighthouse \ --output=json \ --output-path=stdout \ --only-categories=accessibility \ --chrome-flags="--headless --no-sandbox" \ --quiet ``` Parse the JSON output. Extract: - `categories.accessibility.score` (0-1, multiply by 100) - `audits` where `score !== 1` (failed or partial audits) - Each audit's `description` and `details.items` If Lighthouse is unavailable or fails (common in CI environments), skip it and note the gap in the report. In the executive summary and methodology, explicitly say whether Lighthouse was skipped because the CLI was missing, Chrome launch failed, or another runtime error occurred. axe-core results alone are sufficient for a valid audit. #### Scope Control - Default: scan routes discovered in Phase 1 - If a discover.js scan plan exists, pass the plan with `--discover`. The report methodology will record the sampling strategy. - If more than 10 routes exist and no discover plan is available, ask the user which to scan or whether to scan all - The user can provide a specific URL list to override discovery - For SPAs: navigate via the router, not by reloading the page (some routes may not work as direct URLs) #### Result Structure For each page, collect: - `url`: the scanned URL - `violations`: array of axe violations, each with `id`, `impact` (critical/serious/moderate/minor), `description`, `help`, `helpUrl`, `tags` (WCAG criteria), `nodes` (affected elements with selectors) - `passes`: count of passing rules - `incomplete`: rules that could not be fully evaluated - `lighthouseScore`: 0-100 (if available) - `lighthouseAudits`: failed audit details (if available) ### Phase 3 -- Standards Evidence Mapping **Purpose:** Map automated findings to the configured standard's success criteria and any project-specific standards. `scripts/report.js` handles the evidence matrix deterministically. Criteria matrices are data files in `references/standards/`, selected with `--standard `: - `wcag21-aa` (default): all 50 WCAG 2.1 Level A and AA criteria. Cited by the ADA Title II final rule and EN 301 549 V3.2.1. - `wcag22-aa`: all 55 WCAG 2.2 Level A and AA criteria (4.1.1 Parsing removed; 2.4.11, 2.5.7, 2.5.8, 3.2.6, 3.3.7, 3.3.8 added). - `en301549`: EN 301 549 V3.2.1 clause 9 (Web), the harmonised standard under the European Accessibility Act; renders clause numbers alongside the one-to-one WCAG 2.1 criteria mapping. Map the `standards` value in `.a11y-audit/PROJECT_CONTEXT.md` to the matching id (e.g., `WCAG 2.2 AA` → `wcag22-aa`; `EN 301 549` as primary → `en301549`) and pass it via `--standard`. The script maps axe tags to success criteria and produces the matrix in its markdown and JSON output; the JSON records which standard was used. You do not need to build the matrix manually. If `.a11y-audit/PROJECT_CONTEXT.md` specifies additional standards beyond these (e.g., CAN-ASC-6.2), build a secondary mapping. Cross-reference automated findings where the standard maps to WCAG criteria. For requirements that go beyond WCAG (equity, organizational processes, transparency), note them as manual review items referencing the project's existing conformance documentation. ### Phase 4 -- Manual Check Guidance **Purpose:** Generate targeted checklists for what automation cannot verify, prioritized by the automated findings. For each WCAG criterion marked "Manual" in the Phase 3 matrix, generate a testing item. Organize by testing method: Keyboard Navigation, Screen Reader, Visual Inspection, Cognitive, and Timing/Motion. **Dynamic prioritization:** Do not produce a static checklist. Use the Phase 2 results to focus manual effort: - If axe found color-contrast violations, prioritize visual inspection items (SC 1.4.1, 1.4.11, 1.4.10, 1.4.12, 1.4.13) - If axe found ARIA or landmark violations, prioritize screen reader items (SC 1.3.1, 4.1.3, 3.3.1, 3.3.2) - If axe found heading or structure violations, prioritize keyboard navigation items (SC 2.4.3, 2.4.7, 2.1.1) - If no form-related violations were found, deprioritize form testing (SC 3.3.3, 3.3.4) with a note that automated checks passed - Always include timing items (SC 2.2.1, 2.2.2, 2.3.1) since these cannot be automated at all Each checklist item specifies: the WCAG criterion, what to test, how to test it, and which pages to focus on (pages where automated issues were found get priority). If `.a11y-audit/PROJECT_CONTEXT.md` references an existing testing guide, cross-link to it rather than duplicating procedures. ### Phase 5 -- Output Generation **Purpose:** Produce output based on the configured output mode. Run `scripts/report.js` to generate the markdown report and JSON data file from the Phase 2 scan output: ```bash node a11y-audit/scripts/report.js \ --input /tmp/a11y-scan.json \ --output-dir docs/accessibility/audits \ --project-name "Project Name" \ --runtime-url http://127.0.0.1:3000 \ --expected-url http://localhost:3000 \ --discover /tmp/a11y-discover.json ``` Pass `--discover` when a discover.js scan plan was used. This adds a Sampling Strategy subsection to the report methodology documenting template groups and coverage ratio. Pass `--previous ` to generate a Delta from Previous Audit section showing fixed rules, new rules, changed instance counts, and net progress. The script produces `audit-YYYY-MM-DD.md` and `audit-YYYY-MM-DD.json` following the contracts in `references/output-contract.md` and `references/output-schema.json`. You do not need to read those reference files unless modifying the report script itself. After running report.js, review its output and fill in the **Manual Testing Recommendations** section with the Phase 4 guidance (report.js leaves a placeholder for this since it requires reasoning about the specific findings pattern). `.a11y-audit/PROJECT_CONTEXT.md` can override the output path. If the user wants a recurring or on-demand CI job, adapt `assets/ci/github-actions/accessibility-audit.yml` to the target workspace instead of inventing a workflow from scratch. Keep baseline updates outside CI and preserve the Action's discovery and scan artifacts so a failed gate remains reviewable. When using changed-surface selection, also preserve its selection artifact. Do not infer ownership from framework naming: use `references/changed-surfaces.md` and a reviewed map. ### Phase 6 -- Issue Creation (conditional) **Purpose:** Create issue tracker tickets for findings. Runs only when the output mode is `markdown+issues`. **This phase requires explicit user confirmation.** Before creating any tickets, show the user how many will be created, at what priority levels, and ask for approval. Read `references/issue-trackers.md` for tracker configuration, deduplication, priority mapping, and ticket structure. Use the tracker settings from `.a11y-audit/PROJECT_CONTEXT.md`. --- ## Verification After completing an audit, verify these quality checks: 1. **axe results valid**: Compare violation count against a manual axe DevTools browser extension run on the same page. Counts should match within tolerance (axe versions may differ slightly). 2. **Lighthouse score consistent**: Compare against a manual Chrome DevTools Lighthouse run when Lighthouse was actually executed. Should be within 5 points. 3. **Standards matrix complete**: The configured evidence matrix contains the expected criteria count: 50 for `wcag21-aa`, 55 for `wcag22-aa`, or 50 clause-mapped criteria for `en301549`. No criterion is missing. Treat the matrix as evidence-oriented status reporting. Do not frame it as proof of full conformance, because many WCAG criteria remain manual even in a strong automated run. 4. **Report structure**: All required sections present. Tables render correctly in a markdown viewer. 5. **JSON validity** (`markdown+json` mode): JSON file parses without error. Violation counts match the markdown report. 6. **Issue deduplication** (`markdown+issues` mode): Run the skill twice. The second run should create zero duplicate tickets. 7. **Output mode persistence**: After first run, verify the output mode is saved to `.a11y-audit/PROJECT_CONTEXT.md` and used automatically on next run. 8. **Runtime URL reconciliation**: If the app started on a different local URL than expected, verify the report records the mismatch and the context file reflects the actual working `base_url`. --- ## What This Skill Does NOT Do - **Visual regression testing**: does not compare screenshots between runs. Use Percy, Chromatic, or BackstopJS for that. - **PDF accessibility**: does not audit PDF documents for tagged structure, reading order, or alternative text. - **Real device/AT testing**: runs in headless Chromium only. Cannot test on real iOS/Android or with real screen readers. Phase 4 generates manual checklists for this. - **Code fixes**: reports findings but does not modify source code. - **VPAT generation**: does not produce Voluntary Product Accessibility Templates (specific legal format). - **Hosted continuous monitoring**: no scheduled scanning service or dashboard. CI gating *is* supported: the repo ships a composite GitHub Action (`.github/actions/scan`) that runs the scanner on push/PR and can fail on all violations or only findings outside an accepted baseline, plus a workflow starter at `assets/ci/github-actions/accessibility-audit.yml`. The upstream repository exercises the composite Action end to end and runs workflow semantic and security checks. The `markdown+json` output mode provides structured data for building further integrations. - **Third-party auditing**: only audits the project's own frontend, not embedded third-party services.