design-spec-extraction

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:

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": { "$v