copy-design

Copy Design

Crawl any website and produce a production-quality DESIGN.md that captures its complete visual design system — colors, typography, spacing, elevation, components, and layout patterns — in a hybrid format that is both human-readable and machine-parseable.

When to Use

• •User provides a URL and wants a DESIGN.md
• •User says "copy design", "extract design", "design system from this site"
• •User wants to replicate a website's look and feel in their own project

Step 1: Gather Input

Ask the user:

1. URL — which website to analyze (required)
2. Pages — "I'll crawl the homepage. Want me to crawl additional pages for a more complete picture? (e.g., pricing page, about page)" Default: homepage only.
3. Name — auto-extract from domain (e.g., linear.app) unless user overrides
4. Save path — where to save the output file. Default: ./{domain}-DESIGN.md in current directory. User can specify any path.

Step 2: Crawl & Extract Design Tokens

Use a 3-tier fallback chain. All tools run locally — zero API cost.

Tier 1: Playwright Headless (fast, preferred)

Write a Python script to /tmp/design-extract.py that:

# Core extraction logic (adapt as needed):
# 1. Launch headless Chromium
# 2. Navigate to URL, wait for networkidle
# 3. Take desktop screenshot (1440px) → /tmp/design-desktop.png
# 4. Take mobile screenshot (375px) → /tmp/design-mobile.png
# 5. page.evaluate() JavaScript that extracts:
#    - CSS custom properties (--* from :root)
#    - Background-color + color from all visible elements (frequency map)
#    - font-family, font-size, font-weight, line-height, letter-spacing
#      from h1-h6, p, button, a, input, nav, label, span
#    - All unique border-radius values
#    - All unique box-shadow values
#    - Padding/margin from major containers
#    - External stylesheet URLs
# 6. Output JSON → /tmp/design-tokens.json

Run with: python /tmp/design-extract.py "<URL>"

If the page loads but extraction returns sparse data, that's normal — many sites compile CSS variables away. The color/font frequency maps still capture rendered values.

Tier 2: Playwright Headed Mode (if headless is blocked)

If Tier 1 fails with a bot-detection error, re-run with headless=False to open a real browser window. Most anti-bot systems pass headed browsers.

Tier 3: crawl4ai MCP (if Playwright fails entirely)

Call mcp__crawl4ai__crawl with the URL. This returns page content as markdown/HTML. Less detailed than Playwright computed styles, but provides page structure, navigation labels, component names, and inline styles.

If all tiers fail

Tell the user: "This site blocks automated access. Try a different URL or a simpler page on the same site."

Step 3: Screenshot Analysis

Read the saved screenshot images (/tmp/design-desktop.png, /tmp/design-mobile.png).

Analyze visually for things the programmatic extraction might miss:

• •Overall visual atmosphere (warm/cool, dark/light, glassmorphism, etc.)
• •Color-block page rhythm (header → body → feature band → footer)
• •Image/illustration treatment style
• •Whitespace philosophy (generous or tight)
• •Component shapes visible (pill buttons, rounded cards, sharp edges)
• •Responsive differences between desktop and mobile

Step 4: Generate DESIGN.md

First, read the included exemplars for format and quality calibration:

examples/claude-com-DESIGN.md    ← AI/tech SaaS (warm editorial, serif + sans, cream canvas)
examples/starbucks-DESIGN.md     ← Retail/consumer brand (four-tier green system, custom typeface, pill buttons)

These are real DESIGN.md files — use them as gold standards for structure, depth, and tone. Pick the exemplar closest to the target site's category. If the user also has an existing DESIGN.md in their project, match that format instead.

Output Structure: Hybrid Format

The DESIGN.md has two parts:

Part A: YAML Frontmatter (structured tokens between ---)

---
version: alpha
name: "{domain}-design-analysis"
description: "1-2 paragraph brand summary"

colors:
  primary: "#hex"
  primary-active: "#hex"
  # ... semantic color tokens

typography:
  display-xl:
    fontFamily: "Font, fallback"
    fontSize: 64px
    fontWeight: 400
    lineHeight: 1.05
    letterSpacing: -1.5px
  # ... full hierarchy

rounded:
  sm: 4px
  md: 8px
  # ... scale

spacing:
  xs: 8px
  md: 16px
  # ... scale

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.button}"
    rounded: "{rounded.md}"
    padding: 12px 20px
  # ... key components with {token.ref} syntax
---

Part B: Markdown Sections (after the closing ---)

1. Overview — Brand atmosphere narrative + "Key Characteristics" bullet list
2. Colors — Organized by role: Brand & Accent, Surface, Text, Semantic. Each entry: Name (#hex): usage description
3. Typography — Font families, hierarchy table (Token | Size | Weight | Line Height | Spacing | Use), principles
4. Layout — Spacing system, grid & container, whitespace philosophy
5. Elevation & Depth — Treatment table (Level | Treatment | Use), shadow philosophy
6. Shapes — Border radius scale table, photography/illustration treatment
7. Components — Detailed per-component specs (buttons, cards, inputs, nav, tags, footer)
8. Do's and Don'ts — 8-12 Do bullets, 6-10 Don't bullets
9. Responsive Behavior — Breakpoints table, touch targets, collapsing strategy
10. Iteration Guide — Practical tips for using these tokens in code generation
11. Known Gaps — Honest list of what was not captured (proprietary fonts, animations, auth-gated pages)

Critical Rules for Generation

• •Never fabricate hex codes, font names, or pixel values not confirmed by extraction or screenshot
• •Use {token.ref} syntax in components (e.g., "{colors.primary}" not the raw hex)
• •If a section has no extractable data, write the header + "Not extracted — [reason]"
• •Color names should be semantic (e.g., "Coral Primary", "Canvas", "Ink") not generic ("Color 1")
• •Description field should capture the brand personality, not just list features

Step 5: Save & Confirm

Save to the path specified by the user in Step 1 (default: ./{domain}-DESIGN.md).

Check if file exists and ask before overwriting.

Show the user a summary:

• •File path and size
• •Number of colors extracted
• •Number of font families found
• •Number of components documented
• •Any known gaps

Multi-Page Crawling

When crawling multiple pages:

• •Run the extraction script once per page (sequentially)
• •Merge JSON outputs: union of colors, union of typography, union of components
• •Note which page each component was first observed on
• •More pages = more complete design system, but diminishing returns after 3-4 pages

Prerequisites

• •Python 3 with playwright package installed (pip install playwright && playwright install chromium)
• •OR access to the crawl4ai MCP server as fallback
• •Claude Code (or any Claude-based coding tool that can read screenshots)

Example Usage

User: /copy-design https://linear.app
Claude: I'll crawl linear.app homepage. Want additional pages? (features, pricing, changelog?)
User: Just homepage is fine
Claude: [runs extraction → analyzes screenshots → generates DESIGN.md]
       Saved to ./linear.app-DESIGN.md (580 lines)
       - 24 colors extracted
       - 2 font families (Inter, JetBrains Mono)  
       - 18 components documented
       - Known gaps: animation timings, auth-gated dashboard