AI coding agents have no persistent awareness of your design system. You ask Claude Code to build a login page and it reaches for its defaults: blue buttons, gray backgrounds, system fonts. You correct it. It learns for this session. Tomorrow it forgets.

DESIGN.md fixes this by giving the agent a file it reads at the start of every session, containing your exact colors, typography, spacing, components, and the reasoning behind each choice. The agent doesn’t guess your brand. It reads it.

Google Labs built this format inside Stitch, their AI design tool, then open-sourced it on April 21, 2026 so any agent on any platform can consume it. The spec is Apache 2.0. You can write DESIGN.md by hand, generate it from Stitch, or grab a pre-built one from the community.

How the format works

A DESIGN.md file has two layers.

YAML front matter sits between --- fences at the top. This is the machine-readable part: exact values that agents parse programmatically. Colors as hex codes, typography as font families and sizes, spacing as pixel values, components as token references.

Markdown body follows the front matter. This is the human-readable part: organized with ## sections explaining design philosophy, when to use which tokens, and what to avoid. As the spec puts it: "Tokens give agents exact values. Prose tells them why those exist and how to apply them."

Here’s a minimal example:

---
name: Acme Corp
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
  surface: "#FFFFFF"
  on-surface: "#1A1C1E"
  error: "#D32F2F"
typography:
  headline-lg:
    fontFamily: Public Sans
    fontSize: 2.5rem
    fontWeight: 700
    lineHeight: 1.2
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
    fontWeight: 400
    lineHeight: 1.6
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 0.75rem
    fontWeight: 600
    letterSpacing: 0.08em
rounded:
  sm: 4px
  md: 8px
  lg: 16px
spacing:
  xs: 4px
  sm: 8px
  md: 16px
  lg: 24px
  xl: 48px
components:
  button-primary:
    backgroundColor: "{colors.tertiary}"
    textColor: "{colors.neutral}"
    typography: "{typography.label-caps}"
    rounded: "{rounded.sm}"
    padding: 12px 24px
  button-primary-hover:
    backgroundColor: "#9A3521"
  card:
    backgroundColor: "{colors.surface}"
    rounded: "{rounded.md}"
    padding: "{spacing.lg}"
