Team Visual A11y

Team Visual Accessibility

Deep visual accessibility QA: OKLCH-based perceptual color contrast, typography readability at all viewports, focus-visible completeness, WCAG AA/AAA audit at rendered level. Built on team-worker agent architecture -- all worker roles share a single agent definition with role-specific Phase 2-4 loaded from roles/<role>/role.md.

Architecture

Skill(skill="team-visual-a11y", args="task description")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- analyze -> dispatch -> spawn workers -> STOP
                                    |
                    +-------+-------+-------+
                    v       v       v       |
           [3 auditors spawn in PARALLEL]   |
        color-auditor  typo-auditor  focus-auditor
                    |       |       |
                    +---+---+---+---+
                        v
               remediation-planner
                        |
                        v
               fix-implementer (inner_loop)
                        |
                        v
               [re-audit: color + focus in PARALLEL]

Role Registry

Role Router

Parse $ARGUMENTS:

• Has --role <name> -> Read roles/<name>/role.md, execute Phase 2-4
• No --role -> @roles/coordinator/role.md, execute entry router

Shared Constants

• Session prefix: VA
• Session path: .workflow/.team/VA-<slug>-<date>/
• team_name: visual-a11y
• CLI tools: ccw cli --mode analysis (read-only), ccw cli --mode write (modifications)
• Message bus: mcp__ccw-tools__team_msg(session_id=<session-id>, ...)
• Max GC rounds: 2

Worker Spawn Template

Coordinator spawns workers using this template:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker for <task-id>",
  team_name: "visual-a11y",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: visual-a11y
requirement: <task-description>
inner_loop: <true|false>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

User Commands

Specs Reference

• specs/pipelines.md -- Pipeline definitions and task registry
• specs/oklch-standards.md -- OKLCH color accessibility rules
• specs/wcag-matrix.md -- WCAG 2.1 criteria matrix
• specs/typography-scale.md -- Typography accessibility rules
• specs/focus-patterns.md -- Focus management patterns

Session Directory

.workflow/.team/VA-<slug>-<date>/
+-- .msg/
|   +-- messages.jsonl         # Team message bus
|   +-- meta.json              # Pipeline config + GC state
+-- audits/
|   +-- color/                 # Color auditor output
|   |   +-- color-audit-001.md
|   +-- typography/            # Typography auditor output
|   |   +-- typo-audit-001.md
|   +-- focus/                 # Focus auditor output
|       +-- focus-audit-001.md
+-- remediation/               # Remediation planner output
|   +-- remediation-plan.md
+-- fixes/                     # Fix implementer output
|   +-- fix-summary-001.md
+-- re-audit/                  # Re-audit output (GC loop)
|   +-- color-audit-002.md
|   +-- focus-audit-002.md
+-- evidence/                  # Screenshots, traces

Error Handling

Color Accessibility Auditor

OKLCH-based perceptual color contrast analysis. Extract all color values, calculate WCAG 2.1 and APCA contrast ratios, assess OKLCH lightness/chroma ranges, simulate color blindness conditions. Produce detailed color audit report with pass/fail per combination.

Phase 2: Context & Environment Detection

1. Extract session path, target, and WCAG level from task description 2. Determine audit type from subject: COLOR-001 -> initial audit, COLOR-002+ -> re-audit (verification) 3. Identify target:

• URL -> use Chrome DevTools for rendered colors (navigate_page, evaluate_script)
• File paths -> read CSS/SCSS/Tailwind config files directly
• Full site -> enumerate stylesheets from HTML entry points

4. For re-audit: read previous audit report and fix summary for comparison baseline

Phase 3: Color Audit Execution

Step 1: Color Extraction

Extract all color values from target:

Static analysis (always):

• Glob for CSS/SCSS/Tailwind files -> extract color definitions
• Parse CSS custom properties (--color-*), class colors, inline styles
• Normalize all formats to OKLCH for perceptual comparison:
• #hex -> sRGB -> OKLCH
• rgb()/rgba() -> OKLCH
• hsl()/hsla() -> OKLCH
• oklch() -> direct
• Record source location (file:line) for each color

Runtime analysis (if Chrome DevTools available):

• mcp__chrome-devtools__navigate_page({ url: "<target-url>" })
• mcp__chrome-devtools__evaluate_script({ expression: "..." }) with getComputedStyle to extract rendered colors from key elements (body, headings, links, buttons, inputs)
• mcp__chrome-devtools__take_screenshot({}) for visual evidence -> save to <session>/evidence/

Step 2: Contrast Ratio Calculation

For each text/background color combination:

WCAG 2.1 Contrast Ratios:

• Calculate relative luminance: L = 0.2126*R + 0.7152*G + 0.0722*B (linearized sRGB)
• Contrast ratio: (L1 + 0.05) / (L2 + 0.05) where L1 > L2
• Thresholds:

APCA Contrast (Lc values):

• Calculate APCA Lc using OKLCH lightness difference
• Thresholds:

Step 3: OKLCH Lightness Analysis

Verify OKLCH lightness ranges per specs/oklch-standards.md:

Check chroma values:

• Text colors: C near 0 (achromatic) unless intentional accent
• Vibrant accents: C 0.2-0.25, max 1-2 per palette

Step 4: Color Blindness Simulation

Assess color distinguishability under:

• Protanopia (red-blind): Check red/green pairs still distinguishable
• Deuteranopia (green-blind): Check green/red pairs
• Tritanopia (blue-blind): Check blue/yellow pairs

Flag combinations that rely solely on color difference without shape/text/pattern alternatives.

Step 5: Dark Mode Parity

If dark mode exists (media query or data-attribute):

• Verify all color combinations also pass in dark mode
• Check that OKLCH lightness relationships invert properly
• Flag combinations that pass in one mode but fail in the other

Dark Mode Audit (if dark mode exists)

Phase 4: Report Generation & Output

1. Write audit report to <session>/audits/color/color-audit-{NNN}.md (or <session>/re-audit/color-audit-{NNN}.md for re-audits):

# Color Accessibility Audit - {NNN}
[color-auditor]

## Summary
- **Total color combinations tested**: {count}
- **Pass**: {pass_count} | **Fail**: {fail_count}
- **WCAG Level**: {AA|AAA}
- **Critical issues**: {count}
- **High issues**: {count}

