# What is DESIGN.md, and how do coding agents use it?

Updated 2026-11-21 · https://briefatto.com/guides/what-is-design-md/

DESIGN.md is your project's design guide, kept at the project root, that a coding agent reads before it does visual work. Briefatto Board creates it from your site or a brief, freezes it as a numbered version and points every session to it from AGENTS.md and CLAUDE.md.

## What goes in it

Authored prose about layout, spacing, navigation, components, logo, type and voice, described by role, plus a generated block of source wording and exact styles recorded from a fresh render.

Freezing validates the prose against the recorded values, stamps the guide with a version and archives it.

## How your agent uses it

1. Run `npx briefatto-board install`. It adds the skill and a marked block to AGENTS.md and CLAUDE.md.
2. Create the guide: for an existing site run `npx briefatto-board adopt .`, let your agent write DESIGN.md from the captures, then run `npx briefatto-board freeze .` to stamp v1.
3. Ask for visual work. The block tells your agent to read `DESIGN.md` first and to run `board check` on every piece.

## Questions and answers

### Is DESIGN.md the same as AGENTS.md?

No. AGENTS.md carries a short pointer; DESIGN.md holds the design guide and its versions. See [DESIGN.md vs AGENTS.md](https://briefatto.com/guides/design-md-vs-agents-md/).

### Do I need a design system first?

No. `board adopt` captures an existing site's pages and computed styles, and for a new brand you start from a brief.

### Is DESIGN.md about code architecture?

No. In Briefatto Board, DESIGN.md is the visual design guide: layout, components, type and voice.

### 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 to create a DESIGN.md from your site or a new brand](https://briefatto.com/guides/how-to-create-a-design-md/)
- [DESIGN.md vs AGENTS.md: what goes in each file](https://briefatto.com/guides/design-md-vs-agents-md/)
- [How to make Claude Code follow your brand with DESIGN.md](https://briefatto.com/guides/how-to-use-design-md-in-claude-code/)
- [Is DESIGN.md an official standard or an Anthropic format?](https://briefatto.com/guides/is-design-md-an-official-standard/)

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