Team Ui Polish

Team UI Polish

Automatic UI quality improvement pipeline: scan -> diagnose -> optimize -> verify. 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-ui-polish", 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       v
           [team-worker agents, each loads roles/<role>/role.md]
          scanner  diagnostician  optimizer <-> verifier (GC loop)

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: UIP
• Session path: .workflow/.team/UIP-<slug>-<date>/
• 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: "ui-polish",
  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: ui-polish
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/team-config.json -- Team configuration
• specs/anti-patterns.md -- AI slop and design anti-pattern catalog
• specs/design-standards.md -- Impeccable positive design standards
• specs/fix-strategies.md -- Issue-to-fix mapping
• specs/scoring-guide.md -- Scoring rubric

Session Directory

.workflow/.team/UIP-<slug>-<date>/
+-- .msg/
|   +-- messages.jsonl         # Team message bus
|   +-- meta.json              # Pipeline config + GC state
+-- scan/                      # Scanner output
|   +-- scan-report.md
+-- diagnosis/                 # Diagnostician output
|   +-- diagnosis-report.md
+-- optimization/              # Optimizer output
|   +-- fix-log.md
+-- verification/              # Verifier output
|   +-- verify-report.md
+-- evidence/                  # Screenshots (before/after)
|   +-- *.png
+-- wisdom/                    # Cross-task knowledge

Error Handling

Analyze Task

Parse user task -> detect polish scope -> determine pipeline mode -> estimate complexity.

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

Signal Detection

Scope Determination

Dimension Filter (targeted mode only)

When targeted mode detected, extract which dimensions to focus on:

Target Detection

Complexity Scoring

Results: 1-2 Low (scan-only), 3-4 Medium (targeted), 5+ High (full)

Output

Write scope context to coordinator memory:

{
  "pipeline_mode": "<scan-only|targeted|full>",
  "target": "<url|component-path|full_site>",
  "target_type": "<url|component|directory|full_site>",
  "dimension_filters": ["<dimension-names or empty for all>"],
  "complexity": { "score": 0, "level": "Low|Medium|High" }
}

Command: Dispatch

Create the UI polish task chain with correct dependencies and structured task descriptions. Supports scan-only, targeted, and full pipeline modes.

Phase 2: Context Loading

1. Load user requirement and polish scope from session context 2. Load pipeline stage definitions from specs/pipelines.md 3. Read pipeline_mode, target, and dimension_filters from session context

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|component-path|full_site>
  - Dimension filters: <all | specific dimensions>
  - Upstream artifacts: <artifact-1>, <artifact-2>
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <deliverable path> + <quality criteria>
CONSTRAINTS: <scope limits, focus areas>"
})
TaskUpdate({ taskId: "<TASK-ID>", addBlockedBy: [<dependency-list>], owner: "<role>" })

Mode Router

---

Scan-Only Pipeline Task Chain

SCAN-001 (scanner):

TaskCreate({
  subject: "SCAN-001",
  description: "PURPOSE: Scan UI against Impeccable's 8 audit dimensions to discover all design problems | Success: Complete scan report with per-dimension scores and issue inventory
TASK:
  - Load target files or take screenshots via Chrome DevTools
  - Extract color values, font definitions, spacing values, animation declarations
  - Score all 8 dimensions: anti-patterns, color, typography, spacing, motion, interaction, hierarchy, responsive
  - Generate issue inventory with file:line locations and severity
CONTEXT:
  - Session: <session-folder>
  - Target: <target>
  - Dimension filters: all
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/scan/scan-report.md | 8-dimension scored report with issue inventory
CONSTRAINTS: Read-only analysis | Reference specs/anti-patterns.md and specs/design-standards.md"
})
TaskUpdate({ taskId: "SCAN-001", owner: "scanner" })

DIAG-001 (diagnostician):

TaskCreate({
  subject: "DIAG-001",
  description: "PURPOSE: Deep-dive root cause analysis of scan findings, classify severity, group systemic vs one-off | Success: Prioritized diagnosis with fix dependency graph
TASK:
  - Read scan report and classify each issue as systemic or one-off
  - Group issues by root cause
  - Build fix dependency graph (which fixes must come first)
  - Prioritize by severity (P0 -> P1 -> P2 -> P3)
CONTEXT:
  - Session: <session-folder>
  - Upstream artifacts: scan/scan-report.md
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/diagnosis/diagnosis-report.md | Root cause groups with fix strategies and dependency graph
CONSTRAINTS: Read-only analysis | Reference specs/fix-strategies.md"
})
TaskUpdate({ taskId: "DIAG-001", addBlockedBy: ["SCAN-001"], owner: "diagnostician" })

---

Targeted Pipeline Task Chain

Same as scan-only SCAN-001 and DIAG-001, plus:

Note: For targeted mode, SCAN-001 description adds dimension filter:

  - Dimension filters: <specific dimensions from analyze output>

OPT-001 (optimizer):

TaskCreate({
  subject: "OPT-001",
  description: "PURPOSE: Apply targeted fixes for specified dimensions following Impeccable design standards | Success: All P0/P1 issues in targeted dimensions resolved
TASK:
  - Read diagnosis report for prioritized fix plan
  - Apply fixes in dependency order (systemic first, then one-off)
  - Follow Impeccable fix strategies per dimension
  - Self-validate: no regressions, code compiles/lints
CONTEXT:
  - Session: <session-folder>
  - Dimension filters: <targeted dimensions>
  - Upstream artifacts: scan/scan-report.md, diagnosis/diagnosis-report.md
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: Modified source files + <session>/optimization/fix-log.md | Each fix documented with before/after
CONSTRAINTS: Only fix targeted dimensions | Reference specs/fix-strategies.md and specs/design-standards.md"
})
TaskUpdate({ taskId: "OPT-001", addBlockedBy: ["DIAG-001"], owner: "optimizer" })

VERIFY-001 (verifier):

TaskCreate({
  subject: "VERIFY-001",
  description: "PURPOSE: Verify fixes improved scores without introducing regressions | Success: Score improved or maintained in all dimensions, zero regressions
TASK:
  - Re-scan fixed code against same 8 dimensions
  - Calculate before/after score delta per dimension
  - Check for regressions (new issues introduced by fixes)
  - Take after screenshots if Chrome DevTools available
CONTEXT:
  - Session: <session-folder>
  - Upstream artifacts: scan/scan-report.md, optimization/fix-log.md
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/verification/verify-report.md | Before/after comparison with regression check
CONSTRAINTS: Read-only verification | Signal fix_required if regressions found"
})
TaskUpdate({ taskId: "VERIFY-001", addBlockedBy: ["OPT-001"], owner: "verifier" })

---

Full Pipeline Task Chain

Same as targeted pipeline. The difference is in GC loop behavior:

• When VERIFY-001 reports fix_required, coordinator creates OPT-fix task (see monitor.md)
• Full mode enables GC loop; targeted mode does not create GC fix tasks

---

GC Fix Task Template (created by monitor.md when verify fails)

