a11y-audit

What this skill does

# 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 WCAG compliance 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.

### Dependencies

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 not found anywhere, scan.js **auto-installs** both packages to the
skill-local `deps/` directory. This means the skill works against any
project without requiring the target to have accessibility tooling
installed. The `deps/` directory is gitignored.

Because `scan.js` may auto-install missing dependencies, agents should
ask before invoking scan.js when the target workspace does not already
provide `axe-core` and the chosen browser automation package.

The bundled scanner supports Puppeteer only. Treat `--browser` as a
fixed option, not a user-controlled package installer.

### 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`.
- 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 compliance 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).

---

## 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. Ask before installing any missing dependencies.

**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 . \
  --urls http://127.0.0.1:3000/,http://127.0.0.1:3000/about \
  --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