--- name: accessibility description: Use when building or reviewing UI components to ensure WCAG 2.1 compliance, keyboard navigation, semantic HTML, ARIA attributes, color contrast, and assistive technology support. --- # UI Accessibility (WCAG 2.1) ## Overview This skill guides implementation and review of accessible UI components following **WCAG 2.1 Level AA standards**. Accessibility ensures your interface is usable by everyone—keyboard users, screen reader users, users with low vision, and users with cognitive disabilities. **Core principle:** Semantic HTML first, ARIA last. Keyboard navigation and screen reader support are non-negotiable. --- ## When to Use / When NOT to Use ### ✅ Use This Skill When - Building new UI components (buttons, modals, dropdowns, forms, tabs) - Adding keyboard navigation or focus management - Reviewing code for accessibility violations - Testing with screen readers or keyboard-only - Ensuring color contrast and visual focus indicators - Adding ARIA attributes to dynamic content ### ❌ Do NOT Use When - Component is purely decorative (no interaction needed) - Audience explicitly doesn't include users with accessibility needs (internally impossible—always assume diverse users) - You're skipping automated testing due to time constraints (violates DoD) --- ## Core Concepts ### 1. Semantic HTML Structure **Foundation:** Use meaningful HTML elements to convey structure and purpose. ```html

Page Title

Section Heading

Content...

Main Title

Section

Subsection

Another Section

Page Title

Main Title

Jumps to h3 (breaks hierarchy)

``` **Label Association Rules:** ```html ``` --- ### 2. Keyboard Navigation **Principle:** All interactive features usable via keyboard—Tab, Shift+Tab, Enter, Space, Arrow keys, Escape. **Key Bindings:** - **Tab / Shift+Tab**: Move focus forward/backward - **Enter / Space**: Activate buttons, toggle checkboxes - **Arrow keys**: Navigate lists, menus, sliders, tabs (up/down for vertical; left/right for horizontal) - **Home / End**: Jump to first/last item in list - **Escape**: Close modal, dropdown, or menu **Focus Management:** ```html
Skip to main content
button:focus { outline: none; /* NEVER DO THIS */ } ``` **Skip Links (Focus Management):** ```html
``` --- ### 3. ARIA Attributes **Golden Rule:** Semantic HTML first. Use ARIA only when native HTML doesn't exist or to enhance semantics. #### Common ARIA Attributes | Attribute | Purpose | Example | |-----------|---------|---------| | `aria-label` | Names element (for icons, buttons without text) | `` | | `aria-labelledby` | Links to another element as label | `

Confirm Delete

...` | | `aria-describedby` | Adds descriptive text (error, hint) | `

Min 8 chars` | | `aria-live` | Announces dynamic content ("polite" or "assertive") | `

