accessibility-testing

# Accessibility Testing

This skill enables the agent to perform thorough accessibility audits of web pages and components against the Web Content Accessibility Guidelines (WCAG) 2.1 at AA and AAA conformance levels. The agent identifies violations across four principles — Perceivable, Operable, Understandable, Robust — and generates structured compliance reports with specific code fixes. It covers automated checks (color contrast, missing alt text, ARIA misuse), semi-automated checks (keyboard navigation flows, focus management), and manual check guidance (screen reader announcements, cognitive load).

## Workflow

1. **Define Audit Scope and Conformance Target**: Determine which pages, components, or user flows to audit, and whether the target is WCAG 2.1 AA (most common legal requirement) or AAA (highest conformance). Identify the assistive technologies to consider: screen readers (NVDA on Windows, VoiceOver on macOS/iOS, TalkBack on Android), keyboard-only navigation, and magnification tools.

2. **Run Automated Scans**: Execute automated accessibility analysis using axe-core or Lighthouse. These tools detect approximately 30-40% of WCAG violations automatically, including missing alt attributes, insufficient color contrast ratios, missing form labels, duplicate IDs, invalid ARIA roles, and missing document language. Capture each violation with its WCAG criterion reference (e.g., 1.4.3 Contrast Minimum), severity (critical, serious, moderate, minor), the affected HTML element, and the CSS selector path.

3. **Perform Keyboard Navigation Testing**: Manually trace every interactive flow using only Tab, Shift+Tab, Enter, Space, Escape, and arrow keys. Verify that focus order matches visual order, that focus indicators are visible (minimum 2px outline with 3:1 contrast), that modal dialogs trap focus correctly, and that no keyboard traps exist. Document any flow where a keyboard user cannot complete a task that a mouse user can.

4. **Test with Screen Readers**: Navigate the page with at least one screen reader to verify that all content is announced correctly. Confirm that images have meaningful alt text (or `alt=""` for decorative images), that headings form a logical hierarchy (no skipped levels), that landmarks (`<nav>`, `<main>`, `<aside>`) are present, and that dynamic content updates are announced via `aria-live` regions.

5. **Generate the Compliance Report**: Produce a structured report organized by WCAG principle and criterion. For each violation, include: the criterion number and name, the severity level, the affected element's HTML snippet, an explanation of why it fails, and the specific code fix. Include a summary table with pass/fail counts per principle and an overall conformance statement.

6. **Provide Remediation Code**: For every violation, supply a concrete before-and-after code snippet showing the exact fix. Group fixes by component or page region so developers can address them systematically rather than one element at a time.

## Usage

Provide the agent with a URL, a block of HTML, or a React/Vue component. Specify the target conformance level (AA or AAA) and any assistive technology requirements. The agent will audit the content and return a structured report with code fixes.

## Examples

### Example 1: WCAG Compliance Audit Report

**User Request**: "Audit this login form for WCAG 2.1 AA compliance."

```html
<div class="login">
  <img src="logo.png">
  <input type="text" placeholder="Username">
  <input type="password" placeholder="Password">
  <div class="btn" onclick="login()">Sign In</div>
  <p style="color: #aaa; font-size: 12px;">Forgot your password?</p>
</div>
```

**Agent Response — Accessibility Audit Report**:

| # | Criterion | Severity | Element | Issue |
|---|-----------|----------|---------|-------|
| 1 | 1.1.1 Non-text Content | Critical | `<img src="logo.png">` | Image has no `alt` attribute. Screen readers cannot describe it. |
| 2 | 1.3.1 Info and Relationships | Critical | `<input placeholder="Username">` | Input has no associated `<label>`. Placeholder text is not a substitute for a label. |
| 3 | 1.3.1 Info and Relationships | Critical | `<input placeholder="Password">` | Same label issue as above. |
| 4 | 1.4.3 Contrast Minimum | Serious | `<p style="color: #aaa">` | Text color `#aaa` on white background has a contrast ratio of 2.32:1. AA requires 4.5:1 for text this size. |
| 5 | 2.1.1 Keyboard | Critical | `<div class="btn" onclick>` | A `<div>` is not focusable via keyboard. Users cannot Tab to or activate this button. |
| 6 | 4.1.2 Name, Role, Value | Critical | `<div class="btn" onclick>` | Element has no semantic role. Screen readers announce it as generic text, not as a button. |

**Remediation — Fixed Code**:

```html
<form class="login" onsubmit="login(event)">
  <img src="logo.png" alt="Acme Corp logo">

  <label for="username">Username</label>
  <input id="username" type="text" autocomplete="username" required>

  <label for="password">Password</label>
  <input id="password" type="password" autocomplete="current-password" required>

  <button type="submit" class="btn">Sign In</button>

  <a href="/forgot-password" style="color: #595959; font-size: 14px;">
    Forgot your password?
  </a>
</form>
```

Changes made: added `alt` to the image, replaced placeholder-only inputs with explicit `<label>` elements, replaced the `<div>` with a semantic `<button>`, changed the link color from `#aaa` (2.32:1) to `#595959` (7.0:1), wrapped the form in a `<form>` element for proper submit handling, and added `autocomplete` attributes.

### Example 2: Fixing a React Component

**User Request**: "Fix accessibility issues in this React notification component."

**Before (inaccessible)**:
```jsx
function Notification({ message, onClose }) {
  return (
    <div className="notification">
      <span>{message}</span>
      <span className="close-x" onClick={onClose}>✕</span>
    </div>
  );
}
```

**After (accessible)**:
```jsx
function Notificatio