---
name: design-spec-extraction
description: Extract comprehensive JSON design specifications from visual sources including Figma exports, UI mockups, screenshots, or live website captures. Produces W3C DTCG-compliant output with component trees, suitable for code generation, design documentation, and developer handoff.
---

# Design Specification Extraction

Extract comprehensive, production-ready JSON design specifications from visual inputs using a 7-pass serial subtask architecture that ensures complete coverage and cross-validation.

## When to Use This Skill

- Extracting design tokens from Figma exports or screenshots
- Converting visual mockups into structured component specifications
- Creating developer handoff documentation from designs
- Generating design system documentation from existing UIs
- Preparing design data for code generation tools
- Analyzing website screenshots for design reverse-engineering

## Output Format

The extraction produces JSON following the W3C Design Tokens Community Group (DTCG) 2025.10 format with extensions:

- **$version**: Schema version
- **$source**: Metadata (type, dimensions, extraction timestamp)
- **tokens**: Design tokens (colors, typography, spacing, sizing, shadows, radii)
- **components**: Hierarchical component tree with bounding boxes
- **accessibility**: WCAG analysis, contrast issues, semantic structure
- **$extensions**: Layout, component catalog, confidence scores

## CRITICAL: File-Based Architecture

**EVERY pass MUST write its output to a JSON file on disk.** This is non-negotiable.

### Directory Structure

Before starting extraction, create the output directory:

```bash
mkdir -p .design-specs/{project-name}
```

### Required File Outputs

| Pass | Output File | Description |
|------|-------------|-------------|
| 1 | `.design-specs/{project}/pass-1-layout.json` | Layout and structure |
| 2 | `.design-specs/{project}/pass-2-colors.json` | Color tokens |
| 3 | `.design-specs/{project}/pass-3-typography.json` | Typography tokens |
| 4 | `.design-specs/{project}/pass-4-components.json` | Component tree |
| 5 | `.design-specs/{project}/pass-5-spacing.json` | Spacing and dimensions |
| 6 | `.design-specs/{project}/pass-6-states.json` | States and accessibility |
| 7 | `.design-specs/{project}/design-spec.json` | **Final consolidated output** |

### Why File-Based?

1. **Persistence**: Each pass result is saved, enabling resumption if interrupted
2. **Debugging**: Intermediate files allow inspection of each extraction phase
3. **Validation**: Each JSON file can be validated independently
4. **Context Passing**: Subtask agents read previous pass files directly
5. **Audit Trail**: Complete record of extraction process

## Multipass Architecture

The extraction uses 7 serial passes. Each pass MUST:
1. Read previous pass JSON files from disk
2. Perform its analysis
3. **WRITE its output to the designated JSON file**
4. Complete before the next pass begins

```
Screenshot Input
      |
      v
[Pass 1] Source Analysis & Layout  -----> pass-1-layout.json
      |
      v
[Pass 2] Color & Visual Style      -----> pass-2-colors.json
      |
      v
[Pass 3] Typography Analysis       -----> pass-3-typography.json
      |
      v
[Pass 4] Component Detection       -----> pass-4-components.json
      |
      v
[Pass 5] Spacing & Dimensions      -----> pass-5-spacing.json
      |
      v
[Pass 6] States & Accessibility    -----> pass-6-states.json
      |
      v
[Pass 7] Consolidation             -----> design-spec.json (FINAL)
```

---

## Pass 1: Source Analysis & Layout Structure

**Objective**: Establish foundational understanding of the design source and spatial organization.

### Subtask Agent Prompt

