Documentation drifts because it is maintained separately from the thing it describes. Keep the facts (which tokens exist, their values in each theme, which components exist and where they are used) derived from the code, so they cannot go stale, and keep only the intent (when to use what, and why) as hand-written prose. Then check the code against the system regularly, so differences surface as findings rather than surprises.
Separate facts from intent
- Facts: token names and values, themes and modes, component inventory, variants, use counts. Generate these.
- Intent: purpose, do and don't, accessibility requirements, contribution rules. Write these.
This site does exactly that: its tokens live in one JSON file, the CSS is generated from it, and a test fails if they disagree. The design system page shows the generated values next to the written rules.
Check continuously
A scan that runs locally and deterministically can run as often as you like. The same code always gives the same findings, so a change in the findings is a change in the code.
What Saer does about this
- Saer's report and
system.jsonrecord the system that exists in code, for colour, typography, the foundations and components, all in the beta.
- Generated documentation pages: planned.
- A team registry for a shared, versioned record: planned.
Every capability and its state: what Saer checks.
See it on your own codebase.
Request early access