/web-accessibility-audit

name: web-accessibility-audit
description: 'Use when the user requests an accessibility audit, a11y check, or WCAG compliance review. Don''t use for tasks that require source or remote-system changes.'
disable-model-invocation: true

Web accessibility audit

Contract

| Field | Bound contract | |---|---| | Trigger | Accessibility audit, a11y check, or WCAG compliance review | | Authority | Read-only. No file, VCS, credential, paid, published, deployed, or remote mutation. Reads project files and runs only analysis tools already installed in the project; installs 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

A report returned in the conversation (no files created) with sections in order: Summary (scope, WCAG level, issue counts by severity, automated coverage, failed checks), Findings (in severity order: Critical, Serious, Moderate, Minor, each with WCAG criterion, `path:line` locations, before/after code, and fix rationale), Manual testing recommendations, and Next steps.