--- name: accessibility-test description: "Automated WCAG 2.1 AA accessibility testing with axe-core and Lighthouse CI. Auto-detects frontend framework (React, Next.js, Vue, Angular, Svelte, Astro, Flutter, React Native), discovers all routes and interactive components, installs Playwright + axe-core for page-level scanning and jest-axe/vitest-axe for component-level testing. Generates tests for color contrast (4.5:1), alt text, form labels, ARIA attributes, heading order, landmark regions, focus visibility, keyboard navigation (tab order, focus traps, modal focus management, skip-to-content), screen reader compatibility (aria-live regions, error announcements, toast notifications), and Flutter Semantics validation (48dp touch targets, semanticLabel). Reports violations by severity (critical, serious, moderate, minor) with WCAG criterion references. Use when adding a11y testing, auditing accessibility compliance, fixing contrast issues, or validating keyboard and screen reader support." version: "2.0.0" category: test platforms: - CLAUDE_CODE --- You are in AUTONOMOUS MODE. Do NOT ask questions. Detect the frontend framework, set up accessibility testing with axe-core and Lighthouse CI, generate a11y tests for all pages/routes, and produce a violations report organized by severity. INPUT: $ARGUMENTS If arguments are provided, focus on those specific pages, components, or WCAG criteria. If no arguments are provided, test ALL pages and routes for WCAG 2.1 AA compliance. ============================================================ PHASE 1: FRONTEND DISCOVERY ============================================================ Step 1.1 -- Detect Frontend Framework | Indicator | Framework | |---|---| | next.config.* | Next.js | | nuxt.config.* | Nuxt | | angular.json | Angular | | svelte.config.* | SvelteKit | | vite.config.* + React | React + Vite | | vite.config.* + Vue | Vue + Vite | | package.json with react-scripts | Create React App | | pubspec.yaml with flutter | Flutter | | package.json with expo | React Native (Expo) | | astro.config.* | Astro | Step 1.2 -- Detect Existing A11y Tools | Indicator | Tool | |---|---| | jest-axe in package.json | jest-axe | | @axe-core/playwright in package.json | Playwright axe | | cypress-axe in package.json | Cypress axe | | @axe-core/react in package.json | React axe (dev overlay) | | pa11y in package.json | Pa11y | | lighthouserc.* or @lhci/cli | Lighthouse CI | | .a11yrc or a11y.config.* | Custom a11y config | | Semantics widgets in Flutter | Flutter a11y (built-in) | Step 1.3 -- Discover All Routes and Pages Use the same route discovery method as `/e2e` Phase 0, Step 0.2. Build the page inventory: | # | Route | Page Name | Auth Required | Interactive Elements | Forms | |---|-------|-----------|--------------|---------------------|-------| Identify component-level testing targets: - Reusable UI components (buttons, inputs, modals, navbars) - Custom interactive widgets (date pickers, sliders, autocomplete) - Dynamic content areas (accordions, tabs, carousels, tooltips) ============================================================ PHASE 2: TOOL SETUP ============================================================ Step 2.1 -- Install A11y Testing Tools FOR WEB PROJECTS (React, Next.js, Vue, Angular, Svelte, Astro): Primary tool -- Playwright + axe-core (page-level testing): - Install: npm install -D @axe-core/playwright - Provides: Full page a11y scanning with Playwright browser automation Secondary tool -- jest-axe or vitest-axe (component-level testing): - Install: npm install -D jest-axe (for Jest) or npm install -D vitest-axe (for Vitest) - Provides: A11y checks on rendered components in unit tests Reporting tool -- Lighthouse CI: - Install: npm install -D @lhci/cli - Provides: Automated Lighthouse scores including accessibility score - Create lighthouserc.js config FOR FLUTTER: No extra installation needed. Flutter has built-in Semantics testing. - Use WidgetTester to verify Semantics tree - Use flutter test --test-semantics for semantic validation - Use integration_test for full-app a11y flows Step 2.2 -- Configure Lighthouse CI Create lighthouserc.js (or .lighthouserc.json): Configuration must include: - URLs to test (all discovered routes) - Assertions for accessibility score: - minScore: 0.9 (WCAG 2.1 AA target = 90%+) - Number of runs: 3 (for stability) - Preset: "lighthouse:no-pwa" (focus on accessibility, not PWA) - Categories to audit: accessibility, best-practices Step 2.3 -- Configure axe-core Rules Set up axe-core with WCAG 2.1 AA as the baseline: Rule tags to enable: - wcag2a: WCAG 2.0 Level A - wcag2aa: WCAG 2.0 Level AA - wcag21a: WCAG 2.1 Level A - wcag21aa: WCAG 2.1 Level AA - best-practice: Additional best practice rules Rules to explicitly verify: - color-contrast: Text has sufficient contrast ratio (4.5:1 normal, 3:1 large) - image-alt: All images have alt text - label: All form inputs have labels - link-name: All links have discernible text - button-name: All buttons have discernible text - document-title: Page has a title - html-has-lang: HTML element has lang attribute - landmark-one-main: Page has one main landmark - region: All content is within landmarks - aria-required-attr: ARIA elements have required attributes - aria-valid-attr-value: ARIA attributes have valid values - heading-order: Headings are in sequential order - tabindex: No tabindex > 0 (disrupts tab order) - focus-visible: Focused elements have visible focus indicator ============================================================ PHASE 3: TEST GENERATION ============================================================ Step 3.1 -- Page-Level A11y Tests (Playwright + axe) FOR EACH page in the inventory, generate a test file: ``` test('[page-name] - accessibility', async ({ page }) => { // Navigate and wait for page to be fully loaded // Inject axe-core // Run full page scan with WCAG 2.1 AA tags // Assert zero violations }) ``` Each page test must: 1. Navigate to the page (with authentication if required) 2. Wait for all content to load (network idle, fonts, images) 3. Run axe-core scan with wcag2a, wcag2aa, wcag21a, wcag21aa tags 4. Capture all violations with: - Rule ID and description - Impact level (critical, serious, moderate, minor) - Affected HTML element - WCAG success criterion violated - Fix suggestion Test interactive states for each page: - Default state (page loaded) - After opening a modal/dialog (check focus trap, aria attributes) - After expanding an accordion/dropdown (check aria-expanded) - After triggering an error state (check error messages are announced) - After form validation failure (check error association with inputs) Step 3.2 -- Keyboard Navigation Tests FOR EACH page, generate keyboard navigation tests: TAB ORDER: 1. Press Tab repeatedly from the top of the page 2. Verify focus moves in a logical reading order 3. Verify no element is skipped 4. Verify no focus trap (except intentional ones in modals) 5. Verify focus is visible on every focused element KEYBOARD INTERACTIONS: - Buttons: Enter and Space activate - Links: Enter activates - Checkboxes: Space toggles - Radio buttons: Arrow keys move between options - Dropdowns/Select: Arrow keys navigate options, Enter selects - Modals: Escape closes, Tab stays within modal (focus trap) - Menus: Arrow keys navigate, Escape closes - Tabs: Arrow keys switch tabs - Accordions: Enter/Space toggles FOCUS MANAGEMENT: - When a modal opens, focus moves to the first focusable element inside - When a modal closes, focus returns to the trigger element - After deleting an item, focus moves to a sensible element (next item or heading) - Skip-to-content link works (first Tab stop, jumps to main content) Step 3.3 -- Component-Level A11y Tests FOR reusable components, generate unit-level a11y tests: Using jest-axe or vitest-axe: 1. Render the component in isolation 2. Run axe on the rendered output 3. Assert zero violations Test each component variant: - Default state - Disabled state - Error state - Loading state - With different prop combinations Verify semantic HTML: - Buttons use