DESIGN.md Examples

If you're new to the format, start with what DESIGN.md is and keep the DESIGN.md spec guide open in a second tab. This page is the practical companion: files you can copy, with every design decision explained. All three examples are released under CC0: copy, adapt, and ship them, attribution appreciated.

The minimal starter, annotated#

This is the smallest DESIGN.md we'd actually recommend committing. It defines one brand color, two type levels, one radius, a spacing scale, and two components, and it passes all nine lint rules of v0.3.0 with zero warnings.

---
version: alpha
name: Starter
colors:
  primary: "#1D3557"
  surface: "#FFFFFF"
  on-surface: "#1F2933"
typography:
  headline-md:
    fontFamily: Inter
    fontSize: 28px
    fontWeight: 600
    lineHeight: 1.2
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.6
rounded:
  md: 8px
spacing:
  sm: 8px
  md: 16px
  lg: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.surface}"
    rounded: "{rounded.md}"
    padding: 12px
  card:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
    rounded: "{rounded.md}"
    padding: "{spacing.md}"
---

## Overview

Calm and professional. Prefer whitespace over decoration.

## Do's and Don'ts

- Do use the primary navy for one main action per screen.
- Don't introduce colors that are not defined above.

Here is what every line does.

---
version: alpha
name: Starter

The --- fence opens the YAML frontmatter: the machine-readable half of the file. version is optional; alpha is the current (and only) format version. name labels the design system for tools and diffs.

colors:
  primary: "#1D3557"
  surface: "#FFFFFF"
  on-surface: "#1F2933"

colors is a flat map from token name to any valid CSS color string; hex is the recommended default. primary is the one token the spec requires once a colors section exists: omit it and the linter warns (missing-primary) and agents will invent one for you. surface/on-surface follow the spec's recommended semantic names: background and the text that sits on it.

typography:
  headline-md:
    fontFamily: Inter
    fontSize: 28px
    fontWeight: 600
    lineHeight: 1.2

Each typography token is an object. fontSize is a Dimension (a string with px, em, or rem); fontWeight is a number; the unitless lineHeight is a multiplier of the font size, which the spec recommends over fixed dimensions. body-md (16px, weight 400, line-height 1.6) works the same way. Defining at least one typography token also silences the missing-typography warning: without it, agents fall back to default fonts.

rounded:
  md: 8px
spacing:
  sm: 8px
  md: 16px
  lg: 32px

Two more flat maps: scale-level to Dimension. Any descriptive key is valid, but sm/md/lg are the convention. Including both sections avoids the missing-sections info finding.

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.surface}"
    rounded: "{rounded.md}"
    padding: 12px

Components map a component name to a group of properties. The spec defines exactly eight valid properties: backgroundColor, textColor, typography, rounded, padding, size, height, width; anything else is accepted with a warning. Values in {curly.braces} are token references; if one doesn't resolve, that's a broken-ref, the only finding the linter treats as a hard error. White text on #1D3557 navy clears WCAG AA (4.5:1) comfortably, so the contrast-ratio rule stays quiet. Note that every color token is referenced by some component: unreferenced colors trigger orphaned-tokens warnings.

## Overview
...
## Do's and Don'ts

After the closing --- comes the Markdown body. Sections are optional, but the ones you include must follow the canonical order (Overview first, Do's and Don'ts last). As the spec puts it: "The tokens are the normative values; the prose provides context for how to apply them."

Verify it yourself:

npx @google/design.md lint DESIGN.md
# summary: { "errors": 0, "warnings": 0, "infos": 1 }

(The one info finding is token-summary, a neutral token count.)

A complete brand example, section by section#

The starter covers structure; a real brand file adds voice. "Meridian" is a fictional B2B analytics product: 7 colors, 9 typography levels, 5 radii, 6 spacing tokens, 8 components, and all eight canonical body sections. It's built to lint clean and stay spec-compliant throughout. The highlights below, in canonical section order, are the parts shown here.

Overview sets the personality an agent falls back on when no token answers the question: "precise, calm, and trustworthy, closer to a well-set annual report than a startup dashboard."

Colors pairs the token map with prose that names each role:

colors:
  primary: "#134E4A"
  secondary: "#3B4252"
  tertiary: "#9A3412"
  neutral: "#F6F4EF"
  surface: "#FFFFFF"
  on-surface: "#1C1B1A"
  error: "#B3261E"

