/web-accessibility-web-accessibility

name: web-accessibility-web-accessibility
description: WCAG, ARIA, keyboard navigation

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 na