design-to-dev

/design-to-dev

Orchestrate frontend implementation from design wireframes. Takes wireframe screenshots, extracts design tokens, creates Linear issues with full specs, and drives phased parallel development in git worktrees.

Patterns: Mediator (wave orchestration — agents communicate via Linear comments and git PRs, not with each other), State Machine (design/state.json), Structural Isolation (visual judge never receives source code).

Arguments

• /design-to-dev <path1> <path2> ... — wireframe screenshot paths
• /design-to-dev resume — resume from paused state (reads design/state.json)

---

Phase 0 — Preflight

Step 1: Detect project

Verify cwd is a git repository. If not, fail with: "This skill must be run from within a git repository."

Step 2: Detect stack

Scan package.json for React, Tailwind CSS, and shadcn/ui.

If any are missing:

AskUserQuestion:
  question: "The project is missing required dependencies. How should we proceed?"
  options:
    - label: "Scaffold missing deps in Wave 0"
      description: "The foundation wave will install and configure the missing dependencies before any component work begins."
    - label: "Abort"
      description: "Set up the project manually first, then re-run /design-to-dev."

On abort: exit. On scaffold: note missing deps for Wave 0 issue creation.

Step 3: Accept wireframe files

If args contain file paths, use those. Otherwise:

AskUserQuestion:
  question: "Provide the paths to your wireframe/design screenshots."
  options:
    - label: "I'll paste paths now"
      description: "Enter file paths in the chat (space or newline separated)."
    - label: "They're already in design/wireframes/"
      description: "Skip — files are already in the project."

Copy wireframe files to design/wireframes/ in the project root. Create the directory if it doesn't exist. Verify each file exists and is a readable image.

Add design/ to .gitignore if not already present. Design assets are temporary build artifacts — they must be removed after implementation completes.

Step 4: Linear project setup

Discover available teams via mcp__linear__linear_getTeams.

AskUserQuestion:
  question: "Which Linear project should issues go into?"
  options:
    - label: "Create new project"
      description: "Create a new Linear project named after this repo."
    - label: "Use existing project"
      description: "Select from existing projects."

On "Create new": use mcp__linear__linear_createProject with the repo name. On "Use existing": list projects via mcp__linear__linear_getProjects and let the user choose.

Store the project ID and team ID for issue creation.

---

Phase 1 — Design Analysis

Step 5: Extract design tokens

For each wireframe screenshot in design/wireframes/:

Read the image via the Read tool (multimodal). Analyze it to extract:

• Color palette: all hex values with semantic names (primary, secondary, muted, destructive, background, foreground, border, accent, sidebar colors)
• Typography: font family, weights used, sizes for each text level (h1-h4, body, caption, label, table cell)
• Spacing scale: padding, margin, and gap values observed
• Border radius values (cards, buttons, inputs, avatars)
• Shadow values
• Component states visible (hover highlights, active states, disabled elements)

Write the structured output to design/tokens.json:

{
  "colors": { "primary": "#2563EB", "background": "#FFFFFF" },
  "typography": { "fontFamily": "Inter", "sizes": { "h1": "24px" } },
  "spacing": [4, 8, 12, 16, 24, 32, 48],
  "radius": { "sm": "4px", "md": "6px", "lg": "8px", "full": "9999px" },
  "shadows": { "sm": "0 1px 2px rgba(0,0,0,0.05)" }
}

Step 6: Generate Tailwind theme

From design/tokens.json, generate a Tailwind v4 @theme CSS block and write it to design/tokens.css. This file will be imported into the project's src/index.css during Wave 0.

Annotate each token with its wireframe source as a CSS comment.

Step 7: Component inventory

Analyze each wireframe to identify distinct UI regions. For each region, note:

• Candidate component name (e.g., "Sidebar", "UserTable", "StatCard")
• Which wireframe it appears in
• Whether it's shared across wireframes (shared = Wave 0) or page-specific
• Visible states (if data is shown, assume loading/empty/error states exist)
• Candidate shadcn/ui primitives it maps to (Button, Card, Table, Input, etc.)

This inventory drives issue creation in Phase 2.

---

Phase 2 — Issue Breakdown

Step 8: Create Linear issues

For each component/page identified in step 7, create a Linear issue via mcp__linear__linear_createIssue. Use the team ID and project ID from step 4.

