design tokens, the single source of truth
Every color, size and space in werkstatt is named once. How the three layers of tokens work, why the names are roles and not colors, and what happens when one changes.
A design token is a decision with a name. Signal red is a value, #D93A2B; action is a decision, the color of the one thing to do on a screen. The system stores both, in that order, and every component reads the decision rather than the value. That is the whole idea, and most of the benefit comes from taking it seriously.
three layers
The core layer is the palette, the type scale, the spacing steps and the surface values: red, yellow, blue, ink, paper, white; 96 down to 13; 8 up to 96; a 3 pixel rule, a zero radius, no shadow. These are the raw materials, and nothing in the interface uses them directly.
The semantic layer gives each material a job. Action, emphasis, structure, text, border, background, surface, and their on-color partners. A semantic token points at a core token and says what it is for. This is the layer a designer and a developer talk in, because it is the layer that carries meaning: a button is not red, it is the action.
The component layer is the stylesheet. A primary button's background is the action token; a selected tab's background is the emphasis token; the progress bar's fill is the structure token. Components never reach past the semantic layer to the hex value underneath.
why roles and not colors
Name a token after its color and the name becomes a lie the first time the color changes. A token called blue-button that turns yellow is a maintenance problem and a small act of dishonesty. Name it after its role and the change is just a change: emphasis used to be yellow and is now something else, and every component that meant emphasis follows.
The roles also carry the rules. One red per screen is really one action per screen; the token name says it. Yellow is the only color that changes on interaction is really emphasis is the state color. The vocabulary of the tokens is the vocabulary of the principles, which is why the two pages read alike.
what a change does
Suppose the structure color had to shift from ultramarine to a darker blue for contrast. In tokens.css one line changes. The focus ring, the progress bar, the information alert, the ground under a card's picture and the studio wheel's center all follow, because none of them knows the hex. The contrast table on the color page is recomputed from the same file. Nothing is searched for and nothing is missed.
Now suppose someone had written the hex into a component. That component stays ultramarine while the rest of the product moves, and the system has a seam. The rule that follows is short: in your own CSS, use the role, never the value. If the role you need does not exist, the missing token is the proposal, not a new hex.
the files
tokens.css holds the values as custom properties on the root element and is about two kilobytes. tokens.json holds the same values as data with references between them, so a design tool or a build script can read the same decisions. styles.css includes the tokens and adds every component. Three files, one truth, and the truth is in the smallest one.
A design system is sometimes described as a pattern library or a style guide. Those are its outputs. The system itself is the set of named decisions, and the tokens are where it lives.