design-context-extract

デザインコンテキストの抽出

既存のアプリケーションから「デザイン DNA」（色、タイポグラフィ、余白、コンポーネントのパターン）を抽出し、構造化トークンとして出力します。

design-context-extract /tmp/screenshot.png       # From screenshot
design-context-extract /tmp/recording.mp4         # From screen recording (motion spec)
design-context-extract https://example.com        # From live URL
design-context-extract current project            # Scan project's existing styles

パイプライン

Input (screenshot/URL/project)
  │
  ▼
┌──────────────────────────────┐
│ Capture                       │  Screenshot or fetch HTML/CSS
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ Extract                       │  Stitch get_screen + generate_screen_from_text
│                               │  OR multimodal analysis (fallback)
│ → Colors (hex + oklch)        │
│ → Typography (families, scale)│
│ → Spacing (padding, gaps)     │
│ → Components (structure)      │
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ Output                        │  Choose format:
│ → design-tokens.json (W3C)    │
│ → @theme (Tailwind v4)        │
│ → tokens.css (CSS variables)  │
│ → Markdown spec               │
└──────────────────────────────┘

ステップ 0：入力とコンテキストの検出

INPUT = ""

# 1. Create main task IMMEDIATELY
TaskCreate(subject="Extract design context: {INPUT}", description="Extract design DNA", activeForm="Extracting design from {INPUT}")

# 2. Create subtasks for each phase
TaskCreate(subject="Detect input type and context", activeForm="Detecting input type")             # id=2
TaskCreate(subject="Capture source material", activeForm="Capturing source")                       # id=3
TaskCreate(subject="Extract design tokens", activeForm="Extracting tokens")                        # id=4
TaskCreate(subject="Choose output format and generate", activeForm="Generating output")            # id=5
TaskCreate(subject="Recommend shadcn/ui style", activeForm="Recommending style")                   # id=6

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Capture needs input type detected
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Extraction needs captured source
TaskUpdate(taskId="5", addBlockedBy=["4"])  # Output needs extracted tokens
TaskUpdate(taskId="6", addBlockedBy=["5"])  # Style recommendation needs output

# 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

# Determine input type
# "/path/to/file.png" → screenshot
# "/path/to/file.mp4|.mov|.webm|.gif" → screen recording (video pipeline)
# "http..." → URL
# "current project" → scan project styles

ステップ 1：ソースの取得

スクリーンショットの場合： 画像を直接読み取ります（Claude はマルチモーダルです）。貼り付けまたは添付した画像は Read ツールの画像と同じトークン予算に圧縮されるため（CC 2.1.97）、どちらのワークフローも効率は同じです。

解像度の上限（Opus 5.5 / CC 2.1.111+）： 入力の最大サイズは長辺 2,576 px（約 3.75 MP）です。Opus 4.6 の上限の約 3 倍です。高解像度化の恩恵が最も大きいのは、情報量の多いダッシュボード、ダークモードの UI、技術図です。これにより、以前はぼやけていた小さなラベル、間隔の目盛り、コンポーネントの境界も抽出時に読み取れます。1,024 px 未満の画像は拡大しないでください。元のビットマップが上限です。入力が 2,576 px を超える場合にのみサイズを変更してください。

URL の場合：

# If stitch available:
#   list_projects / get_project to locate the project
#   generate_screen_from_text once for the URL goal (can take minutes; DO NOT RETRY;
#     on timeout poll get_screen every 30 s up to 10 times)
#   list_screens, then get_screen(name="projects/{projectId}/screens/{screenId}")
#   fetch download URLs from the response
# If not: WebFetch the URL and analyze HTML/CSS

現在のプロジェクトの場合：

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("**/*.css")  # Look for design token files
Glob("**/theme.*")
# Read and analyze existing style definitions

画面録画（動画）の場合： 動き（イージング、スクロールの振り付け、トランジション）を含む唯一の入力モードです。ffmpeg／ffprobe が必要です（見つからない場合は、インストール方法を案内してスキップします）。

# 1. Probe: duration, dimensions, frame rate
ffprobe -v error -show_entries format=duration,size:stream=width,height,r_frame_rate -of json "$VIDEO"

# 2. Extract frames at timeline beats — NOT uniform thumbnails.
#    Pass A: 1fps sweep to locate transitions; Pass B: re-extract around detected beats.
mkdir -p "$SCRATCHPAD/video-frames"
ffmpeg -y -i "$VIDEO" -vf fps=1 "$SCRATCHPAD/video-frames/frame-%03d.jpg"
# For scroll-heavy or long videos also grab start / middle / end explicitly.

次に、抽出したフレームを読み取り（マルチモーダル）、次のレイヤーに分けて分析します。

レイヤー	取得する内容
レイアウト	ビューポートの構成、グリッド、固定領域、セクションの順序
モーション	表示タイミング、イージング曲線、視差効果、固定／スクラブするセクション、ホバー状態、ループ
ビジュアル	スクリーンショットと同じトークン抽出（色、書体、余白）
再構築	仕組みを特定します：CSS トランジション、IntersectionObserver、GSAP ScrollTrigger、video.currentTime のスクラブ、WebGL

動画入力では、トークン出力に加えて motion-spec.md も出力します。各インタラクションの継続時間（ms）、イージング、トリガー（スクロール／ホバー／読み込み）、および各項目の動きを抑えた場合の代替動作を記載します。動きを「スムーズ」や「良い」と表現しないでください。感覚的な表現を、仕組みと数値に置き換えてください。

ステップ 2：デザインコンテキストの抽出

stitch MCP が利用可能な場合：

