claude-code-workflow 7.2.27 → 7.2.28

package/.claude/skills/team-ux-improve/wisdom/principles/general-ux.md

@@ -1,16 +1,43 @@
 # General UX Principles
 
 ## Feedback & Responsiveness
-- Every user action should have immediate visual feedback
-- Loading states must be shown for operations >200ms
-- Success/error states should be clearly communicated
+- Every user action must have immediate visual feedback (< 100ms perceived)
+- Loading states for operations > 200ms: use skeleton/spinner, set aria-busy="true"
+- Success/error states clearly communicated with both visual and ARIA cues
+- Feedback duration: 100-150ms for hover/active/focus transitions
+- State change transitions: 200-300ms
+- Layout changes: 300-500ms
+
+## Interaction States (8 Required)
+Every interactive element must define all 8 states:
+1. Default — base appearance
+2. Hover — subtle bg/opacity change, wrap in @media(hover:hover)
+3. Focus — :focus-visible with 2px solid accent, offset 2px, 3:1 contrast ratio
+4. Active — scale(0.97) or darker background
+5. Disabled — opacity 0.5, cursor: not-allowed, aria-disabled="true"
+6. Loading — spinner/skeleton, disable interaction, aria-busy="true"
+7. Error — red border, error message below, aria-invalid="true"
+8. Success — green check, success message
 
 ## State Management
-- UI state should reflect the underlying data state
-- Optimistic updates should have rollback mechanisms
-- State changes should be atomic and predictable
+- UI state must reflect underlying data state immediately
+- Optimistic updates must have rollback mechanisms
+- State changes must be atomic and predictable
+- No direct array/object mutation (use spread/filter/map for reactive frameworks)
+- Race conditions: use request cancellation or debounce
+
+## Visual Design Quality
+- Color: OKLCH-based, tinted neutrals (never pure gray/black/white), 60-30-10 rule
+- Typography: distinctive fonts (not Inter/Roboto), modular scale, fluid clamp()
+- Spacing: 4pt base scale with varied rhythm (tight/comfortable/generous)
+- Motion: transform+opacity only, ease-out-quart easing, reduced-motion query required
+- Hierarchy: squint test, single primary CTA per viewport
 
 ## Accessibility
-- Interactive elements must be keyboard accessible
-- Color should not be the only indicator of state
-- Focus states must be visible
+- All interactive elements keyboard accessible (tab + enter/space)
+- Color must NOT be the only indicator of state
+- Focus states must use :focus-visible (not bare :focus)
+- Focus ring: 3:1 contrast against adjacent colors
+- Touch targets: minimum 44x44px, 8px gap between adjacent
+- Visible labels on all form inputs (placeholder is not a label)
+- Skip links for keyboard navigation