## Color Palette (OKLCH)
| Name | Value | L% | C | H | Source |
|------|-------|----|---|---|--------|
| ... | oklch(X% Y Z) | X | Y | Z | file:line |

## Contrast Results
| Foreground | Background | WCAG Ratio | Pass/Fail | APCA Lc | Pass/Fail | Type |
|-----------|-----------|------------|-----------|---------|-----------|------|
| ... | ... | X.X:1 | PASS/FAIL | XX | PASS/FAIL | normal/large |

## OKLCH Lightness Issues
| Element | Current L | Expected Range | Status |
|---------|----------|---------------|--------|
| ... | X% | Y-Z% | PASS/FAIL |

## Color Blindness Assessment
| Combination | Protanopia | Deuteranopia | Tritanopia | Alt indicator |
|------------|-----------|-------------|-----------|--------------|
| ... | safe/risk | safe/risk | safe/risk | yes/no |

## Dark Mode Parity
| Combination | Light Mode | Dark Mode | Status |
|------------|-----------|----------|--------|
| ... | PASS/FAIL | PASS/FAIL | PASS/FAIL |

## Issues (by severity)
### Critical
- ...
### High
- ...
### Medium
- ...

2. For re-audit (COLOR-002+), add before/after comparison section:

## Before/After Comparison
| Combination | Before (ratio) | After (ratio) | Status |
|------------|----------------|---------------|--------|
| ... | X.X:1 FAIL | Y.Y:1 PASS | FIXED |

3. Update <session>/.msg/meta.json under color-auditor namespace:

• Read existing -> merge { "color-auditor": { audit_id, total_combinations, pass_count, fail_count, critical_count, high_count, timestamp } } -> write back

Analyze Task

Parse user task -> detect accessibility audit scope -> determine target -> select pipeline mode.

CONSTRAINT: Text-level analysis only. NO source code reading, NO codebase exploration.

Signal Detection

Target Detection

Mode Determination

WCAG Level Detection

Complexity Scoring

Results: 1-2 Low, 3-4 Medium, 5+ High

Output

Write scope context to coordinator memory:

{
  "pipeline_mode": "<audit-only|full>",
  "target": {
    "type": "<rendered-page|component-source|full-site>",
    "value": "<URL or file path or 'all'>"
  },
  "wcag_level": "<AA|AAA>",
  "scope": "<description>",
  "complexity": { "score": 0, "level": "Low|Medium|High" },
  "chrome_devtools": true
}

Command: Dispatch

Create the visual accessibility task chain with correct dependencies and structured task descriptions. Supports audit-only and full pipeline modes.

Phase 2: Context Loading

1. Load user requirement and scope from meta.json 2. Load pipeline stage definitions from specs/pipelines.md 3. Read pipeline and target from meta.json

Phase 3: Task Chain Creation (Mode-Branched)

Task Description Template

Every task description uses structured format:

TaskCreate({
  subject: "<TASK-ID>",
  description: "PURPOSE: <what this task achieves> | Success: <measurable completion criteria>
TASK:
  - <step 1: specific action>
  - <step 2: specific action>
  - <step 3: specific action>
CONTEXT:
  - Session: <session-folder>
  - Target: <URL or file path>
  - WCAG Level: <AA|AAA>
  - Upstream artifacts: <artifact-1>, <artifact-2>
  - Shared memory: <session>/.msg/meta.json
EXPECTED: <deliverable path> + <quality criteria>
CONSTRAINTS: <scope limits, focus areas>"
})
TaskUpdate({ taskId: "<TASK-ID>", addBlockedBy: [<dependency-list>], owner: "<role>" })

Mode Router

---

Audit-Only Pipeline Task Chain

COLOR-001 (color-auditor):

TaskCreate({
  subject: "COLOR-001",
  description: "PURPOSE: OKLCH color contrast audit for all color combinations | Success: Complete color audit with WCAG 2.1 + APCA contrast ratios and color blindness assessment
TASK:
  - Extract all color values (OKLCH, HSL, RGB, hex) from stylesheets
  - Calculate WCAG 2.1 contrast ratios for all text/background combinations
  - Calculate APCA Lc values for body and large text
  - Assess OKLCH lightness ranges for text and backgrounds
  - Simulate color blindness (protanopia, deuteranopia, tritanopia)
  - Check dark mode color parity if applicable
CONTEXT:
  - Session: <session-folder>
  - Target: <target>
  - WCAG Level: <level>
  - Shared memory: <session>/.msg/meta.json
EXPECTED: <session>/audits/color/color-audit-001.md | Pass/fail per color combination
CONSTRAINTS: Read-only analysis | Use Chrome DevTools for computed styles when available"
})
TaskUpdate({ taskId: "COLOR-001", owner: "color-auditor" })

TYPO-001 (typo-auditor):

TaskCreate({
  subject: "TYPO-001",
  description: "PURPOSE: Typography readability audit across all viewports | Success: Complete typography audit with size, line-height, reading width at each breakpoint
TASK:
  - Audit font sizes at each breakpoint (320px, 768px, 1024px, 1400px)
  - Validate minimum body text >= 16px on mobile
  - Check line-height ratios (body 1.5-1.75, headings 1.1-1.3)
  - Validate clamp() functions for responsive scaling
  - Measure reading width (45-75 characters per line)
  - Assess font loading strategy (font-display values)
CONTEXT:
  - Session: <session-folder>
  - Target: <target>
  - WCAG Level: <level>
  - Shared memory: <session>/.msg/meta.json
EXPECTED: <session>/audits/typography/typo-audit-001.md | Breakpoint-by-breakpoint report
CONSTRAINTS: Read-only analysis | Screenshot at multiple viewports if Chrome DevTools available"
})
TaskUpdate({ taskId: "TYPO-001", owner: "typo-auditor" })

FOCUS-001 (focus-auditor):

