# Audit Accessibility

> Audit a feature for WCAG 2.1 AA compliance using POUR principles when the user asks to check accessibility, audit a11y, or verify WCAG compliance

- Skill: `majiayu000/audit-accessibility` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/audit-accessibility`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/audit-accessibility/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/audit-accessibility

---


# Audit Accessibility

## Overview

Generate a WCAG 2.1 AA compliance audit for a specific feature or component, organized by the POUR principles (Perceivable, Operable, Understandable, Robust). Produces a concrete checklist with testing instructions, keyboard navigation paths, screen reader expectations, and color contrast requirements.

## Workflow

1. **Read feature context** -- Scan `.chalk/docs/product/` for the PRD describing the feature. Check `.chalk/docs/engineering/` for component architecture and any existing a11y guidelines. Read the source code for the feature's UI components to understand the actual implementation.

2. **Parse the audit target** -- Extract from `$ARGUMENTS` the feature, page, or component to audit. If unspecified, ask the user to name a specific feature -- auditing the entire application at once produces shallow results.

3. **Determine the next file number** -- Read filenames in `.chalk/docs/engineering/` to find the highest numbered file. The next number is `highest + 1`.

4. **Audit Perceivable** -- Check:
   - All images have meaningful alt text (decorative images use `alt=""`)
   - Color is not the only means of conveying information
   - Text meets contrast ratios (4.5:1 for normal text, 3:1 for large text)
   - Content is readable at 200% zoom
   - Media has captions or transcripts

5. **Audit Operable** -- Check:
   - All interactive elements are reachable via keyboard (Tab, Shift+Tab, Enter, Space, Escape, Arrow keys)
   - Document the expected keyboard navigation path through the feature
   - Focus order matches visual order
   - No keyboard traps
   - Focus indicators are visible
   - Touch targets are at least 44x44 CSS pixels

6. **Audit Understandable** -- Check:
   - Form inputs have visible labels (not just placeholders)
   - Error messages identify the field and describe how to fix the error
   - Consistent navigation and naming patterns
   - Language is set on the page element

7. **Audit Robust** -- Check:
   - Semantic HTML elements used appropriately (buttons, links, headings, landmarks)
   - ARIA roles, states, and properties are correct and necessary
   - Components work with major screen readers (VoiceOver, NVDA, JAWS)
   - No ARIA is better than bad ARIA

8. **Write the file** -- Save to `.chalk/docs/engineering/<n>_a11y_audit_<feature-slug>.md`.

9. **Confirm** -- Share the file path and highlight the highest-severity issues that block users from completing tasks.

## Output

- **File**: `.chalk/docs/engineering/<n>_a11y_audit_<feature-slug>.md`
- **Format**: Plain markdown with POUR-organized checklist, each item marked pass/fail/needs-review with specific testing instructions
- **First line**: `# Accessibility Audit: <Feature Name>`

## Anti-patterns

- **Checklist without testing instructions** -- "Check color contrast" is not actionable. Specify which elements, what the current ratio is, and what the target ratio should be.
- **ARIA overuse** -- Adding `role="button"` to a `<button>` is redundant. Adding ARIA to fix semantic HTML problems is treating symptoms. Prefer native HTML elements.
- **Keyboard testing only with Tab** -- Many components require Arrow keys (tabs, menus, radio groups), Escape (modals, dropdowns), Space (checkboxes), and Enter (buttons, links). Document the full expected keyboard interaction model.
- **Ignoring screen reader output** -- An element can be technically accessible but produce nonsensical screen reader output. Specify what the screen reader should announce for each interactive element.
- **Treating a11y as a one-time audit** -- Note which checks should be automated in CI and which require manual testing on each release.