A design system that ends in a build pipeline
Most design systems stop at the Figma library. That is the point at which they become a document instead of a system, and the reason a colour change takes a week.
There is a version of a design system that is really a very well-maintained Figma library. It has components, it has variants, it has a naming convention that somebody defended in a meeting. It also has no mechanism by which any of that reaches production, which means the thing engineers ship is a second system that resembles the first one to a degree nobody measures.
You can tell which kind you have with one question: how long does it take to change a colour ramp? If the honest answer is a week of coordinated manual edits, what you have is a document.
Three tiers, and why the middle one matters
The architecture I use has three tiers, authored in DTCG format as plain JSON.
- Primitives — the raw ramps. Colour expressed in OKLCH, so lightness steps are perceptually even instead of merely numerically even. No component ever references these.
- Semantic — meaning, not appearance.
surface.raised,text.muted,border.subtle. This is the tier that lets a theme change without a component change. - Component — the narrow, specific tokens a component owns, referencing semantics rather than primitives.
The middle tier is the one teams skip, and skipping it is why their "system" cannot be re-themed. If a button references blue.600 directly, the button knows about blue. It should only know that it is the primary action.
Contrast is a gate, not a report
The rule I hold to: a semantic name is not issued until the contrast pair it implies passes WCAG 2.2 AA. Not checked afterwards — issued only after passing.
This sounds like bureaucracy and is the opposite. It means accessibility is settled at the token layer, once, by the person who understands the ramp, instead of being rediscovered by every engineer who ever places text on a surface. An audit that finds contrast failures in a system with this property has found a bug in the pipeline, which is a much better problem than finding a hundred bugs in a hundred components.
One source, four targets
Style Dictionary takes the JSON and emits one artefact per platform. In the setups I have built that is four:
- CSS custom properties for web
- Dart constants for Flutter
- Figma variables, generated via plugin from the same token source
- React component tokens
The Figma direction is the one people find surprising. Figma is downstream. The design tool consumes the tokens; it does not author them. If Figma is the source of truth, then the source of truth is a file that cannot be diffed, reviewed, or built — and the pipeline has no beginning.
style-dictionary buildThe test
When the ramp changes, the commit changes it. One edit to the primitive JSON, one build, four artefacts, one pull request that a reviewer can actually read. The design system is the pipeline. Everything upstream of the pipeline is just where the values happen to be typed.