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
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):
- 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" or 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
1---2name: design-system3description: "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'."4allowed-tools:5 - Read6 - Write7 - Edit8 - Bash9 - Glob10 - Grep11compatibility: claude-code-only12metadata:13 source: https://skillmd.com/skills/artubss/design-system14---1516# Design System Extractor1718Analyse 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.1920## When to Use2122- Starting a new project based on an existing site's visual language23- Documenting a site's design system that was never formally written down24- Preparing `.design/DESIGN.md` before running the design loop25- Extracting brand guidelines from a client's existing website26- Creating consistency documentation for a multi-page project27- Extracting design tokens from a Google Stitch project2829## Workflow3031### Step 1: Identify the Source3233Ask the user for one of:3435| Source | Method |36|--------|--------|37| **Live URL** | Browse via Playwright CLI or scraper, screenshot + extract HTML |38| **Local HTML file** | Read the file directly |39| **Screenshot image** | Analyse visually (limited — no exact hex extraction) |40| **Existing project** | Scan `site/public/` for HTML files to analyse |41| **Stitch project** | Use `@google/stitch-sdk` to fetch screen HTML + design theme |4243### Step 2: Extract Raw Design Data4445#### From a Live URL46471. **Browse the site** using Playwright CLI:48 ```49 playwright-cli -s=design open {url}50 playwright-cli -s=design screenshot --filename=.design/screenshots/source-desktop.png51 ```52532. **Extract the full HTML** — either via scraper MCP or by reading the page source54553. **Resize and screenshot mobile** (375px):56 ```57 playwright-cli -s=design resize 375 81258 playwright-cli -s=design screenshot --filename=.design/screenshots/source-mobile.png59 ```60614. Close the session: `playwright-cli -s=design close`6263#### From a Local HTML File6465Read the file directly and extract design tokens from the source.6667#### From a Screenshot Only6869Analyse the image visually. Note: colour extraction will be approximate without HTML source. Flag this limitation in the output.7071#### From a Google Stitch Project7273If `@google/stitch-sdk` is installed and `STITCH_API_KEY` is set:7475```typescript76import { stitch } from "@google/stitch-sdk";7778// List projects to find the target79const projects = await stitch.projects();8081// Get project details (includes designTheme)82const project = stitch.project(projectId);83const screens = await project.screens();8485// Get HTML from the main screen86const screen = screens[0]; // or find by title87const htmlUrl = await screen.getHtml();88const imageUrl = await screen.getImage();89```9091The Stitch `designTheme` object provides structured tokens directly:9293```json94{95 "colorMode": "DARK",96 "font": "INTER",97 "roundness": "ROUND_EIGHT",98 "customColor": "#40baf7",99 "saturation": 3100}101```102103Map these to DESIGN.md sections:104- `colorMode` → Theme (Light/Dark)105- `font` → Typography font family106- `roundness` → Component border-radius (`ROUND_EIGHT` = 8px, `ROUND_SIXTEEN` = 16px, etc.)107- `customColor` → Primary brand colour108- `saturation` → Colour vibrancy (1-5 scale)109110Then 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).111112### Step 3: Analyse Design Tokens113114Extract these from the HTML/CSS source:115116#### Colours117118Look in these locations (priority order):1191201. **CSS custom properties** — `:root { --primary: #hex; }` or `@theme` blocks1212. **Tailwind config** — `<script>` block with `tailwind.config` or `@theme` in `<style>`1223. **Inline styles** — `style="color: #hex"` or `style="background: #hex"`1234. **Tailwind classes** — `bg-blue-600`, `text-gray-900` (map to palette)1245. **Computed from screenshot** — last resort, approximate125126For each colour found, determine its **role**:127128| Role | How to identify |129|------|-----------------|130| Primary | Buttons, links, active states, brand elements |131| Background | `<body>` or `<html>` background |132| Surface | Cards, containers, elevated elements |133| Text Primary | `<h1>`, `<h2>`, main body text |134| Text Secondary | Captions, metadata, muted text |135| Border | Dividers, input borders, card borders |136| Accent | Badges, notifications, highlights |137138#### Typography139140Extract:141142| Token | Where to find |143|-------|---------------|144| Font families | Google Fonts `<link>`, `@import`, `font-family` in CSS |145| Heading weights | `font-bold`, `font-semibold`, or explicit `font-weight` |146| Body size | Base `font-size` on `<body>` or root |147| Line height | `leading-*` classes or `line-height` CSS |148| Letter spacing | `tracking-*` classes or `letter-spacing` CSS |149150#### Components151152Identify patterns for:153154- **Buttons** — shape (rounded-full, rounded-lg), colours, padding, hover states155- **Cards** — background, border, shadow, border-radius, padding156- **Navigation** — sticky/static, background treatment, active indicator157- **Forms** — input style, focus ring, label positioning158- **Hero sections** — layout pattern, overlay treatment, CTA placement159160#### Spacing & Layout161162- **Max content width** — look for `max-w-*` or explicit `max-width`163- **Section padding** — typical vertical padding between sections164- **Grid system** — column count, gap values165- **Whitespace philosophy** — tight, balanced, generous, or dramatic166167### Step 4: Synthesise into Natural Language168169**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.170171| Don't write | Write instead |172|-------------|---------------|173| `rounded-xl` | "Softly rounded corners (12px)" |174| `shadow-md` | "Subtle elevation with diffused shadow" |175| `#1E40AF` | "Deep Ocean Blue (#1E40AF) for primary actions" |176| `py-16` | "Generous section spacing with breathing room" |177178### Step 5: Write DESIGN.md179180Output the file to `.design/DESIGN.md` (or user-specified path).181182Follow the structure from the `design-loop` skill's `references/site-template.md` — specifically the DESIGN.md Template section. The key sections are:1831841. **Visual Theme & Atmosphere** — mood, vibe, philosophy1852. **Colour Palette & Roles** — table with role, name, hex, usage1863. **Typography** — font families, weights, sizes, line heights1874. **Component Styles** — buttons, cards, nav, forms1885. **Layout Principles** — max width, spacing, grid, whitespace1896. **Design System Notes for Generation** — the copy-paste block for baton prompts190191### Step 6: Verify Accuracy192193If browser automation is available:1941951. Generate a small test section (e.g. a card + button + heading) using the extracted design system1962. Screenshot it alongside the original1973. Compare visually — adjust any values that don't match198199### Step 7: Report to User200201Present:202- Summary of extracted tokens (colour count, fonts, component patterns)203- The generated DESIGN.md location204- Any tokens that were approximate (flagged with ⚠️)205- Suggestions for manual review (colours from screenshots, ambiguous typography)206207## Handling Multiple Pages208209If the site has multiple pages with different styles:2102111. Analyse the **homepage first** — it usually has the most complete design language2122. Spot-check 2-3 inner pages for consistency2133. Note any **page-specific overrides** in the Component Styles section2144. If pages are wildly different, ask the user which page to use as the canonical source215216## Tips217218- **Tailwind sites are easiest** — the config block has everything219- **Google Fonts links are gold** — they specify exact families and weights220- **CSS custom properties are reliable** — they represent intentional design tokens221- **Inline Tailwind classes need interpretation** — `bg-slate-900` needs mapping to a role222- **Screenshots are last resort** — accurate hex extraction from images is unreliable223- **Dark mode**: Check for `.dark` class overrides or `prefers-color-scheme` media queries224225## Common Pitfalls226227- ❌ Listing raw CSS values without semantic description228- ❌ Missing the dark mode palette (check for `.dark` class or media query)229- ❌ Ignoring component patterns (just listing colours isn't enough)230- ❌ Not including Section 6 (the copy-paste generation block)231- ❌ Approximate colours from screenshots without flagging the uncertainty