Design to Code
Convert visual designs into production-ready React components using a four-stage pipeline: Extract, Match, Adapt, Render.
/ork:design-to-code screenshot of hero section
/ork:design-to-code /tmp/mockup.png
/ork:design-to-code https://example.com/pricing
Pipeline Overview
Input (screenshot/description/URL)
│
▼
┌─────────────────────────┐
│ Stage 1: EXTRACT │ Stitch MCP → HTML + design context
│ build_site │ Generate up to 5 screens from prompt
│ get_screen_code / _image │ Extract React/HTML + PNG for each
└─────────┬───────────────┘
│
▼
┌─────────────────────────┐
│ Stage 2: MATCH │ 1. Storybook MCP → check existing
│ Storybook-first lookup │ 2. 21st.dev → search public registry
│ Then 21st.dev fallback │ 3. Filesystem → grep codebase
└─────────┬───────────────┘
│
▼
┌─────────────────────────┐
│ Stage 3: ADAPT │ Merge extracted design + matched
│ Apply project tokens │ components into final implementation
│ Customize to codebase │ Tests + types included
└─────────┬───────────────┘
│
▼
┌─────────────────────────┐
│ Stage 4: RENDER │ Register as json-render catalog entry
│ Generate Zod schema │ Same component → PDF, email, video
│ Add to defineCatalog() │ Multi-surface reuse via MCP output
└─────────┬───────────────┘
│
▼
┌─────────────────────────┐
│ Stage 4b: VERIFY │ Storybook MCP → self-healing loop
│ run-story-tests(a11y) │ Fix violations, retry (max 3)
│ preview-stories │ Embed live preview in chat
└─────────────────────────┘
Argument Resolution
INPUT = ""
Step 0: Detect Input Type and Project Context
TaskCreate(subject="Design to code: {INPUT}", description="Four-stage pipeline: extract, match, adapt, render", activeForm="Converting design to code")
TaskCreate(subject="Extract design context", activeForm="Extracting design context")
TaskCreate(subject="Match components (Storybook-first)", activeForm="Matching components")
TaskCreate(subject="Adapt to project tokens and conventions", activeForm="Adapting to project")
TaskCreate(subject="Register in json-render catalog", activeForm="Registering in catalog")
TaskCreate(subject="Verify with Storybook self-healing", activeForm="Verifying component")
TaskUpdate(taskId="3", addBlockedBy=["2"])
TaskUpdate(taskId="4", addBlockedBy=["3"])
TaskUpdate(taskId="5", addBlockedBy=["4"])
TaskUpdate(taskId="6", addBlockedBy=["5"])
TaskUpdate(taskId="2", status="in_progress")
TaskUpdate(taskId="2", status="completed")
Grep("@theme", glob="**/*.css")
Glob("**/tailwind.config.*")
Glob("**/tokens.css")
Glob("**/.tokens.json")
Glob("**/components.json")
Stage 1: Extract Design Context
If stitch MCP is available:
If stitch MCP is NOT available (fallback):
Resolution budget (Opus 5 / CC 2.1.111+): Mockups up to 2,576 px on the long edge (~3.75 MP, 3× prior ceiling) produce better component boundaries and spacing extraction. Full-page desktop mockups at native resolution are now in-budget; previously they had to be resized down and lost fine detail. Only downscale inputs exceeding 2,576 px.
Extract and produce:
- Color palette (hex/oklch values)
- Typography (font families, sizes, weights)
- Spacing patterns (padding, margins, gaps)
- Component structure (headers, cards, buttons, etc.)
- Layout pattern (grid, flex, sidebar, etc.)
Stage 2: Match Components (Storybook-First)
Priority 1 — Check project's own Storybook (if storybook-mcp available):
inventory = list-all-documentation()
for component in inventory.components:
if component matches extracted_description:
details = get-documentation(id=component.id)
Priority 2 — Search 21st.dev (if no Storybook match and 21st-dev-magic available):
Priority 3 — Filesystem fallback (if no MCP servers available):
Grep(pattern="export.*function|export.*const", glob="**/*.tsx")
Glob("**/components/ui/*.tsx")
Present matches to user:
AskUserQuestion(questions=[{
"question": "Which component approach for {component_name}?",
"header": "Component",
"options": [
{"label": "Reuse from Storybook", "description": "{existing_component} — props: {prop_list}"},
{"label": "Use 21st.dev match", "description": "{matched_component_name} — {match_score}% match"},
{"label": "Adapt from codebase", "description": "Modify existing {existing_component}"},
{"label": "Generate from scratch", "description": "Build new component from extracted design"}
],
"multiSelect": false
}])
Stage 3: Adapt to Project
Merge the extracted design context with matched/generated components:
- Apply project tokens — Replace hardcoded colors/spacing with project's design tokens
- Apply shadcn style classes — If
SHADCN_STYLE detected, use style-correct class names:
- Luma:
rounded-4xl buttons/cards, shadow-md + ring-1 ring-foreground/5, gap-6 py-6
- Nova: compact
px-2 py-1, reduced margins, tight spacing
- Lyra:
rounded-none, sharp edges, monospace-friendly
- Mira: ultra-dense, minimal padding
- Match naming conventions — Follow project's component naming patterns
- Add TypeScript types — Full type safety with Zod validation for any data props
- Include tests — MSW handlers for API-backed components, render tests for static
- Responsive — Mobile-first with breakpoints matching project's system
Output Structure
src/components/
└── {ComponentName}/
├── {ComponentName}.tsx # Main component
├── {ComponentName}.test.tsx # Tests
└── index.ts # Barrel export
Stage 4: Register in json-render Catalog
After ADAPT produces a working React component, register it as a json-render catalog entry for multi-surface reuse.
- Generate Zod schema — Derive a Zod schema from the component's TypeScript props
- Add catalog entry — Register in the project's
defineCatalog() call with props schema and children declaration
- Verify rendering — Confirm the component renders correctly through
<Render catalog={catalog} /> path
import { z } from 'zod'
const componentSchema = z.object({
title: z.string().max(100),
variant: z.enum(['default', 'featured']).default('default'),
})
import { defineCatalog } from '@json-render/core'
import { existingCatalog } from './catalog'
export const catalog = {
...existingCatalog,
{ComponentName}: {
props: componentSchema,
children: true,
},
}
Enables: same component output to PDF, email, video, or MCP response — no reimplementation needed.
Skip condition: If the project has no json-render dependency or catalog, inform the user and skip catalog registration. The component from Stage 3 is still fully usable standalone.
Stage 4b: Self-Healing Verification (if storybook-mcp available)
After generating the component, verify it with Storybook MCP:
Write("src/components/{Name}/{Name}.stories.tsx", story_code)
results = run-story-tests(
stories=[{ "storyId": "{name}--default" }],
a11y=True
)
if not results.all_passed:
for failure in results.failures:
Edit("src/components/{Name}/{Name}.tsx", fix)
results = run-story-tests(stories=[...], a11y=True)
previews = preview-stories(stories=[
{ "absoluteStoryPath": "src/components/{Name}/{Name}.stories.tsx",
"exportName": "Default" }
])
Skip condition: If storybook-mcp is not available, skip verification. The component is still usable — just not auto-verified.
Graceful Degradation
| stitch | 21st-dev-magic | storybook-mcp | Behavior |
|---|
| Available | Available | Available | Full pipeline: extract + Storybook-first match + adapt + render + self-heal verify |
| Available | Available | Unavailable | Extract + 21st.dev match + adapt + render (no verification) |
| Available | Unavailable | Available | Extract + Storybook match + adapt + verify |
| Unavailable | Available | Available | Description-based search + Storybook check + adapt + verify |
| Unavailable | Unavailable | Available | Filesystem search + Storybook verify only |
| Unavailable | Unavailable | Unavailable | Manual analysis + generate from scratch (still works) |
The skill ALWAYS produces output regardless of MCP availability. Storybook MCP adds component reuse (Stage 2) and self-healing verification (Stage 4b) — skipping them still yields a working component.
Anti-Patterns
- NEVER output components with hardcoded colors — use design tokens
- NEVER skip TypeScript types — all props must be typed
- NEVER generate without checking existing project patterns first
- NEVER ignore the project's existing component library structure
Quality Bar
Done means all of these hold:
- Generated components carry no hardcoded colors or literal spacing — every visual value resolves through project design tokens.
- Every prop is TypeScript-typed; data-bearing props carry Zod validation.
- Stage 2 checked existing components (Storybook, then 21st.dev, then filesystem) before generating from scratch, and the chosen match source is named.
- When storybook-mcp is available, the component passes
run-story-tests (component + a11y) before handoff, self-healing within at most 3 attempts.
- Output follows the
{ComponentName}/ structure — component, test, and barrel export.
- Each skipped stage (json-render catalog, Storybook verify) is taken ONLY when its dependency is absent, and the skip is stated with its reason.
Related Skills
storybook-mcp-integration — Storybook MCP tools: component discovery, testing, previewscomponent-search — Search 21st.dev registry standalonedesign-context-extract — Extract design DNA from screenshots/ork:design-stylecards — named aesthetic recipes (shadow stacks, glass surfaces, gradients, type scales) for the polish pass on generated componentsdesign-system-tokens — Token architecture and managementstorybook-testing — CSF3 patterns, Vitest integration, Chromatic TurboSnapjson-render-catalog — Catalog definition, Zod schemas, defineCatalog patternsmulti-surface-render — Render catalog entries to PDF, email, video, MCP