TaskCreate({
  subject: "OPT-fix-<round>",
  description: "PURPOSE: Address verification regressions from round <round> | Success: All regressions resolved, no new issues
TASK:
  - Parse verification feedback for specific regressions
  - Apply targeted fixes for regression issues only
  - Self-validate before reporting
CONTEXT:
  - Session: <session-folder>
  - Upstream artifacts: verification/verify-report.md, optimization/fix-log.md
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: Updated source files + appended <session>/optimization/fix-log.md
CONSTRAINTS: Fix regressions only, do not expand scope"
})
TaskUpdate({ taskId: "OPT-fix-<round>", owner: "optimizer" })

Then create new VERIFY task blocked by OPT-fix.

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. GC Checkpoint handling (VERIFY task completed): Read verify signal from message: verify_passed, verify_failed, or fix_required

GC Fix Task Creation:

   TaskCreate({ subject: "OPT-fix-<round>",
     description: "PURPOSE: Address verification regressions | Success: All regressions resolved
   TASK:
     - Parse verification feedback for specific regressions
     - Apply targeted fixes for regression issues only
   CONTEXT:
     - Session: <session-folder>
     - Upstream artifacts: verification/verify-report.md" })
   TaskUpdate({ taskId: "OPT-fix-<round>", owner: "optimizer" })

Then create new VERIFY task blocked by OPT-fix. Increment gc_state.round.

GC Escalation Options (when max rounds exceeded): 1. Accept current state - skip further fixes, complete pipeline 2. Try one more round 3. Terminate

6. -> 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]  SCAN-001     (scanner)        -> scan-report.md
  [DONE]  DIAG-001     (diagnostician)  -> diagnosis-report.md
  [RUN]   OPT-001      (optimizer)      -> applying fixes...
  [WAIT]  VERIFY-001   (verifier)       -> blocked by OPT-001

GC Rounds: 0/2
Score: <before-score>/32 -> pending
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: "ui-polish",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <project>/.claude/skills/team-ui-polish/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: ui-polish
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).`
})

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 < 5 -> generate dynamic role spec 4. Create new task, spawn worker 5. Role count >= 5 -> 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

UI Polish Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Manages linear task chains (scan -> diagnose -> optimize -> verify) with optimizer<->verifier GC loops.

Identity

• Name: coordinator | Tag: [coordinator]
• Responsibility: Analyze task -> 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
• Monitor worker progress via message bus and route messages
• Handle Generator-Critic loops (optimizer<->verifier) with max 2 iterations
• Maintain session state persistence

MUST NOT

• Implement domain logic (scanning, diagnosing, optimizing, verifying) -- workers handle this
• Spawn workers without creating tasks first
• Force-advance pipeline past failed verification
• 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/UIP-*/.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 polish scope:

3. Ask for missing parameters if scope unclear:

   AskUserQuestion({
     questions: [
       { question: "What should I polish?", header: "Target", options: [
         { label: "URL", description: "Live page URL for Chrome DevTools analysis" },
         { label: "Component path", description: "Specific component files to polish" },
         { label: "Full site", description: "Scan and polish entire frontend" }
       ]},
       { question: "Polish mode?", header: "Mode", options: [
         { label: "Scan only", description: "Discover + diagnose, report only" },
         { label: "Targeted fix", description: "Fix specific dimensions" },
         { label: "Full polish", description: "Complete polish cycle" }
       ]}
     ]
   })

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

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-ui-polish

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

   .workflow/.team/UIP-<slug>-<date>/scan/
   .workflow/.team/UIP-<slug>-<date>/diagnosis/
   .workflow/.team/UIP-<slug>-<date>/optimization/
   .workflow/.team/UIP-<slug>-<date>/verification/
   .workflow/.team/UIP-<slug>-<date>/evidence/
   .workflow/.team/UIP-<slug>-<date>/wisdom/
   .workflow/.team/UIP-<slug>-<date>/.msg/

4. Initialize .msg/meta.json via team_msg state_update with pipeline metadata 5. TeamCreate(team_name="ui-polish") 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

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

• issues_found: total from scan report
• issues_fixed: total from optimization log
• issues_remaining: issues_found - issues_fixed + regressions
• before_score: original scan score (out of 32)
• after_score: verification re-scan score (out of 32)
• gc_rounds: number of optimizer<->verifier iterations

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

Root Cause Diagnostician

Deep-dive root cause analysis of discovered design problems. Classify severity, group systemic vs one-off issues, build fix dependency graph, and map each issue group to Impeccable fix strategies.

Phase 2: Context & Artifact Loading

1. Extract session path from task description 2. Read scan report: parse per-dimension scores, issue inventory, systemic patterns 3. Read specs/fix-strategies.md for issue-to-fix mapping 4. Read specs/design-standards.md for target state reference

Phase 3: Root Cause Analysis

Step 1: Issue Classification

For each issue in the scan report, classify:

Step 2: Root Cause Grouping

Group issues by shared root cause. Common root cause patterns:

Step 3: Priority Assignment

For each root cause group:

Step 4: Fix Strategy Mapping

For each root cause group, map to Impeccable fix strategy (from specs/fix-strategies.md):

Step 5: Fix Dependency Graph

Build ordered dependency graph:

1. Design token system (if missing) -- everything else depends on this
2. Color fixes (pure black/white, contrast) -- visual foundation
3. Typography system -- content hierarchy
4. Spacing scale -- layout foundation
5. Anti-AI-slop cleanup -- requires tokens, colors, type to be in place
6. Motion system -- independent
7. Interaction states -- independent per component
8. Visual hierarchy -- requires typography + spacing
9. Responsive fixes -- last, tests everything together

Rules:

• Token system MUST come before individual token consumption fixes
• Color fixes before anti-slop (anti-slop fixes may adjust colors)
• Typography before hierarchy (hierarchy depends on type scale)
• Responsive fixes last (they validate all other fixes at different viewports)

Phase 4: Validate Diagnosis Completeness

Output: <session>/diagnosis/diagnosis-report.md

Report structure:

# Diagnosis Report

## Summary
- Total issues: N (P0: X, P1: X, P2: X, P3: X)
- Root cause groups: N
- Systemic issues: N
- One-off issues: N
- Estimated effort: <low|medium|high>

## Root Cause Groups (by priority)

### [P0] <Root Cause Name>
- **Type**: systemic | one-off
- **Affected issues**: <count>
- **Affected files**: <file list>
- **Description**: <what is fundamentally wrong>
- **Fix strategy**: <from fix-strategies.md>
- **Effort**: <quick fix | medium | systemic change>
- **Dependencies**: <which other fixes must come first>
- **Issues in this group**:
  | # | Location | Severity | Description |
  |---|----------|----------|-------------|
  | 1 | file:line | P0 | ... |

### [P1] <Root Cause Name>
...

## Fix Dependency Graph
<ordered list of fix phases>

## Recommended Fix Order
1. <fix phase 1>: <root cause groups to address>
2. <fix phase 2>: <root cause groups to address>
...

## Metadata
- Source: <session>/scan/scan-report.md
- Original score: X/32
- Timestamp: <ISO timestamp>

After writing the report, send completion message:

mcp__ccw-tools__team_msg(session_id, role="diagnostician", type="diag_complete", content="Diagnosis complete. Root cause groups: N. Systemic: N. Fix phases: N.")
SendMessage(participant="coordinator", message="[diagnostician] DIAG-001 complete. Root cause groups: N (P0: X, P1: X, P2: X, P3: X). Systemic: N, One-off: N. Report: <session>/diagnosis/diagnosis-report.md")

UI Optimizer -- Targeted Fix Application

Apply targeted fixes following Impeccable design standards. Consumes diagnosis report and applies fixes in dependency order. Acts as Generator in the optimizer<->verifier Generator-Critic loop.

Phase 2: Context & Artifact Loading

1. Extract session path from task description 2. Read diagnosis report: parse root cause groups, fix dependency graph, recommended fix order 3. Read scan report: parse positive findings (things to preserve) 4. Read specs/fix-strategies.md and specs/design-standards.md for fix reference 5. Detect task type from subject: "OPT-001" -> initial optimization, "OPT-fix-*" -> GC fix round 6. If GC fix task: read verification feedback for specific regressions to fix

Phase 3: Apply Fixes

Follow the fix dependency graph from diagnosis report. Apply fixes in order, one category at a time. After each category, self-validate before proceeding.

CRITICAL: Preserve positive findings from scan report. Do not break what already works.

---

Fix Category 1: Anti-AI-Slop Fixes

Target: Root cause groups tagged with anti-patterns dimension.

---

Fix Category 2: Color Fixes

Target: Root cause groups tagged with color dimension.

---

Fix Category 3: Typography Fixes

Target: Root cause groups tagged with typography dimension.

---

Fix Category 4: Spacing & Layout Fixes

Target: Root cause groups tagged with spacing dimension.

---

Fix Category 5: Motion Fixes

Target: Root cause groups tagged with motion dimension.

---

Fix Category 6: Interaction State Fixes

Target: Root cause groups tagged with interaction dimension.

---

Fix Category 7: Visual Hierarchy Fixes

Target: Root cause groups tagged with hierarchy dimension.

---

Fix Category 8: Responsive Fixes

Target: Root cause groups tagged with responsive dimension.

---

Phase 4: Self-Validation & Output

1. After all fixes applied, validate:

2. Write fix log: <session>/optimization/fix-log.md

# Optimization Fix Log

## Summary
- Fixes applied: N
- Files modified: N
- Categories addressed: <list>
- GC round: <1 | fix-N>

## Fixes Applied

### Category: <category name>
| # | File | Line | Before | After | Issue Ref |
|---|------|------|--------|-------|-----------|
| 1 | path/to/file.css | 42 | `color: #000` | `color: oklch(0.15 0.01 250)` | P1-Color-3 |

