wcag22-a11y-audit

# WCAG 2.2 Accessibility Audit Skill

## When to Use This Skill

Use this skill when the user wants to:

- Perform accessibility testing or auditing on a live webpage
- Evaluate a page against WCAG 2.2 Success Criteria
- Identify accessibility barriers for keyboard and screen reader users
- Generate a structured accessibility audit report with evidence

---

## Tool Usage Strategy (IMPORTANT)

**This skill uses a hybrid approach combining structured accessibility tree analysis and visual inspection.**

### Priority Order

1. **PRIMARY: Accessibility Tree (search_elements)**
   - Use `search_elements(tabId, query)` to retrieve structured accessibility information
   - This provides `role`, `name`, `value`, `checked`, `expanded`, `disabled`, `focused`, etc.
   - Best for: 1.1.1, 2.1.1, 4.1.2 and element identification for other SCs

2. **SECONDARY: Visual Analysis (Screenshot + LLM)**
   - Use `capture_screenshot(sendToLLM=true)` for visual inspection
   - Essential for: 1.4.3, 1.4.11, 2.4.7 (contrast and focus visibility)
   - Insert `[[screenshot:N]]` placeholders in the report for evidence

3. **KEYBOARD INTERACTION: computer tool**
   - Use `computer(action='key', text='Tab')` for keyboard navigation testing
   - Essential for: 2.1.1, 2.1.2, 2.4.3, 2.4.7
   - Capture screenshots at key moments to document focus path

### Workflow for Each Test

```
1. Identify scope (page/component/flow)
2. Collect evidence via search_elements and/or screenshot
3. Apply SC-specific judgment rules
4. Record Pass/Fail with evidence references
5. Provide actionable fix recommendations
```

---

## Threat Context & Privacy Notes

**IMPORTANT**: This audit may capture sensitive information.

- Screenshots and accessibility tree dumps may contain: account names, order details, personal data, auth tokens, internal URLs.
- **DO NOT** include raw sensitive data in the final report.
- If a screenshot contains PII, note this and recommend masking before sharing.
- Contrast/visual judgments are **estimates**—always recommend verification with dedicated tools (e.g., WebAIM Contrast Checker, axe DevTools).

---

## Pre-Audit Setup (Recommended)

Before starting the audit, confirm with the user:

1. **Target Scope**: Full page, specific component, or user flow?
2. **Target Audience**: Who are the primary users? (general public, internal staff, specific disability considerations)
3. **Priority SCs**: Test all 8 SCs or focus on specific ones?
4. **Known Issues**: Any existing accessibility issues to verify?

---

## Success Criteria Test Procedures

### SC 1.1.1 Non-text Content (Level A)

**Goal**: All non-text content (images, icons, controls) must have text alternatives.

**Test Steps**:

1. **Find images and icons**:
   ```
   search_elements(tabId, "image | img")
   search_elements(tabId, "button | link | menuitem | tab | switch")
   ```

2. **Evaluate each element**:
   - Check if `name` attribute exists and is meaningful
   - **FAIL** conditions:
     - `name` is empty or missing
     - `name` is generic: "icon", "image", "button", "img", "graphic", file names (e.g., "logo.png")
     - `name` duplicates visible text unnecessarily (redundant)
   - **PASS** conditions:
     - `name` accurately describes purpose or equivalent information

3. **For decorative content**:
   - If truly decorative, element should have `role="presentation"` or `role="none"`, or `name=""` (explicitly empty)

**Common Failures**:
- Icon buttons with no accessible name (screen reader announces "button" only)
- Images with `alt="image"` or `alt="logo.png"`
- SVG icons without `aria-label` or visually hidden text

**Fix Recommendations**:
- Add meaningful `alt` text to images
- Use `aria-label` or `aria-labelledby` for icon buttons
- Use native semantic elements where possible (`<button>` instead of `<div>`)

---

### SC 1.4.3 Contrast (Minimum) (Level AA)

**Goal**: Text must have sufficient contrast against its background.

**Requirements**:
- Normal text: ≥ 4.5:1 contrast ratio
- Large text (≥24px regular or ≥18.66px bold): ≥ 3:1 contrast ratio

**Test Steps**:

1. **Capture page states**:
   ```
   capture_screenshot(sendToLLM=true)
   ```
   - Default state
   - Hover/focus states (use `computer` to trigger)
   - Error/disabled states if applicable

2. **Visual analysis prompt** (for LLM):
   > "Analyze this screenshot for text contrast issues. Identify any text that appears to have low contrast against its background. Focus on:
   > - Small/body text that may be below 4.5:1
   > - Placeholder text in input fields
   > - Disabled state text
   > - Text overlaid on images or gradients
   > List suspicious elements with their approximate location."

3. **Record findings**:
   - Note: Visual analysis provides **estimates only**
   - Flag elements for manual verification with contrast checker tools

**Common Failures**:
- Light gray text on white backgrounds
- Placeholder text with insufficient contrast
- Text on image backgrounds without overlay

**Fix Recommendations**:
- Increase text color darkness or background lightness
- Add semi-transparent overlay behind text on images
- Use contrast checker tools to verify exact ratios

---

### SC 1.4.11 Non-text Contrast (Level AA)

**Goal**: UI components and graphical objects must have ≥ 3:1 contrast.

**Applies to**:
- Input field borders
- Button borders
- Focus indicators
- Icons conveying information
- State indicators (checkboxes, toggles, radio buttons)

**Test Steps**:

1. **Identify UI components**:
   ```
   search_elements(tabId, "textbox | combobox | checkbox | radio | switch | button | slider")
   ```

2. **Capture states**:
   ```
   capture_screenshot(sendToLLM=true)
   ```
   - Document default, hover, focus, active, disabled states

3. **Visual analysis prompt**:
   > "Analyze this screenshot for non-text contrast issues. Check if:
   > - Input field borders are clearly visible (≥3:1 against background)
   > - Button boundaries are distinguishable
   > - Icons are clearly visi