Comprehensive Accessibility Module

A Claude Code skill for implementing web accessibility (a11y) standards across your application. Covers WCAG 2.2 compliance, screen reader compatibility, keyboard navigation, color contrast, ARIA patterns, and automated testing — designed to make your product usable by everyone.

When to Use This Skill

Choose Comprehensive Accessibility Module when:

• You need to audit your application for WCAG 2.2 compliance
• You're building new UI components and want them accessible from the start
• You want to fix accessibility issues flagged by automated tools
• You need to implement ARIA patterns for complex interactive widgets
• You're preparing for accessibility legal compliance requirements

Consider alternatives when:

• You need general UI/UX design guidance (use a UI design skill)
• You want CSS framework setup (use a styling framework skill)
• You need form validation logic (use a form module skill)

Quick Start

Copy
# Install the skill
claude install comprehensive-accessibility-module

# Audit a component
claude "Audit this React modal component for accessibility issues: [paste code]"

# Fix specific issues
claude "Make this dropdown menu keyboard accessible with proper ARIA attributes"

# Implement an accessible pattern
claude "Build an accessible data table with sortable columns, pagination, and screen reader announcements"

Core Concepts

WCAG 2.2 Levels

Level	Description	Required For
A	Minimum accessibility baseline	All websites (legal baseline)
AA	Standard accessibility compliance	Government, enterprise, most businesses
AAA	Enhanced accessibility	Specialized accessibility-focused products

Core Accessibility Principles (POUR)

Perceivable:
  → Text alternatives for non-text content (alt text, captions)
  → Content adaptable without losing information
  → Color contrast ratio: 4.5:1 minimum (AA), 7:1 (AAA)

Operable:
  → All functionality available via keyboard
  → No keyboard traps (Tab navigates through, Escape closes)
  → Sufficient time to read and interact
  → No content that causes seizures (no rapid flashing)

Understandable:
  → Clear language and consistent navigation
  → Predictable behavior (no unexpected context changes)
  → Error identification and suggestions

Robust:
  → Valid HTML and proper semantic elements
  → Compatible with assistive technologies
  → ARIA used correctly (not overused)

Common ARIA Patterns

Pattern	Widget	Key Attributes
Dialog	Modal/popup	role="dialog", aria-modal="true", aria-labelledby
Tabs	Tab interface	role="tablist/tab/tabpanel", aria-selected
Menu	Dropdown menu	role="menu/menuitem", aria-expanded
Combobox	Search/autocomplete	role="combobox", aria-autocomplete, aria-activedescendant
Tree	File explorer	role="tree/treeitem", aria-expanded, aria-level
Alert	Notification	role="alert", aria-live="assertive"

Configuration

Parameter	Type	Default	Description
wcag_level	string	"AA"	Target compliance: A, AA, AAA
framework	string	"react"	Frontend framework: react, vue, angular, vanilla
testing_tools	string[]	["axe"]	Testing: axe, lighthouse, pa11y, jest-axe
screen_readers	string[]	["voiceover"]	Target: voiceover, nvda, jaws
include_automated_tests	boolean	true	Include automated a11y test setup

Best Practices

1. Use semantic HTML before ARIA — A <button> is automatically accessible. A <div onClick> needs role="button", tabIndex="0", and keyboard event handlers. Use the right element first; only add ARIA when native elements can't do the job.

2. Test with a real screen reader — Automated tools catch only 30-40% of accessibility issues. Spend 10 minutes testing with VoiceOver (Mac) or NVDA (Windows) to catch issues that automated tools miss, especially around focus management and reading order.

3. Keyboard navigation is non-negotiable — Every interactive element must be reachable and operable with just a keyboard. Tab through your entire application and ensure you can complete every action without a mouse.

4. Color is never the only indicator — Don't rely on color alone to convey information. Error states should have icons and text, not just red borders. Charts should use patterns alongside colors. This helps colorblind users and improves clarity for everyone.

5. Add automated testing to CI — Use jest-axe for component tests and axe-core in your integration tests. Catch regressions before they reach production. An automated check on every PR prevents most common accessibility issues.

Common Issues

Focus management in SPAs — When navigating between pages in a single-page app, screen readers don't announce the new page. Set focus to the main heading or content area after route changes and announce the new page title.

Custom components lack keyboard support — Custom dropdowns, datepickers, and modals often forget keyboard users. Follow the WAI-ARIA Authoring Practices for keyboard interaction patterns. Arrow keys for navigation within widgets, Escape to close.

Dynamic content not announced — When content updates without a page reload (loading states, error messages, live data), screen readers won't notice. Use aria-live regions to announce important changes, with polite for non-urgent updates and assertive for critical messages.