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:

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?

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

Multipass Architecture

The extraction uses 7 serial passes. Each pass MUST:

Read previous pass JSON files from disk
Perform its analysis
WRITE its output to the designated JSON file
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": {
            "background": { "color": "#FFFFFF", "tokenRef": "{colors.semantic.background.elevated}" },
            "shadow": { "tokenRef": "{shadows.elevation-sm}" }
          },
          "children": [
            {
              "id": "logo-1",
              "type": "Image",
              "atomicLevel": "atom",
              "bounds": {"x":24,"y":24,"width":120,"height":32},
              "content": { "alt": "Company Logo" }
            },
            {
              "id": "nav-1",
              "type": "Navigation",
              "atomicLevel": "molecule",
              "bounds": {...},
              "children": [
                {
                  "id": "nav-item-1",
                  "type": "NavItem",
                  "atomicLevel": "atom",
                  "content": { "text": "Home" },
                  "states": { "current": "active" }
                }
              ]
            },
            {
              "id": "btn-signin",
              "type": "Button",
              "atomicLevel": "atom",
              "bounds": {...},
              "content": { "text": "Sign In" },
              "variants": { "variant": "secondary", "size": "md" },
              "states": { "current": "default" }
            }
          ]
        }
      ]
    },
    "catalog": {
      "Button": {
        "name": "Button",
        "category": "action",
        "atomicLevel": "atom",
        "htmlElement": "button",
        "ariaRole": "button",
        "variants": [
          { "name": "variant", "values": ["primary", "secondary", "ghost", "destructive"] },
          { "name": "size", "values": ["sm", "md", "lg"] }
        ],
        "tokens": {
          "background": "{colors.semantic.interactive.primary}",
          "color": "#FFFFFF",
          "borderRadius": "{radii.md}",
          "paddingX": "{spacing.4}",
          "paddingY": "{spacing.2}"
        },
        "instances": ["btn-signin", "btn-cta-1"]
      },
      "Card": {
        "name": "Card",
        "category": "layout",
        "atomicLevel": "organism",
        "htmlElement": "article",
        "ariaRole": "article",
        "variants": [
          { "name": "variant", "values": ["default", "elevated", "outlined"] }
        ],
        "tokens": {
          "background": "{colors.semantic.background.elevated}",
          "borderRadius": "{radii.lg}",
          "shadow": "{shadows.elevation-md}",
          "padding": "{spacing.6}"
        },
        "instances": ["card-1", "card-2"]
      }
    }
  },
  "statistics": {
    "totalComponents": N,
    "byType": {
      "Button": N,
      "Card": N,
      "Input": N
    },
    "byAtomicLevel": {
      "atom": N,
      "molecule": N,
      "organism": N
    }
  }
}

Be exhaustive. Every visible interactive or content element must be cataloged.

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

Pass 5: Spacing & Dimensions

Objective: Extract spacing scale, sizing tokens, borders, and radii.

Subtask Agent Prompt

You are Pass 5 of a 7-pass design specification extraction system. Your focus: SPACING AND DIMENSIONS.

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

First, read previous pass outputs:
- `.design-specs/{project}/pass-1-layout.json`
- `.design-specs/{project}/pass-4-components.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`
- Component data from Pass 4: Read from `.design-specs/{project}/pass-4-components.json`

## Your Task

Measure and systematize ALL spacing and dimension values:

### 1. Spacing Scale
Analyze gaps between elements to find the base spacing unit:
- Measure space between text and container edges (padding)
- Measure space between stacked elements (stack spacing)
- Measure space between inline elements (inline spacing)
- Measure grid/flex gaps

Identify the spacing scale:
- What is the base unit? (4px, 8px typical)
- What multipliers are used? (1x, 2x, 3x, 4x, 6x, 8x, 12x, 16x)

### 2. Component Sizing
Extract size patterns:
- Button heights (small, medium, large)
- Input field heights
- Icon sizes
- Avatar sizes
- Container max-widths

### 3. Border Properties
For each border type:
- Border width (1px, 2px, etc.)
- Border radius values (small, medium, large, full/circular)

### 4. Map to Component Styles
Link spacing values to specific components from Pass 4

