What is DESIGN.md? A design system file for coding agents

Ask Cursor or Claude Code to write an interface and you often get the same sans, the same blue-violet, the same three-card row. The model is not taste-blind. It has no visual contract to follow, so it guesses.

In one sentence

DESIGN.md is a design-system file a coding agent is supposed to obey. The first half is YAML: color, type, spacing, radius, component tokens the machine can parse. The second half is Markdown: why those choices exist, what to do, what to avoid. The agent reads the file before it writes UI, so the result has a chance of not looking like the default skin.

Where the format comes from

The format is related to Google Labs Stitch. A public draft lives on GitHub. design.allworkin.ai exports files against that spec. It does not own the format. google-labs-code/design.md

What the file looks like

A full file also has radius, spacing, components, and eight prose sections. Below is only the YAML colors and typography.

Colors and typography pulled from a Paper export, not the full spec.

name: Paper
colors:
  primary: "#8C4A32"
  background: "#F6F1E8"
  onBackground: "#18181B"
  surface: "#FFFBF4"
typography:
  h1:
    fontFamily: Fraunces
    fontSize: 40px
    fontWeight: 600
    lineHeight: 1.12
    letterSpacing: -0.03em
  body:
    fontFamily: Newsreader
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.55
    letterSpacing: 0em

How an agent uses it

Put DESIGN.md at the repo root. In Cursor rules, CLAUDE.md, or AGENTS.md, say: read this file before writing UI, and treat tokens as normative. Wiring (rules files, skills, importing into Stitch) is a separate article. This one only explains the contract.

Hand-written or visual

You can write the YAML yourself against the public draft. Or pick a style here, preview it, and copy a linted DESIGN.md. Hand-writing fits when you already have brand colors and a type list. Visual export fits when you want the voice settled before the agent starts.

What to do next

Pick a style, copy DESIGN.md, and drop it into the agent project. If you want to tweak while you look, use the editor.

Questions

What is DESIGN.md?

A design-system file for coding agents: YAML tokens for the machine, Markdown rationale for humans.

How does it relate to Stitch?

Stitch is a Google Labs product. The public draft is google-labs-code/design.md. This site exports against that spec and does not own the format.

How do I hook it up in Cursor?

Put DESIGN.md at the repo root and require the rules to read it before writing UI. Step-by-step wiring is a later article.