DESIGN.md Overview

DESIGN.md is a plain-text file that travels with your code. It holds design tokens in YAML frontmatter and design rationale in Markdown prose. Any tool, agent, or contributor can read it without proprietary tooling. The format is maintained as @google/design.md at version alpha (0.3.0).

What is DESIGN.md?#

DESIGN.md is a plain-text file that lives at the root of a project repository, alongside README.md and CONTRIBUTING.md. It is the single source of truth for a project's visual identity: colors, typography, spacing, component styles, and any other design decisions that need to travel with the code.

Because it is plain Markdown, any contributor can read and edit it without design tooling, and any automated tool can parse it. Coding agents, linters, and exporters all consume the same file.

Two-layer structure#

Every DESIGN.md file has exactly two layers:

YAML frontmatter (between --- fences at the top). Machine-readable design tokens. These are the normative values.
Markdown body (everything after the closing ---). Human-readable design rationale organized into ## sections. Prose provides context for how to apply the tokens.

The tokens win when there is a conflict. An agent consuming the file should treat the prose as explanatory, not prescriptive.

Frontmatter fields#

The top-level keys recognized by @google/design.md 0.3.0:

Key	Type	Required	Description
`version`	string	No	Format version. Current value: `"alpha"`.
`name`	string	Recommended	A short human name for the design system (e.g., `Heritage`).
`description`	string	No	One-line summary of the visual identity.
`colors`	map	No	Color tokens as name-to-hex pairs.
`typography`	map	No	Typography tokens as name-to-object pairs.
`rounded`	map	No	Border-radius scale as name-to-dimension pairs.
`spacing`	map	No	Spacing scale as name-to-dimension pairs.
`components`	map	No	Component-level token groups (backgroundColor, textColor, etc.).

Canonical section order#

The Markdown body uses ## headings. Sections can be omitted, but those present must appear in this order. Out-of-order sections trigger a section-order warning from the linter.

#	Section	Accepted aliases
1	Overview	Brand & Style
2	Colors
3	Typography
4	Layout	Layout & Spacing
5	Elevation & Depth	Elevation
6	Shapes
7	Components
8	Do's and Don'ts

Additional or custom sections (e.g., Icons, Accessibility, Voice & Tone) are accepted by the parser and preserved. They do not trigger errors. Duplicate section headings (case-insensitive) are an error.

Minimal working example#

---
name: Heritage
version: alpha
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  body-md:
    fontFamily: Public Sans
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas. Deep ink headlines
on a warm limestone background with a single clay accent.

## Colors

The palette is rooted in high-contrast neutrals and one accent color.

## Typography

Public Sans handles all running text. Optical sizing via `lineHeight: 1.6`
keeps paragraphs airy at any screen density.

Token types at a glance#

Type	Format	Example
Color	`#` + 6-digit hex (sRGB)	`"#B8422E"`
Dimension	number + unit (`px`, `em`, `rem`)	`48px`, `-0.02em`
Token Reference	`{path.to.token}`	`{colors.primary}`
Typography	object with named sub-fields	See Typography

Next steps#

Colors: token shapes, reference syntax, contrast lint
Typography: the full typography object and all sub-fields

Try it in the tool

Was this page helpful?