Design System from Reference

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:

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

/* 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:

# [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:

## 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.