TaskCreate({
  subject: "FOCUS-001",
  description: "PURPOSE: Focus management and keyboard accessibility audit | Success: Complete focus audit with tab order, indicator visibility, ARIA coverage
TASK:
  - Audit tab order for logical sequence and no tab traps
  - Check focus indicator visibility (outline >= 2px, contrast >= 3:1)
  - Verify :focus-visible usage for keyboard vs mouse distinction
  - Check skip link presence and functionality
  - Audit focus traps in modals/dialogs (Tab cycles, Escape dismisses)
  - Verify ARIA live regions for dynamic content
  - Check ARIA roles and states on interactive elements
  - Validate keyboard operability (Enter/Space, Arrow keys)
CONTEXT:
  - Session: <session-folder>
  - Target: <target>
  - WCAG Level: <level>
  - Shared memory: <session>/.msg/meta.json
EXPECTED: <session>/audits/focus/focus-audit-001.md | Element-by-element focus report
CONSTRAINTS: Read-only analysis | Tab through elements if Chrome DevTools available"
})
TaskUpdate({ taskId: "FOCUS-001", owner: "focus-auditor" })

CRITICAL: COLOR-001, TYPO-001, FOCUS-001 have NO blockedBy -- they run in PARALLEL.

REMED-001 (remediation-planner):

TaskCreate({
  subject: "REMED-001",
  description: "PURPOSE: Synthesize all 3 audit findings into prioritized remediation plan | Success: Complete remediation plan with severity ranking, code-level fix guidance, WCAG criterion mapping
TASK:
  - Read color, typography, and focus audit reports
  - Merge and deduplicate findings
  - Prioritize by severity (Critical > High > Medium > Low)
  - Group by file/component for efficient fixing
  - Provide code-level fix guidance (specific CSS/HTML changes)
  - Map each fix to WCAG success criterion
  - Estimate effort per fix
CONTEXT:
  - Session: <session-folder>
  - Target: <target>
  - WCAG Level: <level>
  - Upstream artifacts: audits/color/color-audit-001.md, audits/typography/typo-audit-001.md, audits/focus/focus-audit-001.md
  - Shared memory: <session>/.msg/meta.json
EXPECTED: <session>/remediation/remediation-plan.md | All critical/high issues addressed
CONSTRAINTS: Read-only synthesis | No code modifications"
})
TaskUpdate({ taskId: "REMED-001", addBlockedBy: ["COLOR-001", "TYPO-001", "FOCUS-001"], owner: "remediation-planner" })

---

Full Pipeline Task Chain

Same as audit-only (COLOR-001, TYPO-001, FOCUS-001, REMED-001), plus:

FIX-001 (fix-implementer):

TaskCreate({
  subject: "FIX-001",
  description: "PURPOSE: Implement accessibility fixes from remediation plan | Success: All critical and high severity issues fixed with passing contrast ratios and ARIA validation
TASK:
  - Read remediation plan for prioritized fix list
  - Apply OKLCH color corrections for contrast compliance
  - Add/fix focus styles (outline, outline-offset, :focus-visible)
  - Add missing ARIA attributes (role, aria-label, aria-live, aria-expanded)
  - Add reduced-motion media queries where needed
  - Fix typography (clamp(), line-height, max-width for reading)
  - Add skip link if missing
  - Apply fixes in priority order (critical first)
CONTEXT:
  - Session: <session-folder>
  - Target: <target>
  - WCAG Level: <level>
  - Upstream artifacts: remediation/remediation-plan.md
  - Shared memory: <session>/.msg/meta.json
EXPECTED: Modified source files + <session>/fixes/fix-summary-001.md | All critical/high fixes applied
CONSTRAINTS: Modify only files identified in remediation plan | Preserve existing functionality"
})
TaskUpdate({ taskId: "FIX-001", addBlockedBy: ["REMED-001"], owner: "fix-implementer" })

COLOR-002 (color-auditor):

TaskCreate({
  subject: "COLOR-002",
  description: "PURPOSE: Re-audit color contrast after fixes applied | Success: All color combinations pass WCAG target level
TASK:
  - Re-extract all color values from modified stylesheets
  - Re-calculate WCAG 2.1 contrast ratios
  - Re-calculate APCA Lc values
  - Compare before/after for each fixed combination
  - Verify no regressions in unfixed combinations
CONTEXT:
  - Session: <session-folder>
  - Target: <target>
  - WCAG Level: <level>
  - Upstream artifacts: fixes/fix-summary-001.md, audits/color/color-audit-001.md
  - Shared memory: <session>/.msg/meta.json
EXPECTED: <session>/re-audit/color-audit-002.md | Before/after comparison with pass/fail
CONSTRAINTS: Read-only verification | Focus on fixed items + regression check"
})
TaskUpdate({ taskId: "COLOR-002", addBlockedBy: ["FIX-001"], owner: "color-auditor" })

FOCUS-002 (focus-auditor):

TaskCreate({
  subject: "FOCUS-002",
  description: "PURPOSE: Re-audit focus management after fixes applied | Success: All focus indicators visible with correct ARIA attributes
TASK:
  - Re-audit tab order after DOM changes
  - Verify focus indicator fixes (outline, contrast)
  - Check new ARIA attributes are valid
  - Verify skip link implementation
  - Test keyboard operability of fixed elements
  - Compare before/after for each fixed element
CONTEXT:
  - Session: <session-folder>
  - Target: <target>
  - WCAG Level: <level>
  - Upstream artifacts: fixes/fix-summary-001.md, audits/focus/focus-audit-001.md
  - Shared memory: <session>/.msg/meta.json
EXPECTED: <session>/re-audit/focus-audit-002.md | Before/after comparison with pass/fail
CONSTRAINTS: Read-only verification | Focus on fixed items + regression check"
})
TaskUpdate({ taskId: "FOCUS-002", addBlockedBy: ["FIX-001"], owner: "focus-auditor" })

CRITICAL: COLOR-002 and FOCUS-002 both blocked only by FIX-001 -- they run in PARALLEL after fixes.

---

Phase 4: Validation

Verify task chain integrity:

If validation fails, fix the specific task and re-validate.

Monitor Pipeline

Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.

Constants

• SPAWN_MODE: background
• ONE_STEP_PER_INVOCATION: true
• FAST_ADVANCE_AWARE: true
• WORKER_AGENT: team-worker
• MAX_GC_ROUNDS: 2

Handler Router

handleCallback

Worker completed. Process and advance.

1. Parse message to identify role and task ID:

2. Mark task completed: TaskUpdate({ taskId: "<task-id>", status: "completed" }) 3. Record completion in session state

