---
id: yonatangross/orchestkit/design-context-extract
version: "f1f5eda5"
license: MIT
install: manual
updated: 2026-07-28
---

# design-context-extract — Design Context Extract analyzes existing applications to capture their visual foundation—colors, fonts, spacing, and component structure—and exports the results as structured design tokens or Tailwind configuration. It works from screenshots, live URLs, screen recordings (including motion specs), or your project's existing styles, making it easy to audit designs or bootstrap a design system from a live reference.

Publisher: yonatangross · Stars: 208 · Updated: 2026-07-28

Install (manual): `git clone https://github.com/yonatangross/orchestkit`

## SKILL.md

# Design Context Extract

Extract the "Design DNA" from existing applications — colors, typography, spacing, and component patterns — and output as structured tokens.

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

## Pipeline

```
Input (screenshot/URL/project)
  │
  ▼
┌──────────────────────────────┐
│ Capture                       │  Screenshot or fetch HTML/CSS
└──────────┬───────────────────┘
           │
           ▼
┌──────────────────────────────┐
│ Extract                       │  Stitch extract_design_context
│                               │  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               │
└──────────────────────────────┘
```

## Step 0: Detect Input and Context

```python
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. Before starting each task, verify it's unblocked
task = TaskGet(taskId="2")  # Verify blockedBy is empty

# 5. 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
```

## Step 1: Capture Source

**For screenshots:** Read the image directly (Claude is multimodal). Pasted/attached images are compressed to the same token budget as Read tool images (CC 2.1.97), so both workflows are equally efficient.

> **Resolution budget (Opus 4.8 / CC 2.1.111+):** Max input is **2,576 px on the long edge** (~3.75 MP) — roughly 3× the Opus 4.6 ceiling. Dense dashboards, dark-mode UIs, and technical diagrams benefit the most from the higher ceiling; extraction reads tiny labels, spacing ticks, and component boundaries that were previously blurred. Below 1,024 px, don't upscale — the source bitmap is the ceiling. Resize only when input exceeds 2,576 px.

**For URLs:**
```python
# If stitch available: call build_site(prompt=<url + extraction goal>)
#   then get_screen_code / get_screen_image per generated screen
# If not: WebFetch the URL and analyze HTML/CSS
```

**For current project:**
```python
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
```

**For screen recordings (video):** the only input mode that carries motion — easing, scroll
choreography, transitions. Requires `ffmpeg`/`ffprobe` (skip with an install hint if missing).

```bash
# 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.
```

Then Read the extracted frames (multimodal) and analyze in layers:

| Layer | What to capture |
|-------|-----------------|
| Layout | viewport framing, grids, sticky zones, section order |
| Motion | reveal timing, easing curves, parallax, pinned/scrubbed sections, hover states, loops |
| Visual | same token extraction as screenshots (colors, type, spacing) |
| Rebuild | name the mechanism: CSS transition, IntersectionObserver, GSAP ScrollTrigger, `video.currentTime` scrub, WebGL |

Video inputs additionally emit a **motion-spec.md** alongside the token output: per-interaction
durations (ms), easing, trigger (scroll/hover/load), and a reduced-motion fallback for each entry.
Never describe motion as "smooth" or "nice" — convert taste into mechanism + numbers.

## Step 2: Extract Design Context

**If stitch MCP is available:**
```python
# Official Stitch MCP tools (stitch.withgoogle.com/docs/mcp):
#   - build_site(prompt)          → generates the target design
#   - get_screen_code(screenId)   → React/HTML output per screen
#   - get_screen_image(screenId)  → PNG rasterization per screen
#
# 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
```

**If stitch MCP is NOT available (fallback):**
```python
# 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
```

Extracted data structure:
```json
{
  "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"]
}
```

## Step 3: Choose Output Format

```python
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 is CSS-first: theme values go in an `@theme` block, and `tailwind.config.js`
is ignored entirely (see `ui-components/rules/tailwind-v4-patterns.md`).

```css
/* 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;
}
```

**Legacy (Tailwind v3 only):** if the project pins v3, emit `tailwind.config.ts` with the
same values under `theme.extend`. Offer this only after confirming the v3 pin in
`package.json`. It is never the default.

## Step 4: Generate Output

Write the extracted tokens in the chosen format. If the project already has tokens, show a diff of what's new vs existing.

## Step 5: Recommend Best-Fit shadcn/ui Style

After extracting design DNA, map the extracted characteristics to the best-fit shadcn/ui v4 style:

```python
# 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"
```

**Skip condition:** If the user only needs raw tokens (not a shadcn project), skip this step.

## Anti-Patterns

- **NEVER** guess colors without analyzing the actual source — use precise extraction
- **NEVER** skip the oklch conversion — all colors must have oklch equivalents
- **NEVER** output flat token structures — use three-tier hierarchy (global/alias/component)

## Quality Bar

Done means all of these hold:
- Every color was sampled from the actual source, has an oklch equivalent, and carries a role name
- Typography includes family, weight, and the observed size scale — not "modern sans-serif"
- Output file written in the chosen format and verified to parse (JSON/TS/CSS)
- Video inputs: motion-spec.md names mechanism + duration + easing + reduced-motion fallback per interaction
- If the project already had tokens, the diff of new-vs-existing was shown

## Related Skills

- `ork:design-to-code` — Full pipeline that uses this as Stage 1
- `ork:design-system-tokens` — Token architecture and W3C spec compliance
- `ork:component-search` — Find components that match extracted patterns


[View on SkillFed](https://skillfed.io/yonatangross/orchestkit/design-context-extract) · [View on GitHub](https://github.com/yonatangross/orchestkit)