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