DESIGN.md: give your coding agent a design system so every page looks the same

Ask an agent for five pages and you'll often get five slightly different shades of blue, three button styles and whatever font it felt like. DESIGN.md fixes that by putting your design system in one file every agent reads.

What it is

From the spec: DESIGN.md is "a self-contained, plain-text representation of a design system". The file has two layers:

1. YAML design tokens, the exact values: colors, fonts, sizes, corners, spacing, components
2. Markdown prose, the why: brand personality, when to use the accent color, what to avoid

In the README's words, "Tokens give agents exact values. Prose tells them why those values exist and how to apply them." The token system is inspired by the W3C Design Tokens format, including the {path.to.token} reference syntax. The spec version is currently "alpha".

A minimal DESIGN.md

Put this in your repo root as DESIGN.md:

---
version: alpha
name: Night Shift
colors:
  primary: "#111827"
  secondary: "#6B7280"
  tertiary: "#7C3AED"
  neutral: "#F9FAFB"
  on-tertiary: "#FFFFFF"
typography:
  h1:
    fontFamily: Inter
    fontSize: 3rem
    fontWeight: 700
    lineHeight: 1.1
  body-md:
    fontFamily: Inter
    fontSize: 1rem
    lineHeight: 1.6
rounded:
  sm: 6px
  md: 12px
spacing:
  sm: 8px
  md: 16px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
---

## Overview
Calm, focused developer tool. Dense but never cramped.

## Colors
- **Primary (#111827):** headlines and body text.
- **Tertiary (#7C3AED):** the only interactive color. Use it for buttons and links, nothing else.
- **Neutral (#F9FAFB):** page background.

## Do's and Don'ts
- Do use one primary button per screen.
- Don't introduce new colors; ask first.

The rules that matter

• Section order: sections are optional, but the ones you include should follow this order: Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do's and Don'ts.
• Token types: colors take any CSS color (hex is recommended), and dimensions use px, em or rem.
• Components can use backgroundColor, textColor, typography, rounded, padding, size, height and width. Variants like hover are separate entries, e.g. button-primary-hover.
• No duplicates: a duplicate section heading or top-level YAML key is an error.

Lint it

npx @google/design.md lint DESIGN.md

The linter runs eleven rules and returns JSON findings an agent can act on. Highlights:

It exits with code 1 on errors, so it can run in CI or in a Claude Code hook.

Windows: if the command does nothing or opens a Markdown editor, use npx -p @google/design.md designmd lint DESIGN.md.

Diff versions

npx @google/design.md diff DESIGN.md DESIGN-v2.md

This reports added, removed and modified tokens, and flags a regression (exit code 1) if the new version has more errors or warnings. It's useful when an agent "improves" your design system.

Export to Tailwind or design tokens

npx @google/design.md export --format css-tailwind DESIGN.md > theme.css         # Tailwind v4 @theme
npx @google/design.md export --format json-tailwind DESIGN.md > tailwind.theme.json  # Tailwind v3
npx @google/design.md export --format dtcg DESIGN.md > tokens.json               # W3C design tokens

Now your code and your agent read from the same source.

Wire it into your agent

Add a line to your AGENTS.md or CLAUDE.md:

For any UI work, read DESIGN.md first. Use only its tokens; don't invent colors,
fonts or spacing. Run `npx @google/design.md lint DESIGN.md` after editing it.

To give an agent the full format rules, npx @google/design.md spec prints the spec, ready to paste into a prompt.

Tips

• Write the prose. Tokens alone tell an agent what; a sentence like "tertiary is the only interactive color" stops it putting purple everywhere.
• Keep it short. It goes into context on every UI task.
• Pin the CLI version in CI while the format is alpha.
• Ask your agent to draft it from your existing CSS or Tailwind config, then lint and edit by hand.

Building your first app with an agent? Pair this with our prompt pack for shipping a web app and 10 copy-paste prompts.