### Category: <next category>
...

## Files Modified
- `path/to/file.css`: <summary of changes>
- `path/to/file.tsx`: <summary of changes>

## Preserved (not modified)
- <positive findings that were intentionally kept>

## Metadata
- Source diagnosis: <session>/diagnosis/diagnosis-report.md
- Timestamp: <ISO timestamp>

3. Send completion message:

mcp__ccw-tools__team_msg(session_id, role="optimizer", type="opt_complete", content="Optimization complete. Fixes applied: N. Files modified: N. Categories: <list>.")
SendMessage(participant="coordinator", message="[optimizer] OPT-001 complete. Applied N fixes across N files. Categories: <list>. Log: <session>/optimization/fix-log.md")

UI Scanner -- 8-Dimension Design Audit

Scan existing UI against Impeccable's 8 audit dimensions to discover all design problems. This is the team's core diagnostic engine. Every issue found here drives the entire downstream pipeline.

Phase 2: Context & Artifact Loading

1. Extract session path and target from task description 2. Read specs/anti-patterns.md and specs/design-standards.md for reference criteria 3. Load target files based on target type:

• URL target: Use Chrome DevTools to navigate, take screenshots at 3 viewports:
• Mobile: mcp__chrome-devtools__resize_page(width=375, height=812) + screenshot
• Tablet: mcp__chrome-devtools__resize_page(width=768, height=1024) + screenshot
• Desktop: mcp__chrome-devtools__resize_page(width=1440, height=900) + screenshot
• Save to <session>/evidence/before-mobile.png, before-tablet.png, before-desktop.png
• Component target: Read CSS/SCSS, HTML, JS/TS/JSX/TSX files
• Full site target: Glob for all frontend source files (.css, .scss, .tsx, .jsx, .html, .vue, *.svelte)

4. Extract raw data for analysis:

• All color values (hex, rgb, hsl, oklch, named colors, CSS custom properties)
• All font declarations (font-family, font-size, font-weight, line-height)
• All spacing values (margin, padding, gap, inset)
• All animation/transition declarations
• All interactive pseudo-classes and state handling

5. If Chrome DevTools available: extract computed styles via mcp__chrome-devtools__evaluate_script

Phase 3: 8-Dimension Scan

For each dimension, check every item in the checklist. Record each finding with:

• Location: file:line (or "screenshot: viewport" for visual-only issues)
• Severity: P0 (blocking) / P1 (major) / P2 (minor) / P3 (polish)
• Description: what is wrong and why it matters
• Evidence: the specific code or visual that triggers the finding

---

Dimension 1: Anti-AI-Slop Detection (CRITICAL -- scan first)

The AI Slop Test: "If you showed this to someone and said 'AI made this,' would they believe you immediately? If yes, that is the problem."

Check for these AI-generated UI fingerprints:

Scoring:

• 0: AI slop gallery (5+ tells present)
• 1: Heavy AI influence (3-4 tells)
• 2: Some AI tells (1-2 noticeable)
• 3: Mostly clean (subtle traces only)
• 4: Distinctive (genuinely intentional design, zero AI tells)

---

Dimension 2: Color Quality

Scoring:

• 0: Multiple contrast failures, pure black/white everywhere, no system
• 1: Contrast issues, hard-coded colors, no tokens
• 2: Basic contrast OK but no OKLCH, some hard-coded values
• 3: Good system with minor gaps (some untinted grays or missing tokens)
• 4: OKLCH-based, fully tokenized, WCAG AA+ compliant, proper 60-30-10

---

Dimension 3: Typography Quality

Scoring:

• 0: Generic font, no scale, tiny text, no hierarchy
• 1: Overused font, muddy sizes, missing fluid sizing
• 2: Decent font choice but inconsistent scale or line-height
• 3: Good typography with minor gaps (missing clamp, slight inconsistencies)
• 4: Distinctive font, clear modular scale, fluid sizing, proper rhythm

---

Dimension 4: Spacing & Layout Quality

Scoring:

• 0: Random spacing, nested cards, fixed widths, tiny touch targets
• 1: Some system but many arbitrary values, cards overused
• 2: Decent spacing but monotonous or missing rhythm
• 3: Good system with minor gaps (occasional arbitrary value)
• 4: Consistent scale, varied rhythm, gap usage, proper touch targets

---

Dimension 5: Motion & Animation Quality

Scoring:

