---
name: design-system-from-reference
description: Turn a style reference into a complete, AI-consumable design system: tokens JSON, CSS variables, markdown spec, and visual preview — ready for consistent code generation.
---

# Design System from Reference

Extract tokens, typography, and patterns from any design — screenshot, Figma, or description

Extract a complete design system from any reference — a screenshot, a Figma link, a URL, or a text description. The output is a structured, AI-consumable system that makes code generation consistent.

## The Problem

When AI coding agents generate UI without constraints, they default to generic choices: Inter font, purple gradients, 4px spacing, rounded cards everywhere. The result is "AI slop" that all looks the same.

A design system gives agents precise constraints: exact colors, specific font pairings, a defined spacing scale, and component patterns. The agent focuses creativity within those constraints.

## The Extraction Workflow

### Step 1: Analyze the Reference

From the reference (screenshot, URL, Figma, or description), extract:

**Color**
- Primary brand color (the one that carries identity).
- Secondary/accent colors.
- Neutral palette (grays, backgrounds).
- Semantic colors (success, warning, error, info).
- Background colors (base, raised, sunken).

**Typography**
- Display font (headlines, hero text).
- Body font (paragraphs, labels).
- Mono font (code, data) — if present.
- Type scale (sizes for h1–h6, body, caption, label).

**Spacing**
- Base unit (usually 4px or 8px).
- Scale steps (4, 8, 12, 16, 24, 32, 48, 64).

**Shape**
- Border radius (none, small, medium, large, full).
- Shadow style (none, subtle, medium, dramatic).

**Motion**
- Animation speed (fast, medium, slow).
- Easing style (linear, ease-out, spring).

### Step 2: Build the Token Architecture

Structure tokens in three tiers:

```json
{
  "primitives": {
    "color": {
      "blue": {
        "50": "oklch(0.97 0.02 240)",
        "500": "oklch(0.55 0.2 240)",
        "900": "oklch(0.2 0.1 240)"
      },
      "gray": {
        "50": "oklch(0.98 0.005 240)",
        "500": "oklch(0.55 0.02 240)",
        "900": "oklch(0.2 0.01 240)"
      }
    },
    "spacing": {
      "0": "0rem",
      "1": "0.25rem",
      "2": "0.5rem",
      "4": "1rem",
      "8": "2rem"
    },
    "fontSize": {
      "xs": "0.75rem",
      "sm": "0.875rem",
      "base": "1rem",
      "lg": "1.125rem",
      "xl": "1.25rem",
      "2xl": "1.5rem"
    }
  },
  "semantics": {
    "color": {
      "primary": "{color.blue.500}",
      "fg-primary": "{color.gray.900}",
      "bg-base": "{color.gray.50}",
      "border-default": "{color.gray.300}"
    }
  },
  "components": {
    "button": {
      "bg": "{semantics.color.primary}",
      "fg": "{semantics.color.primary-content}",
      "radius": "{semantics.radius.md}",
      "paddingX": "{primitives.spacing.4}",
      "paddingY": "{primitives.spacing.2}"
    }
  }
}
```

### Step 3: Generate CSS Variables

Convert tokens to CSS custom properties:

```css
/* Primitives */
:root {
  --blue-50: oklch(0.97 0.02 240);
  --blue-500: oklch(0.55 0.2 240);
  --blue-900: oklch(0.2 0.1 240);
  --gray-50: oklch(0.98 0.005 240);
  --gray-500: oklch(0.55 0.02 240);
  --gray-900: oklch(0.2 0.01 240);
  --space-1: 0.25rem;
  --space-2: 0.5rem;
  --space-4: 1rem;
  --space-8: 2rem;
}

/* Semantics */
:root {
  --color-primary: var(--blue-500);
  --fg-primary: var(--gray-900);
  --bg-base: var(--gray-50);
  --border-default: var(--gray-300);
}

/* Components */
:root {
  --btn-bg: var(--color-primary);
  --btn-fg: white;
  --btn-radius: 0.5rem;
  --btn-padding-x: var(--space-4);
  --btn-padding-y: var(--space-2);
}
```

