web-accessibility-web-accessibility

Accessibility

Quick Guide: All interactive elements keyboard accessible. Use headless component libraries for ARIA patterns. WCAG AA minimum (4.5:1 text contrast). Proper form labels and error handling. Combine automated axe-core checks with manual keyboard and screen reader testing.

Detailed Resources:

• [examples/core.md](examples/core.md) - Skip links, semantic HTML, landmarks, button vs link
• [examples/forms.md](examples/forms.md) - Form validation, error handling, accessible select
• [examples/focus.md](examples/focus.md) - Modal dialogs, focus indicators
• [examples/color.md](examples/color.md) - Contrast, color-independent indicators, tokens
• [examples/tables.md](examples/tables.md) - Sortable data tables
• [examples/touch-targets.md](examples/touch-targets.md) - Touch target sizing
• [examples/screen-reader.md](examples/screen-reader.md) - sr-only, hiding decorative content
• [examples/testing.md](examples/testing.md) - Accessibility testing with axe-core
• [reference.md](reference.md) - Decision frameworks, anti-patterns, WCAG quick reference

<critical_requirements>

CRITICAL: Before Using This Skill

All code must follow project conventions in CLAUDE.md (kebab-case, named exports, import ordering, import type, named constants)

(You MUST ensure all interactive elements are keyboard accessible with visible focus indicators)

(You MUST use headless component libraries for complex ARIA patterns instead of manual implementation)

(You MUST maintain WCAG AA minimum contrast ratios - 4.5:1 for text, 3:1 for UI components)

(You MUST never use color alone to convey information - always add icons, text, or patterns)

</critical_requirements>

Auto-detection: Accessibility (a11y), WCAG compliance, ARIA patterns, keyboard navigation, screen reader support, focus management, aria-label, aria-live, role attribute, skip link

When to use:

• Implementing keyboard navigation and focus management
• Ensuring WCAG AA color contrast (4.5:1 text, 3:1 UI components)
• Building interactive components (buttons, forms, modals, tables) with proper ARIA
• Adding dynamic content updates (live regions, status messages)
• Implementing skip links, landmarks, and semantic HTML structure
• Handling motion preferences with prefers-reduced-motion

When NOT to use:

• Working on backend/API code with no UI
• Writing build scripts or configuration files
• Creating documentation or non-rendered content
• Working with CLI tools (different accessibility considerations)

Target: WCAG 2.2 Level AA compliance (minimum), AAA where feasible

<philosophy>

Philosophy

Accessibility ensures digital products are usable by everyone, including users with disabilities. Accessibility is a requirement, not a feature - it should be built in from the start, not retrofitted.

Key philosophy:

• Semantic HTML first - Use native elements for built-in accessibility
• Headless components for complex patterns - Leverage tested, accessible component primitives from your component library
• Progressive enhancement - Start with keyboard, add mouse interactions on top
• WCAG as baseline - Meet AA minimum, aim for AAA where feasible

</philosophy>

<patterns>

Core Patterns

Keyboard Navigation Standards

CRITICAL: All interactive elements must be keyboard accessible

Tab Order

• Logical flow - Tab order must follow visual reading order (left-to-right, top-to-bottom)
• No keyboard traps - Users can always tab away from any element
• Skip repetitive content - Provide skip links to main content
• tabindex rules:
• tabindex="0" - Adds element to natural tab order (use sparingly)
• tabindex="-1" - Programmatic focus only (modal content, headings)
• Never use tabindex > 0 (creates unpredictable tab order)

Focus Management

• Visible focus indicators - Always show clear focus state (never outline: none without replacement)
• Focus on open - When opening modals/dialogs, move focus to first interactive element or close button
• Focus on close - Restore focus to trigger element when closing modals/dialogs
• Focus trapping - Trap focus inside modals using your headless component library or manual implementation
• Programmatic focus - Use element.focus() for dynamic content (search results, error messages)

Keyboard Shortcuts

• Standard patterns:
• Escape - Close modals, cancel actions, clear selections
• Enter/Space - Activate buttons and links
• Arrow keys - Navigate lists, tabs, menus, sliders
• Home/End - Jump to first/last item
• Tab/Shift+Tab - Navigate between interactive elements

Skip Links

MANDATORY for pages with navigation - place as first focusable element, visually hidden until focused.

// components/skip-link.tsx
export function SkipLink({ className }: { className?: string }) {
  return (
    <a href="#main-content" className={className}>
      Skip to main content
    </a>
  );
}

See [examples/core.md](examples/core.md) for full skip link implementation with styling.

ARIA Patterns

Use headless component libraries - they handle ARIA automatically for complex patterns like dialogs, selects, tabs, tooltips, and popovers.

Component-Specific ARIA

Buttons:

• aria-label - For icon-only buttons
• aria-pressed - For toggle buttons
• aria-expanded - For expandable sections
• aria-disabled - Use with disabled attribute

Forms:

• aria-required - Required fields (use with required)
• aria-invalid - Invalid fields
• aria-describedby - Link to error messages, helper text
• aria-errormessage - Explicit error message reference

Navigation:

• aria-current="page" - Current page in navigation
• aria-label - Describe navigation purpose ("Main navigation", "Footer navigation")

Modals/Dialogs:

• role="dialog" or role="alertdialog"
• aria-modal="true"
• aria-labelledby - Points to dialog title
• aria-describedby - Points to dialog description

Tables:

• scope="col" and scope="row" for headers
• <caption> for table description
• aria-sort for sortable columns

Live Regions

Use for dynamic content updates:

• aria-live="polite" - Announce when user is idle (status messages, non-critical updates)
• aria-live="assertive" - Announce immediately (errors, critical alerts)
• aria-atomic="true" - Announce entire region content
• role="status" - For status messages (implies aria-live="polite")
• role="alert" - For error messages (implies aria-live="assertive")

Best practices:

• Keep messages concise and meaningful
• Clear old messages before new ones
• Don't spam with rapid updates (debounce)

Color Contrast & Visual Design

Text contrast (AA):

• Normal text (< 18px): 4.5:1 minimum
• Large text (>= 18px or >= 14px bold): 3:1 minimum
• AAA (recommended): 7:1 for normal, 4.5:1 for large

Non-text contrast:

• UI components (buttons, form inputs): 3:1 minimum
• Focus indicators: 3:1 against background
• Icons (functional): 3:1 minimum

Color Independence:

• Add icons to color-coded states (check for success, X for error)
• Use text labels with status colors
• Provide patterns/textures in charts
• Underline links in body text

See [examples/color.md](examples/color.md) for contrast examples and design tokens.

Semantic HTML

Always use semantic HTML:

• <button> for actions (not <div onclick>)
• <a> for navigation (not <div onclick>)
• <nav> for navigation sections
• <main> for primary content (one per page)
• <header> and <footer> for page sections
• <ul>/<ol> for lists
• <table> for tabular data (not divs with grid CSS)
• <form> with proper <label> associations

Never:

• Use <div> or <span> for interactive elements
• Use click handlers on non-interactive elements without proper role
• Use tables for layout
• U