| name | accessibility-audit |
| description | Review and remediate web accessibility issues against WCAG 2.2 AA. Use when building UI components, reviewing HTML, or preparing for an accessibility audit. |
| license | Apache-2.0 |
| compatibility | Works with coding agents that support Agent Skills. |
| metadata | {"agentpacks.version":"0.2.0"} |
Accessibility Audit
Accessibility is a correctness concern, not a polish pass. WCAG 2.2 AA is the minimum bar for public-facing products.
Semantic HTML
- Use native HTML elements before ARIA:
<button> over <div role="button">, <nav> over <div role="navigation">.
- Every form input must have a corresponding
<label for="id"> — not just a placeholder.
- Heading hierarchy must be logical (h1 → h2 → h3); never skip levels for visual styling.
- Use
<table> with <th scope="col|row"> for tabular data; never use tables for layout.
- Use
<ul>, <ol>, and <dl> for list content; don't fake lists with repeated divs.
Interactive Elements
- All interactive elements must be keyboard-focusable (natural tab order) and operable with Enter and Space.
- Focus must be visible at all times: never
outline: none without a visible custom replacement that meets 3:1 contrast.
- Modals and dialogs must trap focus while open; restore focus to the trigger element on close.
- Custom widgets (dropdowns, carousels, date pickers, comboboxes) must implement the ARIA Authoring Practices Guide pattern.
Images and Media
- Every
<img> must have an alt attribute: descriptive text for informational images, empty string (alt="") for decorative ones.
- Videos must have captions (not just auto-generated); audio content must have transcripts.
- SVG icons used as buttons or links need
aria-label or <title> when there is no visible text.
Color and Contrast
- Normal text (< 18px / < 14px bold): contrast ratio ≥ 4.5:1 against background.
- Large text (≥ 18px / ≥ 14px bold): contrast ratio ≥ 3:1.
- UI component boundaries and focus indicators: ≥ 3:1 against adjacent colors.
- Color alone must never be the sole indicator of information — pair with label, icon, or pattern.
ARIA Usage
aria-label or aria-labelledby is required on any interactive element without visible text.- Use
aria-live="polite" for asynchronous updates; aria-live="assertive" only for urgent, time-sensitive messages.
- Never override a native implicit ARIA role with the same value — redundant roles add noise.
role="presentation" or role="none" removes an element from the accessibility tree — use intentionally.
Testing
- Run automated scanner (axe-core, Lighthouse, IBM Equal Access Checker) — zero critical/serious violations.
- Navigate the entire flow keyboard-only: every action must be reachable and operable without a mouse.
- Test with a screen reader (VoiceOver on macOS/iOS, NVDA on Windows) for critical user flows.
- Zoom to 200% — no content is clipped, overlapping, or requires horizontal scrolling.
- Test in both light and dark modes for contrast compliance.
Checklist
