design-spec-extraction

What this skill does

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