How I structure a design tokens starter
A starter model for primitives, semantic tokens, component tokens, CSS variables, and handoff documentation.
A useful token starter should teach the system as much as it stores values. The goal is not to create a giant JSON file. The goal is to make product decisions portable between design and code.
I start with primitives: raw color ramps, spacing values, font sizes, radii, and shadows. These are materials, not instructions. They should be boring, consistent, and easy to replace.
The second layer is semantic. Semantic tokens describe intent: page background, elevated surface, muted text, strong border, primary action, danger action. This is where the product language starts to appear.
The third layer is component-specific, used sparingly. A button or input may need local tokens for state and interaction, but component tokens should usually point back to semantic tokens. Otherwise the system becomes a pile of unrelated exceptions.
Output matters. A starter should produce CSS variables, a readable JSON source, and enough documentation for designers and engineers to know which layer to use. The best token systems are not only technically correct. They are easy to choose from under deadline pressure.
The adoption test is simple: can a new screen be built without inventing new colors, one-off spacing, or mystery typography? If the answer is yes, the token starter is doing useful work.