` for self-contained content (blog posts, cards, team members) - Use `

` for supplementary content (sidebars, related links) --- ## Focus Management ### Focus Styles All interactive elements have a visible focus indicator: ```css :focus-visible { outline: 3px solid var(--color-brand); outline-offset: 3px; border-radius: var(--radius-sm); } /* Mouse users don't see the ring (cleaner UX) */ :focus:not(:focus-visible) { outline: none; } ``` **Never remove focus styles.** If the default ring doesn't match your design, customize it — don't remove it. ### Modal Focus Trap When a modal opens: 1. Focus moves to the first focusable element inside the modal 2. Tab/Shift+Tab cycles only within the modal 3. Escape closes the modal and returns focus to the trigger ### Mobile Menu Focus Trap Same pattern as modals — focus is trapped inside the mobile nav overlay when open. --- ## Color & Contrast ### Minimum Ratios (WCAG 2.2 AA) | Text type | Minimum ratio | |-----------|--------------| | Normal text (< 18pt / < 14pt bold) | 4.5:1 | | Large text (≥ 18pt / ≥ 14pt bold) | 3:1 | | UI components & focus indicators | 3:1 | | Decorative elements | No requirement | ### Automatic Contrast Text The theme generator (`config/theme.js`) automatically computes whether white or dark text should be used on each generated color: ```js function getContrastText(hex) { // Uses WCAG relative luminance formula // Returns '#ffffff' or '#0f172a' } ``` ### Never Use Color Alone Always pair color with another indicator: - ✅ Error: red border + error icon + error message text - ❌ Error: red border only --- ## Interactive Components ### Buttons - Minimum touch target: **44×44px** (enforced via `min-height: 44px`) - Icon-only buttons **must** have `aria-label` - Disabled buttons use `aria-disabled="true"` (not just `disabled`) when they should remain focusable ```html ``` ### Links vs Buttons - Use `` for navigation (changes the URL) - Use ` aria-controls="panel-id" id="trigger-id"> Question text

``` Keyboard support: - `Enter`/`Space`: Toggle panel - `Arrow Down`: Move to next trigger - `Arrow Up`: Move to previous trigger - `Home`: Move to first trigger - `End`: Move to last trigger ### Tabs ```html

General settings content

``` Keyboard support: - `Arrow Left`/`Right`: Move between tabs (auto-activates) - `Home`: First tab - `End`: Last tab ### Carousel ```html

...

``` - Auto-play pauses on hover and focus - Each slide has `aria-label="Slide X of Y"` - Prev/Next buttons have descriptive `aria-label` - Dot navigation buttons have `aria-label="Go to slide X"` ### Modal / Dialog ```html ``` - `aria-modal="true"` tells screen readers to ignore content behind the modal - `aria-labelledby` points to the dialog's heading - Escape key closes the modal - Focus returns to the trigger element on close --- ## Images ```html Acme dashboard showing 24 deploys today with a 96% success rate

``` --- ## Motion & Animation All animations respect `prefers-reduced-motion`: ```css @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } } ``` The carousel also pauses auto-play when `prefers-reduced-motion` is active. --- ## Screen Reader Testing ### VoiceOver (macOS/iOS) - `Cmd + F5`: Toggle VoiceOver - `VO + Right Arrow`: Read next element - `VO + U`: Open rotor (navigate by headings, links, landmarks) ### NVDA (Windows, free) - `Insert + F7`: List all links/headings - `H`: Jump to next heading - `B`: Jump to next button ### Common Issues to Check 1. All images have meaningful alt text 2. Form errors are announced (use `role="alert"` or `aria-live`) 3. Dynamic content changes are announced (use `aria-live`) 4. Modal focus trap works correctly 5. Skip link is the first focusable element 6. Page title changes on navigation --- ## Automated Testing Tools ```bash # axe-core CLI npm install -g @axe-core/cli axe http://localhost:8080/pages/index.html --tags wcag2a,wcag2aa,wcag22aa # Lighthouse (built into Chrome DevTools) # Open DevTools → Lighthouse → Accessibility # WAVE browser extension # https://wave.webaim.org/extension/ ``` Target score: **100/100 on Lighthouse Accessibility** for all pages.