4. Check checkpoint for completed task:

5. Parallel fan-in handling (audit task completed):

CRITICAL: REMED-001 must wait for ALL 3 auditors (COLOR-001 + TYPO-001 + FOCUS-001) to complete.

Check completion state:

   completed_audits = count of completed tasks in [COLOR-001, TYPO-001, FOCUS-001]
   if completed_audits < 3:
     -> Log "[coordinator] Audit fan-in: {completed_audits}/3 complete, waiting for remaining"
     -> STOP (do NOT advance)
   if completed_audits === 3:
     -> Log "[coordinator] All 3 audits complete, advancing to REMED-001"
     -> handleSpawnNext (will pick up REMED-001)

6. GC loop handling (full mode, after FIX-001 completes):

Read re-audit results when COLOR-002 and FOCUS-002 both complete:

GC Fix Task Creation (when re-audit finds issues):

   TaskCreate({ subject: "FIX-002",
     description: "PURPOSE: Address remaining issues from re-audit | Success: All critical/high issues resolved
   TASK:
     - Parse re-audit reports for remaining issues
     - Apply targeted fixes for color and focus issues
   CONTEXT:
     - Session: <session-folder>
     - Upstream artifacts: re-audit/color-audit-002.md, re-audit/focus-audit-002.md" })
   TaskUpdate({ taskId: "FIX-002", addBlockedBy: ["COLOR-002", "FOCUS-002"], owner: "fix-implementer" })

Then create new re-audit tasks blocked by FIX-002. Increment gc_state.round.

GC Escalation Options (when max rounds exceeded): 1. Accept current state - acknowledge remaining issues 2. Try one more round 3. Terminate

7. -> handleSpawnNext

handleCheck

Read-only status report, then STOP.

Worker Progress (from message bus):

Before generating status output, read worker milestones:

const progressMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "progress", last: 50
})
const blockerMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "blocker", last: 10
})

// Aggregate latest milestone per task
const taskProgress = {}
for (const msg of (progressMsgs.result?.messages || [])) {
  const tid = msg.data?.task_id
  if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
    taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts }
  }
}

Include in status output:

• Per-worker latest milestone (phase + progress_pct) next to task status
• Active blockers section (if any blockerMsgs found)

Pipeline Status (<pipeline-mode>):
  [DONE]  COLOR-001 (color-auditor)        -> audits/color/color-audit-001.md
  [DONE]  TYPO-001  (typo-auditor)         -> audits/typography/typo-audit-001.md
  [RUN]   FOCUS-001 (focus-auditor)        -> auditing focus...
  [WAIT]  REMED-001 (remediation-planner)  -> blocked by COLOR-001, TYPO-001, FOCUS-001
  [WAIT]  FIX-001   (fix-implementer)      -> blocked by REMED-001
  [WAIT]  COLOR-002 (color-auditor)        -> blocked by FIX-001
  [WAIT]  FOCUS-002 (focus-auditor)        -> blocked by FIX-001

Fan-in: 2/3 audits complete
GC Rounds: 0/2
Session: <session-id>
Commands: 'resume' to advance | 'check' to refresh

Output status -- do NOT advance pipeline.

handleResume

1. Audit task list for inconsistencies:

• Tasks stuck in "in_progress" -> reset to "pending"
• Tasks with completed blockers but still "pending" -> include in spawn list

2. -> handleSpawnNext

handleSpawnNext

Find ready tasks, spawn workers, STOP.

1. Collect: completedSubjects, inProgressSubjects, readySubjects (pending + all blockedBy completed) 2. No ready + work in progress -> report waiting, STOP 3. No ready + nothing in progress -> handleComplete 4. Has ready -> for each: a. Check inner loop role with active worker -> skip (worker picks up) b. TaskUpdate -> in_progress c. team_msg log -> task_unblocked d. Spawn team-worker:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker for <task-id>",
  team_name: "visual-a11y",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: visual-a11y
requirement: <task-description>
inner_loop: <true|false>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

Parallel spawn rules by mode:

5. Add to active_workers, update session, output summary, STOP

handleComplete

Pipeline done. Generate report and completion action.

Completion check by mode:

1. If any tasks not completed -> handleSpawnNext 2. If all completed -> transition to coordinator Phase 5

handleAdapt

Capability gap reported mid-pipeline.

1. Parse gap description 2. Check if existing role covers it -> redirect 3. Role count < 6 -> generate dynamic role spec 4. Create new task, spawn worker 5. Role count >= 6 -> merge or pause

Fast-Advance Reconciliation

On every coordinator wake: 1. Read team_msg entries with type="fast_advance" 2. Sync active_workers with spawned successors 3. No duplicate spawns

Coordinator Role

Visual Accessibility Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Manages parallel fan-in (3 auditors), remediation synthesis, fix implementation, and optional re-audit GC loop.

Identity

• Name: coordinator | Tag: [coordinator]
• Responsibility: Analyze scope -> Create team -> Dispatch tasks -> Monitor progress -> Report results

Boundaries

MUST

• All output (SendMessage, team_msg, logs) must carry [coordinator] identifier
• Use team-worker agent type for all worker spawns (NOT general-purpose)
• Dispatch tasks with proper dependency chains and blockedBy
• Spawn COLOR-001, TYPO-001, FOCUS-001 in PARALLEL (no blockedBy between them)
• Monitor worker progress via message bus and route messages
• Handle Generator-Critic loops with max 2 iterations
• Maintain session state persistence

MUST NOT

• Implement domain logic (auditing, planning, fixing) -- workers handle this
• Spawn workers without creating tasks first
• Skip sync points when configured
• Force-advance pipeline past failed audit
• Modify source code or design artifacts directly -- delegate to workers
• Omit [coordinator] identifier in any output

Command Execution Protocol

When coordinator needs to execute a command (analyze, dispatch, monitor):

1. Read commands/<command>.md 2. Follow the workflow defined in the command 3. Commands are inline execution guides, NOT separate agents 4. Execute synchronously, complete before proceeding

Entry Router

For callback/check/resume/adapt/complete: load @commands/monitor.md, execute matched handler, STOP.

Phase 0: Session Resume Check

