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:
npx @google/design.md lint DESIGN.mdThat 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.
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 checkon 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 --consistencylists colours off the frozen palette, each with its nearest frozen colour.board statuslists 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.