Every issue MUST contain all of the following (hard rule — no exceptions):

Title format: [Wave N] Component/Page Name

Description (markdown) must include these sections:

## Overview — What this component/page does and where it appears.

## Wireframe Reference — design/wireframes/<filename>.png with description of which region of the wireframe this issue covers.

## Design Tokens — Every token this component uses, with both CSS variable and Tailwind class name: var(--color-primary) / bg-primary.

## Style Specification — Exact layout, sizing, spacing, colors, typography for every element. Reference design tokens, never raw values. Example: Container: flex flex-col gap-4 p-6 rounded-lg bg-card.

## Behavior & Interactions — Click, hover, focus behavior for each interactive element. Navigation targets. Form validation rules. Loading and transition behaviors.

## State Matrix — Table with columns: State, Description, Mock Data Shape. Required states for data components: loading, empty, error, single-item, full-page, overflow. Required states for forms: pristine, validating, field-errors, submit-loading, success, server-error. Static components: default only.

## shadcn/ui Components — List the shadcn primitives to use.

## Definition of Done

• Builds clean (npm run build passes)
• Matches wireframe region (see Wireframe Reference)
• One Storybook story per state in the State Matrix
• Uses only design token utility classes (no raw hex/px values)
• Code review passes

Step 9: Wave assignment

Assign each issue a wave number in the title [Wave N]:

• Wave 0 (Foundation): Layout shell (sidebar + top bar + content area), routing skeleton with placeholder routes, design token integration (design/tokens.css into src/index.css), shared types/interfaces, any missing dependency scaffolding from step 2.

• Wave 1+: Group issues so no two issues in the same wave touch the same files. Issues depending on components from a prior wave go in a later wave. Shared components before the pages that use them.

Step 10: User approval gate (MANDATORY — never skip)

Print a summary table of all created issues:

| Wave | Issue ID | Title | States |
|------|----------|-------|--------|
| 0    | LIA-XXX  | Layout Shell | 1 |
| 1    | LIA-XXX  | Dashboard Stat Cards | 4 |

AskUserQuestion:
  question: "Issues created. Review them in Linear and confirm when ready."
  options:
    - label: "Proceed to development"
      description: "Issues are correct. Start Wave 0."
    - label: "I'm editing issues first"
      description: "Skill pauses. Run /design-to-dev resume when ready."

On "editing first": write state to design/state.json with status paused, current wave 0, all issue IDs per wave, Linear project ID. Exit.

---

Phase 3 — Phased Development

This phase repeats for each wave until all waves are complete.

Step 11: Pre-wave checks

If resuming (/design-to-dev resume), read design/state.json and re-fetch all Linear issues for the current wave to pick up any user modifications.

Scan all issues in the current wave for [BLOCKING] comments via mcp__linear__linear_getComments. If any found:

AskUserQuestion:
  question: "[BLOCKING] flag found on LIA-XXX: <comment text>"
  options:
    - label: "Halt wave"
      description: "Stop and investigate. Run /design-to-dev resume after resolving."
    - label: "Override and proceed"
      description: "Ignore the blocking flag and continue."

Step 12: Dispatch subagents

For each issue in the current wave, dispatch a Sonnet subagent in a git worktree. Launch ALL agents for the wave in a single message (parallel).

Each agent's prompt:

You are implementing a frontend component. Work in your git worktree.

## Your Issue
[full Linear issue description pasted here]

## Design System
[contents of design/SYSTEM_MANIFEST.md if it exists, otherwise design/tokens.json]

## Rules
- Use ONLY design token utility classes. Never raw hex colors or pixel values.
- Create one Storybook story per state in the State Matrix.
- Import shadcn/ui components from @/components/ui/.
- Follow existing code patterns in the project.
- Show commit message before committing.
- When done, create a PR against main.
- Post your result as a comment on the Linear issue:
  - Success: "SHIP: PR #XX created. <brief summary>"
  - Concern: "[WARNING]: <description>"
  - Blocker: "[BLOCKING]: <description — halts the wave>"

Step 13: Wait and collect

Wait for all subagents to complete. Collect PR URLs from Linear comments.

Step 14: Handle failures

For agents that failed (error, crash, timeout):

