DESIGN.md Creator

Reverse-engineer a website's visual design system and produce a fully spec-compliant DESIGN.md file following the google-labs-code/design.md format.

What this produces

A DESIGN.md file with two layers:

1. YAML frontmatter — machine-readable design tokens: colors, typography, spacing, rounded corners, components
2. Markdown body — human-readable rationale for each design decision, in 8 canonical sections

The output is ready for agents to consume immediately — no post-processing needed.

Step 1: Get the URL

If the user provided a URL via $ARGUMENTS, use it. Otherwise ask:

What website should I reverse-engineer? Provide the URL and I'll generate a DESIGN.md from its visual design.

Optionally, also tell me:

• Where to save the file (default: DESIGN.md in the current directory)
• Whether this is a dark-mode or light-mode site (I'll detect this automatically if you don't know)
• Any specific components you want captured (buttons, cards, inputs, nav, etc.)

Wait for the URL before proceeding.

Step 2: Fetch and analyze the site

Fetch the page and all significant visual signals:

1. Fetch the main URL — use whichever method your agent environment supports:
   • curl (works in any agent with shell access): curl -sL --max-time 15 -A "Mozilla/5.0" "<URL>" — captures raw HTML including <style> blocks and inline CSS
   • webfetch tool (if your agent provides it natively): use it directly for cleaner content extraction
   • If the initial fetch returns no CSS (JS-heavy SPA), also fetch the page's linked .css files: extract <link rel="stylesheet" href="..."> URLs from the HTML, resolve each href to an absolute URL using the page's final URL after redirects (e.g., /assets/app.css → https://example.com/assets/app.css, //cdn.example.com/app.css → https://cdn.example.com/app.css), de-duplicate, then curl each one
2. Identify key sub-pages — if the site has a component library, style guide, or "About" page, fetch those too (up to 2–3 additional pages) to improve coverage
3. Look for existing design system artifacts — check for /design-tokens.json, /tokens.json, tailwind.config.js, or any design system links in the page source

What to extract from the fetched content:

Note: You're inferring from observed CSS/HTML. Be honest about what you can directly observe vs. what you're inferring from visual patterns. Dark-mode sites typically have low-luminance surface colors and high-contrast text; light-mode sites are the inverse. When you can't determine an exact hex value, make a design-coherent choice and note it in the prose.

Step 3: Build the DESIGN.md

Read references/design-md-spec.md for the complete token schema and section rules.

Token extraction rules

Colors — Extract the site's full color role set. At minimum:

• primary — main brand/action color
• secondary — supporting accent or secondary brand color
• neutral / surface — background/surface color
• on-primary, on-surface — text colors on those surfaces
• Include semantic colors if detectable: error, warning, success
• Name tokens semantically (primary, secondary, tertiary, neutral) or use Material Design role names if the site uses a Material-style palette

Typography — Identify the main type scale. Typically 5–12 levels:

• Display/headline levels (large, impactful headings)
• Body levels (body-lg, body-md, body-sm)
• Label levels (captions, tags, small UI text)
• Include all detectable properties: fontFamily, fontSize, fontWeight, lineHeight, letterSpacing
• Dimensions must include units: px, em, or rem

Spacing — Extract the spacing scale. Common pattern: a base unit (4px or 8px) with named steps: xs, sm, md, lg, xl. Also include layout-specific values like gutter, margin, container-max.

Rounded — Extract corner radius values. Name them: sm, DEFAULT, md, lg, xl, full (for pill shapes).

Components — Capture 4–8 key components. For each, include as many valid properties as observed: backgroundColor, textColor, typography (token ref), rounded (token ref), padding, height, width. Use token references like {colors.primary} instead of hardcoded hex values wherever possible. Include hover variants as separate entries (e.g., button-primary-hover).

Sections to write

Write all 8 sections in canonical order. Each section combines YAML tokens (defined in frontmatter) with prose rationale. For sections where tokens aren't applicable (Elevation, Shapes, Do's and Don'ts), write prose only.

1. Overview — Brand personality, target audience, emotional tone, design style (flat, glassmorphism, neumorphism, material, etc.), key design decisions. 2–4 sentences that give a coherent aesthetic picture.

2. Colors — Describe the role of each color palette entry. What does each color mean in the design? When is it used? Reference the token names.

3. Typography — Describe the font strategy: which typefaces, why they were chosen, how the scale is organized, any special treatments (tight tracking on headlines, text-shadow on dark backgrounds, etc.).

4. Layout — Grid system (fluid, fixed, 12-column?), spacing philosophy (8px grid, dense vs. airy), max-width, container strategy.

5. Elevation & Depth — How visual hierarchy is communicated: shadows, tonal layers, glassmorphism, borders, z-axis layering. If flat design, describe what replaces shadows.

6. Shapes — Corner radius philosophy: sharp/technical, soft/organic, fully rounded pills, mixed. Which components use which radius.

7. Components — Walk through the key component tokens and explain the design rationale for each group (action elements, containers, inputs, typography application).

8. Do's and Don'ts — 3–5 concrete rules for maintaining design consistency. Things like "always use {colors.primary} for CTAs, never {colors.secondary}" or "never use pure black (#000000) for text — use on-surface".

YAML frontmatter structure

---
name: <Site/Brand Name>
description: <optional one-line brand tagline>
colors:
  primary: "#XXXXXX"
  ...
typography:
  headline-lg:
    fontFamily: <font>
    fontSize: <Npx>
    fontWeight: <number>
    lineHeight: <1.2 or 24px>
    letterSpacing: <-0.02em or 1px>
  ...
rounded:
  sm: <Npx or Nrem>
  ...
spacing:
  base: <Npx>
  ...
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    ...
  ...
---

Step 4: Validate and save

After generating the content:

1. Self-check these things before writing the file:

   • All token references ({path.to.token}) resolve to a defined token
   • Color values start with # followed by 6 hex digits
   • All dimension values have units (px, em, rem) — no bare numbers except: font weights, unitless line-height multipliers, and spacing values (which may be unitless ratios or column counts per the spec)
   • Section order matches the canonical order (Overview → Colors → Typography → Layout → Elevation & Depth → Shapes → Components → Do's and Don'ts)
   • Component properties: canonical keys (backgroundColor, textColor, typography, rounded, padding, size, height, width) pass the linter silently; unknown keys are accepted by the spec but will produce a linter warning — flag them in the confidence notes

2. Check for an existing file at the target path before writing:

   • If DESIGN.md (or the user-specified path) already exists, warn the user: "A DESIGN.md already exists at this path. Overwrite, save as DESIGN-<site-name>.md, or cancel?" Wait for their choice before writing.
   • If no file exists, proceed directly.

3. Save the file as DESIGN.md in the current working directory (or the path the user specified).

4. Tell the user what was generated:

DESIGN.md saved.

Design system: [Name]
Style: [e.g., Glassmorphism / Flat / Material / Custom]
Colors: [N tokens] — [brief palette description]
Typography: [N levels] — [font family names]
Components: [list of captured components]

Confidence notes:

• [Any values that were inferred rather than directly observed]
• [Any sections that had limited CSS data and required design judgment]

Want me to refine any section, add more components, or lint the file with npx @google/design.md lint DESIGN.md?

Recovery

Rules

• Never fabricate specific brand hex values with false certainty — if you inferred a color, say so
• All token cross-references must point to defined tokens — no dangling refs
• Dimensions must always have units (exception: unitless lineHeight multipliers like 1.5 are valid)
• The YAML frontmatter is normative; prose is explanatory context — don't contradict one with the other
• Output goes in the current working directory as DESIGN.md unless the user specifies otherwise
• If a section has genuinely no applicable content (e.g., a flat design with no elevation), include it briefly and explain: "This design system uses flat tonal layering rather than shadows — see Colors for the tonal surface stack"