Design.md: the one standard file carries your visual identity, for humans and agents

The Anatomy: Tokens Up Top, Prose Below

Open a DESIGN.md and you find two zones. Up top, fenced off, sits YAML frontmatter: typed groups for colors, typography, spacing, rounded corners, and components. Below the fence, Markdown prose, written in a fixed order that opens with Overview and closes with a short list of do’s and don’ts.

Google’s own Paws & Paths example shows the shape in a few lines:

---
colors:
primary: "#855300"     # "Golden Retriever" — main actions
secondary: "#0058be"   # "Sky Walk" — calmer, admin tasks
typography:
body-md: { fontFamily: Plus Jakarta Sans, fontSize: 16px }
---
## Colors
The palette centers on "Golden Retriever" orange to drive
action, balanced by "Sky Walk" blue for scheduling and admin.

Typed values sit above the fence, plain reasoning sits below it, and a component reference like {colors.primary} ties the two together, so a color is defined once and pointed at everywhere.

The structure is fixed; the personality is not. Google’s atmospheric-glass example fills the same sections with a glassmorphism weather app — frosted crystalline panels, a 20-pixel blur, a white palette floating over vibrant gradients — where Paws & Paths reads friendly, rounded, and professional. Same eight headings, opposite moods. That range is the point: the format carries a brand’s character, not just its numbers.

The specification treats that structure as part of the contract. An unknown section heading is preserved rather than rejected. An unknown token is accepted as long as its value is valid.

But a duplicate section heading is an error that rejects the whole file, which tells you the order and the uniqueness of sections are load-bearing, not decoration.

Tokens are declared with intent, so when the prose and the tokens disagree, the tokens win.

Two mechanics are worth learning early. Tokens are normative, so when the prose and the tokens disagree, the tokens win.

A value defined once can be reused by reference: in Paws & Paths, the primary button reads backgroundColor {colors.primary}, rounded {rounded.lg}, padding {spacing.md}, so its look is never a hex code, only a set of pointers. Rebrand, and that is a one-line change rather than a search across forty files.