• 0: Layout animations, no reduced-motion, bounce easing, no system
• 1: Some transform-based but bad easing, missing reduced-motion
• 2: Decent animations but no token system or missing reduced-motion
• 3: Good system with minor gaps (occasional bad easing, missing exit animation)
• 4: Transform+opacity only, exponential easing, reduced-motion, token system, proper stagger

---

Dimension 6: Interaction States

Scoring:

• 0: No hover, no focus, outline:none everywhere, no loading states
• 1: Basic hover but missing focus/active, no loading states
• 2: Hover + focus exist but no focus-visible, missing some states
• 3: Most states present with minor gaps (missing empty state, imperfect focus ring)
• 4: All 8 states implemented, focus-visible, proper focus ring, loading/error/success/empty

---

Dimension 7: Visual Hierarchy

Scoring:

• 0: Everything same visual weight, no clear action, fails squint test
• 1: Some size differences but no clear hierarchy system
• 2: Basic hierarchy via size but missing weight/color/space dimensions
• 3: Good hierarchy with minor issues (occasional visual competition)
• 4: Clear squint test pass, obvious primary action, multi-dimension hierarchy, progressive disclosure

---

Dimension 8: Responsive Design

Scoring:

• 0: No responsive design, horizontal scroll, broken on mobile
• 1: Basic media queries but many breakage points
• 2: Decent mobile but some fixed widths or small targets
• 3: Good responsive with minor issues (missing container queries, occasional small target)
• 4: Fluid design, proper breakpoints, container queries, 44px targets, no overflow

---

Dimension 9: Cognitive Load

Evaluate information processing burden per Impeccable's cognitive load principles.

Dimension 10: Dark Mode Quality

Only score if dark mode exists. Skip and note "N/A — no dark mode" if not present.

---

Phase 4: Generate Scan Report

Output: <session>/scan/scan-report.md

Report structure:

# UI Polish Scan Report

## Overall Score: X/36 (<rating-band>)

## Anti-Patterns Verdict (Dimension 1)
Score: X/4
<verdict summary -- this section comes FIRST as it is most important>
<list of detected AI slop tells>

## Per-Dimension Scores

| Dimension | Score | Key Finding |
|-----------|-------|-------------|
| 1. Anti-Patterns | X/4 | <one-line summary> |
| 2. Color Quality | X/4 | <one-line summary> |
| 3. Typography | X/4 | <one-line summary> |
| 4. Spacing/Layout | X/4 | <one-line summary> |
| 5. Motion | X/4 | <one-line summary> |
| 6. Interaction States | X/4 | <one-line summary> |
| 7. Visual Hierarchy | X/4 | <one-line summary> |
| 8. Responsive | X/4 | <one-line summary> |
| 9. Cognitive Load | X/4 | <one-line summary> |
| 10. Dark Mode | X/4 or N/A | <one-line summary> |

## Issue Inventory

### P0 -- Blocking
| # | Dimension | Location | Description |
|---|-----------|----------|-------------|
| 1 | ... | file:line | ... |

### P1 -- Major
...

### P2 -- Minor
...

### P3 -- Polish
...

## Patterns & Systemic Issues
<recurring problems that affect multiple locations>

## Positive Findings
<what works well -- important for optimizer to not break>

## Scan Metadata
- Target: <target>
- Files scanned: <count>
- Screenshots: <yes/no, viewports>
- Timestamp: <ISO timestamp>

Rating Bands (total out of 36, or 40 with dark mode):

• 32-36: Excellent (36-40 with dark mode)
• 25-31: Good (29-35 with dark mode)
• 18-24: Acceptable (22-28 with dark mode)
• 11-17: Poor (15-21 with dark mode)
• 0-10: Critical (0-14 with dark mode)

After writing the report, send completion message:

mcp__ccw-tools__team_msg(session_id, role="scanner", type="scan_complete", content="Scan complete. Score: X/36. P0: N, P1: N, P2: N, P3: N issues found.")
SendMessage(participant="coordinator", message="[scanner] SCAN-001 complete. Score: X/36 (<rating-band>). Issues: P0=N P1=N P2=N P3=N. Report: <session>/scan/scan-report.md")

Verification & Regression Check

Before/after comparison verification. Re-scan fixed code against same 8 dimensions, calculate improvement, detect regressions. Acts as Critic in the optimizer<->verifier Generator-Critic loop.

Phase 2: Context & Artifact Loading

1. Extract session path from task description 2. Read original scan report: parse before-scores per dimension and issue inventory 3. Read fix log: parse all fixes applied and files modified 4. Read specs for scoring reference

Phase 3: Verification

Step 1: Re-scan Fixed Code

Apply the same 8-dimension scan as the scanner role (reference roles/scanner/role.md Phase 3) to the current state of files. Use identical checklist items and scoring criteria.

If Chrome DevTools available:

• Take screenshots at same 3 viewports (mobile 375px, tablet 768px, desktop 1440px)
• Save to <session>/evidence/after-mobile.png, after-tablet.png, after-desktop.png

Step 2: Calculate Score Delta

For each dimension, compare before and after:

Step 3: Regression Detection

Check for NEW issues not present in original scan report:

Classify regressions:

• Critical: Score dropped in any dimension, WCAG AA violation introduced, build broken
• Non-critical: New minor issues introduced but overall score improved

Step 4: Determine Signal

Phase 4: Generate Verification Report

Output: <session>/verification/verify-report.md

# Verification Report

## Verdict: <PASSED | FAILED | FIX REQUIRED>

## Score Comparison

| Dimension | Before | After | Delta |
|-----------|--------|-------|-------|
| 1. Anti-Patterns | X/4 | Y/4 | +N |
| 2. Color Quality | X/4 | Y/4 | +N |
| 3. Typography | X/4 | Y/4 | +N |
| 4. Spacing/Layout | X/4 | Y/4 | +N |
| 5. Motion | X/4 | Y/4 | +N |
| 6. Interaction States | X/4 | Y/4 | +N |
| 7. Visual Hierarchy | X/4 | Y/4 | +N |
| 8. Responsive | X/4 | Y/4 | +N |
| **Total** | **X/32** | **Y/32** | **+N** |

## Before Rating: <rating-band> -> After Rating: <rating-band>

## Regressions Found
<list of regressions with location, severity, description>
<or "None" if clean>

## Remaining Issues
<issues from original scan that were NOT fixed>

## Improvements
<per-dimension improvement details>

## Screenshots
- Before: <session>/evidence/before-*.png
- After: <session>/evidence/after-*.png
<or "Chrome DevTools not available" if no screenshots>

## Metadata
- Original scan: <session>/scan/scan-report.md
- Fix log: <session>/optimization/fix-log.md
- GC round: <round number>
- Timestamp: <ISO timestamp>

After writing the report, send signal-appropriate message:

If verify_passed:

mcp__ccw-tools__team_msg(session_id, role="verifier", type="verify_passed", content="Verification passed. Score: before X/32 -> after Y/32 (+N). No regressions.")
SendMessage(participant="coordinator", message="[verifier] VERIFY-001 passed. Score: X/32 -> Y/32 (+N). No regressions. Report: <session>/verification/verify-report.md")

If verify_failed:

