Alpha — breaking changes ship without a deprecation cycle. What is built vs. planned
What is a design token?
A design token is a named design decision. Not a color, but a decision about a color: what it’s called, what value it holds, and what it means.
“Our action color is a specific blue” is a decision. Written as a token, it has three parts:
- a name:
primary - a value: a particular blue
- a meaning: “the color of the main thing we want people to do”
That third part is what makes tokens different from a palette. A palette is a list of paints; tokens say which wall each paint goes on.
Two kinds of names#
Mature design systems name things twice, on purpose:
Value names describe what something is: blue-600, gray-50, red-500. They’re your paint buckets: stable, reusable, meaning-free. If you repaint the brand, blue-600 becomes a different blue, and its name still makes sense.
Meaning names describe what something is for: primary, danger, surface, text-muted. They point at value names: primary → blue-600. This is where the design decisions live, and it’s the layer everything downstream should read.
When the brand shifts, you change one pointer (primary now points at a different bucket) and every button, link, and chart that meant “primary” follows. Nothing to search and replace, and no corner of the product left wearing the old blue.
Meaning names also make modes possible. In dark mode, surface means a different value, but every component that says “surface” is still correct. The decision survives; only the value swaps.
The problem tokens don’t solve#
Your product teams don’t build with your token names. They build with frameworks, and every framework has its own dialect for the same meanings:
| Your meaning | shadcn/ui says | Bootstrap says | daisyUI says |
|---|---|---|---|
| the action color | primary | primary | primary |
| destructive | destructive | danger | error |
| raised surface (cards) | card | body-tertiary-bg | base-200 |
Same meanings, different words. Sometimes it’s the same word for different meanings, which is worse: your “secondary” and Bootstrap’s “secondary” are unrelated decisions that happen to share a spelling.
So the decision layer you carefully built gets re-translated by hand, per framework, forever: once into a Bootstrap theme, once into a shadcn stylesheet, once into a chart library’s config. Each copy drifts. Each framework upgrade breaks one. Nobody is sure which copy is current.
Keeping one set of decisions and letting every framework speak it natively is the translation problem Transtyle exists for.
Next: How Transtyle works, the mental model, still no code.