# How do you lint a DESIGN.md?

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

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.

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

```sh
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.

```sh
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.

## 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 docs drift from the real design: how freeze stops it](https://briefatto.com/guides/design-docs-drift-from-the-real-design/)
- [How do you write a good DESIGN.md that an agent can use?](https://briefatto.com/guides/how-to-write-a-good-design-md/)
- [Design tokens for AI coding agents: what goes in DESIGN.md?](https://briefatto.com/guides/design-tokens-for-ai-coding-agents/)
- [How do you enforce design checks in a pre-commit hook?](https://briefatto.com/guides/design-check-in-pre-commit-hook/)
- [Google's design.md format with Briefatto Board: versions and checks](https://briefatto.com/guides/google-design-md-format-briefatto-board/)

## Sources

- https://github.com/google-labs-code/design.md (checked 2026-11-21)
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/design-validation.ts
- https://github.com/Briefatto/briefatto-board/blob/main/CHANGELOG.md
- https://github.com/Briefatto/briefatto-board/blob/main/README.md
- https://github.com/Briefatto/briefatto-board/blob/main/skill/briefatto-board/SKILL.md
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/check.ts
- https://github.com/Briefatto/briefatto-board/blob/main/src/board/cli.ts
- https://git-scm.com/docs/githooks (checked 2026-11-21)
