Design tokens

Design token strategy

CSS variables should define the shared design language. Colours, spacing, radii, font sizes, borders, shadows, and layout values should not be invented randomly inside component styles.

Shared CSS variables

Define project-wide values once, then use them throughout the CSS. This keeps visual decisions consistent and makes later design changes safer.

CSS code example

:root {
    --colour-background: #ffffff;
    --colour-surface: #f7f7f7;
    --colour-text: #111111;
    --colour-accent: #6f3cff;

    --space-xs: 0.25rem;
    --space-s: 0.5rem;
    --space-m: 1rem;
    --space-l: 2rem;
    --space-xl: 4rem;

    --radius-s: 0.25rem;
    --radius-m: 0.5rem;
    --radius-l: 1rem;
}

Use tokens in components

Component CSS should refer to shared variables rather than hard-coded numbers and colours.

CSS code example

.product-card {
    padding: var(--space-m);
    border-radius: var(--radius-m);
    background: var(--colour-surface);
    color: var(--colour-text);
}

Avoid arbitrary values

Random spacing, colours, radii, and one-off values make a codebase harder to maintain. They also make a site feel visually inconsistent over time.

CSS code example

.product-card {
    padding: 17px;
    border-radius: 13px;
    background: #f3f2f9;
    color: #222222;
}

Rules of thumb

Use CSS variables for shared design values.
Prefer named spacing values over one-off measurements.
Do not add random colours directly inside components.
Keep token names predictable and consistent.
Only add a new token when it represents a reusable decision.
Use component-level custom properties only when the component genuinely needs local configuration.