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

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

1. Create the output directory:

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

2. Each pass MUST write to its designated file - Subtask agents will use the Write tool
3. 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

…(truncated)