design-context-extract

# 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. 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 5 / 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:
#