# Design tokens for AI coding agents: what goes in DESIGN.md?

Updated 2026-11-21 · https://briefatto.com/guides/design-tokens-for-ai-coding-agents/

Put the values your pages actually render, named by role, with the reasons and rules for using them, and leave building the tokens to your token pipeline. Briefatto Board records the exact values from a fresh render at freeze, checks the values you write against them, and `board check` notes any colour or font a piece uses outside the guide.

## What to write

- **Values by role.** Name what each colour and face does, such as the signal colour, the body face or the heading face, not only its token name.
- **How the parts are built.** Describe each recurring part by its job and how it uses the values.
- **When to use which.** The rules a designer would hand over: what carries the brand, what recomposes on other canvases.
- **Font load lines** under `## Typography`, so every piece loads the real face.
- **Tokens in YAML front matter,** as Google's design.md format does. Freeze reads them.

## What Board writes for you

You do not copy your token file in. At freeze, Board records source wording and exact styles from a fresh render in a generated block and validates the values you wrote against them, naming any conflict. Measured ratios, coverage percentages and centroid coordinates stay out of the prose.

## How agents use them

- The block in AGENTS.md and CLAUDE.md tells every session to read DESIGN.md before any visual work.
- `board check` notes any colour or font a piece paints outside the current guide; `--consistency` adds the nearest frozen colour.
- `board status` lists which pieces are current after a token change.

## Questions and answers

### YAML front matter or prose?

Either, or both. Freeze reads colour, font-family and font-size values in the front matter and in the prose, and checks them against the render.

### Should DESIGN.md hold every token?

Hold the values the brand depends on, by role. The exact rendered styles go into the generated block at freeze.

### Is Briefatto Board free?

Yes. It is open source under the Apache-2.0 licence and installs with `npx briefatto-board install`.

## Try it

```
npx briefatto-board install
```

Briefatto Board is free and open source under Apache-2.0: https://github.com/Briefatto/briefatto-board

## Related guides

- [How do you keep design tokens consistent in Cursor's output?](https://briefatto.com/guides/keep-design-tokens-consistent-in-cursor/)
- [How do you get Tokens Studio tokens in front of a coding agent?](https://briefatto.com/guides/tokens-studio-to-design-md/)
- [How do you keep a coding agent on your shadcn/ui theme?](https://briefatto.com/guides/shadcn-ui-design-md/)
- [How do you write a good DESIGN.md that an agent can use?](https://briefatto.com/guides/how-to-write-a-good-design-md/)
- [Style Dictionary vs DESIGN.md: what does each give a coding agent?](https://briefatto.com/guides/style-dictionary-vs-design-md/)

## Sources

- https://github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/SKILL.md
- https://github.com/Briefatto/briefatto-board/blob/main/README.md
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/design-validation.ts
- https://github.com/Briefatto/briefatto-board/blob/main/CHANGELOG.md
- https://github.com/google-labs-code/design.md (checked 2026-11-21)
- https://styledictionary.com/ (checked 2026-11-21)
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/check.ts
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/standing.ts
- https://github.com/Briefatto/briefatto-board/blob/main/LICENSE
