How to Create a DESIGN.md from Scratch

Updated on
design-mdtutorialai-agents

A DESIGN.md file is a single Markdown document that holds your entire design system — colors, typography, spacing, components — in the format defined by google-labs-code/design.md. When an agent like Claude Code or Cursor opens your project, it reads DESIGN.md before generating any UI code. Every component it creates follows the same visual rules.

Without this file, each prompt starts from zero. The agent picks arbitrary colors, invents spacing values, and produces inconsistent interfaces. DESIGN.md fixes that by placing hard constraints inside the context window. One file, one source of truth.

The format combines two layers: YAML front matter for machine-readable design tokens and Markdown prose for human-readable rationale. This guide builds a file the official CLI can lint and export — not a free-form CSS dump in Markdown.

Prerequisites

DESIGN.md itself is just a file. The CLI is optional until you validate or export.

Step 1: Create the File

Create a file named DESIGN.md at the root of your project:

my-project/
├── DESIGN.md    ← here
├── src/
├── package.json
└── ...

The root placement matters. AI agents like Claude Code and Cursor scan the project root for context files. If DESIGN.md lives in a subfolder, the agent may not find it automatically.

Step 2: Add YAML Front Matter (tokens)

Open the file and add the YAML header between --- delimiters. This is where normative tokens live — the values the linter, exporters, and agents consume. Put colors, typography objects, spacing, rounded, and components here. Do not rely on CSS custom properties in the Markdown body as your source of truth.

---
name: My App
description: A clean productivity tool with a calm, focused aesthetic
colors:
  primary: "#2563eb"
  primary-hover: "#1d4ed8"
  surface: "#f8fafc"
  border: "#e2e8f0"
  text: "#0f172a"
  text-muted: "#64748b"
  on-primary: "#ffffff"
typography:
  h1:
    fontFamily: Inter
    fontSize: 2.25rem
    fontWeight: 700
    lineHeight: 1.2
  body:
    fontFamily: Inter
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.6
rounded:
  sm: 4px
  md: 6px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: 12px
---

name is expected. primary under colors avoids a missing-primary warning. Component values can reference tokens with {path.to.token}.

Optional: omitted (0.4.0)

If you intentionally skip categories such as spacing or rounded, list them so expected-missing warnings stay quiet:

omitted:
  - spacing
  - name: elevation
    reason: flat UI — no elevation tokens

Unknown or redundant entries produce omitted-rules info findings. Do not invent omitted categories to hide real lint errors.

Step 3: Write Markdown Rationale

Below the front matter, use the canonical ## sections. Present sections must stay in this order (aliases allowed for some):

# Section 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

You can omit sections you do not need. The section-order rule warns when present headings are out of order.

## Overview

This design system prioritizes clarity and calm. Interfaces should feel
spacious, not cramped. Use whitespace generously. Avoid visual noise —
no heavy drop shadows, no more than two font weights on a single screen.

## Colors

- **Primary** (`#2563eb`): main actions, links, focus rings
- **Surface** (`#f8fafc`): cards and section backgrounds
- **Text** (`#0f172a`): body copy; muted for captions

## Typography

- Headings: Inter, bold/semibold
- Body: Inter, regular, 1rem / 1.6

## Layout

Base-8 rhythm. Prefer `{spacing.md}` / `{spacing.lg}` from the front matter.

## Components

- Primary button: filled primary, white text, `{rounded.md}`
- Card: surface background, light border, generous padding

## Do's and Don'ts

- Do keep contrast at least 4.5:1 (WCAG AA)
- Don't invent one-off hex values outside the token map
- Do re-lint after every token change

Prose explains why. Tokens in YAML define what. Keep them aligned.

Step 4: Validate with the Official CLI

Always use npx so you get the published package (0.4.0+ as of 2026-07-27):

npx @google/design.md lint DESIGN.md
npx @google/design.md lint --format json DESIGN.md
npx @google/design.md spec --rules-only --format json

Exit codes: 0 ok (warnings/info allowed), 1 errors, 2 input failure (missing/unreadable file).

Useful rules in 0.4.0 include broken-ref, contrast-ratio, token-like-ignored (token-like YAML keys that are not in the export schema), and omitted-rules.

Step 5: Export When You Need Code

npx @google/design.md export --format json-tailwind DESIGN.md
npx @google/design.md export --format css-tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md
npx @google/design.md export --format css-vars DESIGN.md
npx @google/design.md export --format css-vars --prefix ds DESIGN.md

css-vars ships in 0.4.0. There is no --format tailwind shorthand — use json-tailwind or css-tailwind.

Compare two versions:

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

Complete Example

Minimal file that matches the official schema:

---
name: Starter App
description: Clean SaaS starter with a professional, focused aesthetic
colors:
  primary: "#2563eb"
  primary-hover: "#1d4ed8"
  surface: "#f8fafc"
  border: "#e2e8f0"
  text: "#0f172a"
  text-muted: "#64748b"
  on-primary: "#ffffff"
typography:
  h1:
    fontFamily: Inter
    fontSize: 2.25rem
    fontWeight: 700
    lineHeight: 1.2
  body:
    fontFamily: Inter
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.6
rounded:
  md: 6px
spacing:
  sm: 8px
  md: 16px
  lg: 24px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    rounded: "{rounded.md}"
    padding: 12px
  card:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.md}"
    padding: "{spacing.lg}"
---

## Overview

Calm, professional, and spacious. Prioritize readability and clear hierarchy.

## Colors

Primary for CTAs; surface for cards; keep text/muted from the token map.

## Typography

Inter for headings and body. Avoid mixing extra families without tokens.

## Layout

Use the spacing scale in front matter. Default stack gap: `{spacing.md}`.

## Components

Primary button and card tokens drive generated UI. Prefer refs over raw hex.

## Do's and Don'ts

- Do run `npx @google/design.md lint DESIGN.md` before merging
- Don't put the real palette only as `--color-*` bullets in Markdown
- Do list intentional gaps under `omitted` instead of ignoring warnings

Next Steps