--- name: react-accessibility-validator description: Automatically validate React/Next.js components meet WCAG 2.1 AA standards. Use when creating components, forms, buttons, modals, navigation, or any interactive UI elements. --- # Accessibility Validator Auto-enforces WCAG 2.1 AA accessibility standards for all React/Next.js components. ## Activation Triggers This skill activates when: - Creating React/Next.js components - Building forms, buttons, modals, navigation - Adding interactive elements - Mentioning "component", "UI", "form", "button" - Creating pages or layouts - Working on user-facing features ## WCAG 2.1 AA Requirements (MANDATORY) All components MUST meet: - ✅ **Keyboard navigation** - All interactive elements focusable and usable via keyboard - ✅ **Semantic HTML** - Proper HTML elements and ARIA attributes - ✅ **Color contrast** - 4.5:1 for normal text, 3:1 for large text - ✅ **Screen reader support** - All content accessible to assistive technologies - ✅ **Focus management** - Visible focus indicators, logical tab order - ✅ **Form accessibility** - Labels, error announcements, help text ## Auto-Validation Process ### Step 1: Detect Component Creation When detecting component being written: ```tsx // Component without accessibility function LoginButton({ onClick }) { return

// ❌ Multiple issues! } ``` ### Step 2: Run Accessibility Checklist Verify: 1. ❌ Using div instead of button (semantic HTML) 2. ❌ No keyboard support (only onClick, no onKeyDown) 3. ❌ Not focusable (div not in tab order) 4. ❌ No ARIA attributes 5. ❌ No focus styles ### Step 3: Auto-Fix Violations **Before (Inaccessible):** ```tsx function LoginButton({ onClick }) { return

} ``` **After (Accessible):** ```tsx function LoginButton({ onClick }) { return ( ) } ``` ### Step 4: Explain Fixes > **Accessibility Violations Fixed** > > **Changes:** > 1. ✅ Changed `

` to ` // ✅ CORRECT - link for navigation Go to page ``` ### Pattern 2: Form Labels ```tsx // ❌ WRONG - no label // ❌ WRONG - placeholder as label (insufficient) // ✅ CORRECT - explicit label Email Address // ✅ CORRECT - with error handling Email Address {errors.email && (

{errors.email.message}

)} ``` ### Pattern 3: Modal Dialogs ```tsx // ✅ CORRECT - Accessible modal import { Dialog } from '@headlessui/react' function Modal({ isOpen, onClose, title, children }) { return ( ) } ``` ### Pattern 4: Icon Buttons ```tsx // ❌ WRONG - no accessible name // ✅ CORRECT - with aria-label // ✅ CORRECT - with visually hidden text ``` ### Pattern 5: Loading States ```tsx // ❌ WRONG - no screen reader announcement {isLoading && } // ✅ CORRECT - with live region {isLoading && (

)} ``` ### Pattern 6: Images ```tsx // ❌ WRONG - no alt text

// ✅ CORRECT - with alt text

// ✅ CORRECT - decorative image ``` ## Keyboard Navigation Checklist For every component, verify: - ✅ All interactive elements are focusable (button, a, input, etc.) - ✅ Tab order is logical (follows visual flow) - ✅ Focus is visible (outline, ring, or custom indicator) - ✅ No keyboard traps (can escape from all UI) - ✅ Enter/Space work on buttons - ✅ Escape closes modals/dropdowns - ✅ Arrow keys work in lists/menus ## Color Contrast Requirements Check all text meets minimum contrast: ```tsx // ❌ WRONG - insufficient contrast (2.5:1)

Low contrast text

// ✅ CORRECT - good contrast (7:1)

High contrast text

// ✅ CORRECT - large text can be 3:1

Large heading

``` **Minimum Ratios:** - Normal text (< 18pt): 4.5:1 - Large text (≥ 18pt or bold ≥ 14pt): 3:1 - UI components: 3:1 ## Screen Reader Support ### Landmark Regions ```tsx // ✅ CORRECT - proper landmarks

{/* main content */}

``` ### ARIA Labels ```tsx // ✅ CORRECT - descriptive labels ``` ### Live Regions ```tsx // ✅ CORRECT - announce changes

Error: Please fill in all required fields

5 items in cart

``` ## Focus Management ```tsx 'use client' import { useEffect, useRef } from 'react' function Modal({ isOpen, title }) { const titleRef = useRef(null) // Focus title when modal opens useEffect(() => { if (isOpen && titleRef.current) { titleRef.current.focus() } }, [isOpen]) return ( ) } ``` ## Testing Recommendations Suggest automated tests: ```tsx import { render } from '@testing-library/react' import { axe, toHaveNoViolations } from 'jest-axe' expect.extend(toHaveNoViolations) test('LoginButton has no accessibility violations', async () => { const { container } = render( {}} />) const results = await axe(container) expect(results).toHaveNoViolations() }) ``` ## Common Violations Checked ### Missing Labels - Form inputs without labels - Icon buttons without aria-label - Images without alt text ### Poor Semantics - Divs instead of buttons - Links instead of buttons - Missing heading hierarchy ### Keyboard Issues - Elements not in tab order - Missing focus indicators - Keyboard traps ### Screen Reader Issues - Missing ARIA labels - Incorrect ARIA roles - No live region announcements ### Color Issues - Insufficient contrast - Color-only information - Missing text alternatives ## Integration with Tailwind ```tsx // Utility class for screen reader only text Accessible description // Focus ring utilities // High contrast text

Good contrast in both modes

``` ## Success Criteria ✅ All interactive elements keyboard accessible ✅ All images have alt text ✅ All forms have labels ✅ Color contrast ≥ 4.5:1 (normal text) ✅ Proper semantic HTML used ✅ ARIA attributes where needed ✅ Focus indicators visible ✅ Screen reader tested ✅ Automated axe tests pass ## Behavior **Proactive enforcement:** - Check accessibility without being asked - Fix violations immediately - Add ARIA attributes automatically - Explain WCAG criteria for each fix - Suggest automated tests **Never:** - Require explicit "check accessibility" request - Wait for accessibility audit - Just warn without fixing **Block completion if:** - Buttons are divs - Forms lack labels - Color contrast fails - Icon buttons lack accessible names - Images missing alt text This ensures every component is accessible from day one.