Generate a DESIGN.md

What is DESIGN.md?

DESIGN.md is a portable, markdown-based format for design systems, created by Google as part of the open-source Stitch project. A single file captures an entire design system — colors, typography, spacing, component styles, and the rationale behind them — in a form that any AI coding agent can read without a runtime, plugin, or vendor-specific integration.

Think of it like README.md, but for visual language. You drop it at the root of your repo, and agents like Claude Code, Cursor, and Codex pick it up the same way they pick up any other markdown file.

What's in the file

Two layers: a YAML front matter block encodes machine-readable tokens; the markdown body below explains intent, tone, and edge cases for a human (or an agent reasoning about them).

---
version: 1
name: Stripe-like
description: Confident fintech with a focus on clarity.
colors:
  primary: "#635BFF"
  surface: "#F6F9FC"
  text:    "#1A1F36"
typography:
  h1:   { fontFamily: Inter, fontSize: 48px, fontWeight: 700 }
  body: { fontFamily: Inter, fontSize: 16px, fontWeight: 400 }
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
components:
  button:
    backgroundColor: "{colors.primary}"
    textColor:       "#FFFFFF"
    rounded:         "{rounded.md}"
    padding:         "12px 24px"
---

## Overview
Confident, restrained, high-density — never playful.

## Colors
Primary blue is reserved for calls to action...

Tokens can reference each other— e.g. a button's background can point at {colors.primary} instead of hard-coding a hex. This keeps component specs in sync when you tune the palette later.

The 8 canonical sections

The markdown body follows a fixed order so agents always know where to look.

1. 01

   Overview

   One paragraph of intent and tone.

2. 02

   Colors

   Palette with hex values and usage notes.

3. 03

   Typography

   Type scale, weights, line heights.

4. 04

   Layout

   Spacing scale and grid posture.

5. 05

   Elevation & Depth

   Shadow levels and depth cues.

6. 06

   Shapes

   Border-radius scale.

7. 07

   Components

   Buttons, inputs, cards with variants.

8. 08

   Do's and Don'ts

   Guidance on tone and correct use.

How to use the generated file

1. 1

   Generate + download

   Submit your URL above. After ~30 seconds, download the resulting DESIGN.md.

2. 2

   Save it at your repo root

   Drop the file at ./DESIGN.md. Commit it — review and edit it like any other source file.

3. 3

   Ask your agent to build UI

   Claude Code, Cursor, Codex, and similar tools read DESIGN.md automatically. Components they generate will match the tokens — fonts, colors, spacing, rounded corners, and variants all resolved from the same file.

Why use DESIGN.md?

• Portable

  Plain text. Version it in git, diff it, leave line comments in PR review. No proprietary runtime, no lock-in.

• AI-native

  Agents read DESIGN.md like they read any repo file. No MCP server, no plugin install, no vendor coupling.

• Structure + rationale together

  Machines consume the YAML tokens; humans (and agents) read the prose to understand tone and intent. Neither layer loses information.

• Composable with existing tooling

  The design.md CLI can lint the file, diff two systems, and export to Tailwind config or DTCG tokens — so you can still feed existing pipelines downstream.

FAQ

Is the file valid YAML?

The block between the --- fences is strict YAML. Everything below is plain markdown. Tools like `design lint` (from the google-labs-code repo) will validate the structure end-to-end.

Does it work if my site uses Tailwind?

Yes. Tailwind classes and inline styles surface enough signal for the generator to infer a reasonable palette and type scale. You can also tune the result by editing the file after download — it is just markdown.

How is this different from design tokens JSON or CSS variables?

DESIGN.md bundles machine-readable tokens AND human-readable rationale into a single portable file. Tokens JSON can be exported from DESIGN.md, but the reverse loses the prose that agents use for tone, intent, and do's-and-don'ts guidance.

Which AI coding agents support DESIGN.md?

Any agent that can read files in your repo — Claude Code, Cursor, Codex, and similar — picks it up automatically once DESIGN.md sits at the root. There is no MCP server or runtime integration to install.

Can I regenerate or edit the file afterward?

Yes. Edit it, commit it, diff it in code review. The format is designed to live in git alongside your source — vendor-neutral and loss-free.