### Step 4: Write the Markdown Spec

Create a human-readable design system document:

```markdown
# [Brand] Design System

## Colors
- Primary: [swatch] oklch(0.55 0.2 240) — used for CTAs, links, active states
- Background: [swatch] oklch(0.98 0.005 240) — page background
- Text: [swatch] oklch(0.2 0.01 240) — body text, headings

## Typography
- Display: Fraunces (serif) — headlines, hero text
- Body: Instrument Sans (sans-serif) — paragraphs, labels
- Scale: 0.75 / 0.875 / 1 / 1.125 / 1.25 / 1.5 / 2 / 2.5rem

## Spacing
Base unit: 4px. Scale: 4, 8, 12, 16, 24, 32, 48, 64.

## Components
### Button
- Primary: bg-primary, text-white, radius-md, padding 1rem 0.5rem
- Secondary: bg-transparent, border-default, text-primary
- Danger: bg-error, text-white

## Rules
- Never use raw hex in components — always tokens.
- Dark mode: swap semantics, keep primitives.
- All interactive elements need visible focus indicators.
```

### Step 5: Create Visual Preview

Generate an HTML preview page that shows:
- Color swatches (all primitives + semantics).
- Typography scale (every heading level + body + caption).
- Spacing scale (visual blocks showing each step).
- Component examples (buttons, inputs, cards in all variants).
- Light and dark mode side-by-side.

## Reference Types

### From Screenshot
- Use color picker to extract exact colors.
- Estimate font sizes from known UI elements (buttons are typically 14–16px).
- Identify the spacing rhythm by measuring padding/margins.
- Note the border radius and shadow style.

### From Figma
- Extract design tokens directly (Figma Variables or Styles).
- Export color styles, text styles, and effect styles.
- Map Figma components to your token architecture.

### From URL
- Fetch the page and analyze computed styles.
- Extract CSS custom properties if present.
- Screenshot key sections for visual reference.
- Note the font families from `font-family` declarations.

### From Description
- "Dark fintech app with purple accents" → deep navy base, purple primary, monospace data font, sharp corners.
- "Warm editorial magazine" → cream base, serif display, sans body, generous whitespace, minimal borders.
- "Playful startup landing page" → bright primary color, rounded corners, bouncy animations, friendly sans-serif.

## AI Agent Instructions

Include this section in the markdown spec so AI agents can consume it:

```markdown
## For AI Agents

When generating UI for this project:
1. Use ONLY the defined tokens — never raw hex or arbitrary values.
2. Follow the component patterns exactly (padding, radius, colors).
3. Use the typography scale — don't invent new sizes.
4. Respect the spacing scale — multiples of the base unit only.
5. Dark mode: use the semantic layer swap, don't redesign.
6. All interactive elements need hover, focus, and disabled states.
7. Error states: use semantic error color + descriptive text.
```

## Verification

1. **Token traceability**: every value in component code traces back to a token.
2. **Contrast**: every text/background pair passes WCAG AA.
3. **Consistency**: same token = same visual result everywhere.
4. **Completeness**: the system covers colors, typography, spacing, shape, and motion.
5. **Dark mode**: semantic layer swaps correctly, primitives stay.
6. **Agent test**: give the spec to an AI agent and ask it to build a form. Does the output match the system?

## Anti-Patterns

- **Extracting without structuring**: a list of colors isn't a system. Tokens need hierarchy (primitive → semantic → component).
- **Ignoring the reference's intent**: if the reference is playful, don't extract it as corporate. Match the tone.
- **Over-extraction**: you don't need every single color variation. Capture the system, not every instance.
- **Hardcoded values in the output**: if the CSS has `#6366f1` instead of `var(--color-primary)`, the system failed.
- **No dark mode**: every system needs a dark variant. If the reference is light-only, design the dark mode from the same primitives.