# Accessibility

> Use when building UI components, creating pages, or before launch for WCAG 2.1 AA compliance. Triggers on "accessibility", "a11y", "screen reader", "keyboard nav", "WCAG", "ARIA", "contrast".

- Skill: `amo-tech-ai-rocket-path-ai/accessibility` (Agent Skill)
- Install (CLI): `npx skillmds@latest add amo-tech-ai-rocket-path-ai/accessibility`
- Raw SKILL.md: https://api.skillmd.com/api/skills/amo-tech-ai-rocket-path-ai/accessibility/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: amo-tech-ai (https://skillmd.com/u/amo-tech-ai-rocket-path-ai)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/amo-tech-ai-rocket-path-ai/accessibility

---


# Accessibility

## Overview

WCAG 2.1 AA compliance for React + shadcn/ui — keyboard navigation, screen readers, color contrast, semantic HTML.

## When to Use

- Building any new UI component or page
- Before production launch
- When accessibility audit fails
- When adding forms, modals, or interactive elements

## Workflow

### Phase 1: Semantic HTML

1. Correct heading hierarchy (h1 > h2 > h3, one h1/page)
2. Landmarks: `<nav>`, `<main>`, `<aside>`, `<section>`
3. `<button>` for actions, `<a>` for navigation (never `<div onClick>`)
4. `<label>` for all form inputs

### Phase 2: Keyboard

1. All interactive elements focusable via Tab
2. Visible focus indicators (shadcn `focus-visible` ring)
3. Escape closes modals/dropdowns
4. Arrow keys in menus/tabs
5. Test: navigate entire page with keyboard only

### Phase 3: Screen Readers

1. `aria-label` on icon-only buttons:
   ```tsx
   <Button variant="ghost" size="icon" aria-label="Close dialog">
     <X className="h-4 w-4" />
   </Button>
   ```
2. `aria-live="polite"` on dynamic regions (toasts, loading)
3. `role="alert"` on error messages
4. `aria-hidden="true"` on decorative elements

### Phase 4: Color & Contrast

1. Text contrast: 4.5:1 minimum (AA)
2. Large text (18px+): 3:1 minimum
3. Never color alone to convey meaning (add icons/text)
4. Test: DevTools > Rendering > Emulate vision deficiencies

### Phase 5: Forms

1. Visible labels on every input
2. `aria-required="true"` on required fields
3. Errors linked with `aria-describedby` + `aria-invalid="true"`

### Phase 6: Audit

1. Lighthouse Accessibility > 90
2. axe DevTools extension
3. Keyboard-only walkthrough
4. 200% zoom — layout intact

## Checklist

- [ ] Semantic landmarks and heading hierarchy
- [ ] All elements keyboard-accessible
- [ ] Visible focus indicators
- [ ] `aria-label` on icon buttons
- [ ] `aria-live` on dynamic content
- [ ] 4.5:1 contrast ratios
- [ ] Color not sole indicator
- [ ] Form labels and error linking
- [ ] Lighthouse Accessibility > 90
- [ ] Tested keyboard-only + 200% zoom