Accessibility Skill

WCAG 2.1 Level AA compliance auditing and inclusive design guidance.

Core Principle

Accessibility is not optional. It's legal compliance, user respect, and better code.

WCAG 2.1 Four Principles: POUR

1. Perceivable

Information must be presentable to users in ways they can perceive.

• Text alternatives for images
• Color contrast 4.5:1 (normal), 3:1 (large)
• No info by color alone

2. Operable

Interface components must be operable.

• All functionality via keyboard
• No keyboard traps
• Visible focus indicators

3. Understandable

Information and operation must be understandable.

• Form labels associated
• Error messages clear
• Consistent navigation

4. Robust

Content must work with assistive technologies.

• Valid HTML (no duplicate IDs)
• Proper ARIA usage
• Status messages announced

Full WCAG checklists: See refs/wcag-checklist.md

Quick Audit Process

1. Automated Scan

Open a screenshot file with your harness's file reader, or capture via browser automation if available (e.g., Playwright, Puppeteer, or an MCP browser tool). For automated WCAG scanning, use axe DevTools, Lighthouse, WAVE, or pa11y.

2. Keyboard Test (5 minutes)

• Tab through entire page
• Can reach all interactive elements?
• Focus always visible?
• Tab order logical?
• Can escape modals/menus?

Full keyboard testing guide: See refs/keyboard-testing-basics.md and refs/keyboard-testing-patterns.md

3. Screen Reader Spot Check

• Turn on VoiceOver (Mac) or NVDA (Windows)
• Are images described?
• Are buttons/links clear?
• Are form labels read?

Full screen reader guide: See refs/screen-reader-testing-commands.md and refs/screen-reader-testing-advanced.md

4. Code Review

# Find potential issues — the wicked-garden-search skill over html files:
#   <div.*onclick     non-semantic buttons
#   <img(?!.*alt)     missing alt
#   aria-             ARIA usage

Common Quick Fixes

<!-- ✗ Missing alt -->
<img src="profile.jpg">
<!-- ✓ Fixed -->
<img src="profile.jpg" alt="Profile of Jane Doe">

<!-- ✗ Non-semantic button -->
<div onclick="submit()">Submit</div>
<!-- ✓ Fixed -->
<button onclick="submit()">Submit</button>

<!-- ✗ Form without label -->
<input type="text" placeholder="Email">
<!-- ✓ Fixed -->
<label for="email">Email</label>
<input type="text" id="email">

<!-- ✗ Low contrast -->
<p style="color: #999; background: #fff;">Text</p>  /* 2.5:1 */
<!-- ✓ Fixed -->
<p style="color: #666; background: #fff;">Text</p>  /* 4.7:1 */

More examples: See refs/common-violations-html-css.md and refs/common-violations-interactive.md

Output Format

## A11y Audit

**WCAG**: {✓ Pass | ⚠ Issues | ✗ Fail}
- Perceivable: {✓⚠✗}
- Operable: {✓⚠✗}
- Understandable: {✓⚠✗}
- Robust: {✓⚠✗}

### Critical (Level A)
- Issue: {description}
  - WCAG: {criterion}
  - Fix: {specific code}

### Major (Level AA)
- Issue: {description}
  - WCAG: {criterion}
  - Fix: {recommendation}

### Recommendations
1. {Priority fixes}

Full report template: See refs/audit-report-findings.md and refs/audit-report-results.md

Integration

Tools:

# Color contrast: compute the WCAG ratio (#666 on #fff = 5.74:1, passes AA
# body text); use axe / Lighthouse / WAVE / pa11y for automated scanning.

# Track issues in the harness's task list where it has one (subject "A11y: {issue}"; metadata
# event_type=task, chain_id=a11y-review.root, source_agent=a11y-expert, priority=P0), else your working notes.

Collaboration:

• UX Designer: Ensure accessible patterns in flows
• UI Reviewer: Validate contrast and focus states
• QE: Include keyboard/screen reader testing

External Integration Discovery

Accessibility auditing can leverage available integrations by capability:

Capability	Discovery Patterns	Provides
A11y testing	axe, a11y, accessibility	Automated WCAG scanning
Browser testing	playwright, puppeteer	Screenshots, DOM snapshots
Performance	lighthouse	Combined a11y + performance audit

Discover available integrations via capability detection. When none are available, fall back to computing the WCAG contrast ratio manually against the AA thresholds.

Resources

• WCAG 2.1: https://www.w3.org/WAI/WCAG21/quickref/
• ARIA Patterns: https://www.w3.org/WAI/ARIA/apg/
• WebAIM: https://webaim.org/articles/
• Inclusive Components: https://inclusive-components.design/

Detailed guides in refs/:

• wcag-checklist.md - Complete WCAG checklists
• keyboard-testing-basics.md - Keyboard testing checklist and core tests
• keyboard-testing-patterns.md - Common violations, fixes, and tools
• screen-reader-testing-commands.md - Screen reader commands and setup
• screen-reader-testing-advanced.md - Advanced screen reader tests and workflow
• aria-patterns-basics.md - ARIA basics and simple widgets
• aria-patterns-interactive.md - Tabs, modals, dropdown menus
• aria-patterns-dynamic.md - Combobox, alerts, live regions, best practices
• common-violations-html-css.md - HTML and CSS violation fixes
• common-violations-interactive.md - Interactive component violation fixes
• audit-report-findings.md - Audit findings template
• audit-report-results.md - Audit results and recommendations

When to Audit

• Before major releases
• New UI components
• Form implementations
• Modal/dialog work
• Post-build phase (crew integration)
• User-facing features

Legal context: ADA (US), Section 508 (gov), EAA (EU). ~15-20% of users need accessibility; screen readers double as SEO bots.