# Style Dictionary vs DESIGN.md: what does each give a coding agent?

Updated 2026-11-21 · https://briefatto.com/guides/style-dictionary-vs-design-md/

Style Dictionary exports your design tokens to platforms such as CSS, JS, iOS and Android; DESIGN.md tells a coding agent how the brand uses those values. Briefatto Board is the layer that makes agents use them: one versioned DESIGN.md recorded from your rendered pages, a pointer in AGENTS.md and CLAUDE.md, `board check` on the output and `board status` after a change.

## Different jobs

|  | Style Dictionary | DESIGN.md with Briefatto Board |
| --- | --- | --- |
| Job | Export design tokens to every platform you build for | Tell the agent how the brand looks and how to use those values |
| Starts from | Your token source files | Your rendered pages, or a direction you chose |
| Produces | Platform files such as CSS and JS | A frozen guide with exact rendered styles, versions and a stale list |
| Read by | Your build | The agent, before any visual work |

## Use them together

1. Keep [Style Dictionary](https://styledictionary.com/) building your tokens into CSS.
2. Run `npx briefatto-board adopt .` on the pages that use them. The agent reads the computed styles and the CSS variables the pages use, and writes DESIGN.md by role.
3. Run `npx briefatto-board freeze .`. Freeze records the exact styles your tokens produce on the page and checks the values written in the guide against them.
4. From then on the block in AGENTS.md and CLAUDE.md sends every session to DESIGN.md, and `board check` notes any colour or font a piece paints outside it.

## When a token changes

Rebuild with Style Dictionary, update DESIGN.md and freeze the next version with a note. `board status` lists which pieces still declare the old version.

## Questions and answers

### Do I have to choose between Style Dictionary and DESIGN.md?

No. Style Dictionary builds the values; DESIGN.md, kept by Briefatto Board, is what the agent reads before it uses them.

### How does the agent learn my token names?

It inspects the CSS variables your pages use when it writes DESIGN.md, and freeze reads a braced reference such as `{colors.primary}` as a token name.

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

- [DESIGN.md vs a design system: what is the difference?](https://briefatto.com/guides/design-md-vs-design-system/)
- [Google's design.md format with Briefatto Board: versions and checks](https://briefatto.com/guides/google-design-md-format-briefatto-board/)
- [DESIGN.md vs SKILL.md: what each file does](https://briefatto.com/guides/design-md-vs-skill-md/)
- [The best DESIGN.md generators and libraries in 2026](https://briefatto.com/guides/best-design-md-generators-2026/)
- [Design tokens for AI coding agents: what goes in DESIGN.md?](https://briefatto.com/guides/design-tokens-for-ai-coding-agents/)

## Sources

- https://styledictionary.com/ (checked 2026-11-21)
- 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/src/board/standing.ts
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/check.ts
- https://github.com/Briefatto/briefatto-board/blob/main/LICENSE
