Design contracts

Your brand uses 8px corners and one blue. The agent builds a new screen with 6px corners, Inter at 14px and a blue that is almost yours.

It didn't ignore your design system. It never saw one. Write the system down where an agent looks, and this stops.

Two files an agent reads

A token is a design decision with a name: colors.accent, rounded.md, motion.duration.base. Components use the name; the value lives in one place.

There are two common files that hold tokens for an agent:

Who wins a disagreement

Your prompt says one thing, the contract another, the skill a third. The .design format settles this with a fixed order. Toggle the sources below and watch the value change.

The order, top to bottom: your prompt (this task only), the nearest .design, the design skill's procedure, generic taste skills like design-engineering, and finally the model's defaults.

So if your contract says dialogs open in 400ms, the agent uses 400ms, even though the skill says most UI lands under 300ms. It raises the tension once, in a sentence, then complies.

How an agent reads a .design

The agent walks up from the file it is editing to find the nearest contract. In a monorepo, a package's own contract beats the one at the root.

1. agent.instructions first

   The contract's own short brief, written so the file works even with no skill installed.

2. intent

   The committed direction, where boldness is allowed (the signature), and the register: utilitarian or editorial.

3. constraints, policy, decisions

   Hard rules, and what to do when a component isn't listed: ask, use the nearest, or invent with a note.

4. tokens, voice, components

   Bind every listed property to its token. Apply the voice (casing, terminology, error style) as firmly as the colours.

If there's no contract at all, the agent should offer to create one, after scanning what you already have (global CSS, Tailwind config, an existing DESIGN.md). It should never invent a system silently.

How an agent reads a DESIGN.md

The agent looks in the repo root, then design/, then .design/. The YAML at the top is normative: use {colors.primary}, never a hardcoded hex; match the typography token, not "close enough". The markdown below is context: the overview tells it what the system is trying to feel like, and the do's and don'ts are hard constraints.

The agent never rewrites your DESIGN.md on its own. It may propose an edit, as a review comment, when a token is missing, a pair fails contrast, or a variant like button-primary-active doesn't exist yet.

$ npx -y @google/design.md lint DESIGN.md

Before writing UI, find our design contract (.design first, then DESIGN.md).
Use token references, never raw hex, spacing or radius values.
If our contract and your skill disagree, say so once and follow the contract.
List any literal you had to leave in place and why.

Writing docs an agent can follow

Tokens say what exists. Docs say when to use what. Every decision the docs leave out gets replaced by a guess, and a guess looks exactly like a decision.

Write them for an engineer who joined yesterday and can never ask you a question.

1. Inventory the code first

   Every token, every component's variant list, two or three real uses each. Never write from memory: that's how agents learn variants that don't exist.

2. Size it

   One token file and five components or fewer: one file. Bigger: a short root file plus one file per topic, each under 150 lines.

3. Use the four-part template

   For every component, in this order.

4. Verify by prompting

   Ask for a real screen in one sentence and read the drift.

The four parts:

1. When to use it, and when to use the alternative. "Navigation styled as a button is a Link."
2. Which variant applies where, and the default. Then close the set: "Nothing else exists; an unlisted variant is a bug."
3. One correct and one incorrect example, from real code.
4. A flowchart when there are three or more options.

When the test screen drifts, fix the docs, never just the screen:

Repeat until a fresh prompt drifts zero.