Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add yonatangross/orchestkit --skill design-to-code -a claude-code
Open on GitHub

What 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.png into 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-code

2Manually: put the files in place

~/.claude/skills/design-to-code/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/design-to-code/

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.

design-to-code Atharvsinh-codez The design-to-code Claude Code skill turns visual references into frontend code. It activates for requests to recreate a site, implement a mockup, adapt a page, or fix visual mismatches. CX Codex +1 ★ 150repo stars stitch::react-components official google-labs-code stitch::react-components is a Claude Code skill that turns Stitch designs into modular Vite and React components and syncs existing components with updated designs. CX Codex +1 50,400installs stitch::react-native official google-labs-code stitch::react-native is a Claude Code skill that converts Stitch HTML designs into React Native components with StyleSheet or syncs code to the latest design. CX Codex +1 10,000installs figma-design-to-code official Figma figma-design-to-code is a Codex skill that turns Figma designs into project code. It runs for design implementation requests and calls get_design_context before code is written. CX Codex GP ChatGPT +1 30installs design-systems Mindrally design-systems walks your agent through design tokens, a component library and accessibility rules in one project. CX Codex +1 956installs 21st-registry 21st-dev 21st-registry is a Claude Code skill that publishes components, themes, and templates to 21st.dev. It activates for requests to share work, change a listing, or locate an older component. CX Codex +1 2,300installs Design System taste f Design System taste — a prompt for ChatGPT that enforces pragmatic design system standards, tokens, accessibility, and component architecture. GP ChatGPT ★ 178,201repo stars

From the same set86

The whole set →
ai-ui-generation ai-ui-generation — a skill for Claude Code and Codex that enforces rules for generating, reviewing, and integrating AI-built UI components. Triggers on UI component creation and MCP visual rendering. CX Codex +1 123installs product-analytics The product-analytics skill evaluates A/B tests, cohort retention, and funnels. It helps explain adoption changes, conversion losses, and experiment outcomes. CX Codex +1 120installs testing-perf The testing-perf skill for Claude Code runs load and performance tests with k6 and Locust and parallelizes pytest with xdist. It activates when writing load tests or speeding up test suite runs. CX Codex +1 120installs chain-patterns chain-patterns — a set of patterns for multi-stage pipelines: MCP checks, handoff files, checkpoint recovery, isolated worktree agents, and cron monitoring. CX Codex +1 118installs testing-unit The testing-unit skill provides patterns for unit tests, HTTP mocks, fixtures, and test data in Vitest, Jest, and pytest. It applies while writing tests or setting up test doubles. CX Codex +1 116installs design-context-extract design-context-extract extracts colors, typography, spacing, components, and motion from screenshots, URLs, or recordings. It returns tokens or Tailwind-ready output. CX Codex +1 112installs component-search The component-search Claude Code skill searches 21st.dev for React components and ranks the matches. It runs when a request asks for a UI component or a replacement. CX Codex +1 106installs mcp-visual-output The mcp-visual-output skill for Claude Code transforms MCP tool JSON results into interactive dashboards. It activates when visual data presentation is more effective than plain text output. CX Codex +1 105installs

Project sponsors

Companies that keep this analytics open