mcp__ccw-tools__team_msg(session_id, role="verifier", type="verify_failed", content="Verification failed. N non-critical regressions found. Score: X/32 -> Y/32.")
SendMessage(participant="coordinator", message="[verifier] VERIFY-001 failed. N regressions (non-critical). Score: X/32 -> Y/32. Report: <session>/verification/verify-report.md")

If fix_required:

mcp__ccw-tools__team_msg(session_id, role="verifier", type="fix_required", content="Fix required. N critical regressions. Score dropped: X/32 -> Y/32.")
SendMessage(participant="coordinator", message="[verifier] VERIFY-001 fix_required. N critical regressions. Score: X/32 -> Y/32 (DROPPED). Report: <session>/verification/verify-report.md")

Anti-Pattern Catalog

Complete catalog of UI design anti-patterns from Impeccable's design audit knowledge. Used by scanner for detection and optimizer for remediation.

The AI Slop Test

"If you showed this to someone and said 'AI made this,' would they believe you immediately? If yes, that is the problem."

AI-generated UIs share recognizable fingerprints. These are not inherently bad techniques -- they become problems when used as defaults without intentional design decisions. The issue is not the technique itself but the lack of thought behind it.

AI Slop Tells (20 Items)

1. AI Color Palette

Pattern: Cyan-on-dark (#00d4ff, #06b6d4), purple-to-blue gradients (#8b5cf6 to #3b82f6), neon accents on dark backgrounds. Why it is a tell: Every AI model defaults to the same "futuristic" palette. It signals zero design intent. Detection: Search for cyan/purple/neon values on dark backgrounds. Check if palette could be from any Tailwind dark template. Severity: P1

2. Gradient Text for Impact

Pattern: background-clip: text + gradient applied to metrics, headings, or hero text. Why it is a tell: AI uses gradient text as a crutch to make numbers and titles feel "premium." Real typography achieves emphasis through weight, size, and space. Detection: Search for background-clip: text or -webkit-background-clip: text. Severity: P1

3. Default Dark Mode with Glowing Accents

Pattern: Dark background (gray-900/950) as default with glowing/neon accent colors. No light mode offered or light mode is an afterthought. Why it is a tell: Dark mode with glow effects requires no real color decisions. It hides contrast problems and creates false sophistication. Detection: Check default theme. If dark with glow box-shadow or neon colors, flag it. Severity: P2

4. Glassmorphism Everywhere

Pattern: backdrop-filter: blur(), glass cards, glow borders (box-shadow: 0 0 Xpx <color>), used decoratively on multiple components. Why it is a tell: Glassmorphism is a valid technique for specific use cases (overlays, elevated surfaces). AI applies it everywhere as the default "modern" aesthetic. Detection: Count instances of backdrop-filter: blur. If > 2 components use it without functional reason, flag. Severity: P1

5. Hero Metric Layout

Pattern: Big number (32-48px) + small label underneath + supporting stats in a row + gradient accent or colored bar. Why it is a tell: This is the universal "AI dashboard" template. Every AI-generated analytics page uses this exact layout. Detection: Pattern match for large-number + small-label structures repeated in a metrics row/grid. Severity: P2

6. Identical Card Grids

Pattern: Same-sized cards with icon + heading + body text repeated 3-6 times in a grid. Equal width, equal height, equal spacing. Why it is a tell: Real content varies in importance. AI treats all items as equally important because it has no content strategy. Detection: Grid of 3+ cards with identical structure and sizing. No featured/hero card. Severity: P2

7. Nested Cards

Pattern: Cards inside cards. .card > .card-body > .inner-card. Multiple layers of bordered containers. Why it is a tell: AI nests containers to create visual "depth." It actually creates noise and makes hierarchy unclear. Detection: Search for elements with border/shadow inside elements with border/shadow. Two levels of containment. Severity: P2

8. Generic Fonts

Pattern: Inter, Roboto, Arial, Open Sans, Lato, Montserrat, system-ui used as primary font without intentional choice. Why it is a tell: These are defaults. AI picks them because they are safe. Safe means forgettable. Detection: Check font-family declarations. If primary font is in the generic list, flag. Severity: P2

9. Rounded Rectangles with Generic Drop Shadows

Pattern: border-radius: 8-16px combined with box-shadow: 0 1-4px 6-24px rgba(0,0,0,0.05-0.15) on every container. Why it is a tell: The "safe shape." Every AI output uses this exact combination because it is never wrong -- but never distinctive either. Detection: Count elements with both border-radius (8-16px range) and generic box-shadow. If > 5, flag. Severity: P3

10. Large Icons Above Every Heading

Pattern: 24-48px icons with rounded corners or colored backgrounds placed above every heading or card title. Why it is a tell: AI uses icons as visual filler. Real design uses icons sparingly where they aid comprehension. Detection: Pattern match for icon elements directly above heading elements. If repeated 3+ times, flag. Severity: P2

11. One-Side Border Accent

Pattern: border-left: 3-4px solid <accent-color> or border-top used as the primary accent technique on cards/containers. Why it is a tell: Lazy accent. It is a shortcut to add "personality" without making real design decisions. Detection: Search for border-left: [2-5]px solid or border-top: [2-5]px solid with accent colors. Severity: P3

12. Decorative Sparklines

Pattern: Tiny charts, mini-graphs, or trend indicators that look sophisticated but convey no actionable data. Often in card corners. Why it is a tell: AI adds charts to appear data-driven. If the chart has no axis labels, no values, and no interaction, it is decoration. Detection: Small SVG/canvas charts (<100px) without labels, tooltips, or legends. Severity: P2

13. Bounce/Elastic Easing

Pattern: cubic-bezier(0.68, -0.55, 0.265, 1.55), spring animations, or any easing that overshoots. Why it is a tell: Bounce easing was trendy circa 2015. AI still defaults to it for "playfulness." It feels dated and tacky in modern UI. Detection: Search for cubic-bezier with negative values or spring keyword. Severity: P2

14. Redundant Copy

Pattern: Intro paragraphs that restate the heading. "Welcome to your Dashboard. This is your dashboard where you can see..." Why it is a tell: AI generates text to fill space. Real UX uses headings as the message and body for additional context only. Detection: Compare heading text with first paragraph. If >50% word overlap, flag. Severity: P3

15. All Buttons Primary

Pattern: Every button is filled/primary color. No ghost buttons, text links, outline buttons, or secondary variants. Why it is a tell: AI makes everything important. Real design creates hierarchy: 1 primary, 1-2 secondary, rest tertiary. Detection: Check button variants. If all buttons have same fill/color treatment, flag. Severity: P1

16. Everything Centered

Pattern: text-align: center or justify-content: center / align-items: center on most content blocks including body text. Why it is a tell: Centering is the safe choice. Real design uses left-alignment for readability, centering only for specific elements (headings, hero). Detection: Count centered text blocks. If body text is centered, flag. If > 60% of content sections are centered, flag. Severity: P2

17. Same Spacing Everywhere

Pattern: Identical padding/margin on all cards, sections, and components. No variation in spacing rhythm. Why it is a tell: AI applies uniform spacing because it has no sense of content grouping or visual rhythm. Detection: Extract all padding/margin values. If > 70% are the same value, flag. Severity: P2

18. Monospace as Tech Aesthetic

Pattern: Monospace font (Fira Code, JetBrains Mono, Source Code Pro) used for non-code content to appear "techy." Why it is a tell: AI equates monospace with "developer tool" aesthetic. Real design uses monospace only for actual code. Detection: Monospace font-family on non-<code>, non-<pre> elements. Severity: P3

19. Modal Overuse

Pattern: Modals for confirmations, settings changes, form entries, when inline editing, drawers, or expandable sections would work. Why it is a tell: Modals are AI's default "interaction" pattern because they are self-contained. Real UX considers context loss and flow interruption. Detection: Count modal/dialog components. If > 3 modals for non-critical actions, flag. Severity: P3

20. Pure Black or Pure White

Pattern: #000000 or #ffffff used as primary background/text colors without any tint. Why it is a tell: Pure black and white create harsh contrast and feel sterile. Real design tints toward a brand hue. Detection: Search for #000, #000000, rgb(0,0,0), #fff, #ffffff, rgb(255,255,255) in styles. Severity: P1

Scoring Guide

Design Standards

Impeccable's positive design standards. These are the target state -- what good looks like. Used by scanner for scoring (how close to ideal) and optimizer as fix targets.

---

Color

Principles

• Use OKLCH for perceptually uniform palettes. Colors at the same lightness actually look the same lightness
• Tint neutrals toward brand hue (chroma 0.005-0.01). Never pure gray
• 60-30-10 rule: 60% neutral, 30% secondary/supporting, 10% accent
• Semantic token hierarchy: primitive -> semantic -> component tokens
• Never pure black (#000) or pure white (#fff). Always tint

Color Token Structure

--color-primary          oklch(0.55 0.2 250)
--color-primary-hover    oklch(0.50 0.22 250)
--color-primary-active   oklch(0.45 0.22 250)

--color-neutral-50       oklch(0.98 0.005 250)    /* near-white, brand tinted */
--color-neutral-100      oklch(0.95 0.005 250)
--color-neutral-200      oklch(0.90 0.007 250)
--color-neutral-300      oklch(0.80 0.007 250)
--color-neutral-400      oklch(0.65 0.008 250)
--color-neutral-500      oklch(0.50 0.008 250)
--color-neutral-600      oklch(0.40 0.008 250)
--color-neutral-700      oklch(0.30 0.008 250)
--color-neutral-800      oklch(0.20 0.010 250)
--color-neutral-900      oklch(0.13 0.010 250)
--color-neutral-950      oklch(0.08 0.010 250)    /* near-black, brand tinted */

--color-success          oklch(0.65 0.18 145)
--color-warning          oklch(0.75 0.15 85)
--color-error            oklch(0.55 0.22 25)
--color-info             oklch(0.60 0.15 250)

--color-surface          var(--color-neutral-50)
--color-surface-raised   var(--color-neutral-100)
--color-surface-overlay  var(--color-neutral-900 / 0.5)

--color-text-primary     var(--color-neutral-900)
--color-text-secondary   var(--color-neutral-600)
--color-text-muted       var(--color-neutral-400)

Contrast Requirements (WCAG AA)

• Normal text (<18px / <24px bold): 4.5:1 minimum
• Large text (>=18px / >=24px bold): 3:1 minimum
• UI components and graphical objects: 3:1 minimum
• Focus indicators: 3:1 against adjacent colors

Text on Colored Backgrounds

• Never gray text on colored backgrounds (looks washed out)
• Use shade of the background color, or white/dark with transparency
• color-mix(in oklch, var(--bg-color) 30%, black) for text on colored surfaces

---

Typography

Font Selection

Avoid: Inter, Roboto, Open Sans, Lato, Montserrat, Arial (overused defaults).

Recommended alternatives by category:

• Sans-serif body: Instrument Sans, Plus Jakarta Sans, DM Sans, Geist, General Sans
• Sans-serif display: Space Grotesk, Manrope, Outfit, Satoshi, Clash Display
• Serif display: Fraunces, Playfair Display 2, Source Serif 4
• Monospace (code only): Geist Mono, JetBrains Mono, Fira Code

Modular Type Scale

Choose one ratio and apply consistently:

Fluid Sizing

Use clamp() for display text:

--text-xs:   0.75rem;                                    /* 12px, fixed */
--text-sm:   0.875rem;                                   /* 14px, fixed */
--text-base: 1rem;                                       /* 16px, body */
--text-lg:   1.125rem;                                   /* 18px */
--text-xl:   clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem);   /* 20-24px */
--text-2xl:  clamp(1.5rem, 1.2rem + 1vw, 2rem);         /* 24-32px */
--text-3xl:  clamp(1.875rem, 1.4rem + 1.5vw, 2.5rem);   /* 30-40px */
--text-4xl:  clamp(2.25rem, 1.5rem + 2.5vw, 3.5rem);    /* 36-56px */

Line Height & Spacing

• Body text: line-height: 1.5 (24px at 16px base)
• Headings: line-height: 1.2 (tighter)
• Small text / captions: line-height: 1.6
• Reading width: max-width: 65ch (range: 45-75ch)

Loading

• font-display: swap on all custom fonts
• Provide size-adjust, ascent-override, descent-override on fallback for minimal CLS

---

Spacing

4pt Base Scale

--space-0:  0;
--space-1:  0.25rem;   /* 4px */
--space-2:  0.5rem;    /* 8px */
--space-3:  0.75rem;   /* 12px */
--space-4:  1rem;      /* 16px */
--space-5:  1.25rem;   /* 20px */
--space-6:  1.5rem;    /* 24px */
--space-8:  2rem;      /* 32px */
--space-10: 2.5rem;    /* 40px */
--space-12: 3rem;      /* 48px */
--space-16: 4rem;      /* 64px */
--space-24: 6rem;      /* 96px */

Rhythm

• Tight: 4-8px within component groups (e.g., label + input, icon + text)
• Comfortable: 16-24px between related items (e.g., list items, form fields)
• Generous: 48-96px between major sections (e.g., page sections, content blocks)

Monotonous spacing (same value everywhere) = no rhythm = boring. Vary spacing intentionally.

Layout Principles

• Use gap instead of margin for sibling spacing
• Cards only when content is truly distinct and actionable. Not everything needs a card
• Flatten nested cards -- use spacing + subtle dividers instead
• Container queries (@container) for component-level responsive
• Touch targets: minimum 44x44px for all interactive elements
• Optical adjustments: visually center, not mathematically center (e.g., play button in circle needs right offset)

---

Motion

Property Rules

• Animate ONLY: transform, opacity, clip-path, background-color, color, border-color, box-shadow, filter
• NEVER animate: width, height, top, left, right, bottom, margin, padding (triggers layout)

Easing

• Default (ease-out-quart): cubic-bezier(0.25, 1, 0.5, 1) -- decelerates naturally
• Enter (ease-out): cubic-bezier(0, 0, 0.25, 1) -- elements arrive and settle
• Exit (ease-in): cubic-bezier(0.5, 0, 0.75, 0) -- elements accelerate away
• NEVER: ease (default), linear (mechanical), bounce/elastic (dated)

Duration Scale

--duration-instant:   100ms;   /* tooltip show, ripple */
--duration-fast:      150ms;   /* button hover, focus ring */
--duration-normal:    250ms;   /* dropdown open, tab switch */
--duration-slow:      400ms;   /* modal open, sidebar slide */
--duration-entrance:  500ms;   /* page entrance, hero animation */
--duration-complex:   800ms;   /* complex sequence, page transition */

• Exit = 75% of entrance duration
• Feedback (hover, active, focus): 100-150ms maximum
• State change: 200-300ms
• Layout change: 300-500ms

Stagger

• Max visible items to stagger: 10
• Total stagger duration: max 500ms
• Formula: animation-delay: calc(var(--index) * 50ms)
• Cap: animation-delay: min(calc(var(--index) * 50ms), 500ms)

Reduced Motion

Required -- affects ~35% of adults over 40:

@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;
  }
}

