Product

---
name: accessibility
description: WCAG 2.2 compliance audit — keyboard navigation, screen reader testing, ARIA, color contrast
triggers: [a11y, accessibility, WCAG, keyboard nav, screen reader, aria, color contrast, tab order]
tags: [product]
context_cost: medium
---
# Accessibility Skill

## Goal
Ensure UI features meet WCAG 2.2 Level AA requirements through automated scanning and manual verification. Produce an actionable report with specific violations and fixes.

## Steps

1. **Run automated accessibility scan**
   ```bash
   # axe-core with Playwright (recommended)
   npx playwright test --config=playwright.a11y.config.ts

   # Pa11y for batch URL testing
   npx pa11y http://localhost:3000 --standard WCAG2AA

   # Lighthouse accessibility audit
   npx lighthouse http://localhost:3000 --only-categories=accessibility --output=json
   ```

   **Playwright + axe-core test:**
   ```typescript
   import { test, expect } from '@playwright/test';
   import { checkA11y, injectAxe } from 'axe-playwright';

   test('home page has no accessibility violations', async ({ page }) => {
     await page.goto('/');
     await injectAxe(page);
     await checkA11y(page, null, {
       axeOptions: { runOnly: { type: 'tag', values: ['wcag2a', 'wcag2aa', 'wcag22aa'] } }
     });
   });
   ```

2. **Keyboard navigation check**
   - Tab through all interactive elements — logical focus order?
   - All interactive elements reachable by keyboard (no mouse-only interactions)?
   - Focus is always visible (not removed with `outline: none` without replacement)?
   - Modal dialogs trap focus correctly (Tab/Shift+Tab stays inside modal)?
   - Escape key dismisses modals and popups?
   - Skip navigation link available to bypass repeated navigation?

   ```typescript
   test('can navigate form fields with keyboard', async ({ page }) => {
     await page.goto('/contact');
     await page.keyboard.press('Tab'); // First field
     await expect(page.locator(':focus')).toHaveAttribute('name', 'name');
     await page.keyboard.press('Tab'); // Second field
     await expect(page.locator(':focus')).toHaveAttribute('name', 'email');
   });
   ```

3. **Screen reader compatibility check**
   - All images have descriptive `alt` text (or `alt=""` for decorative images)
   - Form inputs have associated `<label>` elements (not just placeholder)
   - Error messages linked to inputs via `aria-describedby`
   - ARIA roles are used correctly (no `role="button"` on non-interactive elements)
   - Dynamic content changes announced via `aria-live` regions
   - Headings form a logical hierarchy (H1 → H2 → H3, no skipped levels)

   **Common issues to check:**
   ```html
   <!-- BAD: no label for input -->
   <input type="email" placeholder="Enter email">

   <!-- GOOD: associated label -->
   <label for="email">Email address</label>
   <input id="email" type="email" aria-describedby="email-error">
   <span id="email-error" role="alert">Please enter a valid email</span>
   ```

4. **Color contrast check**
   - Normal text: minimum contrast ratio 4.5:1 (WCAG AA)
   - Large text (18pt+): minimum contrast ratio 3:1
   - UI components and graphical objects: minimum 3:1
   ```bash
   # Check specific color combination
   # Use: https://webaim.org/resources/contrastchecker/ or automated axe-core
   ```

5. **Check WCAG 2.2 specific criteria**
   - **2.5.3 Target Size (Minimum):** Interactive targets at least 24×24 CSS pixels
   - **3.3.7 Redundant Entry:** Don't ask users to re-enter info they've already provided
   - **3.3.8 Accessible Authentication:** No cognitive function test required (CAPTCHAs must have alternative)

6. **Produce accessibility report**
   ```markdown
   ## Accessibility Audit Report
   Standard: WCAG 2.2 Level AA
   Date: [date]
   Pages audited: [list]

   ### Critical Violations (WCAG failures — must fix)
   - [ERROR] img elements missing alt text: src/components/ProductCard.tsx:15
   - [ERROR] Form input has no associated label: src/components/ContactForm.tsx:32

   ### Keyboard Navigation Issues
   - [WARNING] Focus not visible on custom button component
   - [INFO] Tab order could be improved on checkout form

   ### Screen Reader Issues
   - [WARNING] Carousel updates not announced (missing aria-live)

   ### Color Contrast
   - [ERROR] #777 on #fff fails 4.5:1 ratio (actual: 4.48:1) — src/styles/typography.css:23

   ### Passed Checks
   - All form inputs have associated labels (except noted above)
   - Heading hierarchy is logical throughout
   - Skip navigation link present

   ### Overall: LEVEL AA NOT MET
   Blocking: [N] critical violations
   ```

## Constraints
- Critical WCAG violations are blocking for public-facing applications
- Accessibility testing must use real browser (Playwright headless chromium, not jsdom)
- Don't mark complete without keyboard navigation test AND automated scan
- Color contrast must be checked at all relevant breakpoints

## Output Format
Accessibility audit report + list of violations with file:line references + recommended fixes.

## Security & Guardrails

### 1. Skill Security (Accessibility)
- **Scanner Sandbox Integrity**: Automated accessibility scanners (like `axe-core` via Playwright) often execute JavaScript within the context of the audited page. The scanning environment must be strictly isolated to prevent malicious XSS payloads on the target site from compromising the auditing agent.
- **Audit Report Immutability**: The generated Accessibility Audit Report must be treated as a compliance document. Agents must not be able to retroactively alter past reports to hide newly discovered violations or falsify compliance metrics.

### 2. System Integration Security
- **Authentication Handlers in Scanning**: When auditing authenticated views, the testing suite must be provisioned with designated, low-privilege `a11y-test` accounts. The agent must NEVER use production admin credentials or real customer session tokens to perform accessibility crawls.
- **Accessible Authentication (WCAG 3.3.8)**: When verifying that authentication workflows do not require cognitive function tests (like complex puzzles), the agent must ensure that the accessible alternative (e.g., WebAuthn, email magic links) maintains equivalent cryptographic strength and resistance to credential stuffing.

### 3. LLM & Agent Guardrails
- **Dark Pattern Recognition**: The agent must be explicitly prompted to flag UI designs that use accessibility features maliciously (e.g., using `aria-hidden="true"` to hide the "Cancel Subscription" button from screen readers) as a critical security/compliance violation.
- **False Negative Veto**: The LLM must not override an automated `[ERROR]` from `axe-core` based on a subjective visual assessment (e.g., "The contrast looks fine to me, I'll ignore the 4.48:1 failure"). Mathematical WCAG thresholds are non-negotiable.