WCAG Audit
You are auditing a user interface for accessibility barriers and fixing them. Disabled users cannot work around a missing label the way a sighted mouse user can: treat each confirmed finding as a real bug that blocks a real person.
Goal: a list of verified findings, each tied to a WCAG 2.2 success criterion, with a precise location, evidence and a minimal fix — and then the fixes, applied and re-verified.
Principles
- Verified or it does not ship. Every finding must survive Phase 3. A short list of true issues beats a long list the user learns to ignore.
- Native HTML first. The best ARIA is no ARIA. Fix
<div onClick>by making it a<button>, not by bolting onrole,tabindexand key handlers. - Minimal, behavior-preserving fixes. Change the markup that fails; do not restyle, refactor or reformat surrounding code. Keep visual design unchanged unless the finding is visual (contrast, focus ring, target size).
- Never invent content. Alt text, labels and link text must reflect what the UI
actually means. If you cannot tell what an image conveys, mark the finding
needs_validationand ask; do not writealt="image". - Automation is a floor, not a ceiling. Tools catch roughly a third to half of WCAG failures. Report what was not tested (see the manual checklist).
Setup
Decide the scope from the user's request: whole repo, a directory, specific components, or a URL. Then check tooling:
npx --yes @mintwork/wcag-audit-skill --version # CLI available?
If the CLI is unavailable (offline, no Node), continue in manual mode: apply the rule list in references/RULES.md by reading the source yourself, and skip Phase 2 unless the user's environment offers another browser tool.
Write all artifacts to .wcag-audit/ at the repository root (create it; suggest adding it
to .gitignore, keeping .wcag-audit/baseline.json if the project commits a CI baseline).
Never write anywhere else unless the user asks.
Workflow
Run the phases in order. Tell the user which phase you are in. For small scopes (one component) phases can be brief, but do not skip Phase 3.
Phase 1 — Static scan (source)
npx @mintwork/wcag-audit-skill scan <path> --json -o .wcag-audit/static.json --fail-on none
Audit without --baseline even if the project commits one (.wcag-audit/baseline.json): the
baseline only lets CI ignore known findings, and they still need review.
Then read references/STATIC-SCAN.md and do the review the tool
cannot: custom components that wrap native elements, conditional rendering, design-system
props (<Icon label=…>), focus styles removed in CSS-in-JS or replaced in another stylesheet
(the CLI checks .css / .scss / .less and Tailwind classes one file at a time), color-only state, and
anything the scanner skipped because of spread props or dynamic values. Add those as
candidate findings with "source": "static" and "confidence": "medium".
Phase 2 — Runtime scan (real browser)
Only if a URL is available or the app can be started. Find the dev command
(package.json scripts, README), start it in the background, wait for it to respond, then:
npx @mintwork/wcag-audit-skill scan http://localhost:3000 --source src --json -o .wcag-audit/runtime.json --fail-on none
# More pages / states:
npx @mintwork/wcag-audit-skill scan http://localhost:3000/login http://localhost:3000/cart --json -o .wcag-audit/runtime-2.json --fail-on none
Scan the pages that matter (home, primary flows, forms, modals open) — see
references/RUNTIME-SCAN.md for states to cover, SPA waits
and auth. Put states (open a modal, submit an empty form, dark mode, 320px) in a config and
run scan --config .wcag-audit/config.json; for logged-in pages use --storage-state <file>
from the user, never credentials. If the project has Storybook, also run
scan --storybook storybook-static (or the running Storybook URL) to cover every component
state. Each runtime finding's sourceHint is a search result: confirm it before fixing there.
Runtime findings catch what static analysis cannot: computed contrast, real accessible
names, focus order, keyboard traps, invisible focus.
Phase 3 — Verification (remove false positives)
For every candidate, follow references/VERIFICATION.md. Try to disprove it: open the source at the reported line, trace props/slots/spreads to where the value is set, check whether a parent supplies the label, check the rendered DOM for runtime findings. Assign one verdict:
confirmed— you traced it and it fails the criterion. Record how you know.needs_validation— plausible but you could not establish it (e.g. alt text quality, content you cannot see, a page you cannot reach). No fix is applied.rejected— disproved. Record why (this teaches the user which rules to tune).
Merge duplicates: the same root cause reported by static and runtime is one finding with both locations.
Phase 4 — Fix
Fix confirmed findings, highest severity first, using
references/FIX-PATTERNS.md. For each fix:
- Make the smallest change that satisfies the criterion, in the framework's idiom
(
htmlForin React,:aria-labelin Vue, etc.). - Explain it in one or two sentences: what was wrong, who it affected, what changed.
- Ask before fixes that change visible UI or copy (contrast colors, new visible labels, link text) unless the user already said to go ahead.
Mechanical findings (html-lang repairs, meta-viewport-zoom, aria-attr-valid typos) can be
fixed by the CLI: run scan <path> --dry-run, show the user the diff, then scan <path> --fix.
A missing lang is only added with --lang <code> once you know the page's language.
Then re-verify mechanically:
npx @mintwork/wcag-audit-skill verify .wcag-audit/static.json
npx @mintwork/wcag-audit-skill verify .wcag-audit/runtime.json # dev server still running
verify exits non-zero if anything remains or a fix introduced a new finding. Iterate
until the confirmed findings are resolved or you have explained why one cannot be fixed
in code (e.g. needs captions content from the user). Run the project's own tests/lint.
Phase 5 — Report
Write .wcag-audit/findings.json conforming to
assets/report-schema.json and validate it:
node <skill-dir>/scripts/validate-findings.mjs .wcag-audit/findings.json
Then write .wcag-audit/REPORT.md and give the user a short summary, following
references/REPORTING.md: counts by severity and verdict, what
was fixed, what needs their input, what was not tested.
Severity
| Severity | Meaning | Examples |
|---|---|---|
| critical | Blocks a task entirely for some users | unlabeled form field, <div onClick> as the only way to submit, keyboard trap, zoom disabled |
| serious | Major difficulty or missing information | low contrast body text, missing page language, link with no name |
| moderate | Friction, confusing structure | skipped heading levels, redundant or vague link text in context |
| minor | Polish, best practice | vague alt text, autofocus |
Severity reflects user impact in this UI, not the rule's default: an unlabeled search box in a footer is less severe than an unlabeled password field on the login page.
Anti-patterns (do not)
- Do not add
aria-labelthat duplicates or contradicts visible text (breaks WCAG 2.5.3). - Do not add
role="button"+tabindex="0"when<button>works. - Do not "fix" a heading-order finding by changing visual size; change the level and keep the CSS.
- Do not set
alt=""on informative images to silence the scanner. - Do not suppress findings (
wcag-audit-ignore) without a written reason next to the comment. - Do not claim WCAG "compliance" — automated + agent review can show failures, not conformance.
- Do not modify generated, vendored or
node_modulescode; fix the source component.
Files
- references/RULES.md — every static and runtime rule, mapped to WCAG
- references/STATIC-SCAN.md — Phase 1 manual review by framework
- references/RUNTIME-SCAN.md — Phase 2 pages, states, SPAs, auth
- references/VERIFICATION.md — Phase 3 disproof procedure per rule
- references/FIX-PATTERNS.md — Phase 4 before/after fixes
- references/REPORTING.md — Phase 5 report format
- references/MANUAL-CHECKLIST.md — what automation cannot check
- assets/report-schema.json — findings.json schema
scripts/validate-findings.mjs— zero-dependency validator for findings.json