package/.claude/skills/team-visual-a11y/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: team-visual-a11y
+description: Unified team skill for visual accessibility QA. OKLCH color contrast, typography readability, focus management, WCAG AA/AAA audit at rendered level. Uses team-worker agent architecture. Triggers on "team visual a11y", "accessibility audit", "visual a11y".
+allowed-tools: Agent, AskUserQuestion, Read, Write, Edit, Bash, Glob, Grep, TaskList, TaskGet, TaskUpdate, TaskCreate, TeamCreate, TeamDelete, SendMessage, mcp__ccw-tools__read_file, mcp__ccw-tools__write_file, mcp__ccw-tools__edit_file, mcp__ccw-tools__team_msg, mcp__chrome-devtools__evaluate_script, mcp__chrome-devtools__take_screenshot, mcp__chrome-devtools__emulate, mcp__chrome-devtools__lighthouse_audit, mcp__chrome-devtools__navigate_page, mcp__chrome-devtools__resize_page
+---
+
+# 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 | Path | Prefix | Inner Loop |
+|------|------|--------|------------|
+| coordinator | [roles/coordinator/role.md](roles/coordinator/role.md) | -- | -- |
+| color-auditor | [roles/color-auditor/role.md](roles/color-auditor/role.md) | COLOR-* | false |
+| typo-auditor | [roles/typo-auditor/role.md](roles/typo-auditor/role.md) | TYPO-* | false |
+| focus-auditor | [roles/focus-auditor/role.md](roles/focus-auditor/role.md) | FOCUS-* | false |
+| remediation-planner | [roles/remediation-planner/role.md](roles/remediation-planner/role.md) | REMED-* | false |
+| fix-implementer | [roles/fix-implementer/role.md](roles/fix-implementer/role.md) | FIX-* | true |
+
+## 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>
+
+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
+
+| Command | Action |
+|---------|--------|
+| `check` / `status` | View execution status graph |
+| `resume` / `continue` | Advance to next step |
+
+## Specs Reference
+
+- [specs/pipelines.md](specs/pipelines.md) -- Pipeline definitions and task registry
+- [specs/oklch-standards.md](specs/oklch-standards.md) -- OKLCH color accessibility rules
+- [specs/wcag-matrix.md](specs/wcag-matrix.md) -- WCAG 2.1 criteria matrix
+- [specs/typography-scale.md](specs/typography-scale.md) -- Typography accessibility rules
+- [specs/focus-patterns.md](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
+
+| Scenario | Resolution |
+|----------|------------|
+| Unknown command | Error with available command list |
+| Role not found | Error with role registry |
+| Session corruption | Attempt recovery, fallback to manual |
+| Fast-advance conflict | Coordinator reconciles on next callback |
+| Completion action fails | Default to Keep Active |
+| GC loop stuck > 2 rounds | Escalate to user: accept / retry / terminate |
+| Chrome DevTools unavailable | Degrade to static analysis only |

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

@@ -0,0 +1,178 @@
+---
+role: color-auditor
+prefix: COLOR
+inner_loop: false
+message_types: [state_update]
+---
+
+# 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
+
+| 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/color/color-audit-*.md | Only for COLOR-002+ |
+
+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:
+
+| Text Type | AA | AAA |
+|-----------|-----|-----|
+| Normal text (< 18pt / < 14pt bold) | >= 4.5:1 | >= 7:1 |
+| Large text (>= 18pt / >= 14pt bold) | >= 3:1 | >= 4.5:1 |
+| Non-text (UI components, icons) | >= 3:1 | >= 3:1 |
+
+**APCA Contrast (Lc values)**:
+- Calculate APCA Lc using OKLCH lightness difference
+- Thresholds:
+
+| Use Case | Minimum Lc |
+|----------|-----------|
+| Body text (16px) | >= 60 |
+| Large text (24px+) | >= 45 |
+| Non-text elements | >= 30 |
+| Placeholder/disabled | >= 15 |
+
+### Step 3: OKLCH Lightness Analysis
+
+Verify OKLCH lightness ranges per specs/oklch-standards.md:
+
+| Element | Expected L Range | Flag If |
+|---------|-----------------|---------|
+| Dark text on light bg | L <= 40% | L > 40% (too light for text) |
+| Light background | L >= 90% | L < 90% (too dark for bg) |
+| Accent colors | L 50-65% | Outside range |
+| Disabled/muted text | L 55-70% | Outside range |
+
+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)
+
+| Check | Requirement | Method |
+|-------|-------------|--------|
+| No pure black background | Base bg uses tinted dark (oklch L >= 0.10, chroma >= 0.005) | evaluate_script: getComputedStyle check |
+| Surface hierarchy | Higher elevation = lighter surface (at least 3 distinct levels) | Screenshot comparison |
+| Font weight reduction | Dark theme reduces weight by 1 step vs light (600→500, 500→400) | Compare computed font-weight |
+| Accent desaturation | Dark theme accents have lower OKLCH chroma than light (by 0.03-0.10) | Compare computed colors |
+| Dangerous combos | No gray text on colored backgrounds, no red-green only indicators | Visual + computed color analysis |
+| All contrast ratios met | WCAG AA requirements must pass in BOTH light and dark themes | Lighthouse audit both themes |
+
+## 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):
+
+```markdown
+# 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:
+```markdown
+## 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

package/.claude/skills/team-visual-a11y/roles/coordinator/commands/analyze.md

@@ -0,0 +1,72 @@
+# 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
+
+| Keywords | Capability | Pipeline Hint |
+|----------|------------|---------------|
+| color, contrast, oklch, palette, hue | color audit | audit-only or full |
+| typography, font, line-height, clamp, readability | typography audit | audit-only or full |
+| focus, tab, keyboard, aria, skip-link, focus-visible | focus audit | audit-only or full |
+| wcag, a11y, accessibility, compliance | full audit | audit-only or full |
+| fix, remediate, implement, correct | fix cycle | full |
+| audit only, assessment, review, check | audit only | audit-only |
+
+## Target Detection
+
+| Signal | Target Type |
+|--------|-------------|
+| URL (http/https) | rendered-page |
+| File path (.tsx, .vue, .html, .css) | component-source |
+| "full site", "all pages", "entire app" | full-site |
+| Component name without path | component-source (search needed) |
+| Unclear | ask user |
+
+## Mode Determination
+
+| Signal | Pipeline Mode |
+|--------|---------------|
+| "audit only", "no fixes", "assessment", "review" | audit-only |
+| "full", "fix", "remediate", "complete cycle" | full |
+| Single audit domain (color OR typography OR focus only) | audit-only |
+| Unclear | ask user |
+
+## WCAG Level Detection
+
+| Signal | Level |
+|--------|-------|
+| "AA" or default | AA |
+| "AAA", "enhanced", "strict" | AAA |
+
+## Complexity Scoring
+
+| Factor | Points |
+|--------|--------|
+| Single component | +1 |
+| Multiple components | +2 |
+| Full site | +3 |
+| Rendered page (Chrome DevTools) | +1 |
+| AAA level requested | +1 |
+| Fix cycle included | +1 |
+
+Results: 1-2 Low, 3-4 Medium, 5+ High
+
+## Output
+
+Write scope context to coordinator memory:
+```json
+{
+  "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
+}
+```