will-change

• Do NOT set in CSS (wastes GPU memory permanently)
• Add via JS on pointerenter / focusin
• Remove on animationend / transitionend

---

Interaction States

The 8 Required States

Every interactive element must define:

Focus Ring Specification

:focus-visible {
  outline: 2px solid var(--color-primary);
  outline-offset: 2px;
  border-radius: inherit;
}

/* Only remove outline for mouse clicks */
:focus:not(:focus-visible) {
  outline: none;
}

Focus ring contrast: 3:1 minimum against all adjacent colors.

Form Labels

• Always provide visible <label> elements
• Placeholders are hints, NOT labels (they disappear)
• Use aria-labelledby or aria-label for icon-only buttons
• Error messages: aria-describedby linking input to error text

Touch Targets

• Minimum: 44x44px (WCAG 2.5.5 AAA) / 24x24px (WCAG 2.5.8 AA minimum)
• Use padding to increase hit area without changing visual size
• Minimum 8px gap between adjacent targets

---

Visual Hierarchy

Squint Test

Blur the page (or squint). You should immediately identify: 1. The most important element (usually primary heading or CTA) 2. The second most important element 3. Clear groupings of related content

If everything looks the same when blurred, hierarchy has failed.

Hierarchy Tools (use 2-3 together)

Primary Action Rule

