DESIGN.md: The Contract Between Design and Code

What is it

DESIGN.md is a text file where you document a product's design system —tokens, canonical components, and usage rules— in a format both a human and an AI agent can read and act on. It's the contract between design and code: what's written there is what gets built.

It comes from a concrete problem in the AI-first workflow: tools like Stitch or Claude Design generate a visual system, but that system lives in images and conversations. When you ask a coding agent to implement it, it needs a text source of truth. DESIGN.md is that source.

The DESIGN.md format originated at Google Stitch and was open-sourced as a portable standard, meant to travel across tools and platforms: you export your design rules from one project to another and any agent can read them.

Mental model

Think of DESIGN.md as the design's README: it isn't the design itself, it's the document anyone —human or AI— reads to understand the rules before touching a line.

Without a contract, every implementation prompt reinvents decisions: one shade of blue here, another there. With the contract, the agent inherits the system and the decisions are already made.

graph LR D[Design in Stitch / Claude Design] --> M[DESIGN.md] M --> C[Claude Code implements] M --> H[Human designer iterates] M --> A[Another agent extends]

What lives in the contract:

Section	Content
Tokens	colors, typography, spacing scale, radii, shadows
Components	button, card, input… with their variants and states
Usage rules	do / don't, when to use each variant
Structure	where each thing goes in the repo

How it's used

After defining the visual system (in Stitch or Claude Design), you distill it into text.
You save it as DESIGN.md at the repo root, next to the code.
You pass it to the agent as context, or reference it from the agent's rules file.

Minimal example of a DESIGN.md:

# Design System — Mimo
 
## Tokens
- color.primary: #E8927C   (coral, primary actions)
- color.surface: #FBF7F0   (background)
- color.text:    #0A2540
- space:  4 / 8 / 16 / 24 / 32
- radius: sm 4px / md 8px / lg 12px
 
## Components
- Button: variants primary | secondary | ghost. States: default, hover, disabled.
  Rule: only one primary per view.
- Card: padding md, radius lg, subtle shadow.
 
## Rules
- Never use raw hex in components: always the token.
- Mobile-first. Breakpoints: 640 / 1024.

Pro Tip: A DESIGN.md isn't written once and abandoned. When the system changes, you update the contract first and the code second — never the other way around. The contract is the source of truth, not the code.

When to use it / when not to

Use it when:

You're implementing a design with a coding agent (Claude Code, Cursor).
The project has more than a handful of screens and needs consistency.
More than one person —or more than one agent— will touch the design.

You don't need it when:

It's a throwaway single-screen prototype.
You're still exploring and the system hasn't stabilized: documenting too early freezes decisions that should still move.