git:20260903.ac7d02a to git:20260903.c54504d

---

name: web-accessibility-audit

description: 'Use when the user requests an accessibility audit, a11y check, or WCAG compliance review. Returns a prioritized WCAG findings report with file and line locations, before and after code fixes, and manual testing recommendations. Don''t use for tasks that require source or remote-system changes.'

---

# Web accessibility audit

## Contract

| Field | Bound contract |

|---|---|

| Trigger | Accessibility audit, a11y check, or WCAG compliance review |

| Authority | Read-only: read project files and run only analysis tools already installed in the project; create, modify, or delete no file; no VCS, credential, paid, publishing, deployment, or remote mutation; install no package |

| Side effect | None: the only artifact is the accessibility report returned in the conversation |

| Done | Report contains prioritized WCAG findings with file/line locations, before/after code, and manual testing recommendations |

## Inputs

- Audit scope: directories, files, or a running URL named by the user. When none is named, the audit targets the web/UI source rooted at the current working directory, the scope the underlying inspection commands use.

- Target WCAG level, optional: A, AA, or AAA as named by the user. When none is named, findings are scored against Level A (must pass) and Level AA (should pass; legal baseline in many jurisdictions), and the report states that basis.

- Nothing is installed or configured; every step runs on present source and, where available, already-installed tooling.

## Procedure

1. Bound the scope before inspecting: enumerate the target directories and files, or the single URL, and reject anything outside it. Read-only throughout: never write a file, never redirect tool output to disk, never install. Done when: scope is enumerated and bounded.

2. Static inspection. For each of the twelve WCAG inspection classes in `references/inspection-classes.md`, search the in-scope markup, components, and styles, open every hit at its location to confirm it, and record confirmed violations as `path:line`. Done when: all twelve classes are inspected and confirmed violations are recorded.

3. Automated scanning, only with tooling already present in the project. Follow the per-tool instructions in `references/fixes-and-scanning.md` (eslint/jsx-a11y, Lighthouse, axe-core). Absent tooling is recorded as absent; never install, never fetch, never write result files. Done when: all available automated tools are run and their results are folded into the matching inspection classes.

4. Prioritize every confirmed finding by user impact using the severity tiers in `references/fixes-and-scanning.md` (Critical, Serious, Moderate, Minor). Done when: every confirmed finding is assigned a severity tier.

5. Write each fix as before/after code taken from the actual file, following the canonical fix patterns in `references/fixes-and-scanning.md`. Done when: every finding has a before/after code fix from the actual source.

6. Include the manual testing recommendations from `references/fixes-and-scanning.md` in every report. Done when: manual testing recommendations are included.

## Failure and recovery

- Scope missing or target is not web/UI source: stop and request a scope; never scan unrelated trees.

- Tooling absent (no eslint/jsx-a11y, no Lighthouse): install nothing; set the summary's automated-coverage line to "none (tooling not installed)" and complete the audit by static inspection. The done predicate still holds: static findings with file/line locations, before/after code, and manual testing recommendations are present.

- A tool run fails or exits without usable output: record the failure and its error in the summary's failed-checks line; never swallow it and never report the check as passed.

- Contrast not computable (dynamic theming, images of text, gradients): list the exact color pairs or elements as open items for manual verification; never guess a ratio.

- Scope too large to finish: return the report explicitly labeled with the classes and paths not yet inspected; presenting a partial audit as complete violates the done predicate.

- Non-mutation: nothing is written at any point, so there is nothing to roll back; if a step could only proceed by writing a file, skip that step and say so in the report.

## Output