Skip to main content
skill CX Codex

design-system · jezweb — Claude Code skill: extract a site's design into DESIGN.md

A skill that reads a live site, HTML file, or screenshot and turns it into a semantic design system in DESIGN.md. Use it when a new project has to match an existing visual language.

MIT 1,200 installs ★ 1,124 updated 2026-10-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jezweb/claude-skills --skill design-system -a claude-code
Open on GitHub

What design-system does

The skill opens a URL through Playwright CLI, grabs desktop and mobile screenshots, pulls the HTML, and inspects it. It identifies colours by role (primary, background, surface, text, border, accent), typography, and component patterns such as buttons, cards, navigation, and forms.

Layout details are captured too: max content width, section padding, grid, whitespace. The output goes to .design/DESIGN.md, written as natural language with exact values attached. rounded-xl becomes “softly rounded corners (12px)”, #1E40AF becomes “deep ocean blue for primary actions”.

A screenshot alone gives approximate colours, because there is no HTML to inspect. For Google Stitch projects the skill needs @google/stitch-sdk installed and STITCH_API_KEY set. The Stitch theme object carries only the primary colour; the full palette sits in generated CSS, so the HTML still has to be downloaded.

What it helps with

  • Turn a live site into a DESIGN.md file
  • Map colours to roles from HTML and CSS
  • Extract fonts, weights, sizes, and line heights
  • Describe components and layout in plain words, not Tailwind classes
  • Produce a design document ready for page generation

Example prompts for the agent

  • Extract the design system from this site and create DESIGN.md
  • Analyse this HTML file and pull out the design tokens
  • Look at this screenshot and describe the visual style for DESIGN.md

How to install design-system

1Skills CLI (Vercel)

npx skills add jezweb/claude-skills --skill design-system -a claude-code

2Manually: put the files in place

~/.claude/skills/design-system/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/design-system/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about design-system

How do I install design-system in Claude Code?

Run npx skills add jezweb/claude-skills --skill design-system -a claude-code. The skill lands in ~/.claude/skills/design-system/SKILL.md.

What does design-system do?

It pulls a design system from a website, HTML file, or screenshot: colours, typography, components, spacing, and overall feel. The result is written to .design/DESIGN.md as a semantic description.

Can it get exact colours from a screenshot?

No. Without HTML, colours are approximate and the skill flags that in the output. Exact hex values require the HTML or CSS source.

Source text

SKILL.md · MIT
---
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:

```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):

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 — 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:

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

### Step 6: Verify Accuracy

If browser automation is available:

1. Generate a small test section (e.g. a card + button + heading) using the extracted design system
2. Screenshot it alongside the original
3. 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:

1. Analyse the **homepage first** — it usually has the most complete design language
2. Spot-check 2-3 inner pages for consistency
3. Note any **page-specific overrides** in the Component Styles section
4. 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

© jezweb · MIT · jezweb/claude-skills

Similar skills

All skills for Design →

design-system by other authors comes first.

design-system claudekit The design-system skill builds design tokens, component specs, and presentation slides. Use it when an interface and its slides need to follow one visual system. CX Codex +1 54,500installs design-system affaan-m Builds a design system out of the styles already in your repo, or audits them: tokens, a ten-point UI score, and a check for generic AI styling. CX Codex +1 6,800installs design-system official anthropics A skill for Claude Code, Cursor, Codex, and three other platforms that audits design systems for inconsistencies, generates component docs, and drafts new patterns. Triggered with /design-system audit, document, or extend. CX Codex +1 4,700installs design-system Donchitos design-system walks one game system through every required GDD section and cross-references its dependencies. Useful when a design doc grows faster than you can keep it straight. CX Codex +1 731installs design-system daveebbelaar The design-system Claude Code skill organizes a macOS app’s accent color and design tokens. It activates for requests about themes, shared screen styles, or a style guide. CX Codex +1 1,000installs extract-design-system arvindrk The extract-design-system skill extracts design primitives from a public website and generates starter tokens.json and tokens.css files for your project. CX Codex +1 131,800installs design-system-generator OneWave-AI design-system-generator builds a design system from tokens, base components and docs. Useful once a second screen shows up and your colors start drifting. CX Codex +1 324installs ui-design-system Alireza Rezvani The ui-design-system skill builds design tokens, component structures, and responsive calculations. Use it when a project needs a consistent UI system or a developer handoff. CX Codex +1 1,076installs claude-design-system-architect OneWave-AI claude-design-system-architect is a Claude Code skill that turns a brand brief or existing site into reusable design tokens, component specs, and project files. It defines shared rules for a new product or inconsistent UI. CX Codex +1 172installs design-system-documenter curiositech design-system-documenter converts raw token files into developer documentation featuring reference tables, implementation code, and WCAG contrast checks. CX Codex +1 165installs design-system-setup Seth Hobson design-system-setup — a Claude Code command that sets up a design system from scratch: tokens, type, spacing, shadows. It asks one question at a time, then writes the files in the format you picked. CX Codex +1 ★ 42,780repo stars

From the same set61

The whole set →
google-chat-messages google-chat-messages — a skill that lets your agent post to Google Chat through an incoming webhook: plain text, cardsV2 cards and threaded replies. CX Codex +1 1,300installs react-patterns react-patterns — a skill that checks React 19 components for waterfalls, bundle bloat and re-renders, and suggests composition fixes. Useful while writing or reviewing code. CX Codex +1 1,300installs react-native Performance guidelines and architecture patterns for React Native and Expo apps. Helps coding agents handle list virtualization, UI-thread animations, and navigation. CX Codex +1 1,300installs onboarding-ux onboarding-ux is a Claude Code skill that finds gaps in in-app guidance and creates content and code to address them. It starts on requests about onboarding, empty states, or a new user's first experience. CX Codex +1 1,200installs d1-migration Walks through the full Cloudflare D1 migration cycle using Drizzle ORM. Catches destructive SQL patterns, applies migrations to local and remote, and recovers stuck migrations. CX Codex +1 1,200installs deep-research The deep-research skill for Claude Code researches your projects, competitors, forums and libraries before you write code, then produces a research brief. CX Codex +1 1,200installs shopify-content shopify-content is a Claude Code skill for creating and editing Shopify pages, blog posts, menus, redirects, and SEO fields. It activates on requests to change a store’s content or navigation. CX Codex +1 1,200installs vite-flare-starter Clones the vite-flare-starter template and configures it into your own Cloudflare Workers app, with React, Hono, D1 and Drizzle, auth and Workers AI already in place. CX Codex +1 1,200installs

Project sponsors

Companies that keep this analytics open