Spec · long-form

What is DESIGN.md?

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 v1 spec — what Google shipped

The original v1 spec defines the file's two halves:

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

A v1 file is enough for an agent to produce something on-brand. But v1 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?

v1.5 — webdesignhot's strict superset

Every entry in this directory ships spec: design.md/v1.5 — a strict superset of v1 that adds the four missing sections plus a richer machine-readable layer. v1.5 is fully backwards compatible: every v1-aware tool reads v1.5 files without modification.

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 v1.5 additions — not in Google's v1, 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 DESIGN.md/v1.5 gives them direct section addressing.

How this directory works

Every entry on webdesignhot.com/design.md is a real-brand DESIGN.md/v1.5 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 linear.
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 v1.5 spec — every required field, every recommended section, every YAML rule — lives at /design.md/spec. The original Google Labs v1 spec is at github.com/google-labs-code/design.md.

v1.5 specced by webdesignhot — a strict superset of Google Labs DESIGN.md/v1. Compatible with every v1 reader; the four extra sections are skip-friendly.