extract-design-system

Files (2)

• SKILL.md
• extract.mjs · scripts/

SKILL.md (first lines)

# Extract Design System from Website

Reverse-engineer a complete design system from a live website using two passes:
1. **CSS source analysis** — fetch and parse stylesheets for declared values
2. **Headed Playwright extraction** — visually browse the site, interact with elements,
   extract computed styles, and capture screenshots at real device resolutions

## Prerequisites

- Playwright installed (`npx playwright install chromium` if not set up)
- `web_fetch` tool for fetching raw HTML/CSS source

## Quick Start

Run the extraction script against the target URL:

```bash
node scripts/extract.mjs <url> [outDir] [subpage1,subpage2,...]
```

Examples:
```bash
node scripts/extract.mjs https://example.com
node scripts/extract.mjs https://example.com ./my-tokens "/about,/pricing,/docs"
node scripts/extract.mjs http://localhost:3000 extracted "/dashboard,/settings"
```

The script opens a **visible browser** (`headless: false`) so you can watch the
extraction. It uses real device profiles for accurate screenshots:

| Breakpoint | Device | Viewport | DPR | Real image size |
|------------|--------|----------|-----|-----------------|
| Mobile | iPhone 15 | 393×659 | 3x | 1179×1977 |
| Tablet | iPad Pro 11 | 834×1194 | 2x | 1668×2388 |
| Desktop | — | 1440×900 | 2x | 2880×1800 |
| Wide | — | 1920×1080 | 2x | 3840×2160 |

Mobile and tablet use Playwright's built-in device descriptors (correct UA,
`isMobile`, `hasTouch`) so sites serving different layouts render correctly.

## Output Structure

```
{outDir}/
├── screenshots/
│   ├── pages/               — full-page at 4 breakpoints × each page
│   │   ├── home-mobile.png
│   │   ├── home-desktop.png
│   │   ├── home-dark-mode.png
│   │   └── ...
│   └── components/          — isolated component + hover/focus states
│       ├── nav.png
│       ├── button-primary.png
│       ├── button-primary-hover.png
│       ├── button-primary-focus.png
│       ├── nav-mobile-open.png
│       └── ...
└── raw/
    ├── colors.json          — CSS custom properties + computed colors
    ├── colors-dark.json     — dark mode variables (if detected)
    ├── typography.json      — font families, type styles, @font-face
    ├── spacing.json         — spacing, radii, shadows, borders, max-widths
    └── components.json      — component manifest + responsive layout data
```

## Workflow

### Step 1: Run the Extraction Script

```bash
node scripts/extract.mjs "TARGET_URL" "extracted-design-system" "/about,/pricing"
```

The script automatically:
- Extracts CSS custom properties and computed colors from 800 sampled elements
- Captures typography from all semantic elements (h1-h6, p, a, button, etc.)
- Measures spacing, radii, shadows, and borders
- Screenshots every page at 4 breakpoints with real device contexts
- Isolates and screenshots 17 common component types
- Captures hover and focus states on interactive elements
- Tests mobile nav by clicking hamburger-like buttons at iPhone viewport
- Detects dark mode via `prefers-color-scheme` emulation and toggle sniffing

### Step 2: CSS Source Analysis (supplementary)

The script captures computed values. This step catches declared values from CSS
source that may not be active on the current page:

```bash
# Fetch stylesheets identified in the HTML
web_fetch <stylesheet-url>

# Look for things the computed pass might miss:
# - Media query breakpoints
# - Keyframe animations
# - CSS custom property definitions with fallbacks
# - Commented-out or unused styles that reveal design intent
```

### Step 3: Organize Raw Data into Tokens

Review `raw/colors.json`, `raw/typography.json`, `raw/spacing.json` and the
screenshots. Then organize into a structured token file.

#### Colors → Palette

Group extracted colors into categories:

| Category | What to look for |
|----------|-----------------|
| **Primary** | Brand color, CTA buttons, most prominent accent |
| **Secondary** | Supporting accent, secondary buttons |
| **Neutral** | Backgrounds, text, borders — the gray scale |
| **Success** | Green tones (confirmations, checkmarks) |
| **Warning** | Yellow/amber tones (alerts) |
| **Error** | Red tones (errors, delete actions) |
| **Info** | Blue tones (informational messages) |

Deduplicate near-identical colors (ΔE < 3 in OKLCH space). A site with 47

From espennilsen/pi, MIT.

More from espennilsen/pi