• Only 1 primary CTA per viewport
• Primary: filled button, highest contrast, most saturated
• Secondary: outline/ghost button
• Tertiary: text link, no background

Progressive Disclosure

• Show summary first, detail on demand
• Expandable sections, "show more," detail panels
• Do not dump all information at once

---

Responsive Design

Breakpoints

/* Mobile first */
--bp-sm:  640px;    /* Small tablets */
--bp-md:  768px;    /* Tablets */
--bp-lg:  1024px;   /* Laptops */
--bp-xl:  1280px;   /* Desktops */
--bp-2xl: 1536px;   /* Large screens */

Fluid Design Principles

• Use %, vw, fr, min(), max(), clamp() instead of fixed px widths
• max-width instead of width for containers
• Grid with fr units for responsive layouts
• Container queries (@container) for component-level responsiveness

Mobile Requirements

• Minimum text: 14px (0.875rem), prefer 16px for body
• Touch targets: 44x44px minimum
• No horizontal scroll at >= 320px viewport
• Must have <meta name="viewport" content="width=device-width, initial-scale=1">
• Images: max-width: 100%; height: auto

Adapt, Don't Hide

• Content should be restructured for smaller screens, not hidden
• Stack horizontal layouts vertically
• Use accordion/tabs for complex content
• Simplify navigation (hamburger, bottom nav)

---

UX Writing

Button Labels

• NEVER: "OK", "Submit", "Yes", "No" (generic)
• ALWAYS: verb + object — "Save changes", "Create account", "Delete message"
• Destructive: name the destruction + count — "Delete 5 items"

Error Messages

Formula: what happened + why + how to fix

• "Password must be 8+ characters with a number" not "Invalid password"
• Never blame user, never use codes alone
• Preserve user input on error

Empty States

Acknowledge + explain value + provide action

• "No projects yet. Create your first project to start collaborating. [Create project]"

Loading Text

• Specific: "Saving your draft..." not "Loading..."
• Multi-step: "Uploading (2 of 5 files)..."

Consistency

• One term per concept (delete/remove → pick one)
• Same icon for same action everywhere

---

Dark Mode (when present)

Rules

• NOT inverted light mode — requires deliberate design
• Surface hierarchy: lighter surfaces = higher elevation
• Base: oklch(0.10-0.15 0.01 <hue>)
• Raised: oklch(0.18-0.22 0.01 <hue>)
• Overlay: oklch(0.24-0.28 0.01 <hue>)
• Font weight: reduce by 1 step (600→500, 500→400) — light text on dark looks heavier
• Accent colors: desaturate — reduce OKLCH chroma by 0.05-0.10 from light theme values
• Never: pure black #000 background

Dangerous Combinations

Fix Strategies

Maps issue categories to Impeccable fix strategies. Used by diagnostician for fix planning and optimizer for implementation guidance.

Strategy Index

---

De-template (Anti-AI-Slop)

When: Anti-patterns dimension score 0-2 (AI slop or heavy AI influence)

Strategy: 1. Replace generic fonts with distinctive alternatives (see design-standards.md Typography) 2. Convert gradient text to solid accent colors with weight/size emphasis instead 3. Break identical card grids: vary sizes, add featured card, introduce asymmetry 4. Remove decorative glassmorphism (keep functional like overlays) 5. Redesign hero metrics with intentional hierarchy, not template layout 6. Flatten nested cards into single-level with spacing 7. Add left-alignment for body text, centering only for specific hero elements 8. Create button hierarchy: 1 primary, ghost secondary, text tertiary 9. Introduce spacing rhythm (tight within groups, generous between sections) 10. Replace bounce easing with exponential curves

Dependency: Requires Colorize and Typeset to be planned (often executed together).

---

Colorize

When: Color dimension score 0-2 or any P0/P1 color issues

Strategy: 1. Token foundation (if no tokens exist):

• Create CSS custom property file with full neutral scale (50-950)
• Define primary, semantic (success/warning/error/info), and surface tokens
• All neutrals tinted toward brand hue (OKLCH chroma 0.005-0.01)

2. Pure black/white removal:

• #000 -> oklch(0.08-0.15 0.01 <hue>) (near-black, brand tinted)
• #fff -> oklch(0.97-0.99 0.005 <hue>) (near-white, brand tinted)

3. Gray tinting:

• Convert all pure grays to brand-tinted variants
• Add chroma 0.005-0.01 at brand hue

4. Contrast fixes:

• Measure each text/background pair
• Adjust lightness until WCAG AA met (4.5:1 normal, 3:1 large)

5. OKLCH conversion:

• Convert key palette colors from hex/hsl to oklch
• Generate tint/shade scales in OKLCH for perceptual uniformity

6. 60-30-10 enforcement:

• Audit accent color usage, reduce to ~10%
• Ensure neutral dominates at ~60%

Dependency: Should run before De-template (anti-slop fixes may need new colors).