Item added to cart
` | | `aria-hidden` | Hides from screen readers (decorative only) | `` | | `role` | Semantic role | `
...` | | `aria-expanded` | Indicates expanded/collapsed state | `` | | `aria-haspopup` | Signals a popup exists | `` | | `aria-selected` | Current selection in list/tabs | `` | | `aria-modal` | Marks modal dialogs | `
...` | | `aria-required` | Flags required form fields | `` | | `aria-invalid` | Indicates validation error | `` | | `aria-atomic` | Reads entire content block | `
Status: Updated
` | --- ### 4. Color Contrast & Visual Focus **WCAG Contrast Ratios:** | Level | Normal Text | Large Text (18pt+) | |-------|-------------|-------------------| | **AA (minimum)** | 4.5:1 | 3:1 | | **AAA (enhanced)** | 7:1 | 4.5:1 | **Visual Focus Indicators (Required):** ```css /* ✅ CORRECT: Visible focus indicator */ button:focus { outline: 2px solid #0066cc; outline-offset: 2px; } /* ✅ CORRECT: Alternative (background change) */ button:focus { background-color: #e6f2ff; box-shadow: inset 0 0 0 2px #0066cc; } /* ❌ WRONG: Removing focus outline */ button:focus { outline: none; /* FORBIDDEN */ } /* ❌ WRONG: Low contrast focus */ button:focus { outline: 1px solid #ccc; /* Too subtle */ } ``` **Never Convey Info by Color Alone:** ```html This field is required This field is required ``` --- ### 5. Testing & Validation **Automated Tools:** - **axe DevTools**: Browser extension for violations (Chrome, Firefox) - **Lighthouse**: Chrome DevTools → Lighthouse → Accessibility (target: 90+) - **Pa11y**: CLI tool for automated scanning - **jest-axe**: Automated testing in Jest **Manual Testing:** 1. **Keyboard-only:** Unplug mouse; navigate using Tab, Enter, Space, arrows 2. **Screen readers:** NVDA (Windows), JAWS (Windows), VoiceOver (macOS/iOS) 3. **Color contrast:** WebAIM Contrast Checker 4. **Zoom:** Test at 200% zoom; ensure nothing breaks **Acceptance Criteria:** - Zero axe DevTools violations - Lighthouse Accessibility ≥ 90 - All features functional via keyboard - All images have alt text - All form inputs have labels --- ## Component Patterns ### Pattern 1: Accessible Dropdown Menu ```jsx import { useState, useRef, useEffect } from 'react'; export function AccessibleDropdown() { const [isOpen, setIsOpen] = useState(false); const [selectedIndex, setSelectedIndex] = useState(0); const buttonRef = useRef(null); const menuRef = useRef(null); const options = ['Edit', 'Duplicate', 'Delete']; // Close on Escape useEffect(() => { const handleKeyDown = (e) => { if (e.key === 'Escape' && isOpen) { setIsOpen(false); buttonRef.current?.focus(); } }; document.addEventListener('keydown', handleKeyDown); return () => document.removeEventListener('keydown', handleKeyDown); }, [isOpen]); // Focus management for arrow keys const handleMenuKeyDown = (e) => { switch (e.key) { case 'ArrowDown': e.preventDefault(); setSelectedIndex((i) => (i + 1) % options.length); break; case 'ArrowUp': e.preventDefault(); setSelectedIndex((i) => (i - 1 + options.length) % options.length); break; case 'Home': e.preventDefault(); setSelectedIndex(0); break; case 'End': e.preventDefault(); setSelectedIndex(options.length - 1); break; case 'Enter': case ' ': e.preventDefault(); handleSelect(options[selectedIndex]); break; default: break; } }; const handleSelect = (option) => { console.log('Selected:', option); setIsOpen(false); buttonRef.current?.focus(); }; return (
{isOpen && ( )}
); } ``` --- ### Pattern 2: Accessible Modal Dialog ```jsx import { useEffect, useRef } from 'react'; export function AccessibleModal({ isOpen, onClose, title, children }) { const dialogRef = useRef(null); useEffect(() => { if (!isOpen) return; // Store the element that opened the modal for focus restore const previouslyFocused = document.activeElement; // Focus the modal dialogRef.current?.focus(); // Focus trap: trap focus inside modal const handleKeyDown = (e) => { if (e.key === 'Escape') { onClose(); previouslyFocused?.focus(); return; } // Trap Tab inside modal if (e.key === 'Tab') { const focusableElements = dialogRef.current?.querySelectorAll( 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])' ); if (!focusableElements || focusableElements.length === 0) return; const firstElement = focusableElements[0]; const lastElement = focusableElements[focusableElements.length - 1]; if (e.shiftKey) { if (document.activeElement === firstElement) { e.preventDefault(); lastElement.focus(); } } else { if (document.activeElement === lastElement) { e.preventDefault(); firstElement.focus(); } } } }; document.addEventListener('keydown', handleKeyDown); return () => { document.removeEventListener('keydown', handleKeyDown); previouslyFocused?.focus(); }; }, [isOpen, onClose]); if (!isOpen) return null; return ( <> {/* Backdrop */}