```
You are Pass 1 of a 7-pass design specification extraction system. Your focus: LAYOUT AND STRUCTURE ONLY.

## CRITICAL REQUIREMENT
You MUST write your output to a JSON file. This is mandatory - do not just return JSON in your response.

OUTPUT FILE: `.design-specs/{project}/pass-1-layout.json`

Use the Write tool to save your analysis as valid JSON to this file.

## Input
- Screenshot: [attached image]

## Your Task

Analyze the screenshot and extract:

### 1. Source Metadata
- Identify source type: Figma export, Sketch export, website screenshot, mockup, or wireframe
- Detect dimensions and estimate device class (mobile/tablet/desktop)
- Note any visible design tool artifacts (rulers, grids, selection boxes)

### 2. Layout Type Detection
Determine the primary layout strategy:
- Single-column centered layout
- Multi-column grid (count columns, estimate gutters)
- Sidebar + main content
- Dashboard/admin layout
- Full-bleed/edge-to-edge

### 3. Region Identification
Map the major layout regions with bounding boxes:
- Header (position, height, sticky?)
- Navigation (type: sidebar, topnav, or none)
- Main content area
- Footer
- Any overlays, modals, or floating elements

### 4. Grid System Analysis
- Identify underlying grid (12-column, 4-column, etc.)
- Measure or estimate gutter width
- Note container max-width if visible

## Output Format
Return JSON:
{
  "$schema": "pass-1-layout",
  "$source": {
    "type": "figma-export|website-screenshot|mockup|...",
    "dimensions": { "width": N, "height": N, "aspectRatio": "W:H", "deviceClass": "..." },
    "confidence": 0.0-1.0
  },
  "layout": {
    "type": "single-column|multi-column|sidebar|...",
    "regions": [
      { "name": "header", "bounds": {"x":0,"y":0,"width":W,"height":H}, "sticky": true|false },
      { "name": "navigation", "type": "sidebar|topnav|none", "bounds": {...} },
      { "name": "main", "bounds": {...} },
      { "name": "footer", "bounds": {...}, "present": true|false }
    ],
    "gridSystem": {
      "columns": N,
      "gutter": "Npx",
      "margin": "Npx",
      "maxWidth": "Npx"
    }
  },
  "containers": [
    {
      "id": "container-N",
      "bounds": { "x": N, "y": N, "width": N, "height": N },
      "layout": "grid|flex|block",
      "parent": "parent-id|null",
      "childCount": N
    }
  ],
  "sections": [
    {
      "id": "section-N",
      "purpose": "hero|features|testimonials|cta|...",
      "bounds": {...}
    }
  ]
}

Use pixel values. Be precise with bounds. Note confidence level for uncertain areas.

## FINAL STEP - MANDATORY
Use the Write tool to save this JSON to: `.design-specs/{project}/pass-1-layout.json`
Do NOT proceed without writing the file. Confirm the file was written successfully.
```

---

## Pass 2: Color & Visual Style Extraction

**Objective**: Extract complete color palette with semantic mappings.

### Subtask Agent Prompt