## Output Format
Return JSON:
{
  "$schema": "pass-5-spacing",
  "tokens": {
    "spacing": {
      "scale": {
        "0": { "$value": "0px", "$type": "dimension" },
        "1": { "$value": "4px", "$type": "dimension", "$description": "Minimal spacing, icon gaps" },
        "2": { "$value": "8px", "$type": "dimension", "$description": "Tight spacing, inline elements" },
        "3": { "$value": "12px", "$type": "dimension" },
        "4": { "$value": "16px", "$type": "dimension", "$description": "Default component padding" },
        "5": { "$value": "20px", "$type": "dimension" },
        "6": { "$value": "24px", "$type": "dimension", "$description": "Card padding, form gaps" },
        "8": { "$value": "32px", "$type": "dimension", "$description": "Section spacing" },
        "10": { "$value": "40px", "$type": "dimension" },
        "12": { "$value": "48px", "$type": "dimension", "$description": "Large section gaps" },
        "16": { "$value": "64px", "$type": "dimension", "$description": "Hero section padding" }
      },
      "semantic": {
        "inset": {
          "card": { "$value": "{spacing.scale.6}", "$type": "dimension", "$description": "Card internal padding" },
          "section": { "$value": "{spacing.scale.8}", "$type": "dimension", "$description": "Section padding" }
        },
        "stack": {
          "tight": { "$value": "{spacing.scale.2}", "$type": "dimension", "$description": "Compact vertical spacing" },
          "default": { "$value": "{spacing.scale.4}", "$type": "dimension", "$description": "Standard vertical spacing" }
        },
        "gap": {
          "grid": { "$value": "{spacing.scale.6}", "$type": "dimension", "$description": "Card grid gap" }
        }
      }
    },
    "sizing": {
      "component": {
        "button-sm": { "$value": "32px", "$type": "dimension" },
        "button-md": { "$value": "40px", "$type": "dimension" },
        "button-lg": { "$value": "48px", "$type": "dimension" },
        "input-md": { "$value": "40px", "$type": "dimension" }
      },
      "icon": {
        "sm": { "$value": "16px", "$type": "dimension" },
        "md": { "$value": "20px", "$type": "dimension" },
        "lg": { "$value": "24px", "$type": "dimension" }
      },
      "avatar": {
        "sm": { "$value": "32px", "$type": "dimension" },
        "md": { "$value": "40px", "$type": "dimension" },
        "lg": { "$value": "48px", "$type": "dimension" }
      }
    },
    "radii": {
      "none": { "$value": "0px", "$type": "dimension" },
      "sm": { "$value": "4px", "$type": "dimension" },
      "md": { "$value": "8px", "$type": "dimension", "$description": "Default for cards, buttons" },
      "lg": { "$value": "12px", "$type": "dimension" },
      "xl": { "$value": "16px", "$type": "dimension" },
      "full": { "$value": "9999px", "$type": "dimension", "$description": "Pills, avatars" }
    },
    "borders": {
      "width": {
        "thin": { "$value": "1px", "$type": "dimension", "$description": "Default borders" },
        "medium": { "$value": "2px", "$type": "dimension", "$description": "Focus rings, emphasis" }
      }
    },
    "container": {
      "maxWidth": {
        "sm": { "$value": "640px", "$type": "dimension" },
        "md": { "$value": "768px", "$type": "dimension" },
        "lg": { "$value": "1024px", "$type": "dimension" },
        "xl": { "$value": "1280px", "$type": "dimension" }
      }
    }
  },
  "componentSpacing": {
    "button": {
      "paddingX": "{spacing.scale.4}",
      "paddingY": "{spacing.scale.2}",
      "gap": "{spacing.scale.2}"
    },
    "card": {
      "padding": "{spacing.scale.6}",
      "gap": "{spacing.scale.4}"
    },
    "input": {
      "paddingX": "{spacing.scale.3}",
      "paddingY": "{spacing.scale.2}"
    }
  }
}

Detect patterns and express them. Use 4px or 8px base unit convention.

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

Pass 6: Interactive States & Accessibility

Objective: Analyze interactive states and accessibility compliance.

Subtask Agent Prompt

You are Pass 6 of a 7-pass design specification extraction system. Your focus: STATES AND ACCESSIBILITY.

## 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-6-states.json`

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

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

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

## Your Task

### 1. Interactive States (infer from visual cues)
For each interactive component type, define state variations:
- Default/rest state
- Hover state (if visible or inferable - darken 5-10%)
- Active/pressed state (darken 10-15%, reduce shadow)
- Focus state (focus ring, 2px outline)
- Disabled state (opacity 0.5-0.6, muted colors)
- Loading state

State Changes:
- Color changes
- Shadow changes
- Border changes
- Opacity changes
- Transform effects

