Team Uidesign

Team UI Design

Systematic UI design pipeline: research -> design tokens -> review -> implementation. 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-uidesign", 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]
          researcher  designer  reviewer  implementer

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: UDS
• Session path: .workflow/.team/UDS-<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: "uidesign",
  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: uidesign
requirement: <task-description>
inner_loop: 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/design-standards.md — Impeccable design standards (OKLCH, typography, spacing, motion, interaction)
• specs/anti-patterns.md — AI slop detection catalog (20 items)
• specs/scoring-guide.md — 8-dimension quality scoring rubric
• specs/ux-writing.md — UX writing standards (labels, errors, empty states, voice)

Session Directory

.workflow/.team/UDS-<slug>-<date>/
├── .msg/
│   ├── messages.jsonl         # Team message bus
│   └── meta.json              # Pipeline config + GC state
├── research/                  # Researcher output
│   ├── design-system-analysis.json
│   ├── component-inventory.json
│   ├── accessibility-audit.json
│   ├── design-intelligence.json
│   └── visual-quality-baseline.json
├── design/                    # Designer output
│   ├── design-tokens.json
│   ├── component-specs/
│   └── layout-specs/
├── audit/                     # Reviewer output
│   └── audit-*.md
├── build/                     # Implementer output
│   ├── token-files/
│   └── component-files/
└── wisdom/                    # Cross-task knowledge

Error Handling

Analyze Task

Parse user task -> detect UI design scope -> build dependency graph -> design pipeline mode.

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

Signal Detection

Scope Determination

Complexity Scoring

Results: 1-2 Low (component), 3-4 Medium (system), 5+ High (full-system)

Industry Detection

Output

Write scope context to coordinator memory:

{
  "pipeline_mode": "<component|system|full-system>",
  "scope": "<description>",
  "industry": "<detected-industry>",
  "complexity": { "score": 0, "level": "Low|Medium|High" }
}

Command: Dispatch

Create the UI design task chain with correct dependencies and structured task descriptions. Supports component, system, and full-system pipeline modes.

Phase 2: Context Loading

1. Load user requirement and design scope from session.json 2. Load pipeline stage definitions from specs/pipelines.md 3. Read pipeline and industry from session.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>
  - Scope: <design-scope>
  - Industry: <industry>
  - 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

---

Component Pipeline Task Chain

RESEARCH-001 (researcher):

TaskCreate({
  subject: "RESEARCH-001",
  description: "PURPOSE: Analyze existing design system, build component inventory, assess accessibility baseline | Success: 4 research artifacts produced with valid data
TASK:
  - Analyze existing design tokens and styling patterns
  - Build component inventory with props and states
  - Assess accessibility baseline (WCAG level, ARIA coverage)
  - Retrieve design intelligence via ui-ux-pro-max
CONTEXT:
  - Session: <session-folder>
  - Scope: <design-scope>
  - Industry: <industry>
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/research/*.json | All 4 research files with valid JSON
CONSTRAINTS: Read-only analysis | Focus on <design-scope>"
})
TaskUpdate({ taskId: "RESEARCH-001", owner: "researcher" })

DESIGN-001 (designer):

TaskCreate({
  subject: "DESIGN-001",
  description: "PURPOSE: Define component design with tokens and specifications | Success: Design tokens + component spec with all states defined
TASK:
  - Define design tokens consuming research findings
  - Create component specification with all 5 interactive states
  - Ensure accessibility spec (role, ARIA, keyboard, focus)
  - Reference design intelligence recommendations
CONTEXT:
  - Session: <session-folder>
  - Scope: <design-scope>
  - Industry: <industry>
  - Upstream artifacts: research/*.json
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/design/design-tokens.json + component-specs/*.md | Complete token system + spec
CONSTRAINTS: Follow W3C Design Tokens Format | All color tokens need light/dark"
})
TaskUpdate({ taskId: "DESIGN-001", addBlockedBy: ["RESEARCH-001"], owner: "designer" })

AUDIT-001 (reviewer):

TaskCreate({
  subject: "AUDIT-001",
  description: "PURPOSE: Audit design for consistency, accessibility, and quality | Success: Audit score >= 8 with 0 critical issues
TASK:
  - Score 5 dimensions: consistency, accessibility, completeness, quality, industry compliance
  - Check token naming, theme completeness, contrast ratios
  - Verify component states and ARIA spec
  - Check against design intelligence anti-patterns
CONTEXT:
  - Session: <session-folder>
  - Scope: <design-scope>
  - Industry: <industry>
  - Upstream artifacts: design/design-tokens.json, design/component-specs/*.md
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/audit/audit-001.md | 5-dimension scored report
CONSTRAINTS: Read-only analysis | GC convergence: score >= 8 and 0 critical"
})
TaskUpdate({ taskId: "AUDIT-001", addBlockedBy: ["DESIGN-001"], owner: "reviewer" })

BUILD-001 (implementer):

TaskCreate({
  subject: "BUILD-001",
  description: "PURPOSE: Implement component code from design specs | Success: Production code with token consumption and accessibility
TASK:
  - Generate CSS custom properties from design tokens
  - Implement component with all 5 states
  - Add ARIA attributes and keyboard navigation
  - Validate no hardcoded values
CONTEXT:
  - Session: <session-folder>
  - Scope: <design-scope>
  - Industry: <industry>
  - Upstream artifacts: design/design-tokens.json, design/component-specs/*.md, audit/audit-001.md
  - Shared memory: <session>/wisdom/.msg/meta.json
EXPECTED: <session>/build/**/* | Component + tokens CSS/TS + tests
CONSTRAINTS: Use var(--token-name) only | Follow project patterns"
})
TaskUpdate({ taskId: "BUILD-001", addBlockedBy: ["AUDIT-001"], owner: "implementer" })

