design-distiller

What this skill does

# Design Distiller

> Give any website URL, extract the complete design system into a Design MD + composable design tokens.

## Triggers

- `/design-distiller`
- "scrape this website's design" / "extract design system"
- "design scrape" / "make a Design MD"
- "analyze this site's design"

## Core Concepts

### Design MD
A pure Markdown design system document that AI agents can read directly to generate matching UI. Format follows [awesome-design-md](https://github.com/VoltAgent/awesome-design-md).

### Reference Pool
`references/{slug}/` — One folder per website, containing the full Design MD + screenshot assets. This is the raw material library.

### Digest Pool
`digests/` — Cross-site design tokens decomposed by dimension (typography, colors, spacing, components, etc.). Each entry is tagged with its source website. Used for mix-and-match composition when building new sites.

## Output Structure

```
design-distiller/
├── references/                # Reference Pool
│   └── {slug}/
│       ├── DESIGN.md          # Full Design MD (9 modules)
│       ├── meta.json          # Metadata
│       └── screenshots/       # Key page screenshots
│           ├── homepage.png
│           ├── homepage-mobile.png
│           └── components.png
└── digests/                   # Digest Pool
    ├── typography.md          # All font systems
    ├── colors.md              # All color systems
    ├── spacing.md             # All spacing systems
    ├── components.md          # All component patterns
    ├── depth.md               # All shadow & elevation systems
    ├── motion.md              # All motion specs
    ├── layouts.md             # All layout systems
    └── philosophy.md          # All design philosophies
```

### Pre-loaded References

The Reference Pool ships with **55 pre-loaded brands** imported from [awesome-design-md](https://github.com/VoltAgent/awesome-design-md) and the nothing-design skill. These text-only imports differ from freshly scraped references:

- **No `screenshots/`** — visual data was not captured during batch import. Screenshots are generated only when running the full 4-phase pipeline on a new URL.
- **No `meta.json`** — metadata is generated only by the pipeline's Generate phase. Pre-loaded references have their metadata embedded in the Digest Pool cross-references instead.
- **Nothing uses an extended format** — `references/nothing/` contains multi-file documentation (DESIGN.md + tokens.md + components.md + platform-mapping.md) from a standalone design system skill. It does not follow the standard 9-module format because its craft rules and composition philosophy cannot be reduced to that template.

All other references follow the standard 9-module Design MD format.

---

## Workflow — 4 Phase Pipeline

### Phase 1: Scrape
-> `prompts/scraper.md`

**Goal**: Extract design information from the target website using all available tools.

#### Tool Priority

| Priority | Method | Use Case | Tool Pattern |
|----------|--------|----------|--------------|
| 1 | **Browser Use Cloud** | Full browsing + screenshots + DOM extraction | `browser-use_run_session`, `browser-use_get_session`, `browser-use_send_task` |
| 2 | **Playwright** | Screenshots + DOM extraction | `playwright_browser_navigate`, `playwright_browser_take_screenshot`, `playwright_browser_evaluate` |
| 3 | **Chrome Headless CLI** | Screenshots | Local Chrome command line via `Bash` |
| 4 | **WebFetch + Source Analysis** | HTML/CSS source code | `webfetch`, `websearch_web_search_exa` |

**Capability Detection**: Before starting a scrape, check which browser tools are available in the current environment. Try the highest-priority tool first; if unavailable or erroring, fall back to the next tier. Do not assume any specific tool is present.

#### Extraction Checklist

For each website, collect:

**A. Visual Screenshots** (via browser tools)
- [ ] Homepage full-page screenshot (desktop 1440px + mobile 390px)
- [ ] Dark/light mode toggle (if available)
- [ ] 2-3 key subpages (about, product, pricing)
- [ ] Interactive states (button hover, input focus)

**B. CSS Source Extraction** (via browser JS execution or source analysis)
- [ ] CSS custom properties (`--*` variables)
- [ ] `@font-face` declarations
- [ ] Computed styles for key selectors (h1-h6, body, button, input, card)
- [ ] Media query breakpoints
- [ ] Animation/transition definitions

**C. Asset Files**
- [ ] External CSS file URL list
- [ ] Font file URLs
- [ ] Design token files (e.g., `design-tokens.json`, `theme.ts`)

**D. Page Structure**
- [ ] DOM hierarchy (main landmark elements)
- [ ] Component pattern identification (nav, card, list, form, etc.)

#### Browser JS Extraction Scripts

Execute via browser tools to extract design data:

```javascript
// 1. Extract all CSS custom properties
(() => {
  const styles = getComputedStyle(document.documentElement);
  const vars = {};
  for (const sheet of document.styleSheets) {
    try {
      for (const rule of sheet.cssRules) {
        if (rule.style) {
          for (let i = 0; i < rule.style.length; i++) {
            const prop = rule.style[i];
            if (prop.startsWith('--')) {
              vars[prop] = rule.style.getPropertyValue(prop).trim();
            }
          }
        }
      }
    } catch(e) {} // cross-origin sheets
  }
  return JSON.stringify(vars, null, 2);
})()

// 2. Extract computed styles for key elements
(() => {
  const selectors = ['h1','h2','h3','h4','h5','h6','p','a','button',
    'input','nav','footer','[class*=card]','[class*=hero]'];
  const result = {};
  for (const sel of selectors) {
    const el = document.querySelector(sel);
    if (!el) continue;
    const s = getComputedStyle(el);
    result[sel] = {
      fontFamily: s.fontFamily,
      fontSize: s.fontSize,
      fontWeight: s.fontWeight,
      lineHeight: s.lineHeight,
      letterSpacing: s.letterSpacing,
      color: s.color,
      backgroundColor: s.backgroundColor,
      padding: s.padding,
      margin: s.margin,
      borderRadius: s.borderRadius,
      boxShadow: s.boxShadow,
      transition: s.transition
    };
  }
  return JSON.stringify(result, null, 2);
})()

// 3. Extract fonts
(() => {
  const fonts = new Set();
  for (const sheet of document.styleSheets) {
    try {
      for (const rule of sheet.cssRules) {
        if (rule instanceof CSSFontFaceRule) {
          fonts.add({
            family: rule.style.getPropertyValue('font-family'),
            src: rule.style.getPropertyValue('src'),
            weight: rule.style.getPropertyValue('font-weight'),
            style: rule.style.getPropertyValue('font-style')
          });
        }
      }
    } catch(e) {}
  }
  return JSON.stringify([...fonts], null, 2);
})()
```

### Phase 2: Analyze
-> `prompts/analyzer.md`

**Goal**: Structure the raw scraped data into the 9 Design MD modules.

#### Design MD — 9 Modules

| # | Module | Content | Key Output |
|---|--------|---------|------------|
| 1 | **Visual Theme & Atmosphere** | Design philosophy, mood, visual personality | 3-5 sentence qualitative description |
| 2 | **Color Palette & Roles** | Semantic color names + hex values + usage | Color palette table |
| 3 | **Typography Rules** | Font families, weight hierarchy, line-height, letter-spacing | Type scale table |
| 4 | **Component Stylings** | Buttons, cards, inputs, nav — all interactive states | Component specs |
| 5 | **Layout Principles** | Spacing system, grid, container widths, whitespace philosophy | Spacing token table |
| 6 | **Depth & Elevation** | Shadow system, surface hierarchy | Shadow level table |
| 7 | **Do's and Don'ts** | Design guardrails, anti-patterns | Rules list |
| 8 | **Responsive Behavior** | Breakpoints, touch targets, collapsing strategies | Breakpoint table |
| 9 | **Agent Prompt Guide** | Quick AI reference, color/font lookup tables | Cheat sheet |

#### Analysis Principles

1. **Observation over guessing** — Only document what screenshots and code show. Never fabricate.
2.