DESIGN.md Author

Distill a visual identity into a single markdown file that an AI coding agent can read and turn into pixel-consistent UI. The artifact is DESIGN.md, the format pioneered by Google Stitch and curated in awesome-design-md. It sits beside AGENTS.md — AGENTS.md says how to build, DESIGN.md says how it should look.

When to use

Invoke this skill when the user wants to:

Capture a website's visual language into one file (e.g. "make a DESIGN.md for stripe.com")
Turn a brand guide / style guide / mood board into AI-readable design tokens
Onboard an AI agent to a project's existing visual identity
Build a "design.md" the way awesome-design-md does it

Do NOT use this skill for:

Writing a CSS file, Tailwind config, or design-tokens JSON — DESIGN.md is markdown-first, prose + tokens, optimized for LLM reading.
A mood board or moodboard PDF — that's an input, not an output.
A figma plugin, code component library, or storybook setup.

Inputs you need before authoring

Before writing a single line, gather (ask the user concisely if missing):

Identity source — a URL, a brand book, screenshots, an existing product, or a mood-board description. The skill is only as accurate as its input. If the user has only a vibe ("I want it to feel like Linear meets Notion"), say so and treat the output as inspirational, not extracted.
Surface scope — marketing site? product UI? mobile app? blog? Default is "marketing surface" the way the awesome-design-md repo treats it.
Light or dark — many brands ship one or both. Pick the canonical canvas; document the other under Known Gaps if not extracted.
Format choice — frontmatter (newer, token-first, YAML + prose) vs numbered (older, prose-first, 9 sections). See "Format selection" below. If unspecified, default to frontmatter.

If the user gives you a URL with no other constraints, browse it (or ask them to grant access), inspect the live site for hex values, font families, radii, and spacing, then proceed.

Format selection

Two formats coexist in awesome-design-md. Both are valid; pick based on the user's preference and the level of structured tokenization they want.

Frontmatter format (default — 60% of the corpus)

YAML frontmatter declares tokens: colors, typography, rounded, spacing, components.
Components reference tokens via {token.refs} interpolation (e.g. backgroundColor: "{colors.primary}").
Prose sections below the frontmatter explain the why and how.
Use when the user wants tokens an LLM can pick up without parsing prose, or when components have many states.
Spec & full skeleton — see references/frontmatter-format.md and templates/frontmatter.md.

Numbered format (older — 40% of the corpus)

No YAML. Pure markdown with 9 numbered sections, hex values inline.
Use when the brand has fewer formal tokens, or when prose is more useful than a token graph (heavy editorial / photography-driven brands).
Spec & full skeleton — see references/numbered-format.md and templates/numbered.md.

If you're unsure, default to frontmatter — it's what newer sites in the corpus use and it gives the agent more to bind to.

The authoring process

Run these phases in order. Don't skip ahead.

Phase 1 — Extract raw values

From the source identity, pull:

Hex values for: page canvas, ink/text (heading, body, muted, disabled), brand primary, primary hover/active/focus, surface ladders (1–4 lifts), hairline borders, semantic (success, warning, error), accent decorations (gradients, shadows).
Typography: display family + body family + mono family (with public fallbacks if any are proprietary). For each role: size (px), weight, line-height, letter-spacing.
Border radius scale: smallest (xs, ~4px) → button (md, ~8px) → cards (lg, ~12px) → big tiles (xl, ~16px) → pill (9999px).
Spacing scale: usually a 4px or 8px base, then scale tokens xxs/xs/sm/md/lg/xl/xxl + a section-padding token (typically 64–96px).
Components: buttons (primary, secondary, ghost, inverse, disabled), cards (feature, pricing, testimonial, product-mockup), inputs, navigation, footer, badges/pills, tabs.
Shadow / elevation system: how depth is conveyed (real shadow? surface lift? hairline border? color-block?).
Photography & illustration treatment: dominant or absent? full-bleed? framed in cards? line-art? product UI?

Record every value next to its source observation ("on /pricing, the featured tier card uses..."). If a value cannot be observed, mark it as a Known Gap rather than guessing.

Phase 2 — Name tokens semantically

Tokens use role names, not literal names. The same hex can wear different role names in different brands. Examples:

colors.canvas not colors.white — canvas is the role; #ffffff is the value.
colors.ink not colors.gray-900 — ink is the role.
colors.primary for the single signature accent (the one chromatic color a brand defends).
colors.surface-1 … colors.surface-4 for a step-ladder of card backgrounds (use only as many steps as the brand actually uses).
colors.hairline and colors.hairline-strong for 1px divider tones.
colors.on-primary, colors.on-dark — text colors guaranteed legible on a given surface.
Semantic: colors.success, colors.warning, colors.error, colors.info.

Typography token names follow display-xl/lg/md/sm, headline, title-lg/md/sm, subhead, body-lg/md/sm, caption, eyebrow, button, nav-link, code/mono. Drop tokens the brand doesn't use; don't pad.

Spacing: xxs/xs/sm/md/lg/xl/xxl/section. Border radius: xs/sm/md/lg/xl/xxl/pill/full.

Phase 3 — Pick the canonical canvas + brand voltage

Every DESIGN.md needs to answer two questions in its first paragraph:

What is the canvas? — the page-level background that anchors the entire system. (Linear: #010102. Stripe: #ffffff. Claude: cream #faf9f5. Vercel: pure white.)
Where is the brand voltage? — the one chromatic accent, where it goes, and how scarce it is. (Linear: lavender on brand mark + primary CTA + focus only. Stripe: purple on CTA + links. Claude: coral on CTA + full-bleed callout cards.)

If you can't answer both in one sentence each, you haven't extracted enough yet — go back to Phase 1.

Phase 4 — Write the prose

This is where the file earns its keep. Tokens alone are not enough; an LLM needs the opinionated voice that explains how the brand differs from its category. See references/writing-voice.md for the full guide. Shortest version:

Be specific, not generic. "Warm coral with slight muted hue" not "orange-ish". "Lavender-blue with negative tracking" not "purple".
Compare to peers. "Where most AI brands use cool blue and slate, Claude uses warm cream and coral." This signals what NOT to default to.
Document scarcity rules. If an accent is used only on the brand mark + primary CTA + focus ring, say exactly that. Otherwise the agent will paint everything that color.
Include anti-patterns. A Don't list is half the document's value. "Don't use lavender as a section background. Don't pill-round CTAs. Don't introduce a second chromatic accent."
Reference tokens, not raw hex. In the frontmatter format, write {colors.primary} not #5e6ad2 in the prose. The frontmatter is the source of truth; prose mirrors it.
Document what's NOT visible. Add a Known Gaps section. Light mode missing? Form errors not extracted? Custom proprietary font? Say so.
Provide font substitutes. If the brand uses a proprietary face, name an open-source equivalent (Inter, Geist Sans, JetBrains Mono, EB Garamond, etc.).

Phase 5 — Assemble & lint

Write the file in the chosen format using the templates. Then sanity-check:

Does every prose mention of a hex have a matching token in YAML? (frontmatter format)
Does every component reference real tokens?
Are state variants (`-ho

design-md