---

System Pipeline Task Chain (Dual-Track)

Create tasks in dependency order:

Task descriptions follow same template as component pipeline, with subject-specific content for tokens vs components and appropriate upstream artifacts.

---

Full-System Pipeline Task Chain

Same as System Pipeline, plus:

---

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. Sync Point handling (AUDIT task completed): Read audit signal from message: audit_passed, audit_result, or fix_required

GC Fix Task Creation:

   TaskCreate({ subject: "DESIGN-fix-<round>",
     description: "PURPOSE: Address audit feedback | Success: All critical/high issues resolved
   TASK:
     - Parse audit feedback for specific issues
     - Apply targeted fixes
   CONTEXT:
     - Session: <session-folder>
     - Upstream artifacts: audit/audit-<NNN>.md" })
   TaskUpdate({ taskId: "DESIGN-fix-<round>", owner: "designer" })

Then create new AUDIT task blocked by fix. Increment gc_state.round.

GC Escalation Options (when max rounds exceeded): 1. Accept current design - skip review, continue implementation 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]  RESEARCH-001 (researcher)  -> research/*.json
  [DONE]  DESIGN-001   (designer)    -> design-tokens.json
  [RUN]   AUDIT-001    (reviewer)    -> auditing tokens...
  [WAIT]  BUILD-001    (implementer) -> blocked by AUDIT-001
  [WAIT]  DESIGN-002   (designer)    -> blocked by AUDIT-001

GC Rounds: 0/2
Sync Points: 0/<expected>
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: "uidesign",
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: ~  or <project>/.claude/skills/team-uidesign/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: uidesign
requirement: <task-description>
inner_loop: 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 < 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 Design Team coordinator. Orchestrate pipeline: analyze -> dispatch -> spawn -> monitor -> report. Manages dual-track task chains (design + implementation), GC loops, sync points.

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 with max 2 iterations
• Maintain session state persistence

MUST NOT

• Implement domain logic (researching, designing, auditing, building) -- 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/UDS-*/.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 design scope:

3. Ask for missing parameters if scope unclear:

   AskUserQuestion({
     questions: [
       { question: "UI design scope?", header: "Scope", options: [
         { label: "Single component" },
         { label: "Component system" },
         { label: "Full design system" }
       ]},
       { question: "Product type/industry?", header: "Industry", options: [
         { label: "SaaS/Tech" }, { label: "E-commerce" },
         { label: "Healthcare/Finance" }, { label: "Education/Content" }, { label: "Other" }
       ]}
     ]
   })

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

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

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

   .workflow/.team/UDS-<slug>-<date>/research/
   .workflow/.team/UDS-<slug>-<date>/design/component-specs/
   .workflow/.team/UDS-<slug>-<date>/design/layout-specs/
   .workflow/.team/UDS-<slug>-<date>/audit/
   .workflow/.team/UDS-<slug>-<date>/build/token-files/
   .workflow/.team/UDS-<slug>-<date>/build/component-files/
   .workflow/.team/UDS-<slug>-<date>/wisdom/
   .workflow/.team/UDS-<slug>-<date>/.msg/

4. Initialize .msg/meta.json via team_msg state_update with pipeline metadata 5. TeamCreate(team_name="uidesign") 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: completed_tasks, gc_rounds, sync_points_passed, final_audit_score 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

Design Token & Component Spec Author

Define visual language through design tokens (W3C Design Tokens Format) and component specifications. Consume design intelligence from researcher. Act as Generator in the designer<->reviewer Generator-Critic loop.

Phase 2: Context & Artifact Loading

1. Extract session path from task description 2. Read research findings: design-system-analysis.json, component-inventory.json, accessibility-audit.json 3. Read design intelligence: recommended colors/typography/style, anti-patterns, ux_guidelines 4. Detect task type from subject: "token" -> Token design, "component" -> Component spec, "fix"/"revision" -> GC fix 5. If GC fix task: read latest audit feedback from audit files

Phase 3: Design Execution

Token System Design (DESIGN-001):

• Define complete token system following W3C Design Tokens Format
• Categories: Color (primary, secondary, background, surface, text, semantic), Typography (font-family, font-size, font-weight, line-height), Spacing (xs-2xl), Shadow (sm/md/lg), Border (radius, width), Breakpoint (mobile/tablet/desktop/wide), Motion Easing, Motion Duration, Motion Stagger
• Color tokens MUST use OKLCH values (reference specs/design-standards.md Color section)
• Neutrals: tint toward brand hue with chroma 0.005-0.01 (never pure gray)
• Add semantic colors: success (oklch hue 145), warning (hue 85), error (hue 25), info (hue 250)
• Typography: choose from recommended fonts (Instrument Sans, Plus Jakarta Sans, DM Sans, Space Grotesk, Fraunces -- NOT Inter/Roboto/Open Sans/Lato/Montserrat/Arial), apply modular scale ratio, define fluid clamp() values for display sizes
• Spacing: follow 4pt scale (0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96)
• Motion tokens: define easing (ease-out-quart cubic-bezier(0.25, 1, 0.5, 1) as default), duration scale (instant 100ms, fast 150ms, normal 250ms, slow 400ms, entrance 500ms, complex 800ms), reduced-motion strategy
• All color tokens must have light/dark variants using $value: { light: ..., dark: ... }
• Integrate design intelligence: recommended.colors -> color tokens, recommended.typography -> font stacks
• Document anti-patterns from design intelligence for implementer reference
• Output categories must include: color, typography, spacing, shadow, border, breakpoint, motion_easing, motion_duration, motion_stagger
• Output: <session>/design/design-tokens.json

Component Specification (DESIGN-002):

• Define component specs consuming design tokens
• Each spec contains: Overview (type: atom/molecule/organism, purpose), Design Tokens Consumed (token -> usage -> value reference), States (all 8 required), Responsive Behavior (changes per breakpoint), Accessibility (role, ARIA, keyboard, focus indicator, contrast), Variants, Anti-Patterns, Implementation Hints, Visual Hierarchy Notes (where component sits in hierarchy, CTA level: primary/secondary/tertiary)
• 8 interaction states required (reference specs/design-standards.md Interaction States):
• Default: base appearance
• Hover: subtle bg/opacity change, wrap in @media(hover:hover) guard
• Focus: :focus-visible with outline: 2px solid var(--color-primary); outline-offset: 2px (NOT bare :focus)
• Active: scale(0.97) or darker background
• Disabled: opacity 0.5, cursor: not-allowed via [disabled], [aria-disabled="true"]
• Loading: spinner/skeleton via [aria-busy="true"]
• Error: red border + message via [aria-invalid="true"]
• Success: green check + message
• Touch targets: minimum 44x44px for all interactive components
• UX Writing: button labels (verb+object), error message templates (what+why+fix), empty state copy pattern, loading text pattern. Reference specs/ux-writing.md
• Dark Mode: if light+dark tokens, ensure dark mode follows rules: lighter surfaces for depth, reduced font weight, desaturated accents
• Elevation: specify z-index layer for overlay/popup components using semantic scale (reference specs/design-standards.md Elevation)
• Output: <session>/design/component-specs/{component-name}.md

GC Fix Mode (DESIGN-fix-N):

• Parse audit feedback for specific issues
• Re-read affected design artifacts; apply fixes (token value adjustments, missing states, accessibility gaps, naming fixes)
• Re-write affected files; signal design_revision instead of design_ready

Phase 4: Self-Validation & Output

1. Token integrity checks:

2. Component spec checks:

3. Update <session>/wisdom/.msg/meta.json under designer namespace:

• Read existing -> merge { "designer": { task_type, token_categories, component_count, style_decisions } } -> write back

Component Code Builder

Translate design tokens and component specifications into production code. Generate CSS custom properties, TypeScript/JavaScript components, and accessibility implementations. Consume design intelligence stack guidelines for tech-specific patterns.

Phase 2: Context & Artifact Loading

1. Extract session path from task description 2. Detect build type from subject: "token" -> Token implementation, "component" -> Component implementation 3. Read design artifacts: design-tokens.json (token build), component-specs/*.md (component build) 4. Read design intelligence: stack_guidelines (tech-specific patterns), anti_patterns (patterns to avoid), ux_guidelines 5. Read latest audit report for approved changes and feedback 6. Detect project tech stack from package.json

Phase 3: Implementation Execution

Token Implementation (BUILD-001):

• Convert design tokens to production code
• Output files in <session>/build/token-files/:
• tokens.css: CSS custom properties with :root (light) and [data-theme="dark"] selectors, plus @media (prefers-color-scheme: dark) fallback
• tokens.ts: TypeScript constants and types for programmatic access with autocomplete support
• README.md: Token usage guide
• Color tokens: generate OKLCH values in CSS custom properties (no hex/rgb)
• Motion tokens: generate easing + duration custom properties + reduced-motion query:

  --easing-default: cubic-bezier(0.25, 1, 0.5, 1);
  --duration-instant: 100ms;
  --duration-fast: 150ms;
  /* ... */
  @media (prefers-reduced-motion: reduce) { /* ... */ }

• Spacing: 4pt scale custom properties (--space-0 through --space-24)
• Z-index tokens: generate semantic z-index custom properties (--z-dropdown through --z-tooltip)
• Dark mode: ensure dark theme uses lighter surfaces for depth, reduced font weight references
• All color tokens must have both light and dark values
• Semantic token names must match design token definitions

Component Implementation (BUILD-002):

• Implement component code from design specifications
• Per-component output in <session>/build/component-files/:
• {ComponentName}.tsx: React/Vue/Svelte component (match detected stack)
• {ComponentName}.css: Styles consuming tokens via var(--token-name) only
• {ComponentName}.test.tsx: Basic render + state tests
• index.ts: Re-export
• Requirements: no hardcoded colors/spacing (use design tokens), implement all 8 states, add ARIA attributes per spec, support responsive breakpoints, follow project component patterns
• Focus: use :focus-visible not bare :focus. Spec: outline: 2px solid var(--color-primary); outline-offset: 2px; border-radius: inherit
• Hover: wrap in @media(hover:hover) guard
• Animation: transform+opacity only (NEVER width/height/margin/padding), use motion tokens for easing and duration, add reduced-motion fallback via @media (prefers-reduced-motion: reduce)
• Touch targets: 44x44px minimum for all interactive elements, 8px gap between adjacent targets
• Accessibility: keyboard navigation, screen reader support, visible focus indicators, WCAG AA contrast
• Responsive images: use srcset with width descriptors + sizes attribute for content images. Use <picture> for art direction
• Input method: beyond @media(hover:hover), also use @media(pointer:coarse) for touch-specific adjustments (larger targets, simpler hover alternatives)
• UX writing: implement button labels, error messages, empty states as specified in component spec. No generic "OK/Cancel"
• Check implementation against design intelligence anti_patterns and specs/anti-patterns.md

Phase 4: Validation & Output

1. Token build validation:

2. Component build validation:

3. Update <session>/wisdom/.msg/meta.json under implementer namespace:

• Read existing -> merge { "implementer": { build_type, file_count, output_dir, components_built } } -> write back

Design System Researcher

Analyze existing design system, build component inventory, assess accessibility baseline, and retrieve industry-specific design intelligence via ui-ux-pro-max. Produce foundation data for downstream designer, reviewer, and implementer roles.

Phase 2: Context & Environment Detection

1. Extract session path and target scope from task description 2. Detect project type and tech stack from package.json or equivalent:

3. Use CLI tools (e.g., ccw cli -p "..." --tool gemini --mode analysis) or direct tools (Glob, Grep, mcp__ace-tool__search_context) to scan for existing design tokens, component files, styling patterns 4. Read industry context from session config (industry, strictness, must-have features) 5. Context-First Protocol: Before any design work, ensure these are known (extract from task description, or ask coordinator to clarify):

• Target audience: Who uses it, in what context? (e.g., developers, end users, admins)
• Use cases: What jobs are they doing? (e.g., data entry, monitoring, content creation)
• Brand personality: How should it feel? (e.g., professional, playful, technical, luxurious)
• If not provided in task description, flag as context_missing in output — designer cannot make good decisions without this

Phase 3: Research Execution

Execute 4 analysis streams:

Stream 1 -- Design System Analysis:

• Search for existing design tokens (CSS variables, theme configs, token files)
• Identify styling patterns (CSS-in-JS, CSS modules, utility classes, SCSS)
• Map color palette, typography scale, spacing system
• Find component library usage (MUI, Ant Design, shadcn, custom)
• Check dark mode implementation quality: surface hierarchy, font weight adjustments, accent desaturation
• Check z-index patterns: arbitrary values vs semantic scale
• Output: <session>/research/design-system-analysis.json

Stream 2 -- Component Inventory:

• Find all UI component files; identify props/API surface
• Identify states supported (hover, focus, disabled, etc.)
• Check accessibility attributes (ARIA labels, roles)
• Map inter-component dependencies and usage counts
• Output: <session>/research/component-inventory.json

Stream 3 -- Accessibility Baseline:

• Check ARIA attribute usage patterns, keyboard navigation support
• Assess color contrast ratios (if design tokens found)
• Find focus management and semantic HTML patterns
• Output: <session>/research/accessibility-audit.json

Stream 4 -- Design Intelligence (ui-ux-pro-max):

• Call Skill(skill="ui-ux-pro-max", args="<industry> <keywords> --design-system") for design system recommendations
• Call Skill(skill="ui-ux-pro-max", args="accessibility animation responsive --domain ux") for UX guidelines
• Call Skill(skill="ui-ux-pro-max", args="<keywords> --stack <detected-stack>") for stack guidelines
• Degradation: when unavailable, use LLM general knowledge, mark _source: "llm-general-knowledge"
• Output: <session>/research/design-intelligence.json

Stream 5 -- Visual Quality Baseline:

• Scan for AI slop tells (reference specs/anti-patterns.md): check for P1 items (AI color palette, gradient text, glassmorphism, all-buttons-primary, pure black/white)
• Check color system: OKLCH usage, pure black/white (#000/#fff), tinted neutrals (chroma 0.005-0.01), 60-30-10 distribution
• Check typography: font choices (flag Inter/Roboto/Open Sans/Lato/Montserrat/Arial), modular scale presence, fluid clamp() usage
• Check spacing: 4pt scale adherence, gap vs margin usage ratio, nested cards detection
• Check motion: easing values (flag bounce/elastic/linear/ease), prefers-reduced-motion query presence, will-change in CSS (should not be permanent)
• Check interaction states: count distinct states per interactive component (target: 8 per specs/design-standards.md)
• Check UX writing quality: generic button labels (OK/Submit/Cancel), error messages without fix guidance, empty states without actions
• Check dark mode: pure black backgrounds, non-desaturated accents, same font weights as light
• Output: <session>/research/visual-quality-baseline.json

Compile research summary metrics: design_system_exists, styling_approach, total_components, accessibility_level, design_intelligence_source, anti_patterns_count, visual_quality_score.

Phase 4: Validation & Output

1. Verify all 5 output files exist and contain valid JSON with required fields:

2. If any file missing or invalid, re-run corresponding stream

3. Update <session>/wisdom/.msg/meta.json under researcher namespace:

• Read existing -> merge { "researcher": { detected_stack, component_count, wcag_level, di_source, scope } } -> write back

Design Auditor

Audit design tokens and component specs for consistency, accessibility compliance, completeness, quality, and industry best-practice adherence. Act as Critic in the designer<->reviewer Generator-Critic loop. Serve as sync point gatekeeper in dual-track pipelines.

Phase 2: Context & Artifact Loading

1. Extract session path from task description 2. Detect audit type from subject: "token" -> Token audit, "component" -> Component audit, "final" -> Final audit, "sync" -> Sync point audit 3. Read design intelligence for anti-patterns and ux_guidelines 4. Read design artifacts: design-tokens.json (token/component audit), component-specs/.md (component/final audit), build// (final audit only) 5. Load audit_history from meta.json for trend analysis

Phase 3: Audit Execution

Score 8 dimensions on 0-4 scale (reference specs/scoring-guide.md). Total: 0-32.

Token Audit: OKLCH color values, tinted neutrals (chroma 0.005-0.01), no pure black/white, semantic token hierarchy (primitive->semantic->component), theme completeness (light+dark), contrast ratios (text >= 4.5:1, large text >= 3:1), distinctive font choice, modular scale ratio, fluid clamp() values, 4pt spacing scale, motion easing + duration tokens, reduced-motion strategy.

Component Audit: All 8 interaction states present, :focus-visible (not bare :focus), hover in @media(hover:hover), active scale(0.97), loading/error/success states with ARIA, touch targets >= 44x44px, token references resolve, CTA hierarchy (primary/secondary/tertiary), no layout property animations.

Final Audit (cross-cutting): Token<->Component consistency (no hardcoded values), Code<->Design consistency (CSS variables match tokens, ARIA implemented as specified), cross-component consistency (spacing, color, interaction patterns), anti-pattern scan across all outputs.

Signal determination:

Phase 4: Report & Output

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

• Summary: overall score (out of 32), signal, rating band (Excellent/Good/Acceptable/Poor/Critical)
• Sync Point Status (if applicable): PASSED/BLOCKED
• 8-Dimension Scores table: Anti-AI-Slop, Color Quality, Typography Quality, Spacing & Layout, Motion & Animation, Interaction States, Visual Hierarchy, Responsive (each 0-4 with weight and weighted score)
• P0/P1/P2/P3 issues with descriptions, locations, fix suggestions, mapped to dimensions
• Anti-pattern detections (reference specs/anti-patterns.md item numbers)
• GC Loop Status: signal, action required
• Trend analysis (if audit_history exists): improving/stable/declining

2. Update <session>/wisdom/.msg/meta.json under reviewer namespace:

• Read existing -> merge { "reviewer": { audit_id, score, critical_count, signal, is_sync_point, audit_type, timestamp } } -> write back

AI Slop Detection Catalog

20 anti-patterns that signal AI-generated or low-effort design. Reference this during research (visual quality baseline), design (avoidance), review (scoring), and implementation (validation).

Severity Guide

---

1. AI Color Palette -- P1

Pattern: Cyan-on-dark, purple-blue gradients, neon accent colors against dark backgrounds. The "AI dashboard" look.

Detection: Check for oklch(... 250-280) as primary + dark background, or gradient from purple to cyan/blue. Check for saturated neon accents (chroma > 0.25) on lightness < 0.15 backgrounds.

Fix: Use brand-derived colors. Reduce chroma. Apply 60-30-10 rule. Tint neutrals toward brand hue.

---

2. Gradient Text for Impact -- P1

Pattern: background-clip: text with gradient fills on headings for visual flair.

Detection: Search for background-clip: text or -webkit-background-clip: text in stylesheets.

Fix: Use solid color with proper contrast. If emphasis needed, use weight or size, not gradient text.

---

3. Default Dark Mode with Glowing Accents -- P2

Pattern: Dark background as default with glowing/neon UI elements. No light mode alternative.

Detection: Check if dark theme is the only theme defined. Look for box-shadow with saturated colors (0 0 Npx oklch(... 0.2+ ...)).

Fix: Design light mode first. Dark mode as opt-in. Use subtle elevation shadows, not glows.

---

4. Glassmorphism Everywhere -- P1

Pattern: backdrop-filter: blur() on more than 2 components. Frosted glass effect as default surface treatment.

Detection: Count backdrop-filter: blur occurrences. Flag if > 2 distinct components use it.

Fix: Reserve glass effect for 1-2 overlay/modal surfaces max. Use solid or semi-transparent backgrounds elsewhere.

---

5. Hero Metric Layout -- P2

Pattern: Big number + small label arranged in rows/grids. The "SaaS dashboard hero" pattern with 3-4 metric cards.

Detection: Look for repeated pattern of large font-size number + small label in card grids at page top.

Fix: Show metrics in context of their meaning. Use sparklines with real data, comparisons, or trends instead of isolated numbers.

---

6. Identical Card Grids -- P2

Pattern: 3+ cards with identical dimensions, same padding, same shadow, same structure. No visual hierarchy.

Detection: Count card components with identical styling. Flag if 3+ share exact same dimensions and no hierarchy differentiation.

Fix: Vary card sizes by importance. Use a featured/primary card. Apply visual hierarchy through size or position.

---

7. Nested Cards -- P2

Pattern: Card inside card -- border/shadow inside border/shadow. Creates visual clutter.

Detection: Check for components with border/box-shadow containing child components that also have border/box-shadow.

Fix: Flatten hierarchy. Use spacing and subtle dividers instead of nested containers.

---

8. Generic Fonts -- P2

Pattern: Inter, Roboto, Open Sans, Lato, Montserrat, or Arial as the primary font. Zero typographic identity.

Detection: Check font-family declarations for the generic font list.

Fix: Choose from recommended fonts: Instrument Sans, Plus Jakarta Sans, DM Sans, Space Grotesk, Fraunces.

---

9. Rounded Rectangles + Generic Drop Shadows -- P3

Pattern: More than 5 elements with identical border-radius and generic box-shadow (e.g., 0 1px 3px rgba(0,0,0,0.1)).

Detection: Count elements sharing identical border-radius + box-shadow values. Flag if > 5.

Fix: Vary border-radius by component type (buttons vs cards vs modals). Use layered shadows with tinted colors.

---

10. Large Icons Above Every Heading -- P2

Pattern: Decorative icon placed above every section heading. Adds visual noise without meaning.

Detection: Check for repeated icon + heading pattern across 3+ sections.

Fix: Use icons sparingly and only where they add meaning. Prefer inline icons at heading size, not oversized decorative ones.

---

11. One-Side Border Accent -- P3

Pattern: border-left: 3px solid var(--accent) on cards or sections as the sole visual treatment.

Detection: Search for one-sided border declarations on 3+ components.

Fix: Use spacing, background tinting, or typography to create differentiation instead.

---

12. Decorative Sparklines -- P2

Pattern: Tiny charts with no axis labels, no data context, no interactivity. Pure decoration.

Detection: Check for chart/sparkline components without accessible labels, axis values, or data source.

Fix: Either make charts meaningful (labels, context, interaction) or remove them. No decorative data visualization.

---

13. Bounce/Elastic Easing -- P2

Pattern: Bounce or elastic easing on UI transitions. Feels toylike and unprofessional.

Detection: Search for bounce, elastic, cubic-bezier with values > 1.0 in the second or fourth parameter.

Fix: Use ease-out-quart cubic-bezier(0.25, 1, 0.5, 1) as default. See design-standards.md Motion section.

---

14. Redundant Copy -- P3

Pattern: Heading restated in the body text immediately below. "Our Features" followed by "Here are our features."

Detection: Compare heading text to first sentence of body. Flag if > 60% word overlap.

Fix: Body text should expand on the heading, not repeat it. Each element earns its space.

---

15. All Buttons Primary -- P1

Pattern: Every button is the same filled/primary style. No visual hierarchy between actions.

Detection: Count button variants. Flag if > 80% of buttons share the same style (all filled, all same color).

Fix: 1 primary CTA per viewport. Secondary = outline. Tertiary = text link. See design-standards.md Visual Hierarchy.

---

16. Everything Centered -- P2

Pattern: Body text, lists, and form labels all center-aligned. Looks "designed" but kills readability.

Detection: Check for text-align: center on body text, lists, or form elements (not just headings).

Fix: Left-align body text. Center only headings, hero text, and short labels. Reading follows left edge.

---

17. Same Spacing Everywhere -- P2

Pattern: More than 70% of spacing values are identical. No rhythm variation.

Detection: Audit spacing tokens usage. Flag if > 70% of gap, padding, margin values use the same token.

Fix: Apply rhythm: tight (4-8px) within groups, comfortable (16-24px) between items, generous (48-96px) between sections.

---

18. Monospace as Tech Aesthetic -- P3

Pattern: Monospace font used on non-code content (headings, labels, body text) for "techy" feel.

Detection: Check for monospace font-family on elements that are not code, pre, kbd, or samp.

Fix: Reserve monospace for code. Use Space Grotesk or similar geometric sans if tech aesthetic is desired.

---

19. Modal Overuse -- P3

Pattern: More than 3 modals in a flow for non-critical actions. Interrupts flow unnecessarily.

Detection: Count modal/dialog components. Flag if > 3 modals exist for non-destructive actions.

Fix: Use inline expansion, drawers, or page navigation. Reserve modals for confirmations and critical decisions.

---

20. Pure Black or Pure White -- P1

Pattern: Using #000000 or #ffffff (or rgb(0,0,0) / rgb(255,255,255)). Harsh contrast, unnatural.

Detection: Search for #000, #fff, #000000, #ffffff, rgb(0,0,0), rgb(255,255,255) in stylesheets and tokens.

Fix: Use tinted neutrals. Darkest: oklch(0.08 0.010 <hue>). Lightest: oklch(0.98 0.005 <hue>).

Impeccable Design Standards

Reference spec for all roles. Every design decision must trace back to these standards.

---

Color (OKLCH)

OKLCH for perceptually uniform palettes. All color tokens MUST use OKLCH notation.

Token Hierarchy

primitive -> semantic -> component

/* Primitives */
--color-primary          oklch(0.55 0.2 250)
--color-primary-light    oklch(0.70 0.15 250)
--color-primary-dark     oklch(0.40 0.22 250)

/* Tinted neutrals (chroma 0.005-0.01, brand hue) */
--color-neutral-50       oklch(0.98 0.005 250)  /* brand tinted */
--color-neutral-100      oklch(0.95 0.006 250)
--color-neutral-200      oklch(0.90 0.007 250)
--color-neutral-300      oklch(0.82 0.007 250)
--color-neutral-400      oklch(0.70 0.008 250)
--color-neutral-500      oklch(0.55 0.008 250)
--color-neutral-600      oklch(0.45 0.009 250)
--color-neutral-700      oklch(0.35 0.009 250)
--color-neutral-800      oklch(0.25 0.010 250)
--color-neutral-900      oklch(0.15 0.010 250)
--color-neutral-950      oklch(0.08 0.010 250)

/* Semantic */
--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.18 250)

Rules

• 60-30-10 rule: 60% neutral, 30% secondary, 10% accent
• Never pure black (#000) or pure white (#fff) -- use tinted neutrals
• Tinted neutrals: chroma 0.005-0.01, hue matching brand primary
• Text on colored backgrounds: use color-mix(in oklch, ...) not gray

Dark Mode Rules

• Dark mode is NOT inverted light mode. It requires deliberate design:
• Use lighter surfaces for elevation/depth (not darker)
• Reduce font weight by 1 step (600→500, 500→400) — light text on dark looks heavier
• Desaturate accent colors — saturated colors vibrate on dark backgrounds
• Surface hierarchy: oklch(0.15 ...) base → oklch(0.20 ...) raised → oklch(0.25 ...) overlay
• Never: pure black #000 background (too harsh). Use oklch(0.10 0.01 <hue>) minimum
• Test: all contrast ratios must meet WCAG AA in BOTH themes

Dangerous Color Combinations

• WCAG AA contrast:
• Normal text: 4.5:1
• Large text (>= 18px bold or >= 24px): 3:1
• UI components and graphical objects: 3:1
• Focus indicators: 3:1

---

Typography

Font Selection

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

Recommended: Instrument Sans, Plus Jakarta Sans, DM Sans, Space Grotesk, Fraunces

Modular Scale

Choose one ratio for the project:

Fluid Sizing

Use clamp() for display and heading sizes:

--text-sm:      clamp(0.8rem, 0.77rem + 0.15vw, 0.875rem);
--text-base:    clamp(0.9rem, 0.85rem + 0.25vw, 1rem);
--text-lg:      clamp(1.05rem, 0.95rem + 0.35vw, 1.125rem);
--text-xl:      clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem);
--text-2xl:     clamp(1.5rem, 1.25rem + 0.75vw, 1.875rem);
--text-3xl:     clamp(1.875rem, 1.5rem + 1.1vw, 2.25rem);
--text-display: clamp(2.25rem, 1.75rem + 1.5vw, 3rem);

Line Height

• Body text: 1.5
• Headings: 1.2
• Small / caption text: 1.6

Reading Width

max-width: 65ch (acceptable range: 45-75ch)

Font Loading

font-display: swap with fallback metrics:

@font-face {
  font-family: 'Plus Jakarta Sans';
  font-display: swap;
  size-adjust: 102%;
  ascent-override: 95%;
}

---

Spacing (4pt Base)

Scale

0, 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 96 px

Map to tokens:

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

Rhythm

Layout Rules

• Use gap not margin for sibling spacing
• Cards only for distinct actionable content -- flatten nested cards
• Container queries for component-level responsive behavior
• Touch targets: 44x44px minimum, 8px gap between adjacent targets

---

Motion

Animatable Properties (ONLY these)

transform, opacity, clip-path, background-color, color, border-color, box-shadow, filter

NEVER Animate (layout triggers)

width, height, top, left, margin, padding

Easing

Default: ease-out-quart cubic-bezier(0.25, 1, 0.5, 1)

NEVER use: ease, linear, bounce, elastic

Duration Scale

• Exit duration = 75% of entrance
• Feedback animations: 100-150ms max

Stagger

• Max 10 items in stagger group
• Max 500ms total stagger duration
• Formula: calc(var(--index) * 50ms)

Reduced Motion (REQUIRED)

@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

Add via JS on pointerenter, remove on animationend/transitionend. Never set permanently in CSS.

---

Interaction States (8 Required)

Every interactive component MUST define all 8 states:

Focus Ring Spec

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

---

Visual Hierarchy

Squint Test

Blur the page -- you should immediately identify the top 2 elements and groupings.

Tools

Size (3:1 ratio between primary and body), weight (max 2 weights per page), color, space, position, contrast.

CTA Hierarchy

• 1 primary CTA per viewport -- filled button
• Secondary -- outline button
• Tertiary -- text link

Progressive Disclosure

Reveal complexity gradually. Default to the simplest view.

---

Responsive

Breakpoints (mobile-first)

640px, 768px, 1024px, 1280px, 1536px

Fluid Design

Prefer %, vw, fr, min(), max(), clamp() over fixed px.

Mobile Requirements

• Minimum 14px text
• 44px touch targets
• No horizontal scroll at 320px viewport
• Adapt layout, don't hide content

---

Elevation & Z-Index

Semantic Z-Index Scale

--z-dropdown:       100;
--z-sticky:         200;
--z-fixed:          300;
--z-modal-backdrop: 400;
--z-modal:          500;
--z-popover:        600;
--z-toast:          700;
--z-tooltip:        800;

• Never use arbitrary z-index values (z-index: 9999)
• Each level has clear semantic meaning
• Modal backdrop + modal are separate layers (backdrop catches clicks)
• Toast above modal (error during modal interaction must be visible)

---

UX Writing

Reference: specs/ux-writing.md for full guidelines.

Key rules for design token and component spec work:

• Button labels: verb + object ("Save changes" not "Submit")
• Error messages: what + why + fix
• Empty states: acknowledge + explain value + action
• Destructive actions: name the destruction + show count
• Never "OK/Cancel" — use specific action names

Pipeline Definitions

UI design pipeline modes and task registry.

Pipeline Modes

Component Pipeline Task Registry

System Pipeline Task Registry

Full-System Pipeline Task Registry

Same as System pipeline, plus:

Checkpoints / Sync Points

GC Loop Behavior

Parallel Spawn Rules

Output Artifacts

8-Dimension Quality Scoring Rubric

Score each dimension 0-4. Total: 0-32.

Dimensions

1. Anti-AI-Slop (Weight: 10%)

2. Color Quality (Weight: 15%)

3. Typography Quality (Weight: 15%)

4. Spacing & Layout (Weight: 12.5%)

5. Motion & Animation (Weight: 10%)

6. Interaction States (Weight: 15%)

7. Visual Hierarchy (Weight: 10%)

8. Responsive Design (Weight: 12.5%)

---

Rating Bands

Severity Mapping

Signal Determination

UX Writing Standards

Guidelines for all text content in UI components. From Impeccable's UX writing reference.

---

Button Labels

• NEVER: "OK", "Submit", "Yes", "No", "Cancel" (generic)
• ALWAYS: verb + object — "Save changes", "Create account", "Delete message"
• Destructive actions: name the destruction + show count — "Delete 5 items" not "Delete selected"
• Primary CTA: specific benefit — "Start free trial" not "Get started"

Error Messages

Formula: (1) What happened + (2) Why + (3) How to fix

• Never blame user: "Please enter..." not "You entered..."
• Never use codes alone: "Error 404" → "Page not found"
• Be specific: "Password must be 8+ characters with a number" not "Invalid password"

Empty States

Three components: (1) Acknowledge + (2) Explain value + (3) Provide action

Loading States

• Be specific: "Saving your draft..." not "Loading..."
• Multi-step: show progress — "Uploading (2 of 5 files)..."
• Duration hint: "This usually takes about 30 seconds"

Confirmation Dialogs

• Use sparingly — prefer undo over confirm
• Title: what will happen — "Delete this project?"
• Body: consequences — "This will permanently delete 12 files. This can't be undone."
• Buttons: specific — "Delete project" / "Keep project" (not OK/Cancel)

Voice & Tone

• Voice: consistent brand personality (professional/friendly/technical — choose one)
• Tone: adapts to moment — cheerful for success, empathetic for errors, neutral for routine
• Keep consistent: same word for same concept everywhere (delete/remove/trash → pick one)

Form Instructions

• Show format with placeholder: placeholder="john@example.com"
• Explain non-obvious fields with helper text below label
• Mark optional fields (not required ones) — most fields should be required
• Group related fields with clear section headers

Translation Planning

• Design for longest language (German)
• Never truncate translated text — allow wrapping
• Avoid idioms and cultural references in source text

Redundant Copy Detection

• Don't repeat visible information (heading ≠ first paragraph)
• Labels describe the field, not restate the value
• Tooltips add information, not repeat the label
• If heading says it all, skip the intro paragraph