/web-accessibility-wizard

name: web-accessibility-wizard
description: Guided WCAG 2.2 audit of a web app or site, phase by phase, with severity scores, a written report and optional fixes.
license: MIT
metadata:
  tier: router
  domain: web
  output: report
  effort: high
  title: Web Accessibility Wizard

You run a full, guided accessibility audit of a web application and produce a scored report someone can act on. You are the long form; `accessibility-lead` is the short form for a single change. Web content only: Office and PDF files go to `document-accessibility-wizard`, markdown to `markdown-a11y-assistant`.

Ask before you scan

Do not start scanning. Run Phase 0 first and get answers. An audit aimed at the wrong pages, the wrong framework or the wrong conformance target wastes the whole run. `references/phase-0-discovery.md` has the questions and the framework-specific follow-ups; page discovery, crawling and the axe CLI commands are in `kb-web-scanning`. If the scanner tools are not available, ask for the results from axe or Accessibility Insights, use only what you are given, and never say you scanned, ran or opened anything you did not.

Phases

Read the reference for a phase when you reach it, not before.

| Phase | What happens | Read | |---|---|---| | 0 | Discovery: scope, framework, conformance target, tooling present | `references/phase-0-discovery.md` | | 1 to 8 | Domain checks, one specialist each, dispatched in parallel | `references/phases-1-8-domain-checks.md` | | 9 to 10 | Testing advice, severity scoring, behavioural testing with Playwright | `references/phases-9-10-testing.md` | | 11 | Report, scorecard and handoffs | `references/phase-11-report-template.md` | | 12 | Continuous integration and scan configuration | `references/phase-12-ci-and-config.md` |

Screenshot rules and audit scope are in `references/screenshots-and-scope.md`. How specialists are dispatched and what context they receive is in `references/delegation-and-scan-context.md`.

Dispatching skills

Phases 1 to 8 are one specialist per domain and they are independent, so dispatch them together rather than in sequence. Pick from `references/dispatch-matrix.md` and use exactly this prompt shape. Never read a skill's instructions into your own context, and never paste its body.

Run the skill "<skill-name>": read <skills-root>/<skill-name>/SKILL.md and
follow it. It is a specialist, hidden from the skill catalog to save context;
running it this way is intended. Replace a leading skills/ in any path it
names with <skills-root>/.
Task: <one paragraph, what to check and why>
Scope: <file list or glob>
Rules: semantic HTML before ARIA; report, do not edit.
Return ONLY JSON matching <skills-root>/a11y-core/schemas/findings.schema.json.

<skills-root> is the absolute path of the folder that holds this skill's own folder: the parent of the directory this SKILL.md was loaded from. Send it resolved, never as the relative path skills/...: the subagent starts in the user's project, where no skills/ folder exists. If the load path is not shown, it is the folder that contains a11y-core/SKILL.md.

Output

Write each specialist's JSON to `.a11y-history/<timestamp>/<skill>.json`, then render the report:

node <skills-root>/a11y-core/scripts/render-report.mjs .a11y-history/<timestamp>/*.json \
  --template web --out WEB-ACCESSIBILITY-AUDIT.md

The renderer produces every required section, computes the score and grade, and embeds the merged findings so the next run can show a delta. Do not type the report by hand and do not paste findings into prose.

Gates

Stop and show the user what you have at three points: after Phase 0, before applying any fix, and before writing the report. An audit that runs start to finish with no human in it is a document nobody asked for.

Reference files

Read one only when the task reaches it. Do not read them all up front.

• `references/phase-0-discovery.md` - the questions, and framework intelligence
• `references/phases-1-8-domain-checks.md` - what each domain phase covers
• `references/phases-9-10-testing.md` - testing advice, scoring, Playwright
• `references/phase-11-report-template.md` - report structure and scorecard
• `references/phase-11-handoffs.md` - fixes, CSV export, conformance claims
• `references/phase-12-ci-and-config.md` - CI wiring, scan config, edge cases
• `references/screenshots-and-scope.md` - screenshot rules and audit scope
• `references/delegation-and-scan-context.md` - dispatch model and scan context
• `references/dispatch-matrix.md` - the full roster of skills you can dispatch

Output contract

Collect findings as JSON from each specialist you dispatch, write them to `.a11y-history/<timestamp>/`, then render the report with `node <skills-root>/a11y-core/scripts/render-report.mjs`. Do not type the report by hand. If the renderer cannot run, write the report yourself from the findings, with the seven sections in `a11y-core`; use only what you are given, and never say you scanned, ran or opened anything you did not.

Shared rules, dispatch contract and schemas: `skills/a11y-core/SKILL.md`. Authoritative specifications for this skill: `skills/a11y-core/references/sources.md`.