mcpbeat

Design System

jezweb/design-system

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'.

2k tokens
context cost
the whole folder, loaded on every use
1
files
instructions only
0
copies elsewhere
how many repositories repackaged it
953
stars on the repo
on the repository, not the skill itself

Install

one command, takes just this skill from the repository 
npx skills add https://github.com/jezweb/claude-skills --skill design-system

The instruction itself

21 sections, as written by the author

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

How to use it

Copy the folder

Take jezweb/design-system from the repository into ~/.claude/skills for personal use, or into .claude/skills inside a project.

Check the name does not clash

The agent identifies a skill by the name field in its header. Two skills with the same name cannot sit side by side — one of them will be ignored.