The body explains intent the values can't carry: tertiary is "the single call-to-action accent, use sparingly." The underlying idea is worth internalizing: clearly described intent shapes a generated design more than exact values do.

Typography uses the spec's recommended nine-level naming (headline-display down to label-sm); most design systems have 9-15 levels. The prose adds a rule no token can express: "Never use Fraunces below 28px."

Layout documents the grid in prose (12 columns, 24px gutters) while spacing carries the values, including named tokens like gutter: 24px.

Elevation & Depth is prose-only by design (the token schema has no shadow type), so this section is where flat-design rules live: "Hierarchy comes from tonal layering, not from shadows."

Shapes mirrors the rounded map: 8px buttons, 16px cards, full: 9999px pills for badges only.

Components is where tokens meet: references can point to composite values here (e.g. typography: "{typography.label-lg}"), and states are separate keys, not nested maps:

components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.surface}"
    typography: "{typography.label-lg}"
    rounded: "{rounded.md}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "#0C3835"

Do's and Don'ts ends the file with guardrails an agent can actually follow: "Do use tertiary (#9A3412) for at most one call to action per screen."

How do you do dark mode in DESIGN.md?#

Since v0.3.0 the format supports nested token groups, referenced with dot-separated paths, so grouping a token's light and dark values is valid:

colors:
  primary:
    light: "#134E4A"
    dark: "#8FD9CE"
components:
  card:
    backgroundColor: "{colors.primary.light}"

References use the dot path ({colors.primary.dark}). One caveat: earlier CLI versions (0.1.x and 0.2.x) were flat-only, so if portability across versions matters, the flat approaches below travel further. (In our July 2026 analysis of all 74 files in the awesome-design-md collection, 3 files failed to parse on a YAML syntax error in a compact mapping, a reminder to keep whatever structure you choose well-formed.) Three flat-friendly ways to theme:

1. Semantic token names plus component variants (one file). Add -dark counterparts as ordinary flat tokens, and dark component variants the same way the spec models hover states:

colors:
  primary: "#134E4A"
  primary-dark: "#8FD9CE"
  surface: "#FFFFFF"
  surface-dark: "#131614"
  on-surface: "#1C1B1A"
  on-surface-dark: "#E8E6E3"
components:
  card:
    backgroundColor: "{colors.surface}"
    textColor: "{colors.on-surface}"
  card-dark:
    backgroundColor: "{colors.surface-dark}"
    textColor: "{colors.on-surface-dark}"

Unknown color token names are explicitly accepted by the spec, so surface-dark is fully valid. Note the dark primary is lighter (#8FD9CE) so it stays AA-legible on near-black. A full dark-mode file built this way, including a dark button variant and theme rules in Do's and Don'ts, is spec-compliant, with every light and dark pair above 4.5:1.

2. One DESIGN.md per theme. Keep DESIGN.md (light) and DESIGN.dark.md with identical token names and different values, and point your agent at the right one. npx @google/design.md diff DESIGN.md DESIGN.dark.md shows exactly which tokens differ, which keeps the files from drifting apart.

3. Prose guidance in Do's and Don'ts. For simple cases, a rule like "In dark mode, swap surface to #131614 and raise primary to #8FD9CE; keep every pair at WCAG AA" costs three lines and travels with the file.

Common mistakes in the wild#

Our July 2026 analysis of all 74 files in the awesome-design-md collection found zero files with lint errors, but not a single file free of warnings (1,341 warnings total, median 16 per file). The failure patterns repeat:

The pattern to copy from the three examples above: define only colors your components actually use, stick to the eight valid component properties, and check every text/background pair against 4.5:1.

Where to find more examples#

The largest collection is VoltAgent's awesome-design-md: 74 DESIGN.md files from well-known brands as of July 2026. Read them for structure and section ideas (all 74 follow the canonical section order), but with the lint caveats above in mind. The official spec repo includes a compact reference example, and when you're ready to write your own from scratch, our guide on how to write a DESIGN.md covers the method.

Preview your file#

Reading YAML is not the same as seeing a design system. Paste any of these examples (or your own file) into the DESIGN.md Viewer and it renders as a navigable brand guideline, entirely in your browser. Then make lint part of the loop:

npx @google/design.md lint DESIGN.md

Next step: pick the starter, swap in your brand's values, and check the result in the DESIGN.md Viewer before you commit it.