Design token strategy

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.

:root {
    --ff: system-ui, sans-serif;
    --fs: 1rem;
    --fs-s: 0.875rem;
    --fs-m: 1.125rem;
    --fs-l: 1.25rem;
    --fs-xl: 1.5rem;
    --lh: 1.5;
    --lh-s: 1.2;
    --lh-m: 1.6;
    --lh-l: 1.7;
    --fw-semibold: 600;

    --c-background: #ffffff;
    --c-surface: #f7f7f7;
    --c-text: #111111;
    --c-accent: #6f3cff;

    --space: 1rem;
    --space-s: 0.5rem;
    --space-m: 1.5rem;
    --space-l: 2rem;

    --br-m: 0.5rem;
    --br-l: 1rem;
}

Names can be shortened when the meaning stays obvious — seetoken naming below.

Token naming

Tokens are referenced hundreds of times. Shorten only prefixes the team recognises at a glance — less noise in var(), not cryptic codes. If a newcomer needs a cheat sheet to decode a name, it is too short.

Base step: bare token name

For scales you use constantly, the default value is the bare name — not --fs-base or --line-height-base. Body font size is --fs; line height for normal copy is--lh; default spacing is --space. Those bare names are the base step on each ladder, not an implicit “medium”. When you need the next step up before-l, use an explicit -m (for example--fs-m, --lh-m, --space-m). Other steps share the same suffix set: 2xs, s, l,xl, 2xl, and so on. Do not mixsm / md / lg on one scale with that ladder on another.

:root {
    /* Font size — bare --fs is base (body); */
    --fs-2xs: 0.625rem;
    --fs-s: 0.875rem;
    --fs: 1rem;
    --fs-m: 1.125rem;
    --fs-l: 1.25rem;
    --fs-xl: 1.5rem;
    --fs-2xl: 2rem;

    /* Line height — bare --lh is base */
    --lh-s: 1.2;
    --lh: 1.5;
    --lh-m: 1.6;
    --lh-l: 1.7;

    /* Spacing — bare --space is base */
    --space-2xs: 0.25rem;
    --space-s: 0.5rem;
    --space: 1rem;
    --space-m: 1.5rem;
    --space-l: 2rem;
    --space-xl: 3rem;
    --space-2xl: 4rem;
}

Prefix map

Agree one map per project. Values change; naming rules should not. Use semantic tokens in components (--c-text, --c-link); define ramps in settings.

/* Document once in settings/tokens.css (or your tokens partial) */

Long prefix              →  Short prefix
--colour-*               →  --c-*              (--c-text, --c-link, ramps)
--font-size-*            →  --fs, --fs-*       base: --fs; ladder 2xs–2xl + -m; not -sm/-md/-lg
--line-height-*          →  --lh, --lh-*       base: --lh; not -tight / -relaxed
--spacing-*              →  --space, --space-*
--border-radius-*        →  --br-*
--font-family            →  --ff, --ff-mono
--font-weight-*          →  --fw-*

Often keep descriptive: --border-*  --shadow-*  --transition-*  --z-*  one-offs (--site-header-offset)

/* Avoid: abbreviations nobody can decode at a glance */
--col-acc: #6f3cff;
--fsize-m: 1rem;
--ln-h: 1.5;
--spc-17: 17px;

Use tokens in components

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

.product-card {
    padding: var(--space);
    border-radius: var(--br-m);
    background: var(--c-surface);
    color: var(--c-text);
    font-size: var(--fs);
    line-height: var(--lh);
}

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.

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

Rules of thumb

• Use CSS variables for shared design values.
• Follow the agreed prefix map: bare name for the base step,-m before -l where needed, same2xs–2xl ladder on every shared scale.
• Prefer named spacing values over one-off measurements.
• Do not add random colours directly inside components.
• Keep token names predictable and consistent across the project.
• Only add a new token when it represents a reusable decision.
• Use component-level custom properties only when the component genuinely needs local configuration.