Tooling is half the design system

The budget goes to components. The failures happen between them.#

Ask a design system team where their effort goes and you will hear components, tokens and documentation. Ask where the system actually degrades and the answer is different: a spacing value that is not on the scale, an instruction file that no longer matches the repo, a claim in a case study that nobody can trace back to anything. None of these are component problems. They are enforcement problems, and enforcement is tooling.

I spent this year building three small tools, each aimed at one specific way systems rot. None of them is a platform. That is deliberate. The pattern I keep relearning is that the highest-leverage tooling is narrow: it automates one check that humans keep failing to make, and it does nothing else.

Three failure modes, three tools#

Spacing drift was the first. Every codebase I audit has values that are almost on the scale: a 14px here, a 22px there, arbitrary Tailwind values that looked fine in the PR. Documentation does not stop this because nobody reads the spacing page while writing CSS. Rhythmguard turns the scale into Stylelint and ESLint rules with autofix. On this site, the migration measured 31 violations autofixed to zero, verified by re-linting. The interesting part is not the number, it is that the correction cost nothing: the diff was a clean 26-line substitution that no human had to think about.

Context drift was the second. Agent instruction files, CLAUDE.md and its cousins, are the new documentation surface, and they rot faster than docs because agents act on them immediately. Project Spine treats instructions as a compile target: brief, repo state and design tokens go in, instruction files for four agent tools come out, every rule carrying a pointer to its source. When the repo changes, a CI gate flags the drift. The instruction file stops being prose someone once wrote and becomes an artifact the build can verify.

Reference rot was the third, and the one this site is built against. A screenshot without provenance, a metric without a method, a source you half remember: these are vibes with timestamps, not something you can stand behind. Precedent captures references locally with context attached at capture time. The AI proposes context, and it never silently asserts it, because a wrong attribution is worse than none. The release gates fail closed on exactly that: the measured incorrect-context rate has to be zero.

When to build instead of adopt#

The default should be adopt. Most checks you need already exist as an axe rule, a Stylelint plugin, a TypeScript compiler flag. I build only when two conditions hold at once: the check encodes a judgment specific to how I work, and the cost of the check failing silently is high. Rhythmguard exists because generic linters do not know my spacing scale. Spine exists because no generic tool knows which repo facts my agent instructions depend on. If either condition is missing, building is hobby time dressed up as leverage.

• Build when the rule is yours: your scale, your tokens, your contracts.
• Build when silent failure is expensive: broken agent output, false claims, shipped drift.
• Adopt when the check is universal: contrast, syntax, types, dead links.
• Never build what you are not willing to release properly. Unversioned tools become the drift they were meant to catch.

What it costs#

Honesty section. Three tools means three release pipelines, three changelogs and three things that break when a dependency majors. Rhythmguard took 18 releases to reach v2.0.1. Spine took 14 releases in three months and most of them were unglamorous: gates, provenance, drift checks. The cost of a tooling portfolio is not the first version, it is the maintenance discipline, and the only way I have found to afford it is to make release engineering part of the tool's design rather than an afterthought.

The payoff is a different kind of design system work. Components are the visible half. The tooling half decides whether the rules survive contact with deadlines, agents and other people. If your system only exists in documentation, you do not have a system, you have a wish.