```
You are Pass 2 of a 7-pass design specification extraction system. Your focus: COLOR EXTRACTION.

## CRITICAL REQUIREMENT
You MUST write your output to a JSON file. This is mandatory - do not just return JSON in your response.

OUTPUT FILE: `.design-specs/{project}/pass-2-colors.json`

First, read the Pass 1 output: `.design-specs/{project}/pass-1-layout.json`
Then use the Write tool to save your analysis as valid JSON.

## Input
- Screenshot: [attached image]
- Layout data from Pass 1: Read from `.design-specs/{project}/pass-1-layout.json`

## Your Task

Extract ALL colors visible in this design:

### 1. Background Colors (by region)
- Page background
- Section/card backgrounds
- Header/footer backgrounds
- Modal/overlay backgrounds
- Input field backgrounds
- Button backgrounds (all variants)

### 2. Foreground Colors (text and icons)
- Primary heading text
- Body text
- Secondary/muted text
- Link text (if distinguishable)
- Icon colors
- Placeholder text

### 3. Border Colors
- Card/container borders
- Input field borders (default, focus, error states if visible)
- Divider/separator colors

### 4. Feedback Colors
- Error/danger indicators
- Success indicators
- Warning indicators
- Info indicators

### 5. Interactive Colors
- Primary action color (main CTA buttons)
- Secondary action color
- Hover states (if visible)
- Focus indicators

### Color Value Extraction
For each color, provide:
- Hex value (best estimate: #RRGGBB)
- Where it appears (semantic context)
- Suggested token name following pattern: color.[category].[variant]

## Output Format
Return JSON:
{
  "$schema": "pass-2-colors",
  "tokens": {
    "colors": {
      "primitive": {
        "blue": {
          "500": { "$value": "#3B82F6", "$type": "color", "$description": "Primary blue" },
          "600": { "$value": "#2563EB", "$type": "color", "$description": "Primary blue dark" }
        },
        "gray": {
          "50": { "$value": "#F9FAFB", "$type": "color" },
          "100": { "$value": "#F3F4F6", "$type": "color" },
          "500": { "$value": "#6B7280", "$type": "color" },
          "900": { "$value": "#111827", "$type": "color" }
        }
      },
      "semantic": {
        "background": {
          "default": { "$value": "{colors.primitive.gray.50}", "$type": "color", "$description": "Page background" },
          "elevated": { "$value": "#FFFFFF", "$type": "color", "$description": "Card surfaces" }
        },
        "foreground": {
          "default": { "$value": "{colors.primitive.gray.900}", "$type": "color", "$description": "Primary text" },
          "muted": { "$value": "{colors.primitive.gray.500}", "$type": "color", "$description": "Secondary text" }
        },
        "interactive": {
          "primary": { "$value": "{colors.primitive.blue.500}", "$type": "color", "$description": "Primary buttons, links" },
          "primary-hover": { "$value": "{colors.primitive.blue.600}", "$type": "color", "$description": "Primary hover" }
        },
        "border": {
          "default": { "$value": "{colors.primitive.gray.200}", "$type": "color", "$description": "Subtle borders" },
          "focus": { "$value": "{colors.primitive.blue.500}", "$type": "color", "$description": "Focus rings" }
        },
        "feedback": {
          "error": { "$value": "#EF4444", "$type": "color", "$description": "Error states" },
          "success": { "$value": "#22C55E", "$type": "color", "$description": "Success states" },
          "warning": { "$value": "#F59E0B", "$type": "color", "$description": "Warning states" },
          "info": { "$value": "#3B82F6", "$type": "color", "$description": "Info states" }
        }
      }
    }
  },
  "shadows": [
    {
      "name": "elevation-sm",
      "$type": "shadow",
      "$value": {
        "offsetX": "0px",
        "offsetY": "1px",
        "blur": "2px",
        "spread": "0px",
        "color": "rgba(0,0,0,0.05)"
      },
      "$description": "Subtle elevation"
    }
  ],
  "gradients": [],
  "componentColorMap": {
    "button-primary": {
      "background": "{colors.semantic.interactive.primary}",
      "text": "#FFFFFF",
      "border": "transparent"
    }
  }
}

Use DTCG $value and $type syntax. Include $description for AI readability.

## FINAL STEP - MANDATORY
Use the Write tool to save this JSON to: `.design-specs/{project}/pass-2-colors.json`
Do NOT proceed without writing the file. Confirm the file was written successfully.
```

---

## Pass 3: Typography Analysis

**Objective**: Extract complete typography system including fonts, sizes, weights, and text styles.

### Subtask Agent Prompt

