---
name: design-md-url
description: Generate a spec-compliant DESIGN.md design-system file from a website URL. Use when the user runs /design-md-url with a URL, or asks to extract, capture, or create a DESIGN.md, design system, or design tokens from a website. Produces a slug-design.md file (e.g. sample.com becomes sample-design.md) based on the Google Stitch DESIGN.md specs.
---

# design-md-url

Turn a live website into a **DESIGN.md** file — the YAML-front-matter + markdown
design-system format from [Google Stitch](https://stitch.withgoogle.com/docs/design-md/overview)
that describes a design system to AI coding agents.

## When to use

- The user types `/design-md-url <url>` (e.g. `/design-md-url sample.com`).
- The user asks to "make a DESIGN.md from this site", "extract design tokens
  from this URL", "capture this site's design system", etc.

## Inputs

1. **A URL.** Accept it with or without a scheme (`sample.com`, `https://sample.com`).
   If no URL is given, ask for one.
2. **Output name (optional).** Default: the first label of the hostname plus
   `-design.md` — so `sample.com` → `sample-design.md`, `https://www.foo.io/x` →
   `foo-design.md`.

## How it works

This skill runs in many environments — Claude Code and other coding agents (with a
terminal), and **online chatbots like claude.ai or other assistants that load
skills but have no terminal or filesystem.** Pick the path that fits your
environment. **Path A works everywhere and is the default.**

### Path A — Agent-authored (works everywhere, no terminal needed)

Use this whenever you can fetch a web page with your own tools. It also produces
the highest-quality, most semantically-correct file.

1. **Fetch the site** with your web tool (WebFetch / browse / read-url). Pull the
   rendered page and its CSS. These are the **ground truth** — only use color,
   font, size, radius, and spacing values that actually appear on the site; do not
   invent values.
2. **Read the format** in [reference/spec.md](reference/spec.md) and skim
   [reference/example-design.md](reference/example-design.md) so the output is
   valid. (Sources: [reference/sources.md](reference/sources.md).)
3. **Synthesize the DESIGN.md.** Map observed values onto *semantic* token names
   (`primary`, `surface`, `on-surface`, `body-md`…), quote hex colors and token
   references (`"{colors.primary}"`), keep dimensions/weights bare, and write the
   body sections **in this order**: Overview, Colors, Typography, Layout,
   Elevation & Depth, Shapes, Components, Do's and Don'ts. Describe the brand
   personality you actually observe.
4. **Validate.** Front matter starts/ends with `---`; `name` is required;
   no duplicate `##` headings; references use `{group.token}`.
5. **Deliver it** (see Output below) — write a file if you have a filesystem, or
   present the full file in the chat for the user to copy/save if you don't.

### Path B — Bundled script (optional, when a terminal/Node is available)

If you have a shell (Claude Code, a local terminal, CI), the bundled
dependency-free Node 18+ tool fetches the site and writes a complete draft on its
own — fast and deterministic. It can also run with **no install** via npx.

```bash
# from the repo
node scripts/design-md.mjs sample.com                 # writes ./sample-design.md
node scripts/design-md.mjs https://stripe.com --out stripe-design.md
node scripts/design-md.mjs sample.com --json          # raw signals, no file

# or with no clone/install
npx design-md-url sample.com

# scan your own dev server (private hosts are blocked by default for safety)
node scripts/design-md.mjs http://localhost:3000 --allow-local
```

See [reference/cli.md](reference/cli.md) for all flags. The script's output is a
solid starting point; you can then refine its naming and prose using Path A.
A good hybrid: run the script (or `--json`) to get exact values, then polish.

## Output

- **Filename:** `<name>-design.md` (e.g. `sample-design.md`). Tell the user it can
  be renamed to `DESIGN.md` and dropped in their project root.
- **If you have a filesystem:** write the file and show its path plus a short
  summary (palette, type scale, components captured). Never overwrite an existing
  file without saying so.
- **If you don't (online chatbot):** output the entire DESIGN.md in a fenced code
  block so the user can copy or download it; there's no file to write.
- **Encoding:** UTF-8, LF line endings.
- **Token values must be real** (observed on the site). Only the *narrative* prose
  may be inferred from the site's look and feel.