# Live Stitch MCP tools (https://stitch.googleapis.com/mcp), matching
# design-context-extractor 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
#   - 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.
#
# Flow: generate_screen_from_text once (or reuse an existing screen) →
# list_screens → get_screen(name=...) → fetch download URLs for multimodal extract.
#
# Also consider Figma Dev Mode MCP as a complementary extraction path
# when the source is a Figma file:
#   - get_variable_defs    → design tokens straight from Figma variables
#   - get_design_context   → layout + typography + spacing
#   - search_design_system → locate existing tokens/components

stitch MCP が利用できない場合（代替手段）：

# Multimodal analysis of screenshot:
# - Identify dominant colors (sample from regions)
# - Detect font families and size hierarchy
# - Measure spacing patterns
# - Catalog component types (cards, buttons, headers, etc.)
#
# For URLs: parse CSS custom properties, Tailwind config, computed styles

抽出データの構造：

{
  "colors": {
    "primary": { "hex": "#3B82F6", "oklch": "oklch(0.62 0.21 255)" },
    "secondary": { "hex": "#10B981", "oklch": "oklch(0.69 0.17 163)" },
    "background": { "hex": "#FFFFFF" },
    "text": { "hex": "#1F2937" },
    "muted": { "hex": "#9CA3AF" }
  },
  "typography": {
    "heading": { "family": "Inter", "weight": 700 },
    "body": { "family": "Inter", "weight": 400 },
    "scale": [12, 14, 16, 18, 24, 30, 36, 48]
  },
  "spacing": {
    "base": 4,
    "scale": [4, 8, 12, 16, 24, 32, 48, 64]
  },
  "components": ["navbar", "hero", "card", "button", "footer"]
}

ステップ 3：出力形式の選択

AskUserQuestion(questions=[{
  "question": "Output format for extracted tokens?",
  "header": "Format",
  "options": [
    {"label": "Tailwind @theme (Recommended)", "description": "@theme block in the CSS entry (app.css) with extracted theme values"},
    {"label": "W3C Design Tokens", "description": "design-tokens.json following W3C DTCG spec"},
    {"label": "CSS Variables", "description": "tokens.css with CSS custom properties"},
    {"label": "Markdown spec", "description": "Human-readable design specification document"}
  ],
  "multiSelect": false
}])

Tailwind v4 は CSS ファーストです。テーマの値は @theme ブロックに記述し、tailwind.config.js は完全に無視されます（ui-components/rules/tailwind-v4-patterns.md を参照）。

/* app.css: the recommended Tailwind output */
@import "tailwindcss";

@theme {
  --color-primary: oklch(0.62 0.21 255);
  --font-sans: "Inter", system-ui, sans-serif;
  --spacing: 0.25rem;
}

レガシー（Tailwind v3 のみ）： プロジェクトが v3 に固定されている場合は、同じ値を theme.extend に設定した tailwind.config.ts を出力します。これは package.json で v3 固定を確認してから提案してください。デフォルトでは決して使用しません。

ステップ 4：出力の生成

選択した形式で抽出済みトークンを書き込みます。プロジェクトにすでにトークンがある場合は、新規分と既存分の差分を表示します。

ステップ 5：最適な shadcn/ui スタイルの提案

デザイン DNA の抽出後、抽出した特性を最適な shadcn/ui v4 スタイルに対応付けます。

# Map extracted design DNA → shadcn style recommendation
radius = extracted["radius"]      # e.g., "large", "pill", "none", "small"
density = extracted["spacing"]    # e.g., "generous", "balanced", "compact", "dense"
elevation = extracted["shadows"]  # e.g., "layered", "subtle", "none"

STYLE_MAP = {
    # (radius, density, elevation) → style
    ("pill/large", "generous", "layered"):  "Luma — polished, macOS-like",
    ("medium",     "balanced", "subtle"):   "Vega — general purpose",
    ("medium",     "compact",  "subtle"):   "Nova — dense dashboards",
    ("large",      "generous", "subtle"):   "Maia — soft, consumer-facing",
    ("none/sharp", "balanced", "none"):     "Lyra — editorial, dev tools",
    ("small",      "dense",    "none"):     "Mira — ultra-dense data",
}
# Present recommendation with the style picker URL:
# "Based on extracted design DNA, recommended style: Luma"
# "Pick and install: https://ui.shadcn.com/create  (select 'Luma' style)"
# Apply to existing project (CLI v4 apply command, Apr 2026):
# "$ npx shadcn@latest apply luma"

スキップ条件： ユーザーが生のトークンのみを必要としている場合（shadcn プロジェクトではない場合）は、このステップをスキップします。

アンチパターン

• 絶対に 実際のソースを分析せずに色を推測しないでください。精密に抽出してください。
• 絶対に oklch への変換を省略しないでください。すべての色に oklch 相当値が必要です。
• 絶対に フラットなトークン構造を出力しないでください。3 層の階層（グローバル／エイリアス／コンポーネント）を使用してください。

品質基準

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

• すべての色が実際のソースからサンプリングされ、oklch 相当値と役割名を持っている
• タイポグラフィには、ファミリー、ウェイト、観測されたサイズのスケールが含まれている。「モダンなサンセリフ体」だけでは不十分です。
• 選択した形式で出力ファイルが書き込まれ、構文解析できることを確認済み（JSON／TS／CSS）
• 動画入力の場合：motion-spec.md に各インタラクションの仕組み、継続時間、イージング、動きを抑えた場合の代替動作が記載されている
• プロジェクトにすでにトークンがある場合：新規分と既存分の差分が表示されている

関連スキル

• ork:design-to-code — これをステージ 1 として使用する完全なパイプライン
• ork:design-system-tokens — トークンのアーキテクチャと W3C 仕様への準拠
• ork:component-search — 抽出したパターンに合うコンポーネントを検索