How to Write an Effective DESIGN.md So AI Generates Designs That Match Your Intent

What DESIGN.md Is and Why It Matters

DESIGN.md is a plain‑text markdown file that describes a product’s visual identity and provides structured guidance for AI tools, allowing them to understand the product’s look and interaction patterns. Originating in Google Stitch and later released as an open specification, it lets AI build on an existing design system instead of inventing styles from scratch.

DESIGN.md Structure

The file consists of two main parts: a YAML front‑matter section and the markdown body.

YAML Front‑Matter

Design system name (e.g., "Roxy Tech Modernism").

Atomic visual‑decision tokens such as colors, typography, radius, and spacing.

---
name: Roxy Tech Modernism
colors:
  surface: '#f9f9ff'
  surface-dim: '#d3daea'
  primary: '#3525cd'
  inverse-primary: '#c3c0ff'
  secondary: '#c3c0ff'
  ...
typography:
  display:
    fontFamily: Inter
  ...
rounded:
  sm: 0.25rem
  DEFAULT: 0.5rem
  md: 0.75rem
spacing:
  base: 4px
  xs: 0.25rem
---

Markdown Body

The body typically includes sections for Brand & Style, Colors, and Components, each referencing the tokens defined in the front‑matter.

## Brand & Style
The brand identity focuses on reliability, clarity, and effortless efficiency.
The design system adopts a **Corporate / Modern** aesthetic that leans heavily into **Minimalism**.
...
## Colors
The palette is anchored by Deep Indigo (`primary`), which serves as the main brand color and the primary action color.
- **Primary:** Deep Indigo for core UI elements.
...
## Components
- **Buttons:** Primary buttons use a Deep Indigo fill with white text. Secondary buttons use a Teal outline (`secondary`). Padding should be consistent (e.g., (`base`)).

Best Practices for DESIGN.md

The core idea is that DESIGN.md should be understandable by both humans and AI, providing clear context for any UI generation tool (Google Stitch, Claude Code, Cursor).

DESIGN.md should tell the story of your product.

Three key principles guide high‑quality DESIGN.md files:

1. Tokens Represent Decisions, Not Variables

Each token encodes a design decision. For example, using the token primary does more than name a color—it defines its role in the interface. Avoid purely visual names like blue or gray-1 because they lack semantic meaning. Prefer role‑based names such as primary, surface, border-subtle, or text-muted.

When auditing tokens, remove unnecessary, duplicate, or unrelated colors to keep the token set focused.

2. Design Decisions Need Reasoning

After defining tokens, add reasoning that connects raw values to intent, explains why the value is chosen, and sets usage constraints. The reasoning chain is:

Original style value → Intent → Reasoning (why/how) → Constraints (when not to use)

Including constraints tells the AI when a style should not be applied, reducing mismatches.

3. Build Components on Tokens and Reasoning

Components are the final section of DESIGN.md and should reference the tokens and their reasoning. For example, a button component uses the Deep Indigo ( primary) color with the rationale that it signals primary actions.

## Components
- **Buttons:** Primary buttons use a Deep Indigo fill with { colors.white } text.
  Secondary buttons use a Teal outline or subtle gray ghost style.
  Padding should be consistent (e.g., {base }).

Describe all possible states of each component (default, hover, active, disabled, loading, focus) so the AI can generate complete UI specifications.

Conclusion

DESIGN.md is not another design document; it is a bridge between a design system and AI‑generated UI. Its value lies in conveying design decisions clearly, not in perfect formatting. By treating tokens as decisions, providing reasoning, and building components on top of them, designers enable AI tools to produce outputs that align with the intended design, reducing guesswork and inconsistency.