How to generate a DESIGN.md (and what it is)

A DESIGN.md sits beside the code and describes the intended design in terms an agent can act on. Coding agents implement UI well, but without art direction they tend to fall back to a neutral house style. The name has since become a small ecosystem: Google Labs open-sourced a DESIGN.md format specification (from the Stitch team, Apache 2.0, still versioned alpha), and it drew tens of thousands of GitHub stars within months. Their spec pairs machine-readable tokens in YAML front matter with human-readable rationale in prose, and ships a CLI that validates files and exports to Tailwind and the W3C design-token format.

That structure, exact values plus written intent in one file, is the same conclusion this guide argues for, and it is worth being precise about what the spec does and does not give you. A format tells you where the tokens and the prose go. It does not produce the design system itself: the tokens still have to come from somewhere, and the motifs, don'ts, and page-structure rules still have to be decided by someone. Catalog sites collect finished DESIGN.md files; the generation approaches below produce one from an actual system, which is the difference between a file that validates and a file that changes what an agent builds.

A DESIGN.md needs more than a color list. Agents also need direction on layout, spacing, component treatment, and the details that distinguish one design from another. A useful brief spends most of its words on those decisions.

A complete brief covers the whole system, not just tokens. The DESIGN.md that Identity Forge generates is organized into these sections:

• Overview: what the design is, who it's for, and the intended feeling in a sentence or two.
• Colors: the semantic tokens as CSS variables ready to paste into globals.css, in light and dark. Semantic color tokens explained.
• Typography: the type pairing, scale, tracking and weights, plus a ready Next.js font setup.
• Layout: spacing base, container width, and composition rules.
• Elevation & Depth: the shadow system (or a deliberate lack of one).
• Shapes: corner radii per element (buttons, cards, inputs, badges) and border treatment.
• Components: how core components should be treated, with a sample.
• Page Structure & Layout: how to compose whole pages; this is where generic AI output is prevented.
• Personality & References: the voice and touchstones behind the design.
• Distinctive Motifs: the signature devices to reproduce; "they define the design as much as the tokens do."
• Do's & Don'ts: the rules that keep generated UI inside the design's world.
• Agent Rules: explicit instructions for the coding agent itself.

The list above is what a complete brief covers. It is worth knowing how far the published ones fall short of it, because the gap is consistent and it tells you exactly which sections to prioritise if you are writing one by hand.

We sampled 299 DESIGN.md files published across public repositories and directories: real files, written to give agents design guidance. 72 were specifically visual-design files.

Set the last two rows against each other and the pattern is unmistakable. Typography is mentioned in 83% of files, and 44% of files never state a single size. These are documents talking about type without saying how big anything is.

The adjective figure explains the rest. "Clean" appears in 39% of these files and "modern" in 36%. Both are words a model satisfies by producing the centre of its training distribution, which is precisely the generic output the file was written to prevent.

The single distinction that separates a brief that changes output from one that does not: can a sentence be checked against a rendered screen? If not, it is decoration.

Every entry in the right column can be verified by looking at a screen or grepping the code. Every entry in the left column can be satisfied by almost anything, which means it constrains nothing.

Three properties separate a prohibition that lands from one that gets ignored.

The third row is the one most often missed. A prohibition with no alternative opens a gap the model fills from the same training distribution you were trying to escape. Every "never X" wants an "instead, Y".

If you are writing one by hand rather than generating it, this is a defensible starting shape. It is short on purpose. A brief nobody can hold in their head competes with the actual task for the model's attention. Roughly 400 lines is a workable ceiling; this skeleton is well under it.

# DESIGN.md

## Overview

A dense internal tool for operations staff who work in it for hours.
Quiet, information-first. Nothing here has to convince anyone of anything.

## Don'ts

- No gradients
- No drop shadows — elevation is a surface step plus a 1px border
- No font-weight above 600
- No colour value outside the tokens in globals.css
- No border-radius above 12px
- No decorative use of the state colours

## Colours