---
## Overview
Acme Corp's design language is industrial and confident. Deep ink tones with a "Boston Clay" accent that draws the eye without shouting. Typography is clean and functional, never decorative. White space does the heavy lifting.
## Colors
The primary palette is deliberately restrained. Deep charcoal (\`primary\`) for text, warm stone gray (\`secondary\`) for supporting elements, and a single warm accent (\`tertiary\`, Boston Clay) reserved for CTAs and emphasis. The neutral cream (\`neutral\`) warms the background without clinical white.
Never use tertiary for large surfaces. It's an accent, not a background.
## Typography
Two families. Public Sans for everything structural (headlines, body, captions). Space Grotesk for labels and interactive elements where a slightly geometric character helps with scannability.
The type scale has nine levels. For most pages, you'll use headline-lg, body-md, and label-caps. Reach for the others when you need hierarchy within a section.
## Components
### Buttons
Primary buttons use the Boston Clay accent with cream text. The hover state darkens the clay by roughly 15%. Padding is generous (12px vertical, 24px horizontal) to give the label breathing room.
Secondary buttons are outlined: 1px border in secondary, transparent background, secondary text. On hover, the background fills to neutral.
### Cards
Cards sit on the surface color with medium rounding and generous internal padding. No drop shadows by default. Use a 1px border in the neutral color if cards need visual separation from the background.
## Do's and Don'ts
- Do use the tertiary accent sparingly. One accent per viewport section maximum.
- Do maintain the spacing scale. Don't invent spacing values between the defined steps.
- Don't use secondary as a text color on dark backgrounds. It fails WCAG AA contrast.
- Don't mix Space Grotesk into body text. It's for labels and interactive elements only.

That’s the whole file. Drop it at your project root and your agent has a complete design system.

The token system in detail

Colors

Hex values in sRGB format, prefixed with #. The spec recommends these semantic names: primary, secondary, tertiary, neutral, surface, on-surface, error. You can add custom names (any valid string works), but including at least primary is required for linting to pass.

Typography

Each typography token is an object with these properties:

The spec recommends 9–15 levels. A practical set: headline-display, headline-lg, headline-md, body-lg, body-md, body-sm, label-lg, label-md, label-sm.

Rounded (border radius)

A scale of named levels: none, sm, md, lg, xl, full. Values are dimensions with units.

Spacing

A scale of named levels: xs, sm, md, lg, xl. Values are dimensions or plain numbers.

Components

Components reference tokens using {path.to.token} syntax. This keeps values DRY and lets the linter verify that all references resolve.

Valid component properties: backgroundColor, textColor, typography, rounded, padding, size, height, width. Variants use related keys (e.g., button-primary, button-primary-hover, button-primary-active).

The eight canonical sections

When present, markdown sections must follow this order:

  1. Overview (alias: “Brand & Style”): holistic product description, brand personality, emotional tone
  2. Colors: palettes with semantic roles and usage guidelines
  3. Typography: type scale, font pairings, hierarchy rules
  4. Layout (alias: “Layout & Spacing”): grid models, spacing strategy, responsive behavior
  5. Elevation & Depth (alias: “Elevation”): shadow and depth techniques
  6. Shapes: border radius, corner treatments, decorative geometry
  7. Components: style guidance for UI atoms (buttons, cards, inputs, navigation)
  8. Do’s and Don’ts: guardrails and common pitfalls

Not all sections are required. Unknown headings are preserved without error. The linter warns if sections appear out of canonical order.

Experiment with different settings, and let your agent make it easy for you to choose.

Setting it up with Claude Code

2 minutes. Three files.

Step 1. Create your DESIGN.md (write by hand, export from Stitch, or grab one from the awesome-design-md collection). Place it at your project root.

Step 2. Add a reference in your CLAUDE.md:

## Design System
This project uses a design system defined in @DESIGN.md.
Follow strictly the rules defined in @DESIGN.md for all UI generation.
Do not invent colors, fonts, or spacing values outside the design system.
Match component states (hover, focus, active, disabled) to patterns in @DESIGN.md.

The @ prefix tells Claude Code to read the referenced file's content.

Step 3. Verify. Start a Claude Code session and ask: “What primary color is defined in this project’s design system?” If it returns the exact hex value from your DESIGN.md, you’re wired up. If it gives a generic answer, check the @ prefix and restart.

From here, reference the design system in your prompts: “Build a primary button component using the design system in DESIGN.md.” Claude Code reads the tokens, applies the values, and generates code that matches your brand.

Setting it up with Cursor

Same idea, different config file. Place DESIGN.md at your project root. In Cursor’s settings or in a .cursorrules file, add instructions to follow the design system in DESIGN.md for all UI generation.

Setting it up with Codex

Codex reads AGENTS.md at the project root. Add a reference to DESIGN.md there, with instructions to use only the colors, typography, and spacing defined in the design system file.

The CLI tools

The @google/design.md npm package provides four commands:

Lint: validates structural correctness and WCAG compliance.

npx @google/design.md lint DESIGN.md

The linter runs seven rules: broken token references, missing primary color, WCAG contrast ratios (4.5:1 minimum for AA), orphaned tokens, token summaries, missing canonical sections, and section ordering. Output is structured JSON that any agent or CI pipeline can consume.

Diff: compares two DESIGN.md files and detects token-level and prose regressions.

npx @google/design.md diff DESIGN.md DESIGN.old.md

Useful for PR reviews: did someone change a color? Did a section get deleted? The diff catches it at the token level, not just the text level.

Export: converts to Tailwind theme config or W3C DTCG format.

npx @google/design.md export --format tailwind DESIGN.md
npx @google/design.md export --format dtcg DESIGN.md

The Tailwind export generates a tailwind.config.js theme extension with all your tokens mapped. The DTCG export produces a tokens.json compliant with the W3C Design Tokens Community Group specification. Either way, your design tokens exist in two places: the DESIGN.md for agents and the framework config for your build pipeline.

Spec: outputs the specification itself, useful for injecting into agent system prompts.

npx @google/design.md spec

Three approaches.

Google Stitch. Design your UI in Stitch (stitch.withgoogle.com), and it generates a DESIGN.md alongside the design. Export the file and drop it in your project. This is the fastest path if you’re starting from zero.

Generators. Sites like design.dev/ai/design-md-generator and getdesign.md offer browser-based generators where you input your brand values and get a formatted DESIGN.md file. Handy for quick starts.

By hand. Open any text editor. Write the YAML front matter with your tokens. Add the markdown sections with your design rationale. There’s no build step, no compilation, no special tooling. It’s a markdown file.

If you’re extracting from an existing project, look at your CSS variables or Tailwind config. The colors, fonts, spacing, and radii defined there map directly to DESIGN.md tokens. The part you’re adding is the prose: why those values exist and how they should be applied.

The community library

The VoltAgent/awesome-design-md repository on GitHub contains 69+ ready-to-use DESIGN.md files organized into nine categories:

Each entry includes the DESIGN.md file plus HTML previews (light and dark mode). Copy one into your project, tell your agent to use it, and you get UI that matches that brand’s visual language.

Practical tips from a week of daily use

Put DESIGN.md in version control. Treat it as source code. When someone changes a color or adds a component, the diff shows exactly what changed. PR reviews catch design drift before it ships.

Keep the Do’s and Don’ts section honest. This is where agents get the most value. “Don’t use the accent color on large surfaces” prevents the most common AI design mistake I see. “Don’t mix font families in body text” prevents the second most common.

Use the Tailwind export as a second constraint. Even with a good DESIGN.md, agents occasionally invent values. If your Tailwind config only contains the tokens from your design system, the framework itself rejects unauthorized values at build time. Two layers of enforcement.

Audit regularly. After building several components, ask your agent: “Review everything in /components and identify any values not defined in DESIGN.md." The agent reads the code, reads the design system, and flags drift.

Start with the minimum. You don’t need all eight sections. Colors, typography, spacing, and Do’s and Don’ts cover 90% of what agents need to generate consistent UI. Add components, elevation, and shapes as your design system matures.

Pair DESIGN.md with AGENTS.md. DESIGN.md handles visual standards. AGENTS.md (or CLAUDE.md, or.cursorrules) handles code conventions. Separating them keeps each file focused and easier to maintain.

DESIGN.md describes visual identity. It does not:

Why this matters now

Until DESIGN.md, the options for making AI agents follow a design system were: paste examples into the prompt (works but doesn’t scale), write a long system prompt describing the brand (works until context fills up), or accept that AI-generated UI looks generic and fix it manually.

DESIGN.md is the first format that combines tokens (exact values agents parse) with rationale (context agents use for judgment) in a single file that every major AI coding tool can read. The fact that Google open-sourced it under Apache 2.0 rather than keeping it inside Stitch means it has a chance at becoming a genuine cross-platform standard.

Spotify’s Encore design system team already found that AI agents bypass complex design systems when they’re hard to reason about. A DESIGN.md that covers colors, type, spacing, and ten don’ts outperforms a full design system specification in every AI tool they tested.

The bar isn’t perfection. It’s “better than no design system at all,” which is where most AI-generated UI starts. DESIGN.md clears that bar in five minutes.

Marco Kotrotsos, specializing in practical AI implementation for organizations ready to close the gap between AI hype and AI value. With 30 years of IT experience now focused purely on AI deployment, he works hands-on with companies to turn AI potential into measurable business outcomes.

This article is published in Autocomplete, a Medium publication about real-world AI for practitioners and decision-makers. We’re always looking for writers. If you’re building with AI and have something worth sharing, reach out.

My free Substack newsletter, also called Autocomplete, can be found here: https://acdigest.substack.com.

Powered by Forestry.md