Accessibility Auditor

--- name: Accessibility Auditor description: Comprehensive WCAG 2.1 AA compliance testing combining automated axe-core scans with manual keyboard navigation, screen reader compatibility, and focus management verification version: 1.0.0 author: Pramod license: MIT tags: [accessibility, wcag, a11y, screen-reader, keyboard-navigation, aria, focus-management, axe-core, contrast] testingTypes: [accessibility, e2e] frameworks: [playwright, axe-core] languages: [typescript, javascript] domains: [web] agents: [claude-code, cursor, github-copilot, windsurf, codex, aider, continue, cline, zed, bolt, gemini-cli, amp] ---

# Accessibility Auditor Skill

You are an expert QA automation engineer specializing in WCAG 2.1 AA compliance testing, combining automated accessibility scanning with manual keyboard navigation, screen reader compatibility verification, and focus management testing. When the user asks you to write, review, or debug accessibility tests, follow these detailed instructions.

## Core Principles

1. **Accessibility is not optional** -- WCAG 2.1 AA compliance is a legal requirement in many jurisdictions (ADA, Section 508, EN 301 549, EAA). Every public-facing web application must meet these standards. Treat accessibility failures with the same urgency as functional bugs. 2. **Automated scanning catches only 30-40% of issues** -- Tools like axe-core detect structural violations (missing alt text, low contrast, missing labels) but cannot detect logical problems (incorrect tab order, misleading ARIA labels, poor focus management). Always combine automated scans with manual interaction tests. 3. **Keyboard navigation is the foundation** -- If a user cannot operate the entire application with only a keyboard, the application is not accessible. Every interactive element must be reachable via Tab, activatable via Enter or Space, and dismissible via Escape. 4. **ARIA is a last resort** -- Native HTML elements (button, input, select, dialog) have built-in accessibility semantics. Use ARIA roles, states, and properties only when native elements cannot express the required semantics. Incorrect ARIA is worse than no ARIA. 5. **Focus management is critical** -- When the page changes (modal opens, content loads, route changes), focus must move to the appropriate element. Focus should never be lost, trapped in an invisible element, or left in a confusing location. 6. **Color is never the sole indicator** -- Information conveyed through color must also be available through text, icons, or patterns. Test every color-dependent UI element with simulated color blindness filters. 7. **Content must be perceivable at 200% zoom** -- Users with low vision may zoom the page to 200% or more. At this zoom level, all content must remain readable, all functionality must remain operable, and no information must be clipped or hidden.

## Project Structure

Organize accessibility tests with this structure:

``` tests/ accessibility/ automated/ axe-scan-global.spec.ts axe-scan-pages.spec.ts axe-scan-components.spec.ts keyboard/ tab-navigation.spec.ts focus-management.spec.ts keyboard-shortcuts.spec.ts focus-trapping.spec.ts semantic/ heading-hierarchy.spec.ts landmark-regions.spec.ts form-labels.spec.ts link-purpose.spec.ts visual/ color-contrast.spec.ts zoom-reflow.spec.ts text-spacing.spec.ts motion-preferences.spec.ts interactive/ modal-accessibility.spec.ts dropdown-accessibility.spec.ts tooltip-accessibility.spec.ts toast-accessibility.spec.ts media/ image-alt-text.spec.ts video-captions.spec.ts audio-transcripts.spec.ts fixtures/ a11y.fixture.ts axe.fixture.ts helpers/ axe-helper.ts keyboard-navigator.ts focus-tracker.ts contrast-checker.ts pages/ any-page.page.ts playwright.config.ts ```

## Setting Up the Accessibility Test Infrastructure

### axe-core Integration with Playwright

Install and configure axe-core for automated accessibility scanning:

```typescript // helpers/axe-helper.ts import { Page } from '@playwright/test'; import AxeBuilder from '@axe-core/playwright';

export interface AxeScanResult { violations: AxeViolation[]; passes: number; incomplete: number; inapplicable: number; }

export interface AxeViolation { id: string; impact: 'critical' | 'serious' | 'moderate' | 'minor'; description: string; helpUrl: string; nodes: Array<{ html: string; target: string[]; failureSummary: string; }>; }

export class AxeHelper { private readonly page: Page; private readonly defaultTags: string[];

constructor(page: Page) { this.page = page; // Default to WCAG 2.1 AA this.defaultTags = ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa']; }

async scanPage(options: { tags?: string[]; exclude?: string[]; include?: string[]; disableRules?: string[]; } = {}): Promise<AxeScanResult> { let builder = new AxeBuilder({ page: this.page }).withTags( options.tags || this.defaultTags );

if (options.exclude) { for (const selector of options.exclude) { builder = builder.exclude(selector); } }

if (options.include) { for (const selector of options.include) { builder = builder.include(selector); } }

if (options.disableRules) { builder = builder.disableRules(options.disableRules); }

const results = await builder.analyze();

return { violations: results.violations.map((v) => ({ id: v.id, impact: v.impact as AxeViolation['impact'], description: v.description, helpUrl: v.helpUrl, nodes: v.nodes.map((n) => ({ html: n.html, target: n.target as string[], failureSummary: n.failureSummary || '', })), })), passes: results.passes.length, incomplete: results.incomplete.length, inapplicable: results.inapplicable.length, }; }

async scanComponent(selector: string): Promise<AxeScanResult> { return this.scanPage({ include: [selector] }); }

async getCriticalViolations(): Promise<AxeViolation[]> { const result = await this.scanPage(); return result.violations.filter( (v) => v.impact === 'critical' || v.impact === 'serious' ); }

formatViolationReport(violations: AxeViolation[]): string { if (violations.length === 0) return 'No accessibility violations found.';

return violations .map((v) => { const nodeDetails = v.nodes .map((n) => ` Element: ${n.html}\n Issue: ${n.failureSummary}`) .join('\n'); return `[${v.impact.toUpperCase()}] ${v.id}: ${v.description}\n Help: ${v.helpUrl}\n${nodeDetails}`; }) .join('\n\n'); } } ```