Defined as semantic roles in globals.css, light and dark.
Do not restate values here — read them from that file.

- `--primary` — primary buttons and active nav state ONLY.
  Never on text, borders, backgrounds or gradients.
- `--muted-foreground` — secondary and supporting text only.
- `--border` — structural edges and dividers.
- `--destructive` / `--success` / `--warning` — reserved for state.

## Typography

Family: Inter (variable). Weights 400 and 600 only.
Scale: 12 / 14 / 16 / 20 / 24 / 32 / 48.
Tracking: -0.02em at 32px and above, 0 below, +0.02em on 12px caps.
Hierarchy comes from size and colour, never from weight above 600.

## Spacing & density

Scale: 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64. No other values.
Controls: 8–12px padding. Table rows: 32px. Section gap: 32px.

## Elevation

A surface step plus a 1px `--border`. Never a box-shadow.

## Shapes

Controls 6px. Cards and panels 12px. Nothing above 12px.

## Composition

One primary action per section.
Related controls share a group; unrelated ones are separated by a full step.
Tables are never nested inside cards.

## Motifs

Section headings carry a 2px `--primary` rule on the left edge.
Numeric columns are always tabular-nums and right-aligned.
Empty states are a single line of `--muted-foreground` text, never an illustration.

## Agent rules

Read this file before writing or editing any UI.
Match the nearest existing component in this repo rather than inventing a
new pattern. If no similar component exists, say so before writing one.

Two things about that file are worth copying even if you change everything else. The don'ts come second, before anything they might modify, so a model reading top to bottom hits the constraints before the permissions. And the colour section points at globals.css rather than restating values: once a hex exists in two places, one will be updated and the other will not, and the model will confidently use the stale copy.

A DESIGN.md is only as good as the system behind it. Below is the free ambient-sage kit: the tokens, fonts, and treatments its DESIGN.md describes, rendered live:

1. 1

   CLI: write DESIGN.md + tokens into your repo

   The fastest path. Pick a kit slug from the gallery and apply it; you get a committed DESIGN.md plus a matching tokens file.

   Copy

   identityforge apply ambient-sage

2. 2

   MCP: let the agent fetch it

   With the MCP server installed, the agent calls get_design_md(slug) to read the full brief and apply_theme to write it. Install for your tool:

   Copy

   npx --yes identityforge@latest install --client claude-code

3. 3

   shadcn: install the tokens the DESIGN.md references

   If you only want the values, the registry item installs the kit's CSS variables directly.

   Copy

   npx shadcn add https://identityforge.io/r/ambient-sage.json

Identity Forge generates the DESIGN.md and tokens from the same kit, so the prose describes the values in the stylesheet. For how this differs from adapting a DESIGN.md catalog entry by hand, see Identity Forge vs getdesign.md.

Writing the file and assuming it landed is how teams find the problem three weeks later. Four checks, cheapest first.

1. 1

   Grep for literal colour values

   If the agent is following semantic roles, there should be no hex outside the token file. This is the fastest possible signal.

   Copy

   grep -rn --include='*.tsx' --include='*.css' -E '#[0-9a-fA-F]{3,8}\b' src \
     | grep -v 'tokens\|globals.css'

2. 2

   Grep for the weights you forbade

   Weight is where hierarchy quietly reverts to the default, and it is the earliest sign that a don't is not landing.

   Copy

   grep -rn --include='*.tsx' -E 'font-(bold|extrabold|black)' src | head -30

3. 3

   Ask for the same screen twice, in separate sessions

   Cross-session consistency is the real test. If two runs differ meaningfully on spacing, radius or hierarchy, the diff tells you exactly which section of the brief is missing.

4. 4

   Build one screen in dark mode first

   If dark mode was derived rather than defined, this is where it surfaces: dead shadows, muddy mid-greys, a glaring accent. Far cheaper to find on screen one than on screen twenty.

The first two belong in CI. A check that fails a pull request containing a raw hex value does more for long-term consistency than any amount of prose, which is the same conclusion Salesforce reached with the SLDS linter.