Accessibility Complete

A Claude Code skill providing comprehensive web accessibility guidance based on WCAG 2.2 and Lighthouse accessibility audits. Covers all aspects of making web content usable by everyone, including people with visual, auditory, motor, and cognitive disabilities.

When to Use This Skill

Choose Accessibility Complete when:

• You need a complete WCAG 2.2 compliance audit of your application
• You want to implement accessibility across your entire project systematically
• You need to fix Lighthouse accessibility audit failures
• You're building new features and want to be accessible from the start
• You need to meet legal accessibility requirements (ADA, Section 508, EN 301 549)

Consider alternatives when:

• You need specific ARIA patterns for complex widgets (use an accessibility module skill)
• You want general UI component implementation (use a UI module skill)
• You need mobile-specific accessibility (use a mobile design skill)

Quick Start

Copy
# Install the skill
claude install accessibility-complete

# Run a full audit
claude "Perform a WCAG 2.2 AA accessibility audit on this component: [paste code]"

# Fix Lighthouse issues
claude "My Lighthouse accessibility score is 72. Here are the failures: [list]. Fix them all."

# Build accessible from scratch
claude "Build an accessible dropdown menu with keyboard navigation, ARIA attributes, and screen reader announcements"

Core Concepts

WCAG 2.2 Principles

Principle	Focus	Key Requirements
Perceivable	Can users perceive the content?	Alt text, captions, contrast, text resize
Operable	Can users operate the interface?	Keyboard access, no traps, sufficient time
Understandable	Can users understand the content?	Clear language, predictable behavior, error help
Robust	Does it work with assistive tech?	Valid HTML, ARIA, compatible with screen readers

Conformance Levels

Level A (minimum):
  → All non-text content has text alternatives
  → All functionality available via keyboard
  → No content causes seizures
  → Pages have titles, headings have structure

Level AA (standard — most organizations target this):
  → Color contrast ≥ 4.5:1 (body), ≥ 3:1 (large text)
  → Text resizable to 200% without loss
  → Consistent navigation across pages
  → Error identification and suggestions
  → Focus visible on all interactive elements

Level AAA (enhanced):
  → Color contrast ≥ 7:1 (body), ≥ 4.5:1 (large text)
  → Sign language for multimedia
  → Extended time limits
  → No timing for interactions

Common Accessibility Patterns

Pattern	Implementation	Testing
Skip Link	Hidden link to main content, visible on focus	Tab from page top
Focus Management	Move focus to new content, trap in modals	Tab through all elements
Live Regions	aria-live="polite" for dynamic updates	Screen reader verification
Error Messages	aria-describedby linking input to error	VoiceOver/NVDA test
Form Labels	<label for="id"> or aria-label	Lighthouse audit

Configuration

Parameter	Type	Default	Description
target_level	string	"AA"	WCAG level: A, AA, AAA
framework	string	"react"	Framework for specific patterns
testing_tools	string[]	["axe", "lighthouse"]	Testing: axe, lighthouse, pa11y, jest-axe
screen_readers	string[]	["voiceover"]	Target: voiceover, nvda, jaws, talkback
legal_standard	string	"wcag"	Standard: wcag, ada, section_508, en_301_549

Best Practices

1. Use semantic HTML as your foundation — <button>, <nav>, <main>, <article>, <header> are accessible by default. ARIA should only supplement, never replace, semantic HTML. A <div onClick> needs 5 lines of ARIA; a <button> needs zero.

2. Test with keyboard only — Unplug your mouse and navigate your entire application using Tab, Shift+Tab, Enter, Space, Escape, and Arrow keys. Every feature must be reachable and operable. This single test catches the majority of accessibility issues.

3. Color contrast is non-negotiable — 4.5:1 for body text and 3:1 for large text (18px+ or 14px bold). Use a contrast checker before finalizing any color combination. This is the most common Lighthouse accessibility failure.

4. Test with a real screen reader — VoiceOver on Mac (Cmd+F5) or NVDA on Windows (free) reveal issues automated tools can't detect: confusing reading order, missing announcements, and unclear focus behavior. Spend 10 minutes per feature.

5. Add automated accessibility testing to CI — Use jest-axe for component tests and axe-core in integration tests. These catch regressions automatically. Combined with manual testing, this creates a robust accessibility quality gate.

Common Issues

Images without alt text — Every <img> needs an alt attribute. Informative images need descriptive alt text. Decorative images need alt="" (empty string, not missing). Icon buttons need aria-label.

Focus not visible on interactive elements — Never set outline: none without providing an alternative focus indicator. Use focus-visible to show focus only for keyboard users, not mouse clicks. Custom focus styles should have 3:1 contrast.

Dynamic content not announced — When content changes without a page reload (loading states, form errors, notifications), screen readers don't notice. Use aria-live="polite" for non-urgent updates and aria-live="assertive" for errors.