design-to-code · yonatangross — Claude Code skill: what it does, how to install
design-to-code — a skill for Claude Code that turns screenshots, descriptions, and URLs into React components. Assembles UI elements while reusing existing Storybook pieces and design tokens.
MIT 116 installs ★ 305 updated 2026-11-14
npx skills add yonatangross/orchestkit --skill design-to-code -a claude-codeWhat design-to-code does
The skill converts mockups or page URLs into React components through a pipeline of extraction, matching, adapting, and rendering. It checks local Storybook stories first, falls back to the public 21st.dev registry, and inspects the codebase to reuse existing components before writing new code.
Tokens are resolved from Tailwind v3 or v4 stylesheets along with shadcn/ui themes declared in components.json. When storybook-mcp is active, the skill runs an automated self-healing loop that checks accessibility test violations and retries fixes up to three times.
Full functionality relies on optional MCP servers: stitch, 21st-dev-magic, and storybook-mcp. The get_component tool on 21st.dev allows only 2 requests daily on the free plan.
What it helps with
- generate React components from screenshots, URLs, or text prompts
- search and reuse existing elements from Storybook and 21st.dev
- align generated markup with Tailwind tokens and shadcn/ui styling
- run automated accessibility test loops via Storybook MCP
Example prompts for the agent
- Convert the hero section mockup from
/tmp/mockup.pnginto a React component - Build a pricing table component matching the UI at
https://example.com/pricing - Implement a dashboard card from this screenshot using existing project tokens
How to install design-to-code
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill design-to-code -a claude-code2Manually: put the files in place
~/.claude/skills/design-to-code/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/design-to-code/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill design-to-code -a codex2Manually: put the files in place
.agents/skills/design-to-code/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill design-to-code -a cursor2Manually: put the files in place
.cursor/skills/design-to-code/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install yonatangross/orchestkit src/skills/design-to-code2Manually: put the files in place
.github/skills/design-to-code/SKILL.md1Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill design-to-code -a gemini-cli2Platform CLI
gemini skills install https://github.com/yonatangross/orchestkit --path src/skills/design-to-codeManually: put the files in place
.devin/skills/design-to-code/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add yonatangross/orchestkit --skill design-to-code -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about design-to-code
How to install design-to-code in Claude Code?
Run npx skills add yonatangross/orchestkit --skill design-to-code -a claude-code. The skill configuration saves to ~/.claude/skills/design-to-code/SKILL.md.
What does design-to-code do?
It processes image files, live URLs, or text descriptions to generate production React components. The workflow matches components against Storybook and applies project tokens before rendering.
What are the requirements for design-to-code?
It requires Claude Code version 2.1.277 or higher. Optional external integrations include Google Stitch MCP, 21st-dev-magic, and storybook-mcp.
Source text
SKILL.md · MIT
---
name: design-to-code
license: MIT
compatibility: "Claude Code 2.1.277+. Optional: stitch (official Google Stitch), 21st-dev-magic, storybook-mcp (@storybook/addon-mcp) MCP servers."
description: "Mockup or screenshot to a React component via Stitch, 21st.dev and Storybook MCP, reusing existing components. For Storybook MCP tools alone, use storybook-mcp-integration."
argument-hint: "[screenshot-path | description | url]"
context: fork
# user-typed commands stay interactive; CC >= 2.1.218 backgrounds forks by default (#3093)
background: false
user-invocable: true
effort: high
model: sonnet
allowed-tools: "Read Write Edit Glob Grep Bash WebFetch WebSearch AskUserQuestion Agent TaskCreate TaskUpdate TaskList mcp__21st-dev-magic__search mcp__21st-dev-magic__search_picker mcp__21st-dev-magic__get_component mcp__21st-dev-magic__get_theme mcp__21st-dev-magic__get_usage mcp__stitch__list_projects mcp__plugin_hq-ext_stitch__list_projects mcp__stitch__get_project mcp__plugin_hq-ext_stitch__get_project mcp__stitch__list_screens mcp__plugin_hq-ext_stitch__list_screens mcp__stitch__get_screen mcp__plugin_hq-ext_stitch__get_screen mcp__stitch__generate_screen_from_text mcp__plugin_hq-ext_stitch__generate_screen_from_text mcp__storybook-mcp__list-all-documentation mcp__storybook-mcp__get-documentation mcp__storybook-mcp__preview-stories mcp__storybook-mcp__run-story-tests"
# "Priority 2 — Search 21st.dev" (below) named the server but granted none of
# its tools, so that whole branch was unreachable. Read-only surface only.
# search/search_picker/metadata are unmetered; get_component is the only metered
# tool (2/day on free, unlimited on paid — call get_usage, do not assume).
# Browse first regardless: the USER should pick, not the model.
# Stitch: body names these five (live stitch.googleapis.com/mcp roster).
# Grant BOTH prefixes: standalone stitch (mcp__stitch__*) and hq-ext plugin
# (mcp__plugin_hq-ext_stitch__*). See https://code.claude.com/docs/en/mcp-servers
# Storybook MCP: body calls these when storybook-mcp is available.
skills:
- design-system-tokens
- component-search
- storybook-mcp-integration
- design-context-extract
- remember
- memory
metadata:
category: workflow-automation
mcp-server: stitch, 21st-dev-magic, storybook-mcp
version: "1.0.1"
author: "OrchestKit"
complexity: "complex"
tags: "design-to-code, stitch, 21st-dev, ui-generation, mockup, component, react, frontend"
triggers:
keywords: ["design to code", "mockup to code", "screenshot to component", "convert design", "implement ui from", "build from mockup"]
examples:
- "convert this screenshot into a React component"
- "implement the UI from this Figma mockup"
- "build a component from this design"
anti-triggers: [explore, assess, review, brainstorm, extract design]
paths:
- "src/components/**/*.{tsx,css}"
- "**/*design-tokens*"
- ".storybook/**"
---
# Design to Code
Convert visual designs into production-ready React components using a four-stage pipeline: Extract, Match, Adapt, Render.
```bash
design-to-code screenshot of hero section # From description
design-to-code /tmp/mockup.png # From screenshot
design-to-code https://example.com/pricing # From URL
```
## Pipeline Overview
```
Input (screenshot/description/URL)
│
▼
┌─────────────────────────┐
│ Stage 1: EXTRACT │ Stitch MCP → screen details + URLs
│ generate_screen_from_text│ Create screens from a text prompt
│ get_screen │ Screen details with download URLs
└─────────┬───────────────┘
│
▼
┌─────────────────────────┐
│ 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
```python
INPUT = "" # Full argument string
# Detect input type:
# - Starts with "/" or "~" or contains ".png"/".jpg" → screenshot file path
# - Starts with "http" → URL to screenshot or live page
# - Otherwise → natural language description
```
## Step 0: Detect Input Type and Project Context
```python
# 1. Create main task IMMEDIATELY
TaskCreate(subject="Design to code: {INPUT}", description="Four-stage pipeline: extract, match, adapt, render", activeForm="Converting design to code")
# 2. Create subtasks for each stage
TaskCreate(subject="Extract design context", activeForm="Extracting design context") # id=2
TaskCreate(subject="Match components (Storybook-first)", activeForm="Matching components") # id=3
TaskCreate(subject="Adapt to project tokens and conventions", activeForm="Adapting to project") # id=4
TaskCreate(subject="Register in json-render catalog", activeForm="Registering in catalog") # id=5
TaskCreate(subject="Verify with Storybook self-healing", activeForm="Verifying component") # id=6
# 3. Set dependencies for sequential stages
TaskUpdate(taskId="3", addBlockedBy=["2"]) # Match needs extracted design context
TaskUpdate(taskId="4", addBlockedBy=["3"]) # Adapt needs matched components
TaskUpdate(taskId="5", addBlockedBy=["4"]) # Render needs adapted component
TaskUpdate(taskId="6", addBlockedBy=["5"]) # Verify needs rendered component
# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress") # When starting
TaskUpdate(taskId="2", status="completed") # When done — repeat for each subtask
# Detect project's design system
Grep("@theme", glob="**/*.css") # Tailwind v4: theme lives in CSS, not a config file
Glob("**/tailwind.config.*") # Tailwind v3 only (v4 ignores this file)
Glob("**/tokens.css")
Glob("**/.tokens.json")
# Read existing tokens if found → used in Stage 3
# Detect shadcn/ui style (v4 style system)
Glob("**/components.json")
# Read → style field (e.g., "radix-luma", "base-nova")
# Determines class names: Luma=rounded-4xl, Nova=compact, Lyra=sharp
# Store: SHADCN_STYLE for Stage 2 filtering + Stage 3 adaptation
```
## Stage 1: Extract Design Context
**If stitch MCP is available:**
```python
# Live Stitch MCP tools (https://stitch.googleapis.com/mcp), matching
# design-context-extractor / design-system-architect agent grants:
# - list_projects() / get_project(projectId)
# - list_screens(projectId)
# - get_screen(name="projects/{projectId}/screens/{screenId}")
# ONE required param: name. Returns screen details including
# download URLs (fetch those URLs; no separate code/image export tool)
# - generate_screen_from_text(projectId, prompt)
# quota-costing write; can take a few minutes. DO NOT RETRY.
# On timeout: poll get_screen(name=...) every 30 s, up to 10 times.
#
# For screenshot/URL input:
# 1. list_projects / get_project to locate the Stitch project
# 2. generate_screen_from_text with the extraction goal (or use an
# existing screen if the project already has one). Never retry.
# 3. list_screens, then get_screen(name="projects/{projectId}/screens/{screenId}")
# 4. Fetch the download URLs (or Read multimodal) for token extraction
#
# For description input:
# 1. generate_screen_from_text(projectId, prompt=<description>) once
# 2. On timeout, poll get_screen(name=...) every 30 s up to 10 times
# 3. Otherwise get_screen(name="projects/{projectId}/screens/{screenId}")
#
# DESIGN.md import (Stitch Pro, Mar 2026+):
# Prefer upload_design_md / create_design_system_from_design_md when
# those tools are available on the live server; otherwise regenerate
# via generate_screen_from_text from the DESIGN.md contents (once, no retry).
```
**If stitch MCP is NOT available (fallback):**
```python
# For screenshot: Read the image file directly (Claude is multimodal)
# Analyze layout, colors, typography, spacing from the image
# For URL: WebFetch the page, extract HTML structure
# For description: Skip extraction, proceed to Stage 2 with description
```
> **Resolution budget (Opus 5.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):**
```python
# Search the project's existing component library first
inventory = list-all-documentation() # Full component + docs manifest
for component in inventory.components:
if component matches extracted_description:
details = get-documentation(id=component.id)
# Returns: props schema, stories, usage patterns
# → Existing component found — skip external search
```
**Priority 2 — Search 21st.dev (if no Storybook match and 21st-dev-magic available):**
```python
# Search 21st.dev for matching components
# Use the component descriptions from Stage 1
# Example: "animated pricing table with toggle"
# Filter: React, Tailwind CSS, shadcn/ui compatible
# If SHADCN_STYLE detected, prefer components matching style's visual language
# (e.g., Luma → rounded/pill-shaped, Nova → compact/dense, Lyra → sharp/boxy)
```
**Priority 3 — Filesystem fallback (if no MCP servers available):**
```python
# Search for components in the project's existing codebase
Grep(pattern="export.*function|export.*const", glob="**/*.tsx")
# Check for shadcn/ui components
Glob("**/components/ui/*.tsx")
# Generate from scratch if no matches found
```
Present matches to user:
```python
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:
1. **Apply project tokens** — Replace hardcoded colors/spacing with project's design tokens
2. **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
3. **Match naming conventions** — Follow project's component naming patterns
4. **Add TypeScript types** — Full type safety with Zod validation for any data props
5. **Include tests** — MSW handlers for API-backed components, render tests for static
6. **Responsive** — Mobile-first with breakpoints matching project's system
7. **Polish from a named recipe**: when the design calls for elevation, a glass surface, a border gradient or a type scale that the project tokens do not carry, take the exact values from `/ork-extras:design-stylecards` instead of inventing them
### 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.
1. **Generate Zod schema** — Derive a Zod schema from the component's TypeScript props
2. **Add catalog entry** — Register in the project's `defineCatalog()` call with props schema and children declaration
3. **Verify rendering** — Confirm the component renders correctly through `<Render catalog={catalog} />` path
```typescript
import { z } from 'zod'
// Zod schema derived from {ComponentName}Props
const componentSchema = z.object({
title: z.string().max(100),
variant: z.enum(['default', 'featured']).default('default'),
// ... props from the adapted component
})
// Add to project catalog
import { defineCatalog } from '@json-render/core'
import { existingCatalog } from './catalog'
export const catalog = {
...existingCatalog,
{ComponentName}: {
props: componentSchema,
children: true, // or false for leaf components
},
}
```
**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:
```python
# 1. Write CSF3 story for the new component
Write("src/components/{Name}/{Name}.stories.tsx", story_code)
# 2. Run tests via MCP (component + a11y)
results = run-story-tests(
stories=[{ "storyId": "{name}--default" }],
a11y=True
)
# 3. Handle failures — self-heal up to 3 attempts
if not results.all_passed:
for failure in results.failures:
# Read violation details, fix the component
Edit("src/components/{Name}/{Name}.tsx", fix)
# Re-run failing tests
results = run-story-tests(stories=[...], a11y=True)
# 4. Preview — embed live story in chat for user confirmation
previews = preview-stories(stories=[
{ "absoluteStoryPath": "src/components/{Name}/{Name}.stories.tsx",
"exportName": "Default" }
])
# Include preview URLs in response for visual confirmation
```
**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, previews
- `component-search` — Search 21st.dev registry standalone
- `design-context-extract` — Extract design DNA from screenshots
- `design-stylecards` — named aesthetic recipes (shadow stacks, glass surfaces, gradients, type scales) for the polish pass on generated components
- `design-system-tokens` — Token architecture and management
- `storybook-testing` — CSF3 patterns, Vitest integration, Chromatic TurboSnap
- `json-render-catalog` — Catalog definition, Zod schemas, defineCatalog patterns
- `multi-surface-render` — Render catalog entries to PDF, email, video, MCP
© OrchestKit · MIT · yonatangross/orchestkit
Similar skills
All skills for Frontend and UI →design-to-code by other authors comes first.