# Design contracts

> Give your agent a .design file or a DESIGN.md so it uses your tokens instead of guessing, know which source wins a disagreement, and write design-system docs an agent can actually follow.

Module: Directing your agent · Level: intermediate · 8 min · https://school.agents.org.in/foundations/agents/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 (A named value, like --color-text-secondary, used instead of typing the raw color everywhere. Change the token and every place that uses it changes) 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:

| | `.design` | `DESIGN.md` |
|---|---|---|
| Made by | AgentsORG (schema `design.v1`) | Google Labs |
| Shape | a machine-readable contract | tokens up top, prose below |
| Holds | tokens, components, voice, rules, and an **intent** | tokens, plus an overview and do's and don'ts |
| When both exist | it is the contract | it becomes the rationale |

> **In plain words.** A design contract (A file in your project (.design or DESIGN.md) that tells an agent how things look: colours, type, spacing, radii, which component to use when. It outranks the skill's defaults) is a file in your project that says how things look, in a form the agent can read: colours, type, spacing, radii, which button to use when. The agent reads it before writing UI.

## 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.

*[Interactive demo: The highest source present wins. The skill only fills in where the contract is silent.]*

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.**

*(Silence isn't permission. Where the contract says nothing, the skill's craft still applies.)*

## 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.

  **Step: agent.instructions first.** The contract's own short brief, written so the file works even with no skill installed.

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

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

  **Step: 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.

```bash
npx -y @google/design.md lint DESIGN.md
```

**Use the contract (paste into your agent):**

```text
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.

  **Step: 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.

  **Step: 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.

  **Step: Use the four-part template.** For every component, in this order.

  **Step: 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.

  **Hedged (avoid):**

Use small text sparingly. Prefer the primary button for important actions.

  **Strict (do this):**

Body 16px, captions 14px, never below 12px. One primary button per view: two means the screen has no hierarchy.

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

| The agent did | The fix |
|---|---|
| hardcoded a colour | move the "semantic tokens only" rule into the root file |
| invented a variant | add "nothing else exists" and tighten the type |
| picked the wrong component | add the when-vs-alternative line for that pair |

Repeat until a fresh prompt drifts zero.

**Check yourself:** Your .design sets dialog duration to 400ms. The skill says most UI should be under 300ms. Your prompt says nothing about it. What should the agent do?

- [ ] Use 200ms, because the skill knows better
- [x] Use 400ms, mention the tension once, and move on
- [ ] Ask you every time it builds a dialog
- [ ] Use 300ms as a compromise

*Why:* The nearest .design outranks generic taste skills. The agent raises the conflict once in prose, then follows the contract.

## In the skill

- https://school.agents.org.in/skill/meta/using-design-file.md
- https://school.agents.org.in/skill/meta/using-design-md.md
- https://school.agents.org.in/skill/meta/design-system-docs.md