Briefatto LabBriefatto Lab

Questions

How do you lint a DESIGN.md?

Lint a DESIGN.md as a file, for format and broken token references, and then against the pages it describes. board freeze does the second, comparing the colours, font families and font sizes your DESIGN.md states with values recorded from a fresh render and naming every conflict.

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

Lint the file

If you write in Google Labs' design.md format, its CLI checks the file itself with 11 rules, such as broken token references, WCAG contrast and section order:

shell
npx @google/design.md lint DESIGN.md

That tells you the file is well formed. It cannot tell you the file is true.

Lint the file against the site

Briefatto Board reads the colour, font-family and font-size values written in your guide, including a YAML colors: block and fontFamily and fontSize fields, and compares them with values recorded from a fresh render. A reference in braces, such as {colors.primary}, counts as a token name, not a new value.

shell
npx briefatto-board freeze . --dry-run
npx briefatto-board freeze .

--dry-run previews the generated guide without writing files. The real freeze names every conflicting value, so the guide cannot silently disagree with the pages at the moment it is stamped.

Lint what gets made from it

  • board check on a frozen board notes every painted colour and font that is not in the current guide, and names the earlier version a stray value came from.
  • board check --consistency lists colours off the frozen palette, each with its nearest frozen colour.
  • board status lists pieces made under an older version of the guide.

Only floor faults set exit status 1, so a pre-commit hook or CI run stops on a broken piece; the stray values and stale pieces above are reported for a reviewer, not failed.

Questions and answers

Do I have to use YAML front matter?

No. Freeze reads the values written in the authored guide, and a YAML colors: block is one of the forms it reads.

Can I run both linters?

Yes. The format lint checks the file and freeze checks it against the render, so they answer different questions.

What does a conflict look like?

Freeze names the style value your guide states and the value the fresh render recorded. Fix whichever is wrong, the prose or the page, and freeze again.

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/google-labs-code/design.md checked 2026-11-21
  2. github.com/Briefatto/briefatto-board/blob/main/src/board/design-validation.ts
  3. github.com/Briefatto/briefatto-board/blob/main/CHANGELOG.md
  4. github.com/Briefatto/briefatto-board/blob/main/README.md
  5. github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/SKILL.md
  6. github.com/Briefatto/briefatto-board/blob/main/src/board/check.ts
  7. github.com/Briefatto/briefatto-board/blob/main/src/board/cli.ts
  8. git-scm.com/docs/githooks checked 2026-11-21