/design-system

name: design-system
description: "Extract a complete design system from an existing website or screenshot into a DESIGN.md file. Analyses colours, typography, component styles, spacing, and atmosphere through browser automation and HTML inspection. Produces a semantic design system document optimised for consistent page generation. Triggers: 'extract design system', 'design system', 'create DESIGN.md', 'analyse the design', 'what design does this site use', 'extract styles from', 'reverse engineer the design'."
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
compatibility: claude-code-only

Design System Extractor

Analyse an existing website, HTML file, or screenshot and synthesise a semantic design system into a `DESIGN.md` file. The output is optimised for use with the `design-loop` skill and general page generation.

When to Use

• Starting a new project based on an existing site's visual language
• Documenting a site's design system that was never formally written down
• Preparing `.design/DESIGN.md` before running the design loop
• Extracting brand guidelines from a client's existing website
• Creating consistency documentation for a multi-page project
• Extracting design tokens from a Google Stitch project

Workflow

Step 1: Identify the Source

Ask the user for one of:

| Source | Method | |--------|--------| | **Live URL** | Browse via Playwright CLI or scraper, screenshot + extract HTML | | **Local HTML file** | Read the file directly | | **Screenshot image** | Analyse visually (limited — no exact hex extraction) | | **Existing project** | Scan `site/public/` for HTML files to analyse | | **Stitch project** | Use `@google/stitch-sdk` to fetch screen HTML + design theme |

Step 2: Extract Raw Design Data

From a Live URL

1. **Browse the site** using Playwright CLI:

   playwright-cli -s=design open {url}
   playwright-cli -s=design screenshot --filename=.design/screenshots/source-desktop.png

2. **Extract the full HTML** — either via scraper MCP or by reading the page source

3. **Resize and screenshot mobile** (375px):

   playwright-cli -s=design resize 375 812
   playwright-cli -s=design screenshot --filename=.design/screenshots/source-mobile.png

4. Close the session: `playwright-cli -s=design close`

From a Local HTML File

Read the file directly and extract design tokens from the source.

From a Screenshot Only

Analyse the image visually. Note: colour extraction will be approximate without HTML source. Flag this limitation in the output.

From a Google Stitch Project

If `@google/stitch-sdk` is installed and `STITCH_API_KEY` is set:

import { stitch } from "@google/stitch-sdk";

// List projects to find the target
const projects = await stitch.projects();

// Get project details (includes designTheme)
const project = stitch.project(projectId);
const screens = await project.screens();

// Get HTML from the main screen
const screen = screens[0]; // or find by title
const htmlUrl = await screen.getHtml();
const imageUrl = await screen.getImage();

The Stitch `designTheme` object provides structured tokens directly:

{
  "colorMode": "DARK",
  "font": "INTER",
  "roundness": "ROUND_EIGHT",
  "customColor": "#40baf7",
  "saturation": 3
}

Map these to DESIGN.md sections:

• `colorMode` → Theme (Light/Dark)
• `font` → Typography font family
• `roundness` → Component border-radius (`ROUND_EIGHT` = 8px, `ROUND_SIXTEEN` = 16px, etc.)
• `customColor` → Primary brand colour
• `saturation` → Colour vibrancy (1-5 scale)

Then also download and analyse the HTML for the full palette (Stitch's theme object only has the primary colour — the full palette is in the generated CSS).

Step 3: Analyse Design Tokens

Extract these from the HTML/CSS source:

Colours

Look in these locations (priority order):

1. **CSS custom properties** — `:root { --primary: #hex; }` or `@theme` blocks 2. **Tailwind config** — `<script>` block with `tailwind.config` or `@theme` in `<style>` 3. **Inline styles** — `style="color: #hex"` or `style="background: #hex"` 4. **Tailwind classes** — `bg-blue-600`, `text-gray-900` (map to palette) 5. **Computed from screenshot** — last resort, approximate

For each colour found, determine its **role**:

| Role | How to identify | |------|-----------------| | Primary | Buttons, links, active states, brand elements | | Background | `<body>` or `<html>` background | | Surface | Cards, containers, elevated elements | | Text Primary | `<h1>`, `<h2>`, main body text | | Text Secondary | Captions, metadata, muted text | | Border | Dividers, input borders, card borders | | Accent | Badges, notifications, highlights |

Typography

Extract:

| Token | Where to find | |-------|---------------| | Font families | Google Fonts `<link>`, `@import`, `font-family` in CSS | | Heading weights | `font-bold`, `font-semibold`, or explicit `font-weight` | | Body size | Base `font-size` on `<body>` or root | | Line height | `leading-*` classes or `line-height` CSS | | Letter spacing | `tracking-*` classes or `letter-spacing` CSS |

Components

Identify patterns for:

• **Buttons** — shape (rounded-full, rounded-lg), colours, padding, hover states
• **Cards** — background, border, shadow, border-radius, padding
• **Navigation** — sticky/static, background treatment, active indicator
• **Forms** — input style, focus ring, label positioning
• **Hero sections** — layout pattern, overlay treatment, CTA placement

Spacing & Layout

• **Max content width** — look for `max-w-*` or explicit `max-width`
• **Section padding** — typical vertical padding between sections
• **Grid system** — column count, gap values
• **Whitespace philosophy** — tight, balanced, generous, or dramatic

Step 4: Synthesise into Natural Language

**Critical**: The DESIGN.md should describe the design in **semantic, natural language** supported by exact values. This is not a CSS dump