Design Tokens with LESS

What Are Design Tokens in a LESS Project?

A design token is simply a named value representing a single design decision, a brand color, a spacing step, a border radius, stored once and referenced everywhere it's needed. In LESS, tokens are naturally expressed as @variables, grouped by category in a dedicated file.

Well-organized tokens make global design changes, like adjusting a brand color or a spacing scale, a matter of editing a handful of variables instead of hunting through every component file.

// _tokens.less
@color-primary: #2563eb;
@color-success: #16a34a;
@color-danger: #dc2626;

@spacing-1: 4px;
@spacing-2: 8px;
@spacing-3: 16px;
@spacing-4: 24px;

@radius-sm: 4px;
@radius-md: 8px;
@radius-lg: 16px;

Grouping tokens by category (color, spacing, radius) with consistent numeric naming makes the scale easy to scan and extend.

Token Naming Convention

@category-variant: value;

@color-primary: #2563eb;
@spacing-2: 8px;
@font-size-lg: 1.25rem;

• Prefix tokens by category (color-, spacing-, radius-, font-size-) for discoverability.
• Use a consistent numeric or named scale (1, 2, 3, 4 or sm, md, lg) rather than arbitrary values per component.
• Keep all tokens in one dedicated file, imported before any component styles.
• Avoid using raw hex or pixel values directly in component files; always reference a token variable instead.

Design Tokens Cheatsheet

Common token categories and example naming patterns.

Deriving Secondary Tokens with Color Functions

Rather than manually picking a hover or border color, derive it directly from a base token using a color function, keeping the entire palette mathematically consistent and easy to adjust globally.

@color-primary: #2563eb;
@color-primary-hover: darken(@color-primary, 8%);
@color-primary-border: darken(@color-primary, 15%);
@color-primary-soft: fade(@color-primary, 10%);

Building a Spacing Scale with Operations

A spacing scale can be generated mathematically from a single base unit, guaranteeing consistent proportional relationships between every step instead of arbitrarily chosen values.

@spacing-unit: 4px;

@spacing-1: @spacing-unit * 1;  // 4px
@spacing-2: @spacing-unit * 2;  // 8px
@spacing-3: @spacing-unit * 4;  // 16px
@spacing-4: @spacing-unit * 6;  // 24px

Tokens as a Single Source of Truth

The real payoff of design tokens is rebranding or theming speed: changing @color-primary in one file cascades correctly through every button, link, and border that was built by referencing the token rather than a hardcoded value.

• Never hardcode a raw color or spacing value directly inside a component file.
• Treat the tokens file as the single source of truth for every visual decision.
• Review new component styles for hardcoded values that should reference an existing token instead.

Common Mistakes

• Hardcoding a hex color or pixel value directly in a component file instead of referencing a token variable.
• Creating inconsistent, one-off spacing values per component instead of committing to a defined scale.
• Deriving a hover or border color by eye instead of using a color function against the base token, causing subtle inconsistencies.
• Splitting design tokens across multiple, poorly organized files instead of one clear, well-grouped tokens file.

Key Takeaways

• Design tokens are named, foundational values (colors, spacing, radii) modeled as LESS variables.
• Group and prefix tokens by category (color-, spacing-, radius-) for discoverability.
• Derive secondary tokens (hover states, borders) from base tokens using color functions and operations.
• Treat the tokens file as the single source of truth; never hardcode raw values in component files.