### 2. Accessibility Analysis

**Contrast Ratios:**
For each text-on-background combination:
- Calculate/estimate contrast ratio
- Check against WCAG AA (4.5:1 normal, 3:1 large)
- Check against WCAG AAA (7:1 normal, 4.5:1 large)
- Flag any failures

**Color Accessibility:**
- Red/green combinations (protanopia/deuteranopia)
- Blue/yellow combinations (tritanopia)
- Information conveyed by color alone

### 3. Semantic Hierarchy
- What should be the h1? (single per page)
- Heading hierarchy (h1 > h2 > h3, no skips)
- Landmark regions (header, nav, main, aside, footer)

### 4. Interactive Element Analysis
For each interactive element:
- Does it have visible text or clear label?
- What ARIA label might be needed?
- Is the clickable area sufficient (44x44px touch target)?
- Is there a visible focus indicator?

## Output Format
Return JSON:
{
  "$schema": "pass-6-states",
  "states": {
    "button": {
      "primary": {
        "default": {
          "background": "{colors.semantic.interactive.primary}",
          "text": "#FFFFFF",
          "border": "transparent",
          "shadow": "{shadows.elevation-sm}"
        },
        "hover": {
          "background": "{colors.semantic.interactive.primary-hover}",
          "shadow": "{shadows.elevation-md}",
          "$description": "Darken 10%, increase elevation"
        },
        "active": {
          "background": "{colors.primitive.blue.700}",
          "shadow": "none",
          "transform": "scale(0.98)"
        },
        "focus": {
          "outline": "2px solid {colors.semantic.interactive.primary}",
          "outlineOffset": "2px"
        },
        "disabled": {
          "background": "{colors.primitive.gray.300}",
          "text": "{colors.primitive.gray.500}",
          "cursor": "not-allowed",
          "opacity": 0.6
        }
      }
    },
    "input": {
      "default": {
        "border": "{colors.semantic.border.default}",
        "background": "#FFFFFF"
      },
      "hover": {
        "border": "{colors.primitive.gray.400}"
      },
      "focus": {
        "border": "{colors.semantic.border.focus}",
        "outline": "2px solid {colors.semantic.interactive.primary}",
        "outlineOffset": "-1px"
      },
      "error": {
        "border": "{colors.semantic.feedback.error}",
        "background": "#FEF2F2"
      },
      "disabled": {
        "background": "{colors.primitive.gray.100}",
        "opacity": 0.6
      }
    }
  },
  "transitions": {
    "fast": {
      "$type": "transition",
      "$value": {
        "duration": "150ms",
        "timingFunction": [0.4, 0, 0.2, 1]
      },
      "$description": "Micro-interactions, hovers"
    },
    "normal": {
      "$type": "transition",
      "$value": {
        "duration": "200ms",
        "timingFunction": [0.4, 0, 0.2, 1]
      },
      "$description": "Standard transitions"
    },
    "slow": {
      "$type": "transition",
      "$value": {
        "duration": "300ms",
        "timingFunction": [0.4, 0, 0.2, 1]
      },
      "$description": "Page transitions, modals"
    }
  },
  "accessibility": {
    "contrastIssues": [
      {
        "element": "components.btn-secondary",
        "foreground": "#9CA3AF",
        "background": "#FFFFFF",
        "ratio": 2.8,
        "required": 4.5,
        "wcagLevel": "AA",
        "passes": false,
        "recommendation": "Darken text to #6B7280 for 4.5:1 ratio"
      }
    ],
    "colorBlindnessIssues": [
      {
        "type": "deuteranopia",
        "affectedElements": ["error-state", "success-state"],
        "recommendation": "Add icons alongside color indicators"
      }
    ],
    "semanticHierarchy": {
      "headings": [
        { "level": 1, "text": "Welcome to Our Platform", "componentRef": "hero-title" },
        { "level": 2, "text": "Features", "componentRef": "features-heading" }
      ],
      "landmarks": [
        { "role": "banner", "componentRef": "header-1" },
        { "role": "navigation", "componentRef": "nav-1" },
        { "role": "main", "componentRef": "main-content" },
        { "role": "contentinfo", "componentRef": "footer-1" }
      ]
    },
    "touchTargets": {
      "minimumSize": "44px",
      "violations": [
        {
          "componentRef": "icon-btn-close",
          "actualSize": "32x32",
          "recommendation": "Increase to 44x44px minimum"
        }
      ]
    },
    "interactiveElements": [
      {
        "componentRef": "icon-btn-menu",
        "type": "IconButton",
        "hasVisibleLabel": false,
        "suggestedAriaLabel": "Open menu"
      }
    ]
  }
}