• Post [WARNING]: re-queued from wave N due to agent failure on the issue
• Move the issue to the next wave in design/state.json
• Do NOT block the wave — successful PRs proceed

Step 15: Code review and merge

For each successful PR, dispatch a code-review subagent (Sonnet). All reviews in parallel.

On SHIP verdict: merge the PR. On REVISE: the review agent fixes issues and re-requests. Loop until SHIP.

Step 16: Post-wave — manifest and coherence

After all PRs merge:

Regenerate manifest: Analyze merged main branch. Write design/SYSTEM_MANIFEST.md (~800-1200 tokens):

• Component inventory: name, file path, props, slot interface
• Design token coverage: tokens used, any raw values detected
• Route map: routes and their components
• Storybook story count vs state matrix total

This manifest is the coherence sweep's data source — it defines what "consistent" means so the sweep agent doesn't need to scan the full codebase.

Coherence sweep: Dispatch a Sonnet agent that:

1. Reads design/SYSTEM_MANIFEST.md
2. Detects dev server command from package.json scripts
3. Starts the dev server
4. Screenshots every route at desktop viewport (1440px) via chrome tools (if chrome unavailable, ask user for screenshots via AskUserQuestion)
5. Evaluates cross-page consistency: spacing rhythm, typography hierarchy, color usage, interactive patterns, navigation continuity
6. Outputs a coherence report

If coherence issues found: create fix-up issues for the current wave, merge fixes, re-run coherence until clean.

Step 17: Wave transition

On clean coherence:

1. Run /handoff for the wave — captures what was built, deviations, warnings
2. Update design/state.json: advance current_wave, status running
3. Return to step 11 for the next wave

If no more waves remain, proceed to Phase 4.

---

Phase 4 — Visual Quality Gate

Step 18: Start dev server

Detect dev server command from package.json scripts.dev field. Start in the background. Wait for it to be reachable.

Step 19: Adversarial visual judge

Dispatch a Sonnet visual-judge agent. This agent is STRUCTURALLY ISOLATED:

Receives ONLY:

• Wireframe screenshot paths from design/wireframes/
• Live app screenshots via chrome tools (fallback: ask user for screenshots)
• design/tokens.json for reference values

NEVER receives:

• Source code paths or file contents
• Component names or implementation details

Layer 1 — Deterministic:

• Navigate to each route
• Run getComputedStyle on key elements via chrome JavaScript tool
• Assert CSS values match design tokens (colors, font sizes, spacing)
• Check heading hierarchy via accessibility tree
• Count Storybook stories vs state matrix rows

Layer 2 — Vision:

• For each page: view wireframe and screenshot at same viewport
• Evaluate: layout fidelity, spacing, colors, typography, element positioning
• Output per-page: SHIP or REVISE with specific region callouts

Step 20: Fix loop

On REVISE:

1. Create fix-up Linear issues per delta, assigned to next wave
2. Re-enter Phase 3 (step 11) for that wave
3. After fixes merge, re-run Phase 4 (step 18)
4. Repeat until judge returns SHIP for all pages

On SHIP: proceed to Phase 5.

---

Phase 5 — Cleanup

Step 21: Remove design assets

AskUserQuestion:
  question: "Implementation complete and visually verified. Remove design assets?"
  options:
    - label: "Remove design/ folder"
      description: "Wireframes and tokens served their purpose. Clean up."
    - label: "Keep design/ folder"
      description: "Preserve for future reference."

On remove: delete design/ directory, remove .gitignore entry if added by this skill, run git worktree prune. Commit the cleanup.

---

State Machine

design/state.json (gitignored, project-scoped):

{
  "status": "running",
  "current_wave": 1,
  "total_waves": 4,
  "linear_project_id": "...",
  "linear_team_id": "...",
  "waves": {
    "0": { "issues": ["LIA-101", "LIA-102"], "status": "complete" },
    "1": { "issues": ["LIA-103", "LIA-104"], "status": "running" },
    "2": { "issues": ["LIA-106", "LIA-107"], "status": "pending" }
  }
}

Valid transitions: preflight → analyzing → issues_created → paused | wave_N → visual_gate → complete

Invalid (skill rejects):

• Skipping waves (paused → wave_2 when wave_1 incomplete)
• Resuming from complete (terminal state)