accessibility-audit

Files (5)

• SKILL.md
• _claude-frontmatter-extras.yaml · references/
• aria-patterns.md · references/
• audit-report-template.md · references/
• wcag-quick-reference.md · references/

SKILL.md (first lines)

# Accessibility Audit

Run a thorough accessibility audit and produce a remediation plan. Stack-agnostic. Anchored to WCAG 2.1 AA, with notes on AAA where relevant.

This skill goes deeper than the accessibility checks in `qa-testing` and `design-standards`. Use this when accessibility itself is the goal.

---

## When to use

- Pre-launch accessibility verification
- Compliance preparation (ADA, EN 301 549, AODA, Section 508)
- Remediation after an audit finding or complaint
- Annual or quarterly accessibility health check
- Onboarding accessibility into a team that hasn't prioritized it before

## When NOT to use

- General QA after deploys (use `qa-testing`)
- Component-level accessibility implementation (use `frontend-component-build`)
- Color contrast for design tokens (use `design-standards` or `brand-identity`)

---

## Required inputs

- The site or product under audit
- The scope (full site, specific section, specific user flow)
- The target standard (WCAG 2.1 AA is most common)
- Any specific concerns or known issues
- Tools available (automated scanners, screen readers, manual testing)

---

## The framework: WCAG's 4 principles

WCAG organizes accessibility around four principles. The audit covers each in depth.

### 1. Perceivable

Information and UI must be presentable in ways users can perceive.

**Audit checks:**

- **Text alternatives.** All non-decorative images have descriptive `alt` text. Decorative images use `alt=""`. Complex images (charts, infographics) have long descriptions.
- **Time-based media.** Videos have captions. Pre-recorded audio has transcripts. Live audio has live captions where required.
- **Adaptable.** Content structure is conveyed through markup (semantic HTML), not just visual styling. Reading order makes sense when CSS is disabled.
- **Distinguishable.** Color is not the sole means of conveying information. Text contrast meets AA (4.5:1 normal, 3:1 large). UI element contrast meets 3:1. Audio can be paused, stopped, or muted.

### 2. Operable

UI components and navigation must be operable.

**Audit checks:**

- **Keyboard accessible.** All functionality available via keyboard alone. No keyboard traps. Focus visible.
- **Enough time.** Time limits can be adjusted, paused, or extended. Auto-updating content can be paused.
- **Seizures and physical reactions.** No content that flashes more than 3 times per second.
- **Navigable.** Skip links present. Pages have descriptive titles. Focus order is logical. Link purpose clear from text or context. Multiple ways to find pages (sitemap, search, navigation). Headings and labels are descriptive.
- **Input modalities.** Pointer gestures have keyboard alternatives. Pointer cancellation supported (mouse-up, not mouse-down for activation). Labels match accessible names. Motion-triggered functionality has alternatives.

### 3. Understandable

Information and operation must be understandable.

**Audit checks:**

- **Readable.** Page language declared (`<html lang="...">`). Unusual words and abbreviations have definitions or expansions. Reading level appropriate to audience.
- **Predictable.** Focus does not change context unexpectedly. Input does not change context unexpectedly. Navigation is consistent across pages. Components that look similar behave similarly.
- **Input assistance.** Errors are identified clearly. Labels and instructions are provided for input. Error suggestions are given where possible. For pages handling legal commitments or financial transactions, errors can be reviewed and corrected before submission.

### 4. Robust

Content must be robust enough to work with current and future user agents.

**Audit checks:**

- **Compatible.** Markup is valid. Name, role, and value of UI components are programmatically determinable. Status messages can be programmatically determined and announced.

---

## Audit methodology

### Stage 1: Automated scan

Run automated scanners across the priority pages. These catch 30 to 50 percent of issues but miss the rest.

**Tools:**
- axe DevTools (browser extension)
- Lighthouse (Chrome DevTools accessibility audit)
- WAVE (browser extension)
- Pa11y (CLI for batch scanning)

**Output:** A list of automated findings, by page.

### Stage 2: Manual keyboard testing

Unplug the mouse. Navigate the priority user flows using only keyboard.

**Test:**
- Tab and Shift+Tab move through interactive elements in logical order
- Enter activates buttons and links
- Space activates buttons (and toggles checkboxes)
- Arrow keys navigate within composite widgets (tabs, menus, listboxes)
- Escape dismisses modals, popovers, menus
- Focus is always visible
- Focus returns to a sensible place after modals or popovers close
- No keyboard trap (focus can always leave)

**Document:** Any flow where keyboard navigation breaks down.

### Stage 3: Screen reader testing

Test with at least one real screen reader, or state the gap per the data-availability rule. Each combination has quirks.

**Common combinations:**
- VoiceOver + Safari (macOS / iOS)
- NVDA + Firefox or Chrome (Windows)
- JAWS + Chrome (Windows; commercial but common in enterprise)

From rampstackco/claude-skills, MIT.

More from rampstackco/claude-skills