pageweave/resources

Design System from Reference

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.

· .md · source ↗

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

Typography

Spacing

Shape

Motion

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:

Reference Types

From Screenshot

From Figma

From URL

From Description

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

← all skills