Design System

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:

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:

Typography

Extract:

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