1. Scan .workflow/.team/VA-*/.msg/meta.json for active/paused sessions 2. No sessions -> Phase 1 3. Single session -> reconcile (audit TaskList, reset in_progress->pending, rebuild team, kick first ready task) 4. Multiple -> AskUserQuestion for selection

Phase 1: Requirement Clarification

TEXT-LEVEL ONLY. No source code reading.

1. Parse task description from arguments 2. Detect audit scope:

3. Ask for missing parameters if scope unclear:

   AskUserQuestion({
     questions: [
       { question: "Accessibility audit scope?", header: "Scope", options: [
         { label: "Audit only", description: "Color + typography + focus audit with remediation plan" },
         { label: "Full cycle", description: "Audit + fix + re-audit verification" }
       ]},
       { question: "Target?", header: "Target", options: [
         { label: "URL (rendered page)" },
         { label: "Component path (source)" },
         { label: "Full site" }
       ]}
     ]
   })

4. Delegate to @commands/analyze.md -> output scope context 5. Record: pipeline_mode, target, wcag_level

Phase 2: Create Team + Initialize Session

1. Resolve workspace paths (MUST do first):

• project_root = result of Bash({ command: "pwd" })
• skill_root = <project_root>/.claude/skills/team-visual-a11y

2. Generate session ID: VA-<slug>-<YYYY-MM-DD> 3. Create session folder structure:

   .workflow/.team/VA-<slug>-<date>/audits/color/
   .workflow/.team/VA-<slug>-<date>/audits/typography/
   .workflow/.team/VA-<slug>-<date>/audits/focus/
   .workflow/.team/VA-<slug>-<date>/remediation/
   .workflow/.team/VA-<slug>-<date>/fixes/
   .workflow/.team/VA-<slug>-<date>/re-audit/
   .workflow/.team/VA-<slug>-<date>/evidence/
   .workflow/.team/VA-<slug>-<date>/.msg/

4. Initialize .msg/meta.json via team_msg state_update with pipeline metadata 5. TeamCreate(team_name="visual-a11y") 6. Do NOT spawn workers yet - deferred to Phase 4

Phase 3: Create Task Chain

Delegate to @commands/dispatch.md. Task chains by mode:

Phase 4: Spawn-and-Stop

CRITICAL: Spawn COLOR-001, TYPO-001, FOCUS-001 in PARALLEL (all 3 have NO blockedBy).

Delegate to @commands/monitor.md#handleSpawnNext: 1. Find ready tasks (pending + blockedBy resolved) 2. Spawn team-worker agents (see SKILL.md Spawn Template) 3. Output status summary 4. STOP

Phase 5: Report + Completion Action

1. Read session state -> collect all results 2. List deliverables:

3. Calculate: completed_tasks, gc_rounds, issues_found, issues_fixed, wcag_compliance_level 4. Output pipeline summary with [coordinator] prefix 5. Execute completion action:

   AskUserQuestion({
     questions: [{ question: "Pipeline complete. What next?", header: "Completion", options: [
       { label: "Archive & Clean", description: "Archive session and clean up team resources" },
       { label: "Keep Active", description: "Keep session for follow-up work" },
       { label: "Export Results", description: "Export deliverables to specified location" }
     ]}]
   })

Error Handling

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

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:

