DESIGN.md is a plain-text spec, originally proposed by Google Labs, that captures a brand's design system — colors, typography, spacing, components, motion, accessibility — in a single Markdown file an AI coding agent can read. It's the first design-system format engineered for agent-as-collaborator workflows.

Why a plain-text format instead of design tokens JSON or a Figma file?

Coding agents (Claude, Cursor, Cline, Copilot, v0) read prose far better than they read schemas. A token JSON file says what the colors are; a DESIGN.md says what they mean — what mood they evoke, when to use which surface, how the type scale carries the voice. That semantic context is what lets an agent produce on-brand UI on the first try.

What does the Google Labs DESIGN.md spec include?

Google Labs publishes the format at github.com/google-labs-code/design.md and currently labels its spec version "alpha". It defines the foundations — colors, typography, spacing, radius, components, lineage — as YAML frontmatter plus free-form markdown. The official lint validates structure but stays loose on values.

How do AI coding agents actually use a DESIGN.md?

You drop the file into your repo, the agent reads it before generating UI, and produces components that match the brand voice — typography weights, color roles, spacing rhythm, motion easing. Works with Anthropic's Claude, Cursor, Cline, GitHub Copilot, v0, and any agent that can read project files.

How does the webdesignhot directory work?

Browse 254 curated DESIGN.md files extracted from real production sites — Linear, Vercel, Stripe, Anthropic, Apple, Tesla, and more. Pick one, run `npx @webdesignhot/design-md add `, and the file lands in your repo. Or extract one from any URL, or AI-generate a custom file from a description.

Spec · long-form

What is DESIGN.md?

Q: How does webdesignhot's spec differ?

webdesignhot publishes its own 0.1 spec — a parallel format that follows the same DESIGN.md philosophy but ships richer machine-readable tokens (multi-theme palettes, motion timings, breakpoint scales, accessibility contrast pairs) and a fixed 15-section markdown body covering motion, accessibility, voice, and dark mode. webdesignhot/0.1 files are designed to round-trip with Google Labs alpha files.

DESIGN.md is a plain-text spec for capturing a brand's design system in a single file an AI coding agent can read. Originally proposed by Google Labs and codified in google-labs-code/design.md, it is the first design-system format engineered for the agent-as-collaborator workflow — not for design tools and not for humans to scroll through.

Why a plain-text format

Coding agents — Claude, Cursor, Cline, GitHub Copilot, v0, Lovable, Replit Agent, Roo, and the long tail of agentic IDEs — all share a single tool: they read files. They do not open Figma. They do not parse JSON token bundles. They do not negotiate design-tool APIs. They read files.

A DESIGN.md is a file in your repo that the agent reads exactly the way it reads README.md or CLAUDE.md. The format is YAML frontmatter for the machine-readable token bundle, then markdown prose for the principles. The agent reads both. The designer (or the original brand's marketing site, if you extracted) writes both.

The Google Labs format

Google Labs publishes the canonical reference at github.com/google-labs-code/design.md. Their current spec version is labelled alpha. The format defines the file's two halves:

YAML frontmatter — a flat token bundle with colors, typography, rounded, spacing, components, plus metadata (name, description).
Markdown body — free-form prose explaining the visual atmosphere, typography rules, component guidelines, layout principles, and do's and don'ts.

A Google-style alpha file is enough for an agent to produce something on-brand. But it leaves out four things every agent eventually asks about: how do animations feel?, what's accessible here?, how does the voice sound?, and what does dark mode look like?

webdesignhot 0.1 — our richer take

Every entry in this directory ships spec: webdesignhot/0.1 — our own parallel format with the same DESIGN.md philosophy but a richer machine-readable layer (multi-theme palettes, motion timings, breakpoint scales, accessibility contrast pairs) and a fixed 15-section body. webdesignhot/0.1 files round-trip with Google Labs alpha — both formats are designed to be cross-readable by any tool that opens a Markdown file.

The body is exactly 15 numbered sections:

1. Visual Theme & Atmosphere

2. Color Palette & Roles

3. Typography Rules

4. Component Stylings

5. Layout Principles

6. Shapes & Radius Scale

7. Depth & Elevation

8. Interaction & Motion ✨

9. Accessibility & A11y ✨

10. Responsive Behavior

11. Content & Voice ✨

12. Dark Mode & Theming ✨

13. Lineage & Influences

14. Do's and Don'ts

15. Agent Prompt Guide

Sections 8, 9, 11, and 12 are webdesignhot/0.1 additions — not in Google Labs alpha, not in VoltAgent's awesome-design-md, not in designdotmd.directory.

How agents actually use it

You drop a single DESIGN.md into your project root (or any path your agent reads). Then in chat or in your CLAUDE.md / .cursorrules / system prompt, you say:

Use DESIGN.md as the source of truth for visual style.
Every component must reuse the color tokens, typography
scale, radius scale, motion timings, and accessibility
contrast pairs declared there. Quote the section number
when you cite a token (e.g. "per §3 Typography Rules").

The agent now produces UI that visibly belongs to the same brand — first try, no manual style-system audit, no Figma import. Switch brands? Replace the file.

Compared to alternatives

Figma — closed format, requires API access + tools. Agents can't read it directly.
DTCG JSON / W3C Design Tokens — machine-readable, but missing the prose principles agents need to make judgment calls. (DESIGN.md exports to DTCG; the inverse loses the voice.)
Tailwind theme config — too narrow. Captures colors and spacing but misses motion, voice, accessibility, and the "why."
Style guides written for humans — wonderful long-form essays, but agents skim. The numbered structure of webdesignhot/0.1 gives them direct section addressing.

How this directory works

Every entry on webdesignhot.com/design.md is a real-brand DESIGN.md (webdesignhot/0.1) file extracted (by hand or by Playwright + Claude vision pipeline) from a real production marketing site. We do not ship invented "vibe" brands. We do not auto-generate. We curate.

You can:

Browse the full catalog by category, tag, mood, or fuzzy search.
Install via the npm CLI — npx @webdesignhot/design-md add stripe.
Generate one with chat — describe the feeling, Claude shapes the tokens.
Extract from any URL — paste a production site, get a draft DESIGN.md.
Press ⌘K anywhere on this site to open the command palette.

Read the spec

The full webdesignhot/0.1 spec — every required field, every recommended section, every YAML rule — lives at /design.md/spec. The Google Labs alpha spec is at github.com/google-labs-code/design.md.

webdesignhot/0.1 — our parallel format alongside Google Labs DESIGN.md alpha. Cross-readable; the four extra sections are skip-friendly for tools expecting free-form prose.