```
You are Pass 3 of a 7-pass design specification extraction system. Your focus: TYPOGRAPHY.

## CRITICAL REQUIREMENT
You MUST write your output to a JSON file. This is mandatory - do not just return JSON in your response.

OUTPUT FILE: `.design-specs/{project}/pass-3-typography.json`

First, read previous pass outputs:
- `.design-specs/{project}/pass-1-layout.json`
- `.design-specs/{project}/pass-2-colors.json`

Then use the Write tool to save your analysis as valid JSON.

## Input
- Screenshot: [attached image]
- Layout data from Pass 1: Read from `.design-specs/{project}/pass-1-layout.json`
- Color data from Pass 2: Read from `.design-specs/{project}/pass-2-colors.json`

## Your Task

Extract ALL typography information:

### 1. Font Family Detection
Analyze visible text to identify:
- Primary font family (body text, UI elements)
- Secondary font family (headings, if different)
- Monospace font (code blocks, if present)
- Is it serif, sans-serif, or display?
- Best guess at specific font name

### 2. Text Style Inventory
For EACH distinct text style visible, extract:

**Headings:**
- Display/Hero text (largest)
- H1, H2, H3, etc.
- Card titles
- Section headers

**Body:**
- Body large (lead paragraphs)
- Body regular (standard text)
- Body small (captions)

**UI Text:**
- Button labels
- Form labels
- Input text
- Link text
- Navigation items
- Badge/tag text

For each style, estimate:
- Font size (in px)
- Font weight (100-900 or light/regular/medium/bold)
- Line height (ratio like 1.5 or pixels)
- Letter spacing (normal, tight, wide)
- Text color (reference token from Pass 2)
- Text transform (none, uppercase, capitalize)

### 3. Typographic Hierarchy
- How many distinct size levels are there?
- What is the size scale ratio?

## Output Format
Return JSON:
{
  "$schema": "pass-3-typography",
  "tokens": {
    "typography": {
      "fontFamilies": {
        "sans": { "$value": ["Inter", "system-ui", "sans-serif"], "$type": "fontFamily", "$description": "Primary font" },
        "mono": { "$value": ["JetBrains Mono", "monospace"], "$type": "fontFamily", "$description": "Code font" }
      },
      "fontWeights": {
        "regular": { "$value": 400, "$type": "fontWeight" },
        "medium": { "$value": 500, "$type": "fontWeight" },
        "semibold": { "$value": 600, "$type": "fontWeight" },
        "bold": { "$value": 700, "$type": "fontWeight" }
      },
      "fontSizes": {
        "xs": { "$value": "12px", "$type": "dimension" },
        "sm": { "$value": "14px", "$type": "dimension" },
        "base": { "$value": "16px", "$type": "dimension" },
        "lg": { "$value": "18px", "$type": "dimension" },
        "xl": { "$value": "20px", "$type": "dimension" },
        "2xl": { "$value": "24px", "$type": "dimension" },
        "3xl": { "$value": "30px", "$type": "dimension" },
        "4xl": { "$value": "36px", "$type": "dimension" },
        "5xl": { "$value": "48px", "$type": "dimension" }
      },
      "lineHeights": {
        "tight": { "$value": 1.25, "$type": "number" },
        "normal": { "$value": 1.5, "$type": "number" },
        "relaxed": { "$value": 1.75, "$type": "number" }
      },
      "letterSpacing": {
        "tighter": { "$value": "-0.05em", "$type": "dimension" },
        "normal": { "$value": "0em", "$type": "dimension" },
        "wide": { "$value": "0.05em", "$type": "dimension" }
      },
      "textStyles": {
        "display": {
          "$type": "typography",
          "$value": {
            "fontFamily": "{typography.fontFamilies.sans}",
            "fontSize": "{typography.fontSizes.5xl}",
            "fontWeight": "{typography.fontWeights.bold}",
            "lineHeight": "{typography.lineHeights.tight}",
            "letterSpacing": "{typography.letterSpacing.tighter}"
          },
          "$description": "Hero headlines"
        },
        "heading-1": {
          "$type": "typography",
          "$value": {
            "fontFamily": "{typography.fontFamilies.sans}",
            "fontSize": "{typography.fontSizes.4xl}",
            "fontWeight": "{typography.fontWeights.bold}",
            "lineHeight": "{typography.lineHeights.tight}"
          },
          "$description": "Page titles"
        },
        "heading-2": {
          "$type": "typography",
          "$value": {
            "fontFamily": "{typography.fontFamilies.sans}",
            "fontSize": "{typography.fontSizes.2xl}",
            "fontWeight": "{typography.fontWeights.semibold}",
            "lineHeight": "{typography.lineHeights.tight}"
          },
          "$description": "Section headings"
        },
        "body": {
          "$type": "typography",
          "$value": {
            "fontFamily": "{typography.fontFamilies.sans}",
            "fontSize": "{typography.fontSizes.base}",
            "fontWeight": "{typography.fontWeights.regular}",
            "lineHeight": "{typography.lineHeights.normal}"
          },
          "$description": "Standard body text"
        },
        "body-small": {
          "$type": "typography",
          "$value": {
            "fontFamily": "{typography.fontFamilies.sans}",
            "fontSize": "{typography.fontSizes.sm}",
            "fontWeight": "{typography.fontWeights.regular}",
            "lineHeight": "{typography.lineHeights.normal}"
          },
          "$description": "Secondary text, captions"
        },
        "button-label": {
          "$type": "typography",
          "$value": {
            "fontFamily": "{typography.fontFamilies.sans}",
            "fontSize": "{typography.fontSizes.sm}",
            "fontWeight": "{typography.fontWeights.medium}",
            "lineHeight": "{typography.lineHeights.tight}"
          },
          "$description": "Button text"
        }
      }
    }
  },
  "typeScale": {
    "ratio": 1.25,
    "base": "16px",
    "steps": [12, 14, 16, 20, 24, 30, 36, 48]
  }
}

Reference tokens using {token.path} syntax per DTCG specification.

## FINAL STEP - MANDATORY
Use the Write tool to save this JSON to: `.design-specs/{project}/pass-3-typography.json`
Do NOT proceed without writing the file. Confirm the file was written successfully.
```