---

Typeset

When: Typography dimension score 0-2 or muddy hierarchy

Strategy: 1. Font replacement: Swap generic fonts for distinctive alternatives

• Body: Plus Jakarta Sans, Instrument Sans, DM Sans, Geist
• Display: Space Grotesk, Manrope, Fraunces

2. Scale establishment: Choose modular ratio (1.25 or 1.333 recommended), generate size scale 3. Fluid sizing: Add clamp() for h1-h3 display sizes 4. Line length: Add max-width: 65ch to prose containers 5. Vertical rhythm: Set line-height system (1.5 body, 1.2 headings) 6. Font loading: Add font-display: swap to all @font-face

Dependency: Run before Clarify (hierarchy depends on type scale).

---

Arrange

When: Spacing dimension score 0-2 or arbitrary spacing values

Strategy: 1. Scale creation: Define 4pt base scale as CSS custom properties 2. Value replacement: Map arbitrary values to nearest scale value 3. Rhythm introduction: Tight (4-8px) within groups, comfortable (16-24px) between items, generous (48-96px) between sections 4. Card flattening: Remove nested cards, replace with spacing + subtle dividers 5. Gap conversion: Replace margin between siblings with gap on flex/grid parent 6. Touch targets: Ensure all interactive elements are 44x44px minimum

Dependency: Independent, but benefits from Colorize tokens being in place.

---

Animate

When: Motion dimension score 0-2 or layout property animations

Strategy: 1. Property fix: Replace layout animations (width/height/margin/padding) with transform+opacity 2. Easing fix: Replace ease/linear/bounce with exponential curves 3. Reduced-motion: Add @media (prefers-reduced-motion: reduce) global rule 4. Token system: Create duration + easing custom properties 5. Stagger cap: Cap stagger at 10 items, 500ms total 6. will-change: Remove from CSS, document JS activation pattern

Dependency: Independent.

---

Harden

When: Interaction states dimension score 0-2 or missing critical states

Strategy: 1. Hover: Add :hover with subtle visual change, wrap in @media(hover:hover) 2. Focus: Add :focus-visible with 2px solid accent ring, offset 2px 3. Active: Add :active with scale(0.97) or darker background 4. Disabled: Add [disabled] with opacity 0.5, cursor not-allowed 5. Loading: Add aria-busy pattern with spinner/skeleton 6. Error/Success: Add form validation visual states 7. Focus ring: Ensure 3:1 contrast against all adjacent colors 8. Labels: Replace placeholder-as-label with visible <label> elements 9. Touch targets: Pad interactive elements to 44px minimum

Dependency: Requires Colorize tokens for consistent state colors.

---

Simplify (quieter + distill)

When: Visual noise, too many decorations, competing elements

Strategy: 1. Remove decorative elements that do not aid comprehension 2. Mute icon colors (reduce saturation/opacity) 3. Remove background decorations and unnecessary borders 4. Reduce shadow intensity 5. Simplify card borders (remove or lighten) 6. Remove sparkline decorations without data value

Dependency: Independent.

---

Strengthen (bolder + delight)

When: Too bland, everything same weight, no emphasis

Strategy: 1. Increase primary element size by 1.5-2x 2. Add color saturation to primary CTA 3. Increase weight contrast (bold primary, regular secondary) 4. Add subtle micro-interactions (hover lift, active press) 5. Introduce one distinctive element (asymmetric layout, unexpected color, custom illustration)

Dependency: Requires Typeset and Colorize to be in place.

---

Clarify (hierarchy)

When: Visual hierarchy dimension score 0-2 or fails squint test

Strategy: 1. Identify primary element, increase to 3:1 ratio over body 2. Use 2-3 hierarchy tools together (size + weight + color) 3. Group related content with proximity (smaller gaps within, larger between) 4. Reduce visual weight of competing secondary elements 5. Ensure only 1 primary CTA per viewport 6. Add progressive disclosure where appropriate

Dependency: Requires Typeset (size hierarchy) and Colorize (color hierarchy).

---

Adapt (responsive)

When: Responsive dimension score 0-2 or broken mobile experience

Strategy: 1. Replace fixed widths with fluid (%, vw, fr, min/max/clamp) 2. Add missing breakpoints (640, 768, 1024, 1280px) 3. Fix overflow (horizontal scroll causes) 4. Fix mobile text sizes (minimum 14px) 5. Fix touch targets (minimum 44px) 6. Add container queries for component-level responsive 7. Restructure hidden content (adapt, don't hide) 8. Add viewport meta tag if missing

Dependency: Run last -- tests all other fixes at different viewports.

---

Fix Order (Default)

When applying all strategies in a full polish cycle:

Phase 1: Foundation
  1. Colorize (token system + color fixes)
  2. Typeset (font + scale + fluid sizing)
  3. Arrange (spacing scale + layout)

Phase 2: Aesthetic
  4. De-template (anti-AI-slop cleanup)
  5. Simplify or Strengthen (as needed)

Phase 3: Interaction
  6. Animate (motion system)
  7. Harden (interaction states)

Phase 4: Structure
  8. Clarify (visual hierarchy)

Phase 5: Validation
  9. Adapt (responsive -- tests everything)

Pipeline Definitions

UI polish pipeline modes and task registry.

Pipeline Modes

Scan-Only Pipeline Task Registry

Targeted Pipeline Task Registry

Full Pipeline Task Registry

GC Loop (Full Mode Only)

GC Fix Tasks (dynamically created)

Collaboration Patterns

Spawn Rules

All modes use sequential spawning (one task at a time) since each task depends on the previous.

Output Artifacts

Scoring Guide

How to score each dimension consistently. Used by scanner for initial audit and verifier for re-assessment.

Rating Bands (Total Score out of 36)

Per-Dimension Scoring (0-4)

General Rubric

Dimension 1: Anti-AI-Slop Detection

Dimension 2: Color Quality

Dimension 3: Typography Quality

Dimension 4: Spacing & Layout Quality

Dimension 5: Motion & Animation Quality

Dimension 6: Interaction States

Dimension 7: Visual Hierarchy

Dimension 8: Responsive Design

Dimension 9: Cognitive Load & UX Writing

Dimension 10: Dark Mode Quality (Conditional)

Only scored if dark mode exists. If no dark mode, this dimension is excluded from total.

When dark mode exists: total out of 40, bands shift +4. When no dark mode: total out of 36.

---

Severity Mapping

---

Scoring Process

1. For each dimension, go through every checklist item in the scanner audit 2. Count the number and severity of violations found 3. Apply the dimension-specific rubric to assign 0-4 4. Sum all 8 dimensions for total (0-32) 5. Apply rating band

Tie-Breaking Rules

• If between two scores, the presence of any P0 issue in that dimension rounds down
• If between two scores with no P0, consider the count of P1 issues
• When in doubt, score lower (conservative) -- it is better to fix something unnecessary than miss something important

Verification Scoring

When verifier re-scores after optimization:

• Use identical checklist and rubric as original scan
• Score independently (do not adjust based on "how much improved")
• Report both absolute score and delta from original
• Flag any dimension where score decreased (regression)