Design systems
How to build a design system from tokens
A design system starts from tokens: inventory the raw values, name the scales, add semantic roles, then build components. Code comes last.
Key points
- Start from the raw values already in the code: they are your current system.
- Two levels are enough: scales with neutral names and semantic roles.
- If changing one token touches fifty files, it was a raw value in disguise.
You build a design system from tokens: first inventory the raw values, then name the decisions, then generate the components. Code comes last, not first.
Step 1: count the raw values
grep -rhoE '#[0-9a-fA-F]{6}' src --include='*.tsx' | sort | uniq -c | sort -rn | head -20The command lists the hex colours written by hand in components and how often each appears. The top twenty values are your current system, even if nobody ever called it one.
Step 2: name the scales
Group the values into scales: colour, space, radius, type, shadow. Each step gets a neutral name (--gray-100, --space-4) and a value. Do not mix semantics into the scale yet.
Step 3: add the semantic layer
On top of the scale put the roles: --primary, --muted, --border. Components use only the roles, so a dark theme changes the roles and not the files. shadcn/ui, an MIT project, uses that scheme in globals.css, as the dropdown menu record shows.
Step 4: generate the CSS
Write the tokens once in a JSON file and generate the CSS with a script. The JSON file is the source, the CSS is the artefact; a manual CSS edit is gone at the next build.
Step 5: build one component at a time
Start from the most used components: button, field, dialog, table. Every component consumes tokens, not values. In the EneUI catalogue you find 111,985 components and 12,808 icons as reference, plus 1,556 blocks already composed.
Step 6: document the rule, not the file
For each token write when to use it and when not to. Useful documentation is the sentence that prevents the mistake, not the table that repeats the value.
The limitation
Tokens do not fix a wrong component. If the button has insufficient contrast, the semantic token spreads the same error into every theme; that needs a contrast measurement, not another variable.
Where to continue
The full theme is in how to theme shadcn, the contrast measurement in palette and measured contrast. The comparison between a UI kit and a design system is in UI kit, component library or design system.
Frequently asked questions
Where do I start if the project already has components?
From the inventory: count the colours and spacing written by hand and group them into scales. The system grows out of the values you already use.
Are tokens and CSS variables the same thing?
No. A token is a decision with a name; a CSS variable is one way to distribute it. From the same token you can generate CSS, TypeScript types or JSON.
Do I have to use a standard such as W3C design tokens?
It is not mandatory. The W3C JSON format helps when several tools read the same tokens; for a single project your own JSON file is enough.
How many token levels do I need?
Two are enough: scale and semantics. A third level per component is justified only when a component needs a value no one else uses.
How do I update a token already in use?
Change the value at the source, regenerate the CSS and read the diff. If the change touches fifty files, the token was a raw value in disguise.