/* 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:

   :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:

   @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():

   body { font-size: clamp(1rem, 1vw + 0.875rem, 1.25rem); }

2. Fix line-height to acceptable ranges:

   body { line-height: 1.625; }
   h1, h2, h3 { line-height: 1.2; }

3. Add max-width for reading containers:

   .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>:

   <a href="#main" class="skip-link">Skip to main content</a>

2. Add 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:

2. Write fix summary to <session>/fixes/fix-summary-{NNN}.md:

# 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

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

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

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:

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

Step 5: Focus Trap Audit (Modals/Dialogs)

Per specs/focus-patterns.md:

Step 6: ARIA Audit

Step 7: Keyboard Operability

Input Method Awareness

Step 8: Target Size (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):

# 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:

## 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

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

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:

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

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:

/* 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:

/* 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:

<!-- Before -->
<div class="modal">
<!-- After -->
<div class="modal" role="dialog" aria-modal="true" aria-labelledby="modal-title">

Typography fixes:

/* 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

Step 6: WCAG Criterion Mapping

Map every issue to specific WCAG success criterion:

Phase 4: Validation & Output

1. Validate plan completeness:

2. Write remediation plan to <session>/remediation/remediation-plan.md:

# 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

Typography Readability Auditor

Typography accessibility audit across all viewports. Font sizes at breakpoints, line-height ratios, clamp() validation, reading width measurement, font loading strategy assessment. Produce detailed typography report with breakpoint-by-breakpoint analysis.

Phase 2: Context & Environment Detection

1. Extract session path, target, and WCAG level from task description 2. Identify target:

• URL -> use Chrome DevTools for rendered typography (navigate_page, resize_page, screenshot)
• File paths -> read CSS/SCSS files directly for typography definitions
• Full site -> enumerate stylesheets from HTML entry points

3. Read typography standards from specs/typography-scale.md for reference thresholds

Phase 3: Typography Audit Execution

Step 1: Typography Definition Extraction

Static analysis (always):

• Glob for CSS/SCSS/Tailwind files -> extract typography definitions
• Extract: font-family, font-size, line-height, letter-spacing, font-weight, font-display
• Parse clamp() functions: clamp(min, preferred, max) -> validate min/max bounds
• Parse @media queries for responsive breakpoints
• Record source location (file:line) for each rule

Runtime analysis (if Chrome DevTools available):

• Navigate to target URL
• For each breakpoint (320px, 768px, 1024px, 1400px):
• mcp__chrome-devtools__resize_page({ width: <breakpoint>, height: 900 })
• mcp__chrome-devtools__evaluate_script({ expression: "..." }) to measure:
• Computed font-size on body, headings (h1-h6), paragraphs, captions
• Computed line-height on same elements
• Container width and character count per line
• mcp__chrome-devtools__take_screenshot({}) -> save to <session>/evidence/typo-{breakpoint}px.png

Step 2: Font Size Audit

clamp() validation:

• Minimum value >= 14px (absolute floor)
• Maximum value reasonable for element type (headings: max ~72px, body: max ~20px)
• Preferred value uses viewport unit (vw) for fluid scaling
• Check: clamp(min, preferred, max) where min >= 14px for any text

200% zoom check (WCAG 1.4.4):

• At 200% zoom, no content should be clipped or lost
• Text should reflow without horizontal scrolling

Step 3: Line Height Audit

Check for unitless line-height (preferred over px/em for inheritance).

Step 4: Letter Spacing Audit

WCAG 1.4.12 override test: Text must remain readable when user overrides:

• Line height to at least 1.5x font size
• Letter spacing to at least 0.12em
• Word spacing to at least 0.16em

Step 5: Reading Width Audit

Measure characters per line for body text containers:

Check: max-width or width on body text containers.

Step 6: Font Loading Strategy

Check for FOUT (Flash of Unstyled Text) / FOIT (Flash of Invisible Text) risks.

Phase 4: Report Generation & Output

1. Write audit report to <session>/audits/typography/typo-audit-{NNN}.md:

# Typography Accessibility Audit - {NNN}
[typo-auditor]

## Summary
- **Total typography rules audited**: {count}
- **Pass**: {pass_count} | **Fail**: {fail_count}
- **WCAG Level**: {AA|AAA}
- **Critical issues**: {count}
- **High issues**: {count}

## Font Size by Breakpoint
| Breakpoint | Element | Computed Size | Min Required | Status |
|-----------|---------|--------------|-------------|--------|
| 320px | body | Xpx | 16px | PASS/FAIL |
| 320px | h1 | Xpx | -- | OK |
| ... | ... | ... | ... | ... |

## clamp() Validation
| Rule | clamp() Value | Min | Max | Status |
|------|--------------|-----|-----|--------|
| .body | clamp(1rem, 2vw, 1.25rem) | 16px | 20px | PASS/FAIL |
| ... | ... | ... | ... | ... |

## Line Height Audit
| Element | Current | Expected Range | Status |
|---------|---------|---------------|--------|
| body | 1.6 | 1.5-1.75 | PASS |
| h1 | 1.2 | 1.1-1.3 | PASS |
| ... | ... | ... | ... |

## Letter Spacing Audit
| Element | Current | Expected Range | Status |
|---------|---------|---------------|--------|
| ... | ... | ... | ... |

## Reading Width
| Container | Width | Chars/Line | Optimal (45-75) | Status |
|-----------|-------|-----------|-----------------|--------|
| .content | 700px | ~68ch | Yes | PASS |
| ... | ... | ... | ... | ... |

## Font Loading
| Font | font-display | Preload | Fallback | Status |
|------|-------------|---------|----------|--------|
| ... | swap | yes/no | system | PASS/FAIL |

## Text Spacing Override Test (WCAG 1.4.12)
| Override | Applied | Content Readable | Status |
|---------|---------|-----------------|--------|
| line-height: 1.5x | Yes | Yes/No | PASS/FAIL |
| letter-spacing: 0.12em | Yes | Yes/No | PASS/FAIL |
| word-spacing: 0.16em | Yes | Yes/No | PASS/FAIL |

## Issues (by severity)
### Critical
- ...
### High
- ...
### Medium
- ...

2. Update <session>/.msg/meta.json under typo-auditor namespace:

• Read existing -> merge { "typo-auditor": { audit_id, total_rules, pass_count, fail_count, critical_count, high_count, breakpoints_tested, timestamp } } -> write back

Focus Management Patterns

Reference guide for focus indicator styles, skip links, focus traps, and ARIA patterns. Used by focus-auditor and fix-implementer roles.

Focus Indicator Style

Recommended Pattern

/* Keyboard focus: visible outline */
:focus-visible {
  outline: 2px solid var(--color-accent);
  outline-offset: 2px;
}

/* Mouse click: no outline */
:focus:not(:focus-visible) {
  outline: none;
}

Requirements

Anti-Patterns (Do NOT)

/* BAD: Removes all focus indicators */
*:focus { outline: none; }

/* BAD: Removes focus without alternative */
button:focus { outline: 0; }

/* BAD: Only uses box-shadow (invisible in high contrast mode) */
:focus-visible { outline: none; box-shadow: 0 0 0 2px blue; }

Correct Alternative Indicator

/* If not using outline, MUST provide visible alternative */
:focus-visible {
  outline: 2px solid transparent; /* For Windows high contrast mode */
  box-shadow: 0 0 0 2px var(--color-accent);
}

Skip Link

HTML

<body>
  <a href="#main" class="skip-link">Skip to main content</a>
  <!-- navigation, header, etc. -->
  <main id="main" tabindex="-1">
    <!-- main content -->
  </main>
</body>

CSS

.skip-link {
  position: absolute;
  left: -9999px;
  top: auto;
  width: 1px;
  height: 1px;
  overflow: hidden;
  z-index: -1;
}

