Briefatto LabBriefatto Lab

Questions

How do you write a good DESIGN.md that an agent can use?

Write it as a handoff from one designer to another: layout, spacing, components and logo described by role, the voice taken from your real pages, and nothing the reader cannot build from the file alone. Briefatto Board's skill has the agent write DESIGN.md that way from captures of your site, and board freeze records the exact styles beside the prose.

Updated Markdown version

Briefatto BoardFree and open source, Apache-2.0

Blind-tested against Impeccable, Taste Skill and Hallmark

Automated tests, green CI

Claude Code, Codex, Cursor, Copilot, Gemini CLI, Windsurf and any agent that reads AGENTS.md

What a usable DESIGN.md holds

  • Parts by their job. Name each recurring part by what it does, then say how it is built and how the parts sit together.
  • Layout, spacing, navigation, components and logo, described by role, the way a designer briefs the next designer.
  • The real voice. Example copy comes from your actual pages, not from a template.
  • How it recomposes. Say how the arrangement changes for other canvases.
  • Typography with load lines. Under ## Typography, say which parts use each face and include the font load lines.
  • Sufficient on its own. Write for a reader who has this file and your brand assets, and nothing else.

What Board writes for you

You do not type the exact values. board freeze records source wording and exact styles from a fresh render in a generated block, validates the prose against those values and names any conflicting style value. The prose carries the judgement; the generated block carries the numbers.

The steps

  1. Run npx briefatto-board install, then npx briefatto-board adopt ..
  2. The agent opens each screenshot, reads evidence.json for computed styles and visible copy, and inspects your CSS variables, Tailwind configuration, theme and logo files.
  3. It drafts DESIGN.md. Preview the result with npx briefatto-board freeze . --dry-run.
  4. Freeze it: npx briefatto-board freeze .. From then on, AGENTS.md and CLAUDE.md tell every session to read it first.

Questions and answers

Should I put hex codes in the prose?

Yes. Freeze reads colour, font-family and font-size values written in the guide and compares them with the render, so a wrong value is named before the guide is frozen.

Will Claude Code read the file?

Yes. After freeze, the block in CLAUDE.md and AGENTS.md tells it to read DESIGN.md before any visual work.

Is Briefatto Board free?

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

One guide. Every agent.

Briefatto Board is free and open source under Apache-2.0. One command adds the skill and the pointer your agent reads.

npx briefatto-board install

Sources

  1. github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/SKILL.md
  2. github.com/Briefatto/briefatto-board/blob/main/README.md
  3. github.com/Briefatto/briefatto-board/blob/main/CHANGELOG.md
  4. github.com/Briefatto/briefatto-board/blob/main/src/board/design-validation.ts
  5. github.com/Briefatto/briefatto-board/blob/main/src/board/standing.ts
  6. github.com/Briefatto/briefatto-board/blob/main/LICENSE