Infer states from visual context. When states are not visible, provide reasonable defaults.

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

Pass 7: Consolidation & Validation

Objective: Merge all passes into final spec, validate completeness, resolve conflicts.

Subtask Agent Prompt

You are Pass 7 (FINAL) of a 7-pass design specification extraction system. Your focus: CONSOLIDATION.

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

OUTPUT FILE: `.design-specs/{project}/design-spec.json`

First, read ALL previous pass outputs:
- `.design-specs/{project}/pass-1-layout.json`
- `.design-specs/{project}/pass-2-colors.json`
- `.design-specs/{project}/pass-3-typography.json`
- `.design-specs/{project}/pass-4-components.json`
- `.design-specs/{project}/pass-5-spacing.json`
- `.design-specs/{project}/pass-6-states.json`

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

## Input
- All previous pass outputs (Passes 1-6) - Read from the JSON files listed above

## Your Task

Create the final, validated design specification:

### 1. Merge Token Groups
Combine all token extractions into unified structure:
- Resolve any duplicate tokens
- Ensure consistent naming
- Verify all references resolve correctly

### 2. Validate Component Tree
- Check all components have required fields
- Verify parent-child relationships
- Ensure style references link to valid tokens
- Check bounding boxes don't overlap incorrectly

### 3. Cross-Reference Validation
- Every color used in components should exist in tokens
- Every font used should be in typography tokens
- Every spacing value should map to spacing scale

### 4. Quality Scoring
Assign confidence scores:
- Overall extraction confidence
- Per-section confidence
- Flag areas of uncertainty

### 5. Generate Recommendations
Based on analysis:
- Accessibility fixes needed
- Token consolidation opportunities
- Component naming suggestions

## Final Output Format
Return complete JSON matching the schema at references/design-tokens-schema.json:

{
  "$schema": "https://design-tokens.org/schema.json",
  "$version": "1.0.0",
  "$source": {
    "type": "<figma-export|website-screenshot|mockup>",
    "dimensions": { "width": N, "height": N, "aspectRatio": "W:H", "deviceClass": "..." },
    "extractedAt": "<ISO timestamp>",
    "confidence": 0.0-1.0
  },
  
  "tokens": {
    "colors": {
      "primitive": {...},
      "semantic": {...}
    },
    "typography": {
      "fontFamilies": {...},
      "fontWeights": {...},
      "fontSizes": {...},
      "lineHeights": {...},
      "letterSpacing": {...},
      "textStyles": {...}
    },
    "spacing": {
      "scale": {...},
      "semantic": {...}
    },
    "sizing": {...},
    "radii": {...},
    "borders": {...},
    "shadows": {...},
    "transitions": {...}
  },
  
  "components": {
    "$root": {...},
    "catalog": {...}
  },
  
  "layout": {
    "type": "...",
    "regions": [...],
    "gridSystem": {...}
  },
  
  "accessibility": {
    "contrastIssues": [...],
    "colorBlindnessIssues": [...],
    "semanticHierarchy": {...},
    "touchTargets": {...}
  },
  
  "semantics": {
    "designPatterns": [
      { "pattern": "Hero Section", "confidence": 0.95, "instances": [...] },
      { "pattern": "Card Grid", "confidence": 0.9, "instances": [...] }
    ],
    "contentTypes": ["marketing", "e-commerce"],
    "brandPersonality": {
      "traits": ["modern", "professional"],
      "tone": "friendly"
    }
  },
  
  "$extensions": {
    "com.design-spec.extraction": {
      "passesCompleted": 7,
      "confidence": {
        "overall": 0.85,
        "layout": 0.9,
        "colors": 0.95,
        "typography": 0.8,
        "components": 0.85,
        "spacing": 0.9,
        "accessibility": 0.75
      },
      "recommendations": [
        "Increase contrast on secondary buttons",
        "Add aria-labels to icon-only buttons"
      ]
    }
  }
}

The final file MUST be valid JSON. Validate all references resolve correctly.

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

Execution Instructions

IMPORTANT: File-Based Workflow

Before launching any pass:

Create the output directory:

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

Each pass MUST write to its designated file - Subtask agents will use the Write tool
Verify file exists before proceeding to next pass - Read the file to confirm

Using Task Subtask Agents

