Start a Design System with Tokens, Not a Component Library

A practical approach

Step 1

Audit the existing interface and collect every colour, font size and spacing value currently in use.

Step 2

Reduce them to a small scale: a handful of neutral greys, brand colours with defined uses, a type scale and a spacing scale.

Step 3

Name tokens by purpose where possible, such as text-muted or surface-raised, rather than by appearance, such as grey-500, so their meaning survives a redesign.

Step 4

Implement tokens as CSS custom properties, generated from a single source if you need them in several platforms.

Step 5

Replace hard-coded values in the most used screens first, then build or refactor components on top of the tokens.

Worked example

An audit of a learning website finds 27 distinct greys, 14 font sizes and spacing values from 3 to 61 pixels. Defining seven neutrals, a six-step type scale and an eight-step spacing scale as CSS variables, then updating the header, cards and forms, makes pages look noticeably more consistent. Adding a dark theme later requires changing only the token values.

A mistake to avoid

Do not create a token for every one-off value you find. A token system with hundreds of near-duplicates is as inconsistent as no system. Each token should represent a decision you want to repeat.

Try it yourself

List every colour used in one page's CSS. Group similar values, choose one per group and give each a purpose-based name. Replace the original values with your new custom properties.

Your implementation checklist

• Existing values have been audited
• Colour, type and spacing use small defined scales
• Token names describe purpose
• Tokens are implemented as custom properties from one source
• New components use tokens instead of raw values