# DESIGN.md vs a design system: what is the difference?

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

A design system is the components and tokens your product is built from, and DESIGN.md is the written guide your agent reads before it designs. Briefatto Board keeps that guide true: it records exact styles from a fresh render, validates the prose against them and versions the result.

## Code and guide

|  | Design system | DESIGN.md |
| --- | --- | --- |
| Lives in | Code: components, tokens, themes | One document at the project root |
| Read by | Your build | Your agent, before visual work |
| Says | What to build with | How the brand looks and speaks: layout, components, type and voice by role |

In Briefatto Board, DESIGN.md holds authored prose plus a generated block of source wording and exact styles recorded from a fresh render.

## How Briefatto Board keeps the guide true

- `board adopt .` captures your pages and computed styles, so the guide starts from what your site renders.
- `board freeze .` validates the written guide against the recorded values and names any conflicting style values.
- `board check` tests every rendered piece against the quality floor.

## Questions and answers

### Does DESIGN.md replace my design system?

No. It sits next to it as the guide your agent reads. Your components and tokens stay where they are.

### Can Briefatto Board create DESIGN.md from my existing site?

Yes. `npx briefatto-board adopt .` captures the site's pages and computed styles, your agent writes DESIGN.md from what it sees, and `npx briefatto-board freeze .` freezes it as v1.

### Is it free?

Yes. Briefatto Board is open source under Apache-2.0.

## 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 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/)
- [A free, open-source DESIGN.md tool for coding agents](https://briefatto.com/guides/design-md-open-source/)
- [Impeccable vs Taste Skill: what a blind test showed](https://briefatto.com/guides/impeccable-vs-taste-skill/)

## 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/CHANGELOG.md
- https://github.com/Briefatto/briefatto-board/blob/main/LICENSE