Execute each pass as a dedicated subtask agent. Replace {project} with actual project name in ALL prompts.

// Step 0: Create directory
mkdir -p .design-specs/my-design

// Step 1: Pass 1 - Layout
Task({
  prompt: "[Pass 1 prompt - agent MUST write to .design-specs/my-design/pass-1-layout.json]",
  model: "sonnet"
});
// VERIFY: Read .design-specs/my-design/pass-1-layout.json exists

// Step 2: Pass 2 - Colors
Task({
  prompt: "[Pass 2 prompt - agent reads pass-1, MUST write to pass-2-colors.json]",
  model: "sonnet"
});
// VERIFY: Read .design-specs/my-design/pass-2-colors.json exists

// ... Continue for Passes 3-6, verifying each file exists ...

// Step 7: Pass 7 - Final Consolidation
Task({
  prompt: "[Pass 7 prompt - agent reads ALL pass files, MUST write to design-spec.json]",
  model: "opus"  // Use Opus for complex consolidation
});
// VERIFY: Read .design-specs/my-design/design-spec.json exists

Verification After Each Pass

After each subtask completes, verify the output file was written:

// After Pass N completes:
Read(".design-specs/{project}/pass-N-{type}.json")
// If file doesn't exist or is invalid JSON, re-run the pass

Model Recommendations

Passes 1-6: Use Sonnet for focused visual analysis tasks
Pass 7 (Consolidation): Use Opus for complex synthesis and validation

Output Delivery

After extraction, provide:

Summary: Key statistics and findings
Complete JSON: Full spec matching schema
Recommendations: Suggested improvements
Confidence Report: Areas of uncertainty

Example Summary Output

## Design Spec Extraction Complete

### Statistics
- Colors extracted: 24 (8 primitive, 16 semantic)
- Typography styles: 12
- Components detected: 47 (18 atoms, 15 molecules, 14 organisms)
- Spacing values: 11
- Accessibility issues: 2 (contrast)

### Key Findings
- Layout: 12-column grid with 24px gutters
- Primary font: Inter (sans-serif)
- Design patterns: Hero, Card Grid, Feature List, CTA
- Device class: Desktop (1440px width)

### Accessibility Notes
- 2 contrast failures requiring attention
- Recommend adding icons to status indicators

### Confidence
- Overall: 0.89
- Colors: 0.95
- Typography: 0.88
- Components: 0.85
- Spacing: 0.90

[Full JSON spec attached]

Best Practices

For Accurate Extraction

Use highest resolution source available
Prefer Figma exports over screenshots when possible
Ensure design shows actual content (not lorem ipsum)
Include multiple states if analyzing interactions
Provide context about target platform

For AI-Readable Output

Use semantic naming (intent over appearance)
Include $description explaining when/how to use tokens
Document token relationships and pairings
Show which tokens apply to which components
Include usage examples for complex tokens

For Processing Efficiency

Start with layout pass to establish structure
Use component IDs consistently across passes
Pass only relevant previous results to each subtask
Validate incrementally, not just at end

Reference Files

references/design-tokens-schema.json - Complete JSON Schema for output validation
references/extraction-patterns.md - Detailed patterns for visual analysis

Load these references as needed during extraction for detailed guidance on specific analysis tasks.

Schema Compliance

Output follows W3C Design Tokens Community Group format (2025.10):

All tokens use $value, $type, $description properties
Token references use {group.token} syntax
Extensions use reverse domain notation in $extensions

design-spec-extraction

Install Skill

SKILL.md

Design Specification Extraction

When to Use This Skill

Output Format

CRITICAL: File-Based Architecture

Directory Structure

Required File Outputs

Why File-Based?

Multipass Architecture

Pass 1: Source Analysis & Layout Structure

Subtask Agent Prompt

Pass 2: Color & Visual Style Extraction

Subtask Agent Prompt

Pass 3: Typography Analysis

Subtask Agent Prompt

Pass 4: Component Detection & Classification

Subtask Agent Prompt

Pass 5: Spacing & Dimensions

Subtask Agent Prompt

Pass 6: Interactive States & Accessibility

Subtask Agent Prompt

Pass 7: Consolidation & Validation

Subtask Agent Prompt

Execution Instructions

IMPORTANT: File-Based Workflow

Using Task Subtask Agents

Verification After Each Pass

Model Recommendations

Output Delivery

Example Summary Output

Best Practices

For Accurate Extraction

For AI-Readable Output

For Processing Efficiency

Reference Files

Schema Compliance