Design Workflow Orchestrator

Single entry point for all design work. Enforces the correct phase order so nothing gets skipped.

/design [project-name] [flags]

Flags:
  --skip-state    Skip Phase 1 (static pages, no app state)
  --polish-only   Jump to Phase 4 (already have a design, just polish)
  --qa-only       Jump to Phase 5 (already polished, final gate)

Phase Overview

Phase 0: Pre-flight     → Load config, check prerequisites
Phase 1: State Design   → /state-design (data architecture)
Phase 2: Creative        → /frontend-design new|revamp (3 proposals)
Phase 3: Selection       → User picks winner
Phase 4: Production      → /ui-revamp (4-phase audit + polish)
Phase 5: Final QA        → /frontend-design qa (ship gate)

EXECUTION

Phase 0: Pre-flight

Before anything, load context:

Load style config (personality layer):
- Check for project-level: ai/style.config.md
- Fall back to user-level: ~/.claude/style.config.md
- If neither exists, warn: "No style config found. Designs will use skill defaults. Create ~/.claude/style.config.md for personalized output."
- Extract: brand words, color preferences, motion philosophy, signature elements, anti-patterns
Decide color mode (lock this before any design work):
- Dark-only: dev tools, terminals, creative tools, gaming, entertainment, products where dark IS the identity
- Both modes: documentation, reading-heavy apps, productivity apps used 8+ hrs/day, diverse non-technical audience
- Light-only: e-commerce, marketing, editorial, most SaaS dashboards
- Log decision in ai/design-progress.md as color_mode: dark-only | both | light-only
- Do NOT default to "both" -- it doubles the design surface. Only build both if the product type demands it.
Check prerequisites:
- Does project exist? Is there a working directory?
- For Phase 1: Does a scope/requirements doc exist? (warn if not, don't block)
- For Phase 2+: Has Phase 1 been completed or explicitly skipped?
Read design progress (resume support):
- Check ai/design-progress.md for prior state
- If exists, report current phase and offer to continue
Initialize tracking:
- Create ai/design-progress.md if it doesn't exist
- Log start time and project name
Load design knowledge (optional, enhances output):
- If you have design reference guides available, load them for typography, color, spacing, motion, and accessibility knowledge
- The skill works without external guides but produces better results with them

Output after Phase 0:

Design Workflow: [project-name]
Style Config: [loaded from X | not found]
Color Mode: [dark-only | both | light-only] — [reason]
Current Phase: [starting fresh | resuming Phase N]
Flags: [--skip-state | none]

Ready to begin Phase 1: State Design
(Use --skip-state if this is a static page with no app state)

Phase 1: State Design

Gate: None (first phase) Skip condition: --skip-state flag or user confirms no app state needed

Execute /state-design [project-name]

When complete:

Verify output exists at ai/state-design.md or equivalent

Update ai/design-progress.md:

phase_1: completed | skipped
state_design_output: [path or "skipped - static page"]

Proceed to Phase 2

Phase 2: Creative (3 Proposals)

Gate: Phase 1 must be completed or skipped. Check ai/design-progress.md. If gate fails: "Phase 1 (State Design) hasn't been completed. Run /state-design first or use --skip-state."

Before generating proposals, apply knowledge of:

Typography: font scales, weight pairing, line height rules
Color: palette construction, contrast, semantic color
Spacing & Layout: spacing scale, layout patterns
Motion & Animation: timing, easing, what to animate
Personality: what makes designs feel human, not generic

Also load from style config:

Brand words (set the tone for all 3 proposals)
Color preferences (respect preferred/anti colors)
Motion philosophy (match motion style)
Signature elements (incorporate into proposals)
Anti-patterns (avoid these on top of banned defaults)

Execute /frontend-design new (or revamp if redesigning existing UI)

The skill handles 3-proposal generation, DNA codes, banned defaults, etc.

When complete:

Verify 3 proposal files exist in ./proposals/

Update ai/design-progress.md:

phase_2: completed
proposals: [proposal-1.html, proposal-2.html, proposal-3.html]
dna_codes: [DNA-X-X-X-X-X, DNA-Y-Y-Y-Y-Y, DNA-Z-Z-Z-Z-Z]

Present proposals to user

Phase 3: Selection

Gate: Phase 2 must be completed. 3 proposals must exist.

Present the choice:

3 proposals generated. Pick your direction:

1. Proposal 1 (DNA-X-X-X-X-X) - [brief description]
2. Proposal 2 (DNA-Y-Y-Y-Y-Y) - [brief description]
3. Proposal 3 (DNA-Z-Z-Z-Z-Z) - [brief description]
4. Hybrid - combine elements from multiple proposals

Which direction? (pick a number or describe what you want)

When user selects:

Update ai/design-progress.md:

phase_3: completed
selected: [proposal number or "hybrid: details"]

If hybrid: document which elements from which proposals
Build the selected/hybrid design as the production codebase
Proceed to Phase 4

Phase 4: Production Polish

Gate: Phase 3 must be completed. Selected design must be built. Skip condition: --polish-only flag bypasses Phases 1-3 (assumes design already exists)

Apply knowledge of:

Shadows & Depth: shadow values, layering, elevation
Motion & Animation: spring physics, timing functions
Dark Mode: if applicable
Interactive Elements: state layers, animation timing, easing curves

Execute /ui-revamp (full 4-phase: audit, plan, implement, validate)

When complete:

Verify audit passes

Update ai/design-progress.md:

phase_4: completed
audit_result: [pass/fail]
issues_fixed: [count]

Proceed to Phase 5

Phase 5: Final QA

Gate: Phase 4 must be completed. Skip condition: --qa-only flag bypasses Phases 1-4 (assumes polished design exists)

Run full QA checklist covering:

Typography (font sizes, weights, line heights, hierarchy)
Contrast (WCAG AA minimum, text over backgrounds)
Spacing (consistent scale, no magic numbers)
Interactive (hover/focus/active states, transitions)
Dark Mode (if applicable)
Accessibility (focus management, ARIA, keyboard nav)

Execute /frontend-design qa

When complete:

Update ai/design-progress.md:

phase_5: completed
qa_result: [APPROVED | NEEDS REVISION]

If APPROVED: "Design complete. Ready to ship."
If NEEDS REVISION: List remaining issues, loop back to Phase 4

Progress File Format

ai/design-progress.md:

# Design Progress: [project-name]

Started: [date]
Style Config: [path loaded]
Flags: [any flags used]

## Phase 1: State Design
Status: pending | completed | skipped
Output: [path]

## Phase 2: Creative (3 Proposals)
Status: pending | completed
Proposals: [list]
DNA Codes: [list]

## Phase 3: Selection
Status: pending | completed
Selected: [choice]

## Phase 4: Production Polish
Status: pending | completed
Audit Result: [pass/fail]

## Phase 5: Final QA
Status: pending | completed
QA Result: [APPROVED | NEEDS REVISION]

Short-Circuit Flags

--skip-state: Skips Phase 1. Use for:

Static marketing pages
Simple landing pages
Pages with no dynamic state

--polish-only: Jumps to Phase 4. Use when:

You already have a design you like
Skipping creative phase, just need production polish
Coming back to polish after a break

--qa-only: Jumps to Phase 5. Use when:

Polish is done, just need the final gate check
Quick verification before shipping

Resume Support

The orchestrator reads ai/design-progress.md on every run. If a phase is already completed, it skips ahead to the next pending phase. You never lose progress between sessions.

To restart from scratch: delete ai/design-progress.md.