claude-code-workflow 7.2.27 → 7.2.29

package/.claude/skills/team-visual-a11y/roles/fix-implementer/role.md

@@ -0,0 +1,246 @@
+---
+role: fix-implementer
+prefix: FIX
+inner_loop: true
+message_types: [state_update]
+---
+
+# Accessibility Fix Implementer
+
+Implement accessibility fixes from the remediation plan. OKLCH color corrections, focus styles, ARIA attributes, reduced-motion queries, typography adjustments. Apply fixes in priority order (critical first) and self-validate results.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Remediation plan | <session>/remediation/remediation-plan.md | Yes |
+| Color audit report | <session>/audits/color/color-audit-001.md | Yes |
+| Focus audit report | <session>/audits/focus/focus-audit-001.md | Yes |
+| Typography audit report | <session>/audits/typography/typo-audit-001.md | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+| Re-audit reports (GC loop) | <session>/re-audit/*.md | Only for FIX-002+ |
+
+1. Extract session path from task description
+2. Read remediation plan -- this is the primary work instruction
+3. Parse priority matrix for ordered fix list
+4. Read audit reports for detailed context on each issue
+5. For FIX-002+ (GC loop): read re-audit reports for remaining issues
+
+## Phase 3: Fix Implementation
+
+Apply fixes in priority order: Critical -> High -> Medium -> Low.
+
+### Category 1: OKLCH Color Corrections
+
+**Goal**: Adjust OKLCH lightness/chroma to meet contrast requirements.
+
+**Process**:
+1. Read remediation plan for specific color changes needed
+2. Locate CSS custom properties or color definitions in source files
+3. Apply lightness adjustments:
+   - Text too light -> decrease L% (e.g., L 55% -> L 35%)
+   - Background too dark -> increase L% (e.g., L 80% -> L 92%)
+   - Maintain hue (H) and adjust chroma (C) minimally
+4. Verify new contrast ratios meet WCAG target
+5. If dark mode exists, apply corresponding adjustments
+
+**Example**:
+```css
+/* Before: contrast 3.2:1 */
+--color-text: oklch(55% 0 0);
+--color-bg: oklch(98% 0 0);
+
+/* After: contrast 7.2:1 (AAA) */
+--color-text: oklch(25% 0 0);
+--color-bg: oklch(98% 0 0);
+```
+
+### Category 2: Focus Styles
+
+**Goal**: Add visible, high-contrast focus indicators for keyboard users.
+
+**Process**:
+1. Add `:focus-visible` rules per specs/focus-patterns.md:
+   ```css
+   :focus-visible {
+     outline: 2px solid var(--color-accent);
+     outline-offset: 2px;
+   }
+   :focus:not(:focus-visible) {
+     outline: none;
+   }
+   ```
+2. Remove bare `outline: none` or `outline: 0` that suppress focus without alternative
+3. Verify focus indicator contrast >= 3:1 against adjacent colors
+4. Add consistent focus style across all interactive elements
+
+### Category 3: ARIA Attributes
+
+**Goal**: Add missing ARIA roles, states, and properties.
+
+**Process**:
+1. Add `role` attributes where semantic HTML is not used:
+   - `<div onclick>` -> add `role="button"` and `tabindex="0"`
+   - Custom widgets -> appropriate ARIA role
+2. Add state attributes:
+   - Toggle buttons: `aria-pressed="true|false"`
+   - Expandable: `aria-expanded="true|false"`, `aria-controls="panel-id"`
+   - Dialogs: `role="dialog"`, `aria-modal="true"`, `aria-labelledby="title-id"`
+3. Add labels:
+   - `aria-label` for icon-only buttons
+   - `aria-labelledby` for dialogs and sections
+   - `aria-describedby` for form error messages
+4. Add live regions:
+   - Status messages: `aria-live="polite"`
+   - Error messages: `aria-live="assertive"`
+
+### Category 4: Reduced-Motion Queries
+
+**Goal**: Respect user's motion preferences.
+
+**Process**:
+1. Wrap animations and transitions in media query:
+   ```css
+   @media (prefers-reduced-motion: reduce) {
+     *,
+     *::before,
+     *::after {
+       animation-duration: 0.01ms !important;
+       animation-iteration-count: 1 !important;
+       transition-duration: 0.01ms !important;
+       scroll-behavior: auto !important;
+     }
+   }
+   ```
+2. Or per-element: disable specific animations while keeping layout
+3. Ensure no content is lost when motion is reduced
+
+### Category 5: Typography Adjustments
+
+**Goal**: Fix font sizes, line heights, and reading widths.
+
+**Process**:
+1. Replace fixed font sizes with responsive clamp():
+   ```css
+   body { font-size: clamp(1rem, 1vw + 0.875rem, 1.25rem); }
+   ```
+2. Fix line-height to acceptable ranges:
+   ```css
+   body { line-height: 1.625; }
+   h1, h2, h3 { line-height: 1.2; }
+   ```
+3. Add max-width for reading containers:
+   ```css
+   .content { max-width: 70ch; }
+   ```
+
+### Category 6: Skip Link
+
+**Goal**: Add skip-to-main-content link if missing.
+
+**Process** (per specs/focus-patterns.md):
+1. Add as first child of `<body>`:
+   ```html
+   <a href="#main" class="skip-link">Skip to main content</a>
+   ```
+2. Add CSS:
+   ```css
+   .skip-link {
+     position: absolute;
+     left: -9999px;
+     top: auto;
+   }
+   .skip-link:focus {
+     position: fixed;
+     left: 16px;
+     top: 16px;
+     z-index: 9999;
+     background: var(--color-paper, #fff);
+     color: var(--color-ink, #000);
+     padding: 8px 16px;
+     border-radius: 4px;
+     text-decoration: underline;
+   }
+   ```
+3. Ensure main content has `id="main"` (or equivalent target)
+
+### Category 7: Focus Trap for Modals
+
+**Goal**: Implement proper focus management in dialogs.
+
+**Process** (per specs/focus-patterns.md):
+1. On dialog open:
+   - Store `document.activeElement` as return target
+   - Move focus to first focusable element within dialog
+2. Trap Tab/Shift+Tab within dialog:
+   - Collect all focusable elements within dialog
+   - On Tab at last element -> focus first element
+   - On Shift+Tab at first element -> focus last element
+3. On Escape -> close dialog, restore focus to stored element
+4. Set `aria-modal="true"` on dialog container
+5. Optional: set `inert` on background content
+
+## Phase 4: Self-Validation & Output
+
+1. Validate each fix category:
+
+| Category | Validation Method |
+|----------|------------------|
+| Color | Recalculate contrast ratios for changed colors, verify >= target |
+| Focus | Search for :focus-visible rules, verify no bare outline:none |
+| ARIA | Check all dialogs have role+aria-modal, all buttons have labels |
+| Motion | Verify prefers-reduced-motion media query exists |
+| Typography | Check clamp() minimum >= 1rem, line-height in range |
+| Skip link | Verify skip link element exists, CSS hides then shows on focus |
+| Focus trap | Verify dialog has focus management code |
+
+2. Write fix summary to `<session>/fixes/fix-summary-{NNN}.md`:
+
+```markdown
+# Fix Summary - {NNN}
+[fix-implementer]
+
+## Overview
+- **Total fixes applied**: {count}
+- **Critical fixed**: {count}
+- **High fixed**: {count}
+- **Medium fixed**: {count}
+- **Files modified**: {count}
+
+## Fixes Applied
+
+### Fix 1: Color contrast (Critical, WCAG 1.4.3)
+- **File**: `src/styles/globals.css:12`
+- **Before**: `--color-text: oklch(55% 0 0)` (contrast 3.2:1)
+- **After**: `--color-text: oklch(25% 0 0)` (contrast 7.2:1)
+- **Validated**: PASS
+
+### Fix 2: Focus indicators (High, WCAG 2.4.7)
+- **File**: `src/styles/globals.css:45`
+- **Before**: No :focus-visible rules
+- **After**: Added :focus-visible with 2px outline
+- **Validated**: PASS
+
+...
+
+## Files Modified
+| File | Changes |
+|------|---------|
+| src/styles/globals.css | Color adjustments, focus styles, reduced-motion |
+| src/components/Modal.tsx | Focus trap, ARIA attributes |
+| src/app/layout.tsx | Skip link |
+
+## Remaining Issues
+- {Any medium/low issues not addressed in this round}
+
+## Verification Status
+- [ ] Color contrast: {n}/{total} passing
+- [ ] Focus indicators: {n}/{total} visible
+- [ ] ARIA coverage: {n}/{total} complete
+- [ ] Typography: {n}/{total} compliant
+```
+
+3. Update `<session>/.msg/meta.json` under `fix-implementer` namespace:
+   - Read existing -> merge `{ "fix-implementer": { fix_id, total_fixes, critical_fixed, high_fixed, medium_fixed, files_modified, timestamp } }` -> write back

package/.claude/skills/team-visual-a11y/roles/focus-auditor/role.md

@@ -0,0 +1,222 @@
+---
+role: focus-auditor
+prefix: FOCUS
+inner_loop: false
+message_types: [state_update]
+---
+
+# Focus & Keyboard Accessibility Auditor
+
+Focus-visible completeness audit. Tab order, focus indicator visibility (3:1 contrast), skip link, focus traps, ARIA live regions, keyboard operability. Produce detailed focus audit report with element-by-element analysis.
+
+## Phase 2: Context & Environment Detection
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Target (URL or file paths) | From task description CONTEXT | Yes |
+| WCAG level (AA/AAA) | From task description CONTEXT | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | No |
+| Previous audit (re-audit) | <session>/audits/focus/focus-audit-*.md | Only for FOCUS-002+ |
+
+1. Extract session path, target, and WCAG level from task description
+2. Determine audit type from subject: FOCUS-001 -> initial audit, FOCUS-002+ -> re-audit (verification)
+3. Identify target:
+   - URL -> use Chrome DevTools for interactive focus testing
+   - File paths -> read HTML/JSX/Vue/Svelte files for interactive elements
+   - Full site -> enumerate pages from navigation/routes
+4. For re-audit: read previous audit report and fix summary for comparison baseline
+5. Read focus patterns from specs/focus-patterns.md for reference
+
+## Phase 3: Focus Audit Execution
+
+### Step 1: Interactive Element Inventory
+
+**Static analysis** (always):
+- Glob for HTML/JSX/TSX/Vue/Svelte files
+- Extract all interactive elements:
+  - Native focusable: `<a href>`, `<button>`, `<input>`, `<select>`, `<textarea>`, `<details>`
+  - Custom focusable: elements with `tabindex`, `role="button"`, `role="link"`, `role="tab"`, etc.
+  - Modals/dialogs: `role="dialog"`, `role="alertdialog"`, `<dialog>`
+  - Dynamic content areas: `aria-live`, `role="status"`, `role="alert"`
+- Record source location (file:line) and context for each element
+
+**Runtime analysis** (if Chrome DevTools available):
+- `mcp__chrome-devtools__navigate_page({ url: "<target-url>" })`
+- `mcp__chrome-devtools__evaluate_script({ expression: "..." })` to:
+  - Enumerate all focusable elements in DOM order
+  - Check `tabindex` values (0, -1, positive)
+  - Detect focus traps (elements that prevent Tab from escaping)
+
+### Step 2: Tab Order Audit
+
+| Check | Criterion | Standard |
+|-------|-----------|----------|
+| Logical sequence | Tab order follows visual/reading order | WCAG 2.4.3 |
+| No positive tabindex | `tabindex > 0` is an anti-pattern | Best practice |
+| No tab traps | Tab can escape all containers (except modals) | WCAG 2.1.2 |
+| Skip link first | First focusable element is skip-to-content link | WCAG 2.4.1 |
+| All interactive reachable | Every interactive element reachable via Tab | WCAG 2.1.1 |
+
+Flag:
+- `tabindex > 0` (disrupts natural tab order)
+- `tabindex="-1"` on elements that should be focusable
+- Missing `tabindex="0"` on custom interactive elements
+- `outline: none` or `outline: 0` without alternative focus indicator
+
+### Step 3: Focus Indicator Visibility
+
+Per specs/focus-patterns.md:
+
+| Check | Requirement | Standard |
+|-------|-------------|----------|
+| Outline present | At least 2px outline on :focus-visible | WCAG 2.4.7 |
+| Outline contrast | >= 3:1 against adjacent colors | WCAG 2.4.11 |
+| :focus-visible used | Keyboard focus distinct from mouse click | Best practice |
+| Not obscured | Focus indicator not hidden by overlays, sticky headers | WCAG 2.4.11 |
+| Consistent style | Same focus style across similar elements | Best practice |
+
+**CSS analysis**:
+- Search for `:focus`, `:focus-visible`, `:focus-within` rules
+- Check for `outline: none` / `outline: 0` without alternative (box-shadow, border)
+- Verify `:focus:not(:focus-visible) { outline: none; }` pattern (mouse click suppression)
+- Calculate focus indicator contrast against adjacent background
+
+### Step 4: Skip Link Audit
+
+| Check | Requirement |
+|-------|-------------|
+| Exists | `<a href="#main">` or similar as first focusable element |
+| Visually hidden until focus | `position: absolute; left: -9999px` pattern |
+| Visible on focus | Repositions on `:focus` to visible area |
+| Target exists | `#main` or target ID exists in DOM |
+| Functional | Focus moves to main content on activation |
+
+### Step 5: Focus Trap Audit (Modals/Dialogs)
+
+Per specs/focus-patterns.md:
+
+| Check | Requirement | Standard |
+|-------|-------------|----------|
+| Focus moves to dialog | On open, focus moves to first focusable or dialog itself | ARIA Practices |
+| Tab cycles within | Tab/Shift+Tab stay within dialog focusable elements | ARIA Practices |
+| Escape closes | Escape key closes dialog | ARIA Practices |
+| Focus restores | On close, focus returns to trigger element | ARIA Practices |
+| Background inert | Background content not focusable while dialog open | Best practice |
+| Scroll lock | Background scroll locked while dialog open | Best practice |
+
+### Step 6: ARIA Audit
+
+| Element Type | Required ARIA | Standard |
+|-------------|--------------|----------|
+| Buttons | `role="button"` (if not `<button>`), `aria-pressed` (toggle), `aria-expanded` (disclosure) | WCAG 4.1.2 |
+| Dialogs | `role="dialog"`, `aria-modal="true"`, `aria-labelledby` | ARIA Practices |
+| Navigation | `role="navigation"` (if not `<nav>`), `aria-label` for multiple nav regions | WCAG 4.1.2 |
+| Live regions | `aria-live="polite"` (status), `aria-live="assertive"` (errors) | WCAG 4.1.3 |
+| Forms | `aria-required`, `aria-invalid`, `aria-describedby` for errors | WCAG 4.1.2 |
+| Tabs | `role="tablist"`, `role="tab"`, `role="tabpanel"`, `aria-selected` | ARIA Practices |
+| Accordions | `aria-expanded`, `aria-controls` | ARIA Practices |
+
+### Step 7: Keyboard Operability
+
+| Element | Expected Keys | Standard |
+|---------|--------------|----------|
+| Links/buttons | Enter activates | WCAG 2.1.1 |
+| Buttons | Space activates | WCAG 2.1.1 |
+| Checkboxes | Space toggles | WCAG 2.1.1 |
+| Radio groups | Arrow keys navigate within group | ARIA Practices |
+| Tabs | Arrow keys switch tabs, Tab moves to panel | ARIA Practices |
+| Menus | Arrow keys navigate, Enter selects, Escape closes | ARIA Practices |
+| Sliders | Arrow keys adjust value | ARIA Practices |
+
+### Input Method Awareness
+
+| Check | Requirement |
+|-------|-------------|
+| Hover guard | `:hover` styles wrapped in `@media(hover:hover)` — touch devices don't hover |
+| Pointer detection | `@media(pointer:coarse)` used for larger touch targets (48px+) |
+| Focus-visible distinction | `:focus-visible` for keyboard only, not mouse clicks |
+| Touch target sizing | All interactive elements >= 44x44px on `pointer:coarse` devices |
+
+### Step 8: Target Size (WCAG 2.5.8)
+
+| Check | Requirement | Standard |
+|-------|-------------|----------|
+| Interactive elements | Minimum 24x24px CSS pixels | WCAG 2.5.8 AA |
+| Inline links | Exempt if within text paragraph | Exception |
+| Spacing | At least 24px between targets OR targets themselves >= 24px | WCAG 2.5.8 |
+
+## Phase 4: Report Generation & Output
+
+1. Write audit report to `<session>/audits/focus/focus-audit-{NNN}.md` (or `<session>/re-audit/focus-audit-{NNN}.md` for re-audits):
+
+```markdown
+# Focus & Keyboard Accessibility Audit - {NNN}
+[focus-auditor]
+
+## Summary
+- **Total interactive elements**: {count}
+- **Pass**: {pass_count} | **Fail**: {fail_count}
+- **WCAG Level**: {AA|AAA}
+- **Critical issues**: {count}
+- **High issues**: {count}
+
+## Tab Order
+| # | Element | Type | tabindex | Logical | Status |
+|---|---------|------|----------|---------|--------|
+| 1 | Skip link | <a> | 0 | Yes | PASS |
+| 2 | Logo link | <a> | 0 | Yes | PASS |
+| ... | ... | ... | ... | ... | ... |
+
+## Focus Indicators
+| Element | :focus-visible | Outline | Contrast | Obscured | Status |
+|---------|---------------|---------|----------|----------|--------|
+| ... | yes/no | Xpx solid | X:1 | no | PASS/FAIL |
+
+## Skip Link
+| Check | Status | Details |
+|-------|--------|---------|
+| Exists | PASS/FAIL | ... |
+| Hidden until focus | PASS/FAIL | ... |
+| Target exists | PASS/FAIL | ... |
+
+## Focus Traps (Modals/Dialogs)
+| Dialog | Focus on open | Tab cycles | Escape closes | Focus restores | Status |
+|--------|-------------|-----------|--------------|---------------|--------|
+| ... | yes/no | yes/no | yes/no | yes/no | PASS/FAIL |
+
+## ARIA Coverage
+| Element | Role | Label | States | Status |
+|---------|------|-------|--------|--------|
+| ... | ... | ... | ... | PASS/FAIL |
+
+## Keyboard Operability
+| Element | Enter | Space | Arrows | Escape | Status |
+|---------|-------|-------|--------|--------|--------|
+| ... | yes/no | yes/no | n/a | n/a | PASS/FAIL |
+
+## Target Size
+| Element | Size | Min 24x24 | Status |
+|---------|------|----------|--------|
+| ... | WxH | yes/no | PASS/FAIL |
+
+## Issues (by severity)
+### Critical
+- ...
+### High
+- ...
+### Medium
+- ...
+```
+
+2. For re-audit (FOCUS-002+), add before/after comparison section:
+```markdown
+## Before/After Comparison
+| Element | Before | After | Status |
+|---------|--------|-------|--------|
+| ... | FAIL (no outline) | PASS (2px solid) | FIXED |
+```
+
+3. Update `<session>/.msg/meta.json` under `focus-auditor` namespace:
+   - Read existing -> merge `{ "focus-auditor": { audit_id, total_elements, pass_count, fail_count, critical_count, high_count, skip_link_present, focus_traps_valid, timestamp } }` -> write back

package/.claude/skills/team-visual-a11y/roles/remediation-planner/role.md

@@ -0,0 +1,206 @@
+---
+role: remediation-planner
+prefix: REMED
+inner_loop: false
+message_types: [state_update]
+---
+
+# Remediation Planner
+
+Synthesize findings from all 3 audit reports (color, typography, focus) into a prioritized remediation plan with code-level fix guidance. Map each issue to WCAG success criterion, estimate effort, and group by file/component for efficient fixing.
+
+## Phase 2: Context & Artifact Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task description | From task subject/description | Yes |
+| Session path | Extracted from task description | Yes |
+| Color audit report | <session>/audits/color/color-audit-001.md | Yes |
+| Typography audit report | <session>/audits/typography/typo-audit-001.md | Yes |
+| Focus audit report | <session>/audits/focus/focus-audit-001.md | Yes |
+| WCAG level (AA/AAA) | From task description CONTEXT | Yes |
+| .msg/meta.json | <session>/.msg/meta.json | Yes |
+
+1. Extract session path and WCAG level from task description
+2. Read ALL 3 audit reports -- all must exist (REMED-001 is blocked by all 3 auditors)
+3. Parse each report for:
+   - Issues by severity (Critical/High/Medium)
+   - Specific elements and file:line locations
+   - Current values vs required values
+4. Read meta.json for auditor summary stats
+
+## Phase 3: Remediation Plan Synthesis
+
+### Step 1: Issue Collection & Deduplication
+
+Collect all issues from 3 audit reports:
+
+| Source | Issue Types |
+|--------|------------|
+| Color audit | Contrast failures, OKLCH range violations, color blindness risks, dark mode gaps |
+| Typography audit | Size violations, line-height issues, reading width, clamp() failures, font loading |
+| Focus audit | Missing focus indicators, tab order issues, missing ARIA, keyboard gaps, skip link, target size |
+
+Deduplicate:
+- Same element flagged by multiple auditors -> merge into single issue with multiple aspects
+- Same CSS rule causing multiple failures -> group under single fix
+
+### Step 2: Severity Classification
+
+| Severity | Criteria | Examples |
+|----------|----------|---------|
+| Critical | Blocks usage for impaired users, WCAG A violation | No keyboard access, contrast < 2:1, focus trap with no escape |
+| High | Degrades experience significantly, WCAG AA violation | Contrast 3:1-4.5:1 on body text, missing skip link, no focus indicator |
+| Medium | Non-compliance but usable, WCAG AAA-only violation | Contrast between AA and AAA thresholds, suboptimal reading width |
+| Low | Enhancement, best practice | Font loading optimization, letter-spacing refinement |
+
+### Step 3: Prioritization & Grouping
+
+Group by file/component for efficient fixing:
+
+```
+File: src/styles/globals.css
+  [CRITICAL] Color: --text-primary contrast 3.2:1 (need 4.5:1) -> WCAG 1.4.3
+  [HIGH]     Focus: No :focus-visible on buttons -> WCAG 2.4.7
+  [MEDIUM]   Typography: line-height 1.4 on body (need 1.5) -> WCAG 1.4.12
+
+File: src/components/Modal.tsx
+  [CRITICAL] Focus: No focus trap in modal -> WCAG 2.1.2
+  [HIGH]     ARIA: Missing aria-modal="true" -> WCAG 4.1.2
+```
+
+Priority order within each file: Critical -> High -> Medium -> Low.
+
+### Step 4: Code-Level Fix Guidance
+
+For each issue, provide specific fix:
+
+**Color fixes**:
+```css
+/* Before: contrast 3.2:1 */
+--text-primary: oklch(55% 0 0);
+/* After: contrast 5.1:1 -- adjust lightness down */
+--text-primary: oklch(35% 0 0);
+```
+
+**Focus fixes**:
+```css
+/* Add :focus-visible to interactive elements */
+button:focus-visible,
+a:focus-visible {
+  outline: 2px solid var(--color-accent);
+  outline-offset: 2px;
+}
+button:focus:not(:focus-visible) {
+  outline: none;
+}
+```
+
+**ARIA fixes**:
+```html
+<!-- Before -->
+<div class="modal">
+<!-- After -->
+<div class="modal" role="dialog" aria-modal="true" aria-labelledby="modal-title">
+```
+
+**Typography fixes**:
+```css
+/* Before: fixed font-size */
+body { font-size: 14px; }
+/* After: responsive with floor */
+body { font-size: clamp(1rem, 1vw + 0.875rem, 1.25rem); line-height: 1.625; }
+```
+
+### Step 5: Effort Estimation
+
+| Effort | Criteria |
+|--------|----------|
+| Trivial (< 5 min) | Single CSS property change (contrast, outline) |
+| Small (5-15 min) | Multiple CSS changes in one file, add ARIA attributes |
+| Medium (15-60 min) | Focus trap implementation, skip link, keyboard navigation |
+| Large (1-4 hours) | Responsive typography overhaul, dark mode color parity |
+
+### Step 6: WCAG Criterion Mapping
+
+Map every issue to specific WCAG success criterion:
+
+| Issue Domain | Common Criteria |
+|-------------|----------------|
+| Color contrast | 1.4.3 (AA), 1.4.6 (AAA), 1.4.11 (non-text) |
+| Typography | 1.4.4 (resize), 1.4.12 (text spacing) |
+| Focus indicators | 2.4.7 (visible), 2.4.11 (not obscured) |
+| Keyboard | 2.1.1 (keyboard), 2.1.2 (no trap) |
+| Tab order | 2.4.3 (focus order) |
+| Skip link | 2.4.1 (bypass blocks) |
+| ARIA | 4.1.2 (name/role/value) |
+| Target size | 2.5.8 (target size) |
+| Live regions | 4.1.3 (status messages) |
+
+## Phase 4: Validation & Output
+
+1. Validate plan completeness:
+
+| Check | Requirement |
+|-------|-------------|
+| All critical issues addressed | Every critical issue has a fix |
+| All high issues addressed | Every high issue has a fix |
+| File grouping complete | Every fix maps to specific file:line |
+| WCAG mapping complete | Every fix maps to WCAG criterion |
+| No orphan issues | Every audit issue appears in plan |
+
+2. Write remediation plan to `<session>/remediation/remediation-plan.md`:
+
+```markdown
+# Remediation Plan
+[remediation-planner]
+
+## Executive Summary
+- **Total issues**: {count} (Critical: {n}, High: {n}, Medium: {n}, Low: {n})
+- **Files affected**: {count}
+- **Estimated total effort**: {hours}
+- **WCAG target**: {AA|AAA}
+
+## Priority Matrix
+| # | Severity | Domain | WCAG | File | Issue | Fix | Effort |
+|---|----------|--------|------|------|-------|-----|--------|
+| 1 | Critical | Color | 1.4.3 | globals.css:12 | Contrast 3.2:1 | L 55% -> 35% | Trivial |
+| 2 | Critical | Focus | 2.1.2 | Modal.tsx:45 | No focus trap | Add trap logic | Medium |
+| ... | ... | ... | ... | ... | ... | ... | ... |
+
+## Fixes by File
+
+### `src/styles/globals.css`
+#### Fix 1: Color contrast (Critical, WCAG 1.4.3)
+- **Current**: `--text-primary: oklch(55% 0 0);` (contrast 3.2:1)
+- **Target**: `--text-primary: oklch(35% 0 0);` (contrast 5.1:1)
+- **Effort**: Trivial
+
+#### Fix 2: Focus indicators (High, WCAG 2.4.7)
+- **Current**: No :focus-visible rules
+- **Target**: Add :focus-visible with 2px outline
+- **Effort**: Small
+
+### `src/components/Modal.tsx`
+#### Fix 3: Focus trap (Critical, WCAG 2.1.2)
+- **Current**: No focus management
+- **Target**: Implement focus trap (store activeElement, cycle Tab, Escape to close)
+- **Effort**: Medium
+
+## Implementation Order
+1. All Critical fixes (blocks usage)
+2. All High fixes (degrades experience)
+3. Medium fixes (non-compliance)
+4. Low fixes (enhancements)
+
+## Verification Checklist
+- [ ] All color combinations pass WCAG {level} contrast
+- [ ] All interactive elements have visible focus indicators
+- [ ] Tab order is logical with no traps (except modals)
+- [ ] Skip link present and functional
+- [ ] All ARIA roles and states correct
+- [ ] Typography meets minimum sizes at all breakpoints
+```
+
+3. Update `<session>/.msg/meta.json` under `remediation-planner` namespace:
+   - Read existing -> merge `{ "remediation-planner": { total_issues, critical, high, medium, low, files_affected, estimated_effort, timestamp } }` -> write back