# What is DESIGN.md

> DESIGN.md is a Markdown design-system file for AI coding agents. See its format, a small example, the official linter and how to make one from any site.

Canonical page: https://sitepeel.dev/guides/what-is-design-md/

DESIGN.md is a plain Markdown file that describes a design system for AI coding agents: color, type, spacing and component tokens at the top, short usage rules below.

Published: 2026-10-24

Tool used in this guide: [Design MD generator](https://sitepeel.dev/design-md-generator/index.md)

## How to use it

1. **Make the file** Paste a website link into Sitepeel’s free DESIGN.md generator, or write the file by hand in the format below.
2. **Review the tokens** Check the primary color, headings and buttons against the site. Delete one-off campaign styles you don’t want copied.
3. **Lint it** Run npx @google/design.md lint DESIGN.md to catch broken token references, a missing primary color and low contrast.
4. **Link it to your agent** Save it in the project root and reference it from CLAUDE.md, AGENTS.md, GEMINI.md or a Cursor rule.
5. **Build one screen first** Ask for one page and compare it with DESIGN.md. Fix the file or the prompt before building more.

## What goes in a DESIGN.md file

The file has two layers. YAML front matter between --- lines holds the tokens: exact values an agent can copy. The Markdown body explains when and how to use them. When the two disagree, the spec says the tokens win.

The DESIGN.md format at a glance

| Part | What it holds |
| --- | --- |
| Front matter | version, name, description, then colors, typography, rounded, spacing and components |
| Token references | Components point at tokens, such as {colors.primary}, instead of repeating values |
| Body sections, in order | Overview, Colors, Typography, Layout, Elevation & Depth, Shapes, Components, Do’s and Don’ts |
| Rules | A primary color is required. You can leave sections out, but the ones you keep stay in order |

## A small DESIGN.md example

This file passes Google’s linter with no errors or warnings. A file made from a real site carries more tokens: surface colors, a fuller type scale and more components.

Example: DESIGN.md

```
---
version: alpha
name: Acme
description: Calm light interface with one blue accent.
colors:
  primary: "#2563EB"
  on-primary: "#FFFFFF"
  background: "#FFFFFF"
  on-background: "#111827"
typography:
  headline-lg:
    fontFamily: Inter
    fontSize: 40px
    fontWeight: 600
    lineHeight: 1.1
  body-md:
    fontFamily: Inter
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  md: 8px
spacing:
  sm: 8px
  md: 16px
  lg: 32px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.on-primary}"
    typography: "{typography.body-md}"
    rounded: "{rounded.md}"
    padding: 12px 20px
---

## Overview
Calm, product-first pages with plenty of white space.

## Colors
Blue marks primary actions only. Text is near-black on white.

## Typography
Inter throughout. One headline size per screen.

## Layout
Spacing steps of 8, 16 and 32px. Content column up to 1120px.

## Shapes
8px corners on buttons, cards and inputs.

## Components
Primary button: blue fill, white text, 12px by 20px padding.

## Do's and Don'ts
- Do keep one primary button per view.
- Don't add gradients or glows.
```

## How AI agents use DESIGN.md

An agent copies exact values from the tokens and uses the prose for judgment calls, such as when the accent color belongs. Most agents won’t open a file just because it’s called DESIGN.md, so connect it once in the file your agent already loads.

Where to link DESIGN.md for each agent

| Agent | File it loads |
| --- | --- |
| Claude Code | CLAUDE.md, with an @DESIGN.md import |
| Cursor | .cursor/rules/*.mdc or AGENTS.md |
| OpenAI Codex | AGENTS.md |
| GitHub Copilot | .github/copilot-instructions.md, .github/instructions/*.instructions.md or AGENTS.md |
| Windsurf (Devin Desktop) | .windsurf/rules/*.md, .devin/rules/*.md or AGENTS.md |
| Gemini CLI | GEMINI.md, with an @./DESIGN.md import |
| v0, Lovable, Bolt, Replit | Instructions, Knowledge or replit.md |

- [Use DESIGN.md with Claude Code](https://sitepeel.dev/guides/design-md-claude-code/index.md)
- [Use DESIGN.md with Cursor](https://sitepeel.dev/guides/design-md-cursor/index.md)
- [Use DESIGN.md with OpenAI Codex](https://sitepeel.dev/guides/design-md-codex/index.md)
- [Use DESIGN.md with GitHub Copilot](https://sitepeel.dev/guides/design-md-github-copilot/index.md)
- [Use DESIGN.md with Windsurf](https://sitepeel.dev/guides/design-md-windsurf/index.md)
- [Use DESIGN.md with Gemini CLI](https://sitepeel.dev/guides/design-md-gemini-cli/index.md)
- [Use DESIGN.md with v0, Lovable, Bolt and Replit](https://sitepeel.dev/guides/design-md-app-builders/index.md)

## Check a file with the official linter

Google publishes a linter and exporter as the npm package @google/design.md. Lint exits with code 1 when it finds errors, so it can run in CI.

- npx @google/design.md lint DESIGN.md checks token references, the primary color, contrast and section order
- npx @google/design.md diff DESIGN.md DESIGN-v2.md shows what changed between two versions
- npx @google/design.md export --format dtcg DESIGN.md turns the tokens into DTCG design tokens; Tailwind formats exist too
- On Windows PowerShell, run npx -p @google/design.md designmd lint DESIGN.md

## Make a DESIGN.md from any website

Paste a link into Sitepeel’s free DESIGN.md generator. Sitepeel opens the page and measures it after it fully loads: computed colors and where they appear, the type scale, spacing, corner radii, shadows and button hover states.

The file follows the Stitch format and passes the official linter. For pages behind a login, several pages in one file or local edits, use the Design MD tool in Sitepeel for Chrome.

- [Make a DESIGN.md from a link, free](https://sitepeel.dev/design-md/index.md)
- [Review a generated DESIGN.md before you use it](https://sitepeel.dev/guides/create-design-md-from-website/index.md)
- [Design MD in Sitepeel for Chrome](https://sitepeel.dev/design-md-generator/index.md)

## Questions and answers

### What is a DESIGN.md file?

A Markdown file that describes a design system for AI coding agents. YAML tokens at the top give exact colors, fonts, spacing, corner radii and component styles; the sections below explain how to apply them.

### Who created DESIGN.md?

Google Labs introduced DESIGN.md in Stitch, its AI design tool, in March 2026. In April 2026 Google open-sourced the draft spec and a linter under the Apache 2.0 license.

### Is DESIGN.md the same as AGENTS.md?

No. AGENTS.md tells coding agents how to work in a repository: commands, conventions and checks. DESIGN.md describes how the interface should look. Many projects keep both and point to DESIGN.md from AGENTS.md.

### Do AI agents read DESIGN.md automatically?

Usually not. Claude Code, Codex, Cursor, Copilot and Gemini CLI load their own instruction files. Import or mention DESIGN.md there, or attach it to the chat.

## Further reading

- [Google Labs: the DESIGN.md format and CLI on GitHub](https://github.com/google-labs-code/design.md)
- [Google Labs: the DESIGN.md specification](https://github.com/google-labs-code/design.md/blob/main/docs/spec.md)
- [Google: Stitch’s DESIGN.md format is now open source (April 2026)](https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-design-md/)
- [Google: the Stitch update that introduced DESIGN.md (March 2026)](https://blog.google/innovation-and-ai/models-and-research/google-labs/stitch-ai-ui-design/)
- [@google/design.md on npm](https://www.npmjs.com/package/@google/design.md)

## Related pages

- [Create a Design MD file](https://sitepeel.dev/guides/create-design-md-from-website/index.md): Make a DESIGN.md file from any website with the free generator or Sitepeel’s Design MD tool, then check it so an AI can use it well.
- [Use Design MD with AI](https://sitepeel.dev/guides/use-design-md-with-ai/index.md): Hand DESIGN.md to Cursor, Claude Code or another AI coding assistant: where to save it, two prompts to copy and how to review what it builds.
- [DESIGN.md with Claude Code](https://sitepeel.dev/guides/design-md-claude-code/index.md): Import DESIGN.md into CLAUDE.md with @DESIGN.md so Claude Code follows your colors, type and spacing. Includes a sample CLAUDE.md and checks.
- [DESIGN.md with Cursor](https://sitepeel.dev/guides/design-md-cursor/index.md): Point Cursor at DESIGN.md with a project rule in .cursor/rules, AGENTS.md or an @ mention. Includes a sample .mdc rule and the four rule types.
- [When AI ignores DESIGN.md](https://sitepeel.dev/guides/ai-ignoring-design-md/index.md): Your agent has DESIGN.md but the UI is still wrong? Check that it loads, remove conflicting rules, name real components and verify the result.