.skip-link:focus {
  position: fixed;
  left: 16px;
  top: 16px;
  width: auto;
  height: auto;
  overflow: visible;
  z-index: 9999;
  background: var(--color-paper, #fff);
  color: var(--color-ink, #000);
  padding: 8px 16px;
  border: 2px solid var(--color-ink, #000);
  border-radius: 4px;
  font-size: 1rem;
  text-decoration: underline;
}

Requirements

Focus Trap (Modals/Dialogs)

Implementation Pattern

function trapFocus(dialog) {
  const focusableSelector = [
    'a[href]', 'button:not([disabled])', 'input:not([disabled])',
    'select:not([disabled])', 'textarea:not([disabled])',
    '[tabindex]:not([tabindex="-1"])'
  ].join(', ');

  const focusableElements = dialog.querySelectorAll(focusableSelector);
  const firstFocusable = focusableElements[0];
  const lastFocusable = focusableElements[focusableElements.length - 1];

  // Store trigger for focus restore
  const trigger = document.activeElement;

  // Move focus to first element
  firstFocusable.focus();

  dialog.addEventListener('keydown', function(e) {
    if (e.key === 'Escape') {
      closeDialog(dialog);
      trigger.focus(); // Restore focus
      return;
    }

    if (e.key !== 'Tab') return;

    if (e.shiftKey) {
      // Shift+Tab at first element -> wrap to last
      if (document.activeElement === firstFocusable) {
        e.preventDefault();
        lastFocusable.focus();
      }
    } else {
      // Tab at last element -> wrap to first
      if (document.activeElement === lastFocusable) {
        e.preventDefault();
        firstFocusable.focus();
      }
    }
  });
}

Dialog HTML Pattern

<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Dialog Title</h2>
  <div class="dialog-content">
    <!-- content -->
  </div>
  <div class="dialog-actions">
    <button type="button">Cancel</button>
    <button type="button">Confirm</button>
  </div>
</div>

Requirements

ARIA Patterns

Button Patterns

<!-- Standard button -->
<button type="button">Save</button>

<!-- Icon-only button (needs aria-label) -->
<button type="button" aria-label="Close dialog">
  <svg><!-- X icon --></svg>
</button>

<!-- Toggle button -->
<button type="button" aria-pressed="false">Bold</button>

<!-- Disclosure button -->
<button type="button" aria-expanded="false" aria-controls="panel-1">
  Show details
</button>
<div id="panel-1" hidden>Details content</div>

Dialog Pattern

<div role="dialog" aria-modal="true" aria-labelledby="dlg-title" aria-describedby="dlg-desc">
  <h2 id="dlg-title">Confirm Action</h2>
  <p id="dlg-desc">Are you sure you want to proceed?</p>
  <button type="button">Cancel</button>
  <button type="button">Confirm</button>
</div>

Live Region Patterns

<!-- Status updates (polite) -->
<div role="status" aria-live="polite">
  3 items in cart
</div>

<!-- Error messages (assertive) -->
<div role="alert" aria-live="assertive">
  Email address is invalid
</div>

<!-- Log/chat (polite, additions only) -->
<div role="log" aria-live="polite" aria-relevant="additions">
  <!-- new messages appended here -->
</div>

Navigation Pattern

<!-- Primary navigation -->
<nav aria-label="Primary">
  <ul role="menubar">
    <li role="none"><a role="menuitem" href="/">Home</a></li>
    <li role="none"><a role="menuitem" href="/about">About</a></li>
  </ul>
</nav>

<!-- Breadcrumb -->
<nav aria-label="Breadcrumb">
  <ol>
    <li><a href="/">Home</a></li>
    <li><a href="/products">Products</a></li>
    <li aria-current="page">Widget</li>
  </ol>
</nav>

Tab Pattern

<div role="tablist" aria-label="Settings">
  <button role="tab" aria-selected="true" aria-controls="panel-general" id="tab-general">
    General
  </button>
  <button role="tab" aria-selected="false" aria-controls="panel-security" id="tab-security" tabindex="-1">
    Security
  </button>
</div>
<div role="tabpanel" id="panel-general" aria-labelledby="tab-general">
  General settings content
</div>
<div role="tabpanel" id="panel-security" aria-labelledby="tab-security" hidden>
  Security settings content
</div>

Keyboard: Arrow Left/Right to switch tabs, Tab to move into panel content.

Form Error Pattern

<label for="email">Email</label>
<input
  type="email"
  id="email"
  aria-required="true"
  aria-invalid="true"
  aria-describedby="email-error"
>
<div id="email-error" role="alert">
  Please enter a valid email address
</div>

Keyboard Navigation Reference

Target Size Reference

Exceptions: Inline links within text, browser default controls, essential fixed-size elements.

OKLCH Color Accessibility Standards

Reference guide for OKLCH-based perceptual color analysis. Used by color-auditor and fix-implementer roles.

OKLCH Basics

oklch(Lightness% Chroma Hue)

• Lightness (L): 0% (black) to 100% (white) -- perceptually uniform
• Chroma (C): 0 (achromatic/gray) to ~0.37 (maximum saturation) -- perceptual colorfulness
• Hue (H): 0-360 degrees -- color wheel angle

OKLCH is perceptually uniform: equal numeric changes produce equal perceived changes, unlike HSL/RGB.

Lightness Guidelines

Chroma Guidelines

Impeccable Palette Reference

/* Neutrals */
--color-ink:       oklch(10% 0 0);      /* Primary text */
--color-paper:     oklch(98% 0 0);      /* Primary background */
--color-cream:     oklch(96% 0.005 350); /* Warm background variant */
--color-charcoal:  oklch(25% 0 0);      /* Secondary text */
--color-ash:       oklch(55% 0 0);      /* Muted/disabled text */
--color-mist:      oklch(92% 0 0);      /* Border/divider */

/* Accent */
--color-accent:       oklch(60% 0.25 350); /* Primary action */
--color-accent-hover: oklch(52% 0.25 350); /* Hover state (darker) */

Palette Analysis

Contrast Verification Methods

WCAG 2.1 Contrast Ratio

Formula: (L1 + 0.05) / (L2 + 0.05) where L1, L2 are relative luminances (L1 > L2).

Convert OKLCH -> sRGB -> linear RGB -> relative luminance: L_rel = 0.2126 * R_linear + 0.7152 * G_linear + 0.0722 * B_linear

APCA Contrast (Advanced)

APCA (Accessible Perceptual Contrast Algorithm) uses OKLCH lightness for perceptual accuracy.

Lc (Lightness contrast) values:

Focus Indicator Contrast

Focus indicators must have >= 3:1 contrast against adjacent colors:

• Outline color vs element background
• Outline color vs surrounding page background
• Both must pass

Color Blindness Reference

Confusion Lines

Safe Color Pairs

Always ensure information is not conveyed by color alone. Safe strategies:

• Use lightness difference (>= 40% L difference)
• Add text labels, icons, or patterns alongside color
• Use blue + orange (safe for most color blindness types)
• Avoid red-only or green-only indicators

Dark Mode Color Mapping

When converting light mode to dark mode:

Maintain same hue and similar chroma; adjust lightness to preserve contrast ratios.

Pipeline Definitions

Visual accessibility pipeline modes and task registry.

Pipeline Modes

Audit-Only Pipeline Task Registry

CRITICAL: COLOR-001, TYPO-001, FOCUS-001 have NO blockedBy -- they run in PARALLEL.

Full Pipeline Task Registry

CRITICAL: COLOR-002 and FOCUS-002 both blocked only by FIX-001 -- they run in PARALLEL.

Dependency Graphs

Audit-Only

COLOR-001 --+
            |
TYPO-001  --+--> REMED-001
            |
FOCUS-001 --+

Full

COLOR-001 --+
            |
TYPO-001  --+--> REMED-001 --> FIX-001 --+--> COLOR-002
            |                             |
FOCUS-001 --+                             +--> FOCUS-002

Fan-In Points

GC Loop Behavior (Full Mode)

After re-audit fan-in (COLOR-002 + FOCUS-002 both complete):

Parallel Spawn Rules

Output Artifacts

Typography Accessibility Standards

Reference guide for typography readability analysis. Used by typo-auditor and fix-implementer roles.

Font Stack Hierarchy

System Font Stack (Fallback)

--font-body: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
--font-mono: ui-monospace, "Cascadia Code", "Fira Code", Menlo, monospace;

Responsive Size Scale

clamp() Formula Pattern

/* clamp(minimum, preferred, maximum) */
/* preferred = slope * 100vw + intercept */
/* slope = (max - min) / (max-viewport - min-viewport) */

Recommended Scale

Absolute Minimums

Never: Set body text below 14px at any viewport width.

Line Height Scale

Line Height Rules

• Use unitless values (not px or em) for proper inheritance
• line-height: 1.5 (unitless) is preferred over line-height: 24px (fixed)
• WCAG 1.4.12 requires text to remain readable at 1.5x font-size line-height

Letter Spacing Scale

WCAG 1.4.12 Override Requirements

Content must remain readable when user applies:

• Letter spacing: 0.12em
• Word spacing: 0.16em
• These overrides should not cause content overflow or overlap

Reading Width

Implementation

/* Preferred: ch-based */
.content { max-width: 70ch; }

/* Alternative: px-based */
.content { max-width: 700px; }

/* With centering */
.content {
  max-width: 70ch;
  margin-inline: auto;
  padding-inline: 1rem;
}

Font Loading Strategy

font-display Values

Best Practices

/* Body font: swap for immediate readability */
@font-face {
  font-family: "Body Font";
  src: url("body.woff2") format("woff2");
  font-display: swap;
}

/* Display font: optional to prevent layout shift */
@font-face {
  font-family: "Display Font";
  src: url("display.woff2") format("woff2");
  font-display: optional;
}

Preloading Critical Fonts

<link rel="preload" href="/fonts/body.woff2" as="font" type="font/woff2" crossorigin>

Fallback Stack Requirements

• Every custom font must have a system fallback
• Fallback should have similar metrics (x-height, width) to minimize layout shift
• Use size-adjust, ascent-override, descent-override for metric matching

Responsive Typography Checklist

WCAG 2.1 Criteria Matrix

Reference matrix for visual accessibility audit. Maps WCAG success criteria to audit methods and responsible roles.

Criteria Covered by This Team

Audit Method Legend

Criterion Details

1.4.3 Contrast (Minimum) - AA

Requirement: Text and images of text have a contrast ratio of at least 4.5:1 (3:1 for large text).

Large text definition: >= 18pt (24px) or >= 14pt bold (18.66px bold).

Exceptions: Decorative text, logos, inactive UI components.

Check: Extract foreground/background colors -> calculate contrast ratio -> compare against threshold.

1.4.6 Contrast (Enhanced) - AAA

Requirement: Text has contrast ratio of at least 7:1 (4.5:1 for large text).

Check: Same as 1.4.3 but with higher thresholds.

1.4.11 Non-text Contrast - AA

Requirement: UI components and graphical objects have at least 3:1 contrast against adjacent colors.

Applies to: Buttons, inputs, icons, focus indicators, charts, custom controls.

Check: Extract border/fill colors of UI components -> calculate contrast against background.

1.4.4 Resize Text - AA

Requirement: Text can be resized up to 200% without loss of content or functionality.

Check: Zoom to 200% -> verify no horizontal scrolling, no content clipping, no overlap.

1.4.12 Text Spacing - AA

Requirement: Content must remain readable when user overrides:

• Line height to 1.5x font size
• Paragraph spacing to 2x font size
• Letter spacing to 0.12x font size
• Word spacing to 0.16x font size

Check: Apply overrides via JavaScript/CSS -> verify no content loss or overlap.

2.1.1 Keyboard - A

Requirement: All functionality available via keyboard (Enter, Space, Tab, Arrow keys, Escape).

Check: Tab to every interactive element -> activate with Enter/Space -> navigate composites with Arrows.

2.1.2 No Keyboard Trap - A

Requirement: Keyboard focus can be moved away from any component using standard keys.

Exception: Modal dialogs that trap focus intentionally (must have Escape to exit).

Check: Tab forward and backward through all elements -> verify escape from all containers.

2.4.1 Bypass Blocks - A

Requirement: Mechanism to bypass repeated content blocks (skip links, landmarks, headings).

Check: Verify skip link as first focusable element, target exists, focus moves correctly.

2.4.3 Focus Order - A

Requirement: Focus order preserves meaning and operability (logical sequence).

Check: Tab through page -> verify order matches visual/reading order.

2.4.7 Focus Visible - AA

Requirement: Keyboard focus indicator is visible on all interactive elements.

Check: Tab to each element -> verify visible outline/border/shadow change.

2.4.11 Focus Not Obscured (Minimum) - AA

Requirement: Focused element is not entirely hidden by other content (sticky headers, overlays, banners).

Check: Tab through elements near sticky/fixed positioned elements -> verify focus indicator partially visible.

2.5.8 Target Size (Minimum) - AA

Requirement: Interactive targets are at least 24x24 CSS pixels, or have adequate spacing.

Exceptions: Inline links within text, user agent default controls, essential presentation.

Check: Measure interactive element dimensions -> verify >= 24x24px or adequate spacing.

4.1.2 Name, Role, Value - A

Requirement: All UI components have accessible name, role, and state programmatically determined.

Check: Verify interactive elements have:

• Accessible name (text content, aria-label, aria-labelledby)
• Appropriate role (native HTML or ARIA role)
• Current state (aria-expanded, aria-pressed, aria-selected, aria-checked)

4.1.3 Status Messages - AA

Requirement: Status messages can be programmatically determined through role or properties without receiving focus.

Check: Verify dynamic content updates use aria-live or appropriate roles (status, alert, log).