Tokens, primitives and the governance model that stops one component library becoming three within a year.
Executive Summary
- A component library fragments when teams can ship a fork faster than they can get a change merged; governance is a release problem, not a design one.
- Tokens are the contract. Anything a product team can restyle without a token has already left the system.
- Version the primitives separately from the patterns built on them, so a visual change never forces a breaking upgrade.
Where teams usually start
Most teams arrive at this problem from the same direction: something that worked at one scale stopped working at the next, and the fix that used to be obvious no longer is. This guide walks the path we take with clients, in the order we take it.
The approach
Work in slices that can each ship on their own. A slice that cannot be deployed independently is not a slice, it is a phase – and phases are where migrations go to die.
What to measure
Decide the numbers that say it worked before you start, and instrument them first. Retrofitting measurement onto a finished migration tells you nothing about what the migration changed.
Conclusion
None of this is exotic. It is the discipline of small, reversible steps applied to a problem large enough that skipping the discipline is tempting.
