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.
Impact: Medium
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)
Sources