What Is a DESIGN.md File? Format, Structure, and How to Generate One
DESIGN.md is a structured markdown file that documents a design system — colors, typography, spacing, and component tokens — in plain text. It is the file AI coding agents read to understand your brand before writing a single line of UI code.
What is a DESIGN.md file?
A DESIGN.md file is a plain-text markdown document that captures a design system in a portable, version-controllable format. It stores the visual decisions that define a product's look and feel — color tokens, type scale, spacing values, border radius, shadows — alongside human-readable rationale explaining why those decisions were made.
The name follows the same convention as README.md and CONTRIBUTING.md: a well-known filename placed at the root of a project, readable by anyone who opens the repository. The difference is that DESIGN.md is written for machines as much as for humans. AI coding agents, build tools, and linters can parse a structured DESIGN.md and apply its values automatically.
In practice, DESIGN.md serves three audiences simultaneously:
- AI coding agents — load it as session context so generated UI uses your brand colors, type scale, and spacing instead of generic defaults
- Developers — a single reference file that answers "what color is the primary button?" without opening Figma
- Build pipelines — a machine-parseable source of truth for token generation scripts and design-lint checks
The Google Labs open-source spec
If you search for "DESIGN.md," you will encounter two distinct things. The first is the Google Labs open-source DESIGN.md specification — a machine-readable design language standard that Google researchers developed to define a formal interchange format for design systems. It is a rigorous, schema-driven spec aimed at tooling interoperability.
The second is the broader convention of naming a design reference file DESIGN.md — the pattern this page describes, and what MYDESIGN.MD generates. The two share a name and a philosophy (design systems as text files), but differ in scope:
- Google Labs DESIGN.md spec — a formal machine-readable standard for design system interchange between tools. Targeted at tooling authors building on top of the format.
- DESIGN.md as a convention — a project-level markdown file documenting a design system in a format both humans and AI agents can read. Targeted at developers, AI agent users, and teams who want a portable design reference.
The Google Labs spec is worth knowing about — it represents where the industry may standardize. MYDESIGN.MD generates a DESIGN.md that aligns with the spirit of that spec (structured, portable, machine-readable) while optimizing for practical developer and AI agent use.
File anatomy: what's inside a DESIGN.md
A complete DESIGN.md file has two layers: a structured token block and human-readable prose. The token block gives machines exact values. The prose gives humans the intent behind those values.
Color tokens
The color section starts with a primitive palette (the raw brand colors) and then assigns semantic roles (what each color is used for). Separating these two layers is the key pattern — it is what makes tokens refactorable without breaking every component.
## Colors ### Primitive palette | Token | Value | Usage | |----------------------|-----------|------------------| | --color-slate-900 | #0F172A | Dark backgrounds | | --color-indigo-500 | #6366F1 | Brand accent | | --color-white | #FFFFFF | Light surfaces | | --color-slate-100 | #F1F5F9 | Muted backgrounds| ### Semantic roles | Token | Maps to | When to use | |-------------------------|-------------------|---------------------| | --color-bg-primary | --color-white | Page background | | --color-bg-surface | --color-slate-100 | Card backgrounds | | --color-text-primary | --color-slate-900 | Body text | | --color-accent | --color-indigo-500| CTAs, links, focus |
Typography scale
The type section documents every text role in the product — display, heading, subheading, body, caption, label — with the exact font-family, size, weight, and line-height for each.
## Typography Font: Space Grotesk (headings), Inter (body) | Role | Size | Weight | Line height | Usage | |------------|--------|--------|-------------|--------------------| | Display | 56px | 700 | 1.1 | Hero headlines | | Heading 1 | 40px | 600 | 1.2 | Page titles | | Heading 2 | 28px | 600 | 1.3 | Section titles | | Heading 3 | 20px | 600 | 1.4 | Card titles | | Body | 16px | 400 | 1.6 | Paragraph text | | Caption | 13px | 400 | 1.5 | Labels, meta text |
Spacing scale
The spacing section defines the base unit and scale. Most design systems use an 8px base with predictable multipliers. Naming each step makes the values usable as token references rather than magic numbers.
## Spacing Base unit: 8px | Token | Value | Usage | |----------------|-------|-------------------------------| | --space-1 | 4px | Tight internal padding | | --space-2 | 8px | Icon gaps, tight stacks | | --space-3 | 12px | Compact list item padding | | --space-4 | 16px | Standard component padding | | --space-6 | 24px | Section sub-divisions | | --space-8 | 32px | Card padding, section gaps | | --space-12 | 48px | Large vertical spacing | | --space-16 | 64px | Section separators |
Border radius, shadows, and component patterns
A complete DESIGN.md also captures the radius scale (what roundness values are used and where), the shadow definitions (elevation system), and key component patterns — the specific token combinations used for buttons, cards, inputs, and badges.
## Border radius | Token | Value | Usage | |---------------|--------|--------------------| | --radius-sm | 4px | Tags, chips | | --radius-md | 8px | Buttons, inputs | | --radius-lg | 12px | Cards | | --radius-full | 9999px | Pills, avatars | ## Component patterns ### Button (primary) background: var(--color-accent) /* #6366F1 */ color: var(--color-white) padding: var(--space-3) var(--space-6) /* 12px 24px */ radius: var(--radius-md) /* 8px */ font-size: 15px font-weight: 500 ### Card background: var(--color-bg-surface) /* #F1F5F9 */ border: 1px solid rgba(0,0,0,0.07) radius: var(--radius-lg) /* 12px */ padding: var(--space-8) /* 32px */
Design rationale (human-readable prose)
Below the token tables, a well-written DESIGN.md includes plain-text sections explaining the intent behind key decisions. This context is what makes the file useful to new team members — and to AI agents that need to understand when to break a rule.
## Design rationale ### Color system The color system uses a cool-dark primary (slate-900) with a vibrant indigo accent. Avoid warm colors — they conflict with the technical, precise brand voice. The accent is used sparingly: CTAs, active states, and focus rings only. ### Type hierarchy Space Grotesk is used for all headings to reinforce the geometric, modern product character. Inter carries the body text because it maximizes legibility at small sizes. Never mix two geometric sans-serifs in a single layout — the pairing rule is Grotesk for display, Inter for everything else. ### Spacing All spacing values are multiples of 8. When in doubt, round up to the next 8px step rather than using an intermediate value. The 4px (--space-1) unit exists only for micro-adjustments inside components.
Why AI coding agents need this file
AI coding agents — Claude Code, OpenAI Codex, Cursor, GitHub Copilot, Windsurf — start every session with no memory of the previous one. Ask any of them to build a button without design context and they will produce something technically functional but visually generic: an arbitrary blue, 4px radius, system font, 16px padding.
Providing a DESIGN.md file at session start gives the agent your exact design vocabulary before it writes a single line. The agent applies your primary color because it knows what that color is. It uses your border radius because it has the value. It reaches for the right type size because your scale is in its context window.
How each agent loads DESIGN.md
| Agent | Where to add DESIGN.md | How it is loaded |
|---|---|---|
| Claude Code | Add @DESIGN.md to CLAUDE.md | Auto-loaded every session via CLAUDE.md |
| OpenAI Codex | Add @DESIGN.md to AGENTS.md | Auto-loaded every session via AGENTS.md |
| Cursor | Paste tokens into .cursor/rules/design-tokens.mdc | Persistent workspace rule, all conversations |
| GitHub Copilot | Add to .github/copilot-instructions.md | Repository-scoped instructions, all files |
| Windsurf | Add tokens to .windsurfrules | Persistent project rules file |
How to generate a DESIGN.md automatically
Writing a DESIGN.md by hand from an existing website takes 4–8 hours of DevTools inspection, value extraction, and document formatting. MYDESIGN.MD generates the same output from a URL in a few minutes.
The automated workflow
- Paste your production URL into the extractor on the MYDESIGN.MD homepage
- Extraction runs automatically — CSS parsing, DOM inspection, screenshot analysis, font detection, and component pattern recognition run in parallel
- Download your DESIGN.md — along with design-tokens.json (DTCG format), CSS custom properties, Tailwind v4 config, and a design audit report
- Commit it to your project root and reference it in your agent context file (CLAUDE.md, AGENTS.md, .cursor/rules, etc.)
What the output includes
A DESIGN.md generated by MYDESIGN.MD covers every layer of a design system:
- Full color palette with primitive values and semantic role assignments
- Typography scale — every text role with family, size, weight, and line-height
- Spacing scale with named token references
- Border radius values across all usage contexts
- Box shadow definitions and elevation system
- Key component patterns: buttons, cards, inputs, badges
- Design rationale notes inferred from the extracted visual language
Keeping DESIGN.md in sync
DESIGN.md is a versioned snapshot, not a live sync. When your design changes — new brand colors after a rebrand, updated type scale, new spacing values — re-run the extraction on your updated production URL and commit the new file. The git diff shows exactly what changed, giving you a design changelog alongside your code history.
Frequently asked questions
What is a DESIGN.md file?
DESIGN.md is a structured markdown file that documents a design system — colors, typography, spacing, border radius, shadows, and component patterns — in plain text. It serves as a portable design specification readable by AI coding agents, developers, and build tools.
Is DESIGN.md an official standard?
There are two distinct uses of the name. Google Labs publishes an open-source DESIGN.md specification as a machine-readable design language standard. Separately, DESIGN.md is a widely-adopted filename convention for project-level design documentation — the same way README.md is a convention, not an official standard. MYDESIGN.MD generates the latter: a portable, human+machine-readable design reference document optimized for AI coding agent use.
What goes in a DESIGN.md file?
A complete DESIGN.md includes: color tokens (primitive palette + semantic roles), typography scale (family, size, weight, line-height per text role), spacing scale, border radius values, shadow definitions, and component patterns. It also typically includes design rationale — human-readable prose explaining the intent behind key decisions.
How is DESIGN.md different from a design system?
A design system is the full collection of guidelines, components, and tooling — typically maintained in Figma, Storybook, or a component library. DESIGN.md is a distilled, flat-file representation of what that system actually looks like in your live production website: a single document capturing the essential values and patterns without requiring any external tool to access. It reflects reality, not intention — what shipped, not what was spec'd.
Which AI coding agents support DESIGN.md?
All of them — because DESIGN.md is plain markdown. Claude Code references it via CLAUDE.md. OpenAI Codex via AGENTS.md. Cursor via .cursor/rules/design-tokens.mdc. GitHub Copilot via .github/copilot-instructions.md. Windsurf via .windsurfrules.
How do I add DESIGN.md to Claude Code?
Place DESIGN.md in the project root. Open or create CLAUDE.md in the same directory and add @DESIGN.md on its own line. Claude Code reads CLAUDE.md at the start of every session, so your design tokens load automatically as persistent context.
How do I generate a DESIGN.md from my website?
Paste your production URL into MYDESIGN.MD. The extractor runs CSS parsing, DOM inspection, screenshot analysis, and font detection in parallel and returns a complete DESIGN.md in a few minutes — no install, no configuration required.
Do I need to update DESIGN.md when my design changes?
Yes. DESIGN.md is a snapshot, not a live sync. When your design changes, re-run the extraction on your updated production URL and commit the new file. The git diff gives you a design changelog alongside your code history.