| name | accessibility-audit |
| description | Audits a page, component, or template for WCAG 2.1 AA / Section 508 compliance. Use when the user says accessibility audit, check a11y, find accessibility issues, is this accessible, Section 508 check, or review this for accessibility. Apply when the user shares a page or component and wants compliance validation even if they don't say 'audit'. |
| typicalNext | Document the findings in the ticket/issue (or a new one), prioritize by impact level and user reach, and open follow-up items for anything that won't ship in the current scope. Re-run the validation commands after fixes land. |
Accessibility Audit
Project contract
The impact-to-priority mapping, validation tooling, environment, and stack-specific checks are
project-specific. Read them from .agents/project-contract.md (shared contract), then layer .agents/project-contract.personal.md on top if it exists (personal entries win where they overlap):
## Priority guide → Accessibility impact levels: the A/B/C (or equivalent) impact-to-
priority mapping and bump up/down rules.## Environments: local environment to audit against, and the a11y validation tooling
(e.g. Pa11y, cypress-axe, axe).## Stack: design-system styling rules (tokens vs. hex, !important, BEM) and the a11y
baseline; whether the stack is Drupal/Twig (enables the template checks below).## Sanctioned AI → Browser inspection MCP: which browser tool browser-check uses.
If no project contract is present, default to WCAG 2.1 AA and ask the user for the project's tooling.
When to Use
Invoke to audit a page, template, component, or test spec for accessibility issues; WCAG 2.1 AA,
Section 508, or project-specific a11y requirements.
Approach
- Identify scope: page URL, component path, or template file
- Live page inspection: use
browser-check (with the project contract's browser MCP) to navigate,
capture screenshots, and inspect the rendered DOM before static analysis
- Static analysis: review markup for:
- Missing or inadequate alt text on images
- Heading hierarchy violations (skipped levels, multiple H1s)
- Form inputs without associated labels
- Links with non-descriptive text ("click here", "read more")
- Color used as the only means of conveying information
- Missing ARIA roles, labels, or landmarks where needed
- Keyboard trap risks (modals, dropdowns, custom widgets)
- Focus management gaps in dynamic content
- Design-system checks: verify the project contract's
## Stack styling rules (e.g. color tokens, no
hex; no !important; class-based styling)
- Template checks (if the project contract's stack is Drupal/Twig): confirm
|e filter on dynamic
output, #plain_text for user content
- Report findings: classify each by impact level and priority using the project contract's
Accessibility impact levels
Output Format
Return a flat list of findings. For each:
- Issue: short description
- Location: file path or selector
- WCAG criterion: e.g. 1.1.1, 2.4.6
- Impact level: per the project contract's impact typology
- Priority: per the project contract's priority scheme
- Fix: concrete corrective action
End with a summary count by priority and the project contract's a11y validation commands to verify the fix.
Voice
Apply .agents/style/voice.md to finding descriptions and fix suggestions. Run shared audit prose through tone-check before posting.
Attribution
If the active project contract defines an attribution marker (see its ## Attribution marker section), end
shared findings with that marker as the last line. Skip it for personal-use output, or if the
project contract defines no marker. Don't name the specific AI tool (see security-check).
Example
You ask: use the accessibility-audit skill on the new filter sidebar
You get:
- Issue: Filter checkbox missing label association
Location: src/components/Filter.jsx:23
WCAG: 1.3.1, 4.1.2 | Impact: serious | Priority: High
Fix: wrap input in <label> or add htmlFor
- Issue: Sidebar toggle button has no aria-expanded
Location: src/components/Sidebar.jsx:11
WCAG: 4.1.2 | Impact: serious | Priority: High
Fix: add aria-expanded reflecting open state
Summary: 2 serious findings. Verify with the project's a11y command.
Related Skills
- Upstream gate:
security-check (run before auditing any environment higher than local, or pasting screenshots / tooling output that may contain PII or authored content)
- Invokes:
browser-check (live page inspection before static analysis)
- Sibling Validate-phase skills:
responsive-design, performance-frontend,
frontend-peer-review, drupal-peer-review (the last only when the project contract's stack is Drupal); these
may all run on the same change
- Downstream:
qa-steps (a11y findings often produce QA verification steps), tone-check (run shared audit prose through tone check before posting)
Security
Audit against the project contract's local environment by default. If a higher-environment audit is
needed:
- A human runs the audit and pastes findings (selectors, contrast ratios, screen reader output)
into the AI session, never raw page state
- Screenshots saved to
.agents/reviews/ are PII-redacted before commit (author emails, user
content, draft content)
- Tooling output (Pa11y, cypress-axe, etc.) is reviewed for PII before sharing
