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

Browse the site using Playwright CLI:

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

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

Resize and screenshot mobile (375px):

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

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

@google/stitch-sdk

is installed and

STITCH_API_KEY

is set:

typescript

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:

json

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

CSS custom properties —
```
:root { --primary: #hex; }
```
or
```
@theme
```
blocks
Tailwind config —
```
<script>
```
block with
```
tailwind.config
```
or
```
@theme
```
in
```
<style>
```

Inline styles —

style="color: #hex"

style="background: #hex"

Tailwind classes —
```
bg-blue-600
```
,
```
text-gray-900
```
(map to palette)
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 — it's a document a designer or AI can read to understand and reproduce the visual language.

Don't write	Write instead
`rounded-xl`	"Softly rounded corners (12px)"
`shadow-md`	"Subtle elevation with diffused shadow"
`#1E40AF`	"Deep Ocean Blue (#1E40AF) for primary actions"
`py-16`	"Generous section spacing with breathing room"

Step 5: Write DESIGN.md

Output the file to

.design/DESIGN.md

(or user-specified path).

Follow the structure from the

design-loop

skill's

references/site-template.md

— specifically the DESIGN.md Template section. The key sections are:

Visual Theme & Atmosphere — mood, vibe, philosophy
Colour Palette & Roles — table with role, name, hex, usage
Typography — font families, weights, sizes, line heights
Component Styles — buttons, cards, nav, forms
Layout Principles — max width, spacing, grid, whitespace
Design System Notes for Generation — the copy-paste block for baton prompts

Step 6: Verify Accuracy

If browser automation is available:

Generate a small test section (e.g. a card + button + heading) using the extracted design system
Screenshot it alongside the original
Compare visually — adjust any values that don't match

Step 7: Report to User

Present:

Summary of extracted tokens (colour count, fonts, component patterns)
The generated DESIGN.md location
Any tokens that were approximate (flagged with ⚠️)
Suggestions for manual review (colours from screenshots, ambiguous typography)

Handling Multiple Pages

If the site has multiple pages with different styles:

Analyse the homepage first — it usually has the most complete design language
Spot-check 2-3 inner pages for consistency
Note any page-specific overrides in the Component Styles section
If pages are wildly different, ask the user which page to use as the canonical source

Tips

Tailwind sites are easiest — the config block has everything
Google Fonts links are gold — they specify exact families and weights
CSS custom properties are reliable — they represent intentional design tokens
Inline Tailwind classes need interpretation —
```
bg-slate-900
```
needs mapping to a role
Screenshots are last resort — accurate hex extraction from images is unreliable
Dark mode: Check for
```
.dark
```
class overrides or
```
prefers-color-scheme
```
media queries

Common Pitfalls

❌ Listing raw CSS values without semantic description
❌ Missing the dark mode palette (check for
```
.dark
```
class or media query)
❌ Ignoring component patterns (just listing colours isn't enough)
❌ Not including Section 6 (the copy-paste generation block)
❌ Approximate colours from screenshots without flagging the uncertainty

design-system

NPX Install

Tags

SKILL.md Content