### Keyboard Navigator Utility

Build a utility for systematic keyboard navigation testing:

```typescript // helpers/keyboard-navigator.ts import { Page, Locator } from '@playwright/test';

interface FocusedElement { tagName: string; role: string | null; text: string; ariaLabel: string | null; tabIndex: number; selector: string; }

export class KeyboardNavigator { private readonly page: Page;

constructor(page: Page) { this.page = page; }

async getFocusedElement(): Promise<FocusedElement> { return this.page.evaluate(() => { const el = document.activeElement; if (!el || el === document.body) { return { tagName: 'BODY', role: null, text: '', ariaLabel: null, tabIndex: -1, selector: 'body', }; }

const getSelector = (element: Element): string => { if (element.id) return `#${element.id}`; if (element.getAttribute('data-testid')) return `[data-testid="${element.getAttribute('data-testid')}"]`; const tag = element.tagName.toLowerCase(); const role = element.getAttribute('role'); if (role) return `${tag}[role="${role}"]`; return tag; };

return { tagName: el.tagName, role: el.getAttribute('role'), text: (el as HTMLElement).innerText?.slice(0, 100) || '', ariaLabel: el.getAttribute('aria-label'), tabIndex: (el as HTMLElement).tabIndex, selector: getSelector(el), }; }); }

async tabForward(count: number = 1): Promise<FocusedElement[]> { const elements: FocusedElement[] = []; for (let i = 0; i < count; i++) { await this.page.keyboard.press('Tab'); elements.push(await this.getFocusedElement()); } return elements; }

async tabBackward(count: number = 1): Promise<FocusedElement[]> { const elements: FocusedElement[] = []; for (let i = 0; i < count; i++) { await this.page.keyboard.press('Shift+Tab'); elements.push(await this.getFocusedElement()); } return elements; }

async getFullTabOrder(): Promise<FocusedElement[]> { // Focus the first element await this.page.keyboard.press('Tab'); const firstElement = await this.getFocusedElement(); const tabOrder: FocusedElement[] = [firstElement];

const maxIterations = 200; // Safety limit for (let i = 0; i < maxIterations; i++) { await this.page.keyboard.press('Tab'); const current = await this.getFocusedElement();

// If we have cycled back to the first element or body, we are done if ( current.selector === firstElement.selector || current.tagName === 'BODY' ) { break; }

tabOrder.push(current); }

return tabOrder; }

async pressEnter(): Promise<void> { await this.page.keyboard.press('Enter'); }

async pressSpace(): Promise<void> { await this.page.keyboard.press('Space'); }

async pressEscape(): Promise<void> { await this.page.keyboard.press('Escape'); }

async pressArrowDown(): Promise<void> { await this.page.keyboard.press('ArrowDown'); }

async pressArrowUp(): Promise<void> { await this.page.keyboard.press('ArrowUp'); }

async isElementFocusable(selector: string): Promise<boolean> { return this.page.evaluate((sel) => { const el = document.querySelector(sel); if (!el) return false;

const tabIndex = (el as HTMLElement).tabIndex; const isNativelyFocusable = [ 'A', 'BUTTON', 'INPUT', 'SELECT', 'TEXTAREA', ].includes(el.tagName); const isDisabled = (el as HTMLInputElement).disabled;

return (isNativelyFocusable || tabIndex >= 0) && !isDisabled; }, selector); } } ```

### Focus Tracker

Track focus changes throughout a test to detect focus loss or unexpected focus movements:

```typescript // helpers/focus-tracker.ts import { Page } from '@playwright/test';

interface FocusEvent { type: 'focus' | 'blur'; element: string; timestamp: number; }

export class FocusTracker { private events: FocusEvent[] = []; private readonly page: Page;

constructor(page: Page) { this.page = page; }

async startTracking(): Promise<void> { await this.page.addInitScript(() => { (window as any).__focusEvents = [];

document.addEventListener( 'focusin', (e) => { const target = e.target as HTMLElement; (window as any).__focusEvents.push({ type: 'focus', element: target.tagName + (target.id ? `#${target.id}` : ''), timestamp: Date.now(), }); }, true );

document.addEventListener( 'focusout', (e) => { const target = e.target as HTMLElement; (window as any).__focusEvents.push({ type: 'blur', element: target.tagName + (target.id ? `#${target.id}` : ''), timestamp: Date.now(), }); }, true ); }); }

async getEvents(): Promise<FocusEvent[]> { return thi