aiox-core 5.0.1 → 5.0.3

package/pro/squads/design/tasks/a11y-audit.md

@@ -0,0 +1,340 @@
+# Task: a11y-audit
+
+> **Command:** `*a11y-audit {path}`
+> **Agent:** Brad Frost (Design System Architect)
+> **Purpose:** Comprehensive WCAG 2.2 accessibility audit with automated + manual checks
+> **Execution Type:** `Agent`
+> **Dependencies:** depends_on: `[]` · enables: `[contrast-matrix, focus-order-audit, aria-audit]` · workflow: `accessibility`
+
+---
+
+## Output Schema
+- **produces:** `outputs/design-system/{project}/accessibility/a11y-audit-report.json`
+- **format:** JSON data
+- **consumed_by:** contrast-matrix, focus-order-audit, aria-audit
+
+## Overview
+
+Full accessibility audit combining:
+1. **Automated scanning** (axe-core rules via code analysis)
+2. **Manual inspection patterns** (focus order, ARIA usage, semantic HTML)
+3. **Contrast validation** (WCAG 2.2 + APCA)
+4. **Keyboard navigation** mapping
+5. **Screen reader compatibility** assessment
+
+---
+
+## Input
+
+| Parameter | Required | Description |
+|-----------|----------|-------------|
+| `path` | Yes | Directory or file to audit (e.g., `./app/components`) |
+| `--level` | No | WCAG level: `AA` (default) or `AAA` |
+| `--scope` | No | Scope: `full`, `color`, `keyboard`, `aria` (default: `full`) |
+| `--fix` | No | Auto-fix simple issues (missing alt, missing labels) |
+
+---
+
+## Execution Steps
+
+### Phase 1: Discovery (Automated)
+
+```bash
+# 1. Find all component files
+glob("**/*.tsx", "**/*.jsx", "**/*.vue", "**/*.html")
+
+# 2. Count interactive elements
+grep: "onClick|onKeyDown|href|<button|<a |<input|<select|<textarea"
+
+# 3. Find existing ARIA usage
+grep: "aria-|role=|tabIndex"
+
+# 4. Find images without alt
+grep: "<img(?![^>]*alt=)"
+```
+
+### Phase 2: Contrast Analysis
+
+For each color pair found in the codebase:
+
+```typescript
+interface ContrastResult {
+  foreground: string;
+  background: string;
+  ratio: number;
+  wcagAA_normal: boolean;   // ≥4.5:1
+  wcagAA_large: boolean;    // ≥3:1
+  wcagAAA_normal: boolean;  // ≥7:1
+  wcagAAA_large: boolean;   // ≥4.5:1
+  apca_Lc: number;          // APCA Lightness contrast
+  usage: string[];          // Where used
+}
+```
+
+**WCAG 2.2 Contrast Requirements:**
+| Element Type | AA Minimum | AAA Target |
+|--------------|------------|------------|
+| Normal text (<18px) | 4.5:1 | 7:1 |
+| Large text (≥18px or bold ≥14px) | 3:1 | 4.5:1 |
+| UI components | 3:1 | 3:1 |
+| Graphical objects | 3:1 | 3:1 |
+| Focus indicators | 3:1 | 3:1 |
+
+### Phase 3: Keyboard Audit
+
+Check each interactive element:
+
+```typescript
+interface KeyboardAuditItem {
+  element: string;
+  file: string;
+  line: number;
+  issues: {
+    notFocusable: boolean;      // Missing tabIndex or not native interactive
+    noKeyHandler: boolean;       // onClick without onKeyDown
+    focusNotVisible: boolean;    // outline: none without replacement
+    trapDetected: boolean;       // Focus can't escape
+  };
+  severity: 'critical' | 'serious' | 'moderate' | 'minor';
+}
+```
+
+**Critical Patterns to Detect:**
+1. `<div onClick>` without `role="button"` and `tabIndex={0}`
+2. `outline: none` or `outline: 0` without `:focus-visible` replacement
+3. Custom dropdowns without arrow key support
+4. Modals without focus trap + Escape close
+5. Tab order jumping (positive tabIndex values)
+
+### Phase 4: ARIA Validation
+
+```typescript
+interface AriaAuditItem {
+  element: string;
+  file: string;
+  line: number;
+  issue: AriaIssueType;
+  suggestion: string;
+}
+
+type AriaIssueType =
+  | 'invalid-role'           // Role doesn't exist
+  | 'missing-required-prop'  // role="slider" without aria-valuenow
+  | 'redundant-role'         // <button role="button">
+  | 'orphan-aria-label'      // aria-labelledby points to non-existent id
+  | 'missing-live-region'    // Dynamic content without aria-live
+  | 'wrong-aria-usage';      // aria-expanded on non-expandable element
+```
+
+**Common ARIA Errors:**
+| Pattern | Issue | Fix |
+|---------|-------|-----|
+| `<span role="button">` | Missing keyboard support | Add `tabIndex={0}` + `onKeyDown` |
+| `<input aria-label="x" aria-labelledby="y">` | Conflicting labels | Use one or the other |
+| `<div aria-hidden="true">` with focusable children | Hidden but focusable | Remove focusable or aria-hidden |
+| Dynamic content update | No announcement | Add `aria-live="polite"` |
+
+### Phase 5: Semantic HTML Check
+
+```typescript
+interface SemanticIssue {
+  pattern: string;
+  occurrences: number;
+  severity: 'critical' | 'serious' | 'moderate';
+  recommendation: string;
+}
+```
+
+**Anti-Patterns:**
+| Anti-Pattern | Better Alternative |
+|--------------|-------------------|
+| `<div onClick>` | `<button>` |
+| `<span>` for links | `<a href>` |
+| `<b>` for emphasis | `<strong>` |
+| Multiple `<h1>` | Single `<h1>`, then `<h2>`, etc. |
+| `<table>` for layout | CSS Grid/Flexbox |
+| Missing `<main>` | Wrap main content |
+| Missing `<nav>` | Wrap navigation |
+
+---
+
+## Output
+
+### 1. Summary Report
+
+```markdown
+# Accessibility Audit Report
+
+**Path:** ./app/components
+**Date:** 2026-01-05
+**Level:** WCAG 2.2 AA
+
+## Summary
+
+| Category | Issues | Critical | Serious | Moderate | Minor |
+|----------|--------|----------|---------|----------|-------|
+| Contrast | 12 | 3 | 5 | 4 | 0 |
+| Keyboard | 8 | 2 | 4 | 2 | 0 |
+| ARIA | 15 | 1 | 6 | 5 | 3 |
+| Semantic | 6 | 0 | 3 | 2 | 1 |
+| **Total** | **41** | **6** | **18** | **13** | **4** |
+
+## Compliance Score
+
+**Current:** 72% (AA)
+**Target:** 100% (AA)
+
+## Critical Issues (Must Fix)
+
+1. **[CONTRAST]** Button text #777 on #f5f5f5 = 2.9:1 (need 4.5:1)
+   - Files: Button.tsx:45, Card.tsx:89
+   - Fix: Change to #595959 for 5.4:1
+
+2. **[KEYBOARD]** div.clickable-item has onClick without keyboard support
+   - Files: ListItem.tsx:23
+   - Fix: Add role="button" tabIndex={0} onKeyDown
+
+...
+```
+
+### 2. Issues by File
+
+```markdown
+## app/components/ui/Button.tsx
+
+| Line | Severity | Issue | Rule |
+|------|----------|-------|------|
+| 45 | Critical | Low contrast text | WCAG 1.4.3 |
+| 67 | Serious | Missing aria-label on icon button | WCAG 1.1.1 |
+| 89 | Moderate | Generic link text "click here" | WCAG 2.4.4 |
+```
+
+### 3. Contrast Matrix (if scope includes color)
+
+```markdown
+## Color Contrast Matrix
+
+| Foreground | Background | Ratio | AA Normal | AA Large | Usage |
+|------------|------------|-------|-----------|----------|-------|
+| #1a1a1a | #ffffff | 16.1:1 | ✓ | ✓ | Body text |
+| #666666 | #ffffff | 5.7:1 | ✓ | ✓ | Secondary text |
+| #999999 | #ffffff | 2.8:1 | ✗ | ✗ | Placeholder |
+| #D4AF37 | #1a1a1a | 8.2:1 | ✓ | ✓ | Primary accent |
+```
+
+### 4. Fix Suggestions (Auto-Fixable)
+
+```typescript
+// Auto-fixable issues (with --fix flag)
+
+// Issue: Missing alt attribute
+// File: Avatar.tsx:15
+- <img src={user.avatar} />
++ <img src={user.avatar} alt={`${user.name}'s avatar`} />
+
+// Issue: Missing form label
+// File: SearchInput.tsx:8
+- <input type="search" placeholder="Search..." />
++ <label htmlFor="search" className="sr-only">Search</label>
++ <input id="search" type="search" placeholder="Search..." />
+```
+
+---
+
+## Success Criteria
+
+| Metric | Target |
+|--------|--------|
+| Critical issues | 0 |
+| Serious issues | 0 |
+| AA compliance | 100% |
+| Auto-fixable applied | All (if --fix) |
+
+---
+
+## WCAG 2.2 New Success Criteria
+
+WCAG 2.2 added these criteria (check all):
+
+| Criterion | Level | Description |
+|-----------|-------|-------------|
+| 2.4.11 Focus Not Obscured (Minimum) | AA | Focused element not fully hidden |
+| 2.4.12 Focus Not Obscured (Enhanced) | AAA | Focused element not partially hidden |
+| 2.4.13 Focus Appearance | AAA | Focus indicator size/contrast |
+| 2.5.7 Dragging Movements | AA | Single pointer alternative to drag |
+| 2.5.8 Target Size (Minimum) | AA | 24x24px minimum target |
+| 3.2.6 Consistent Help | A | Help in consistent location |
+| 3.3.7 Redundant Entry | A | Don't re-ask same info |
+| 3.3.8 Accessible Authentication (Minimum) | AA | No cognitive function test |
+| 3.3.9 Accessible Authentication (Enhanced) | AAA | No object recognition |
+
+---
+
+## Integration with Other Commands
+
+```bash
+# Full audit
+*a11y-audit ./app/components
+
+# Color focus only
+*a11y-audit ./app/components --scope color
+# → Use *contrast-matrix for detailed color analysis
+
+# Keyboard focus only
+*a11y-audit ./app/components --scope keyboard
+# → Use *focus-order for detailed tab order
+
+# ARIA focus only
+*a11y-audit ./app/components --scope aria
+# → Use *aria-audit for detailed ARIA validation
+
+# Auto-fix simple issues
+*a11y-audit ./app/components --fix
+```
+
+---
+
+## Failure Handling
+
+- **No interactive elements found in path:** Verify path contains UI components. If correct, report "Zero interactive elements — minimal a11y surface"
+- **Contrast calculation fails (color format not recognized):** Convert all color formats to hex before calculation. Skip unparseable dynamic colors, log as "contrast: unable to evaluate {N} dynamic colors"
+- **ARIA validation references missing spec data:** Use built-in WAI-ARIA 1.2 role requirements. If role not in spec, flag as "unknown role — verify against latest spec"
+- **Auto-fix (--fix) causes syntax errors:** Revert auto-fix changes, output fix suggestions as manual recommendations instead
+
+## State Update
+
+After execution, update `.state.yaml`:
+
+```yaml
+a11y_audit:
+  last_run: "2026-01-05T14:30:00Z"
+  path: "./app/components"
+  level: "AA"
+  results:
+    total_issues: 41
+    critical: 6
+    serious: 18
+    moderate: 13
+    minor: 4
+    compliance_score: 72
+  categories:
+    contrast: 12
+    keyboard: 8
+    aria: 15
+    semantic: 6
+  auto_fixed: 0
+  next_action: "Fix 6 critical issues"
+```
+
+---
+
+**Brad says:** "Accessibility isn't a feature. It's a quality bar. Zero critical issues or it doesn't ship."
+
+
+## Related Checklists
+
+- `squads/design/checklists/ds-accessibility-wcag-checklist.md`
+- `squads/design/checklists/ds-a11y-release-gate-checklist.md`
+
+## Process Guards
+- **On Fail:** Stop execution, capture evidence, and return remediation steps before proceeding.