DESIGN.md — The Design System File Your AI Agent Actually Reads

DESIGN.md Format

Two layers in one file

A DESIGN.md file has two parts: YAML front matter with design tokens, and a Markdown body with the reasoning behind them. Tokens are the source of truth for values. Prose tells the agent how to use those values — and when not to.

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview

Architectural Minimalism meets Journalistic Gravitas.
The UI evokes a premium matte finish.

## Colors

- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.

Feed this file to an agent and the result is predictable: deep ink headlines in Public Sans, warm limestone background, Boston Clay buttons. No guessing.

Tokens

DESIGN.md token schema

Tokens live as YAML front matter. The schema draws from the W3C Design Tokens spec — typed token groups, the {path.to.token} reference syntax for cross-linking values. Familiar if you've worked with Figma variables or Tailwind themes.

version: <string>          # optional, current: "alpha"
name: <string>
description: <string>      # optional
colors:
  <token-name>: <Color>
typography:
  <token-name>: <Typography>
rounded:
  <scale-level>: <Dimension>
spacing:
  <scale-level>: <Dimension | number>
components:
  <component-name>:
    <token-name>: <string | token reference>

Token types

Structure

8 sections of the DESIGN.md spec

Sections use ## headings. You can skip any of them, but those you include must follow this order — the LLM reads top to bottom, and sequence matters for context buildup.

## Overview
Architectural Minimalism meets Journalistic Gravitas.
The UI evokes a premium matte finish — a high-end broadsheet
or contemporary gallery.

## Colors
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions.
- **Tertiary (#B8422E):** "Boston Clay" — sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation.

## Typography
- **Headlines:** Public Sans Semi-Bold — institutional, trustworthy.
- **Body:** Public Sans Regular at 16px — long-form readability.
- **Labels:** Space Grotesk — geometric precision. Uppercase, generous spacing.

## Layout
Fluid Grid model for mobile, Fixed-Max-Width Grid for desktop (max 1200px).
Strict 8px spacing scale with 4px half-step for micro-adjustments.

## Elevation & Depth
Depth through Tonal Layers rather than heavy shadows.
Background uses soft off-white, primary content on pure white cards.

## Shapes
Architectural Sharpness. All interactive elements use minimal 4px corner radius.
Just enough softness to feel modern while maintaining a rigid aesthetic.

components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.on-tertiary}"
    rounded: "{rounded.sm}"
    padding: 12px
  button-primary-hover:
    backgroundColor: "{colors.tertiary-container}"

## Do's and Don'ts
- Do use primary only for the single most important action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
- Don't use more than two font weights on a single screen

Tools

DESIGN.md CLI tools

The @google/design.md package ships four commands: validate, compare, export, and inspect. Everything runs from npx — no global install.

npx @google/design.md lint DESIGN.md

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

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 spec
npx @google/design.md spec --rules --format json

Validation

Linting rules

The linter checks 9 rules against your DESIGN.md file. Each produces findings with a fixed severity — errors block, warnings advise, info just reports.

Programmatic API

Use the linter as a library

Need the linter inside your own tooling — CI pipelines, editor extensions, custom validators? It exports as a plain JavaScript library.

import { lint } from '@google/design.md/linter';

const report = lint(markdownString);

console.log(report.findings);       // Finding[]
console.log(report.summary);        // { errors, warnings, info }
console.log(report.designSystem);   // Parsed DesignSystemState

Why this format

Why DESIGN.md uses Markdown + YAML (not JSON)

Markdown is the format LLMs understand best — the bulk of their training data uses it. No special parsing instructions needed.

JSON tokens define values but not rules. You can't express "use primary only for the main CTA" in a tokens.json. DESIGN.md combines YAML tokens (exact values for machines) with Markdown prose (semantics and constraints for agents) in one file, zero build pipeline. The export command converts to Tailwind or DTCG when you need it downstream.

Get started

How to get a DESIGN.md file

Four paths, fastest to most hands-on.

Naming

Recommended token names (Non-Normative)

These names show up across most design systems. Not required — but using them makes your DESIGN.md instantly familiar to anyone (or any agent) reading it.

Compatibility

DESIGN.md works with every AI coding agent

It's plain Markdown — any agent that reads project files can use it. No plugins, no integrations, no vendor lock-in. Drop the file in your repo root and point your agent config at it.

FAQ

Frequently asked questions about DESIGN.md