design-to-code

デザインからコードへ

Extract、Match、Adapt、Render の4段階のパイプラインを使用して、ビジュアルデザインを本番環境に対応した React コンポーネントに変換します。

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

パイプラインの概要

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
└─────────────────────────┘

引数の解決

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

ステップ 0：入力タイプとプロジェクトのコンテキストを検出する

# 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

ステージ 1：デザインのコンテキストを抽出する

stitch MCP が利用可能な場合：

# 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).

stitch MCP が利用できない場合（フォールバック）：

# 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

解像度の上限（Opus 5.5 / CC 2.1.111+）： 長辺が 2,576 px 以下のモックアップ（約 3.75 MP、従来の上限の3倍）では、コンポーネントの境界と間隔をより正確に抽出できます。ネイティブ解像度のデスクトップ全ページモックアップも、現在は上限内で処理できます。以前は縮小する必要があり、細部が失われていました。2,576 px を超える入力のみ縮小してください。

抽出して、以下を作成します。

• カラーパレット（hex／oklch 値）
• タイポグラフィ（フォントファミリー、サイズ、太さ）
• 間隔のパターン（パディング、マージン、ギャップ）
• コンポーネントの構造（ヘッダー、カード、ボタンなど）
• レイアウトのパターン（グリッド、フレックス、サイドバーなど）

ステージ 2：コンポーネントを照合する（Storybook を優先）

優先度 1 — プロジェクト独自の Storybook を確認する（storybook-mcp が利用可能な場合）：

# 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

優先度 2 — 21st.dev を検索する（Storybook に一致するものがなく、21st-dev-magic が利用可能な場合）：

# 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)

優先度 3 — ファイルシステムにフォールバックする（MCP サーバーが利用できない場合）：

# 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

一致した候補をユーザーに提示します。

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
}])

ステージ 3：プロジェクトに合わせて調整する

抽出したデザインのコンテキストを、一致したコンポーネントまたは生成したコンポーネントに統合します。

1. プロジェクトのトークンを適用する — ハードコードされた色や間隔を、プロジェクトのデザイントークンに置き換えます
2. shadcn のスタイルクラスを適用する — SHADCN_STYLE が検出された場合は、スタイルに合ったクラス名を使用します。
   • Luma：ボタン／カードに rounded-4xl、shadow-md と ring-1 ring-foreground/5、gap-6 py-6
   • Nova：コンパクトな px-2 py-1、マージンを減らし、間隔を狭くする
   • Lyra：rounded-none、鋭いエッジ、モノスペースフォントに適したスタイル
   • Mira：極めて高密度で、最小限のパディング
3. 命名規則を合わせる — プロジェクトのコンポーネント命名パターンに従います
4. TypeScript の型を追加する — データ用の props には Zod によるバリデーションを含め、完全な型安全性を確保します
5. テストを含める — API を利用するコンポーネントには MSW ハンドラー、静的コンポーネントにはレンダリングテストを用意します
6. レスポンシブにする — プロジェクトのシステムに合ったブレークポイントで、モバイルファーストにします

出力構造

src/components/
  └── {ComponentName}/
      ├── {ComponentName}.tsx       # Main component
      ├── {ComponentName}.test.tsx  # Tests
      └── index.ts                 # Barrel export

ステージ 4：json-render カタログに登録する

ADAPT によって動作する React コンポーネントが作成されたら、複数のサーフェスで再利用できるよう、json-render のカタログエントリーとして登録します。

1. Zod スキーマを生成する — コンポーネントの TypeScript props から Zod スキーマを導出します
2. カタログエントリーを追加する — props スキーマと children の宣言を含めて、プロジェクトの defineCatalog() 呼び出しに登録します
3. レンダリングを検証する — <Render catalog={catalog} /> の経路でコンポーネントが正しくレンダリングされることを確認します

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
  },
}

実現できること： 同じコンポーネントの出力を PDF、メール、動画、または MCP レスポンスに利用できます。再実装は不要です。

スキップ条件： プロジェクトに json-render の依存関係またはカタログがない場合は、ユーザーに知らせてカタログ登録をスキップします。ステージ 3 のコンポーネントは、単体でも引き続き完全に利用できます。

ステージ 4b：自己修復検証（storybook-mcp が利用可能な場合）

コンポーネントを生成した後、Storybook MCP で検証します。

# 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

スキップ条件： storybook-mcp が利用できない場合は、検証をスキップします。コンポーネントは引き続き利用できますが、自動検証は行われません。

Graceful Degradation

stitch	21st-dev-magic	storybook-mcp	動作
Available	Available	Available	完全なパイプライン：抽出 + Storybook 優先の照合 + 適応 + レンダリング + 自己修復検証
Available	Available	Unavailable	抽出 + 21st.dev での照合 + 適応 + レンダリング（検証なし）
Available	Unavailable	Available	抽出 + Storybook での照合 + 適応 + 検証
Unavailable	Available	Available	説明ベースの検索 + Storybook の確認 + 適応 + 検証
Unavailable	Unavailable	Available	ファイルシステム検索 + Storybook による検証のみ
Unavailable	Unavailable	Unavailable	手動分析 + ゼロから生成（引き続き動作します）

このスキルは、MCP が利用可能かどうかにかかわらず、必ず出力を生成します。Storybook MCP はコンポーネントの再利用（Stage 2）と自己修復検証（Stage 4b）を追加します。これらをスキップしても、動作するコンポーネントを生成できます。

アンチパターン

• 絶対にハードコードされた色を使ったコンポーネントを出力しないでください。デザイントークンを使用してください。
• 絶対にTypeScript の型を省略しないでください。すべての props に型を指定してください。
• 絶対に既存のプロジェクトパターンを先に確認せずに生成しないでください。
• 絶対にプロジェクト既存のコンポーネントライブラリの構成を無視しないでください。

品質基準

以下のすべてを満たせば完了です。

• 生成されたコンポーネントにはハードコードされた色や固定のスペーシング値がなく、すべての視覚的な値がプロジェクトのデザイントークンを通じて解決されます。
• すべての prop に TypeScript の型が指定され、データを含む prop には Zod による検証が適用されています。
• ゼロから生成する前に、Stage 2 で既存のコンポーネント（Storybook、次に 21st.dev、次にファイルシステム）を確認し、選択した照合元を明記しています。
• storybook-mcp が利用可能な場合、引き渡し前にコンポーネントが run-story-tests（コンポーネント + a11y）に合格し、自己修復の試行回数が最大 3 回以内です。
• 出力は {ComponentName}/ の構成（コンポーネント、テスト、barrel export）に従っています。
• スキップする各ステージ（json-render カタログ、Storybook の検証）は、依存関係がない場合に限ってスキップし、その理由を明記しています。

関連スキル

• storybook-mcp-integration — Storybook MCP ツール：コンポーネントの検出、テスト、プレビュー
• component-search — 21st.dev レジストリを単独で検索
• design-context-extract — スクリーンショットからデザインの DNA を抽出
• design-stylecards — 生成されたコンポーネントの仕上げ工程で使う、名前付きの美的レシピ（シャドウスタック、ガラス風サーフェス、グラデーション、文字サイズのスケール）
• design-system-tokens — トークンのアーキテクチャと管理
• storybook-testing — CSF3 のパターン、Vitest の統合、Chromatic TurboSnap
• json-render-catalog — カタログ定義、Zod スキーマ、defineCatalog のパターン
• multi-surface-render — カタログのエントリーを PDF、メール、動画、MCP 向けにレンダリング