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 transition、IntersectionObserver、GSAP ScrollTrigger、video.currentTime scrub、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，则生成包含相同值的 tailwind.config.ts，并将其放在 theme.extend 下。只有在确认 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 值
• 绝不输出扁平的令牌结构——应使用三层层级（全局/别名/组件）

质量标准

满足以下所有条件即为完成：

• 每种颜色都从实际来源中采样，具有对应的 oklch 值，并标注了用途名称
• 字体排版包含字体系列、字重和观察到的字号比例——不能只写“现代无衬线字体”
• 已按所选格式写入输出文件，并验证其可解析（JSON/TS/CSS）
• 对于视频输入：motion-spec.md 为每种交互标明了实现机制、时长、缓动和减少动态效果回退方案
• 如果项目已有令牌，已展示新增内容与现有内容的差异

相关技能

• ork:design-to-code — 完整流程，将此技能作为第 1 阶段
• ork:design-system-tokens — 令牌架构和 W3C 规范合规性
• ork:component-search — 查找与提取模式相匹配的组件