---

## Pass 4: Component Detection & Classification

**Objective**: Build hierarchical component tree with atomic design classification.

### Subtask Agent Prompt

```
You are Pass 4 of a 7-pass design specification extraction system. Your focus: COMPONENT DETECTION.

## CRITICAL REQUIREMENT
You MUST write your output to a JSON file. This is mandatory - do not just return JSON in your response.

OUTPUT FILE: `.design-specs/{project}/pass-4-components.json`

First, read previous pass outputs:
- `.design-specs/{project}/pass-1-layout.json`
- `.design-specs/{project}/pass-2-colors.json`
- `.design-specs/{project}/pass-3-typography.json`

Then use the Write tool to save your analysis as valid JSON.

## Input
- Screenshot: [attached image]
- Layout data from Pass 1: Read from `.design-specs/{project}/pass-1-layout.json`
- Color data from Pass 2: Read from `.design-specs/{project}/pass-2-colors.json`
- Typography data from Pass 3: Read from `.design-specs/{project}/pass-3-typography.json`

## Your Task

Identify and classify ALL UI components:

### 1. Atomic Components (Atoms)
Simple, indivisible elements:
- Buttons (all variants: primary, secondary, icon, ghost)
- Icons (note semantic meaning)
- Inputs (text, password, search)
- Checkboxes, radios, toggles
- Labels and text elements
- Images and avatars
- Badges and tags
- Dividers

### 2. Molecular Components (Molecules)
Simple combinations of atoms:
- Form fields (label + input + helper)
- Search bars
- Navigation items
- Breadcrumbs
- Menu items
- List items

### 3. Organism Components (Organisms)
Complex, distinct UI sections:
- Navigation bars
- Headers
- Cards (all variants)
- Forms
- Tables
- Footers
- Hero sections

### 4. For Each Component, Extract:
- Unique ID (generated)
- Component type name
- Atomic level (atom/molecule/organism)
- Bounding box (x, y, width, height)
- Visual styles (link to tokens where possible)
- Content (text, icons)
- Current state (default, hover, active, disabled)
- Child components (for molecules/organisms)

### 5. Component Catalog
Create definitions for reusable component types:
- Suggested HTML element
- ARIA role
- Props/variants
- Token mappings

## Output Format
Return JSON:
{
  "$schema": "pass-4-components",
  "components": {
    "$root": {
      "id": "root",
      "type": "Page",
      "bounds": {"x":0,"y":0,"width":W,"height":H},
      "children": [
        {
          "id": "header-1",
          "type": "Header",
          "name": "Main Navigation Header",
          "atomicLevel": "organism",
          "bounds": {"x":0,"y":0,"width":W,"height":80},
          "styles": {