--- name: audit-accessibility description: > Automated WCAG 2.2 accessibility audit using Playwright browser MCP to crawl every page, inject axe-core via browser_evaluate, test keyboard navigation, check color contrast, ARIA labels, heading hierarchy, form labels, and focus management. Cross-references Sentry for assistive-technology-related errors, researches current WCAG guidelines via Firecrawl, and produces a structured PASS/FAIL compliance report per criterion. Works with any project — auto-detects pages from the route manifest. Use when asked to: "audit accessibility", "check a11y", "WCAG audit", "check keyboard nav", "test screen reader", "accessibility compliance", "ADA compliance check", "run a11y audit", "check color contrast", or "audit for disabilities". license: MIT --- # Accessibility Audit Automated WCAG 2.2 accessibility audit: axe-core scanning, keyboard navigation testing, color contrast verification, ARIA compliance, and assistive technology error analysis. Works with **any project** — auto-detects pages from the codebase route structure. ## Critical Rules > **Always use the `browser-anti-stall` protocol** when using Playwright browser MCP tools. > **Test every publicly reachable page.** Accessibility bugs on obscure pages still affect real users. > **Keyboard-only testing is non-negotiable.** If a feature cannot be operated without a mouse, it fails WCAG 2.1.1 regardless of what axe-core says. > **Automated tools catch ~30-40% of a11y issues.** Always supplement axe-core with manual checks (heading order, focus management, meaningful link text, reading order). > **Use concrete WCAG success criteria IDs.** "Color contrast is bad" is not actionable. "Fails WCAG 2.2 SC 1.4.3 (Contrast Minimum) — foreground #777 on background #fff = 4.48:1, needs 4.5:1" is. --- ## Phase 0: Auto-Detect Pages and Components ### 0a. Discover Route Structure ``` Glob("**/app/**/page.{tsx,jsx,ts,js}") Glob("**/pages/**/*.{tsx,jsx,ts,js}") Glob("**/src/routes/**/*.{tsx,jsx,svelte,vue}") ``` ### 0b. Find the App URL ``` Grep(pattern: "NEXT_PUBLIC_APP_URL|NEXT_PUBLIC_BASE_URL|VITE_APP_URL|APP_URL|localhost", glob: ".env*") ``` If no production URL, default to `http://localhost:3000` (or detected dev server port). ### 0c. Detect CSS Framework and Component Library ``` Grep(pattern: "tailwindcss|@chakra-ui|@mui|@radix-ui|shadcn|bootstrap|bulma", glob: "package.json") ``` This matters because each framework has different a11y defaults (e.g., Radix primitives are accessible by default, custom components may not be). ### 0d. Detect Existing a11y Tooling ``` Grep(pattern: "axe-core|@axe-core|eslint-plugin-jsx-a11y|pa11y|lighthouse|@testing-library", glob: "package.json") Grep(pattern: "aria-|role=|tabIndex|sr-only|visually-hidden", glob: "*.{tsx,jsx,vue,svelte}", output_mode: "count") ``` Record: - `APP_URL` — base URL for testing - `PAGES` — list of routes to audit - `CSS_FRAMEWORK` — Tailwind, MUI, Chakra, etc. - `COMPONENT_LIB` — Radix, shadcn, MUI, Headless UI, etc. - `EXISTING_A11Y_TOOLS` — what's already in place - `ARIA_USAGE_COUNT` — rough indicator of a11y awareness in the codebase --- ## Phase 1: Research Current WCAG Guidelines ### 1a. Firecrawl Research ```json CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_search", arguments: { "query": "WCAG 2.2 success criteria checklist web accessibility 2026", "limit": 5 }) ``` ```json CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_search", arguments: { "query": "axe-core automated accessibility testing best practices common false positives", "limit": 5 }) ``` ```json CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_search", arguments: { "query": " accessibility best practices common issues", "limit": 5 }) ``` Scrape the 2-3 most authoritative results: ```json CallMcpTool(server: "user-firecrawl", toolName: "firecrawl_scrape", arguments: { "url": "", "formats": ["markdown"], "onlyMainContent": true }) ``` ### 1b. Framework-Specific a11y Docs (Context7) If the project uses a component library, fetch its accessibility documentation: ```json CallMcpTool(server: "context7", toolName: "resolve-library-id", arguments: { "libraryName": "" }) ``` ```json CallMcpTool(server: "context7", toolName: "query-docs", arguments: { "libraryId": "", "query": "accessibility ARIA keyboard navigation focus management" }) ``` --- ## Phase 2: Automated Scanning (axe-core via Playwright) ### 2a. Navigate to Each Page For each page discovered in Phase 0a: ```json CallMcpTool(server: "user-playwright", toolName: "browser_navigate", arguments: { "url": "" }) ``` Apply the `browser-anti-stall` protocol: wait 2s, snapshot, verify page loaded. ### 2b. Inject and Run axe-core Use `browser_evaluate` to inject axe-core from CDN and run a full scan: ```json CallMcpTool(server: "user-playwright", toolName: "browser_evaluate", arguments: { "javascript": "await new Promise((resolve, reject) => { const script = document.createElement('script'); script.src = 'https://cdnjs.cloudflare.com/ajax/libs/axe-core/4.10.2/axe.min.js'; script.onload = resolve; script.onerror = reject; document.head.appendChild(script); }); const results = await axe.run(); return JSON.stringify({ violations: results.violations.map(v => ({ id: v.id, impact: v.impact, description: v.description, help: v.help, helpUrl: v.helpUrl, nodes: v.nodes.length, targets: v.nodes.slice(0, 3).map(n => n.target[0]) })), passes: results.passes.length, incomplete: results.incomplete.length, inapplicable: results.inapplicable.length });" }) ``` For each violation returned, record: - **Rule ID** (e.g., `color-contrast`, `image-alt`, `label`) - **Impact** (critical, serious, moderate, minor) - **WCAG criteria** mapped from the rule - **Affected elements** (CSS selectors) - **Count** of affected nodes ### 2c. Check Specific WCAG Categories Manually axe-core cannot catch everything. For each page, also check: **Heading Hierarchy (WCAG 1.3.1):** ```json CallMcpTool(server: "user-playwright", toolName: "browser_evaluate", arguments: { "javascript": "return JSON.stringify(Array.from(document.querySelectorAll('h1,h2,h3,h4,h5,h6')).map(h => ({ tag: h.tagName, text: h.textContent.trim().substring(0, 50) })));" }) ``` Verify: only one `h1`, headings don't skip levels (h1 -> h3 without h2). **Image Alt Text (WCAG 1.1.1):** ```json CallMcpTool(server: "user-playwright", toolName: "browser_evaluate", arguments: { "javascript": "return JSON.stringify(Array.from(document.querySelectorAll('img')).map(img => ({ src: img.src.substring(img.src.lastIndexOf('/') + 1), alt: img.alt, hasAlt: img.hasAttribute('alt'), decorative: img.getAttribute('role') === 'presentation' || img.alt === '' })));" }) ``` Verify: all informative images have descriptive alt text, decorative images have `alt=""` or `role="presentation"`. **Link Text (WCAG 2.4.4):** ```json CallMcpTool(server: "user-playwright", toolName: "browser_evaluate", arguments: { "javascript": "return JSON.stringify(Array.from(document.querySelectorAll('a')).filter(a => { const text = (a.textContent || '').trim().toLowerCase(); return text === 'click here' || text === 'here' || text === 'read more' || text === 'learn more' || text === '' || text === 'link'; }).map(a => ({ href: a.href, text: (a.textContent || '').trim(), ariaLabel: a.getAttribute('aria-label') })));" }) ``` Flag generic link text ("click here", "read more", empty links without aria-label). **Form Labels (WCAG 1.3.1, 4.1.2):** ```json CallMcpTool(server: "user-playwright", toolName: "browser_evaluate", arguments: { "javascript": "return JSON.stringify(Array.from(document.querySelectorAll('input,select,textarea')).map(el => ({ type: el.type, name: el.name, id: el.id, hasLabel: !!document.querySelector('label[for=\"' + el.id + '\"]'), ariaLabel: el.getAttribute('aria-label'), ariaLabelledBy: el.getAttribute('aria-labelledby'), placeholder: el.placeholder })));" }) ``` Verify: every form control has an associated `