DESIGN.md Format Specification to Document Design Systems for AI Agents
A new format specification, DESIGN.md (published under @google/design.md), pairs machine-readable YAML design tokens with human-readable markdown prose. It gives coding agents a persistent, structured understanding of a design system, helping them apply consistent color palettes, typography, and contrast standards.
Why it matters
AI agents frequently write code and generate UIs, but without structured visual constraints, they can easily violate brand design guidelines and contrast standards.
TL;DR
- 01DESIGN.md bridges the gap between machine-readable design tokens and human-readable guidelines for coding agents.
- 02The format uses YAML front matter for raw design variables and standard Markdown for contextual explanation.
- 03Windows command resolution requires using the dot-free `designmd` alias due to `.md` file associations.
- 04Supports multiple export formats including Tailwind v3 (via json-tailwind/tailwind) and Tailwind v4 (via css-tailwind).
Key facts
- Version
- alpha
- Supported Export Formats
- json-tailwind, css-tailwind, tailwind, dtcg
Structure of a DESIGN.md File
At the top of the file, YAML front matter defines raw design variables under keys like colors, typography, and spacing:
---
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"
---Below the front matter, standard markdown sections (e.g., ## Palette and ## Typography) provide context on why those variables exist.
Windows Workarounds and Execution
Due to a command resolution conflict where Windows associates the .md file suffix with Markdown editors, developers on Windows/PowerShell should invoke the linter using the designmd alias:
npx -p @google/design.md designmd lint DESIGN.mdCompiling to Tailwind CSS
The CLI can compile design guidelines into direct code setups. To output variables compatible with Tailwind v4, use the export flag:
npx @google/design.md export --format css-tailwind DESIGN.md > theme.cssThis enables an automated pipeline from high-level spec instructions straight to build systems.
Try it in 2 minutes
version: "alpha"
colors:
primary: "#1A1C1E"
secondary: "#6C7278"
tertiary: "#B8422E"
neutral: "#F7F5F2"yaml
✓ When to use
- When onboarding coding agents to build or maintain a project with strict brand design requirements
- When you need to export design tokens directly to Tailwind CSS or DTCG formats
✕ When NOT to use
- For projects without any visual components or frontend UI design requirements
- If you do not plan to use automated coding agents or automated design token compilation
What to do today
- Install the DESIGN.md CLI via npm package `@google/design.md`
- Create a DESIGN.md file with YAML front matter specifying your color palette and typography
- Lint your design spec using `npx @google/design.md lint DESIGN.md` (or `designmd` on Windows)