Design Tokens vs CSS Variables

Understanding design tokens vs CSS variables clarifies two related but distinct concepts in design system architecture. CSS variables provide a native browser mechanism for storing and reusing values within stylesheets. Design tokens represent a higher-level abstraction that can target CSS variables as one output among many. These concepts overlap but serve different purposes at different levels of the system.

What Are CSS Variables

CSS variables, formally known as CSS custom properties, are entities defined in CSS that contain values to be reused throughout a document. They are declared with a double-hyphen prefix (--color-primary) and accessed using the var() function (var(--color-primary)).

CSS variables are browser-native, requiring no build process. They can be scoped to selectors, inherited through the DOM, and modified at runtime with JavaScript. This makes them powerful for dynamic styling and theming.

What Are Design Tokens

Design tokens are platform-agnostic design decisions stored in a format that can be transformed into any platform’s native styling language. A design token might be defined in JSON and transformed into CSS variables for web, XML for Android, Swift for iOS, and other formats as needed.

Design tokens exist as an abstraction layer above any specific platform implementation. They capture design intent in a way that travels across codebases, tools, and platforms.

How They Work Together

In most web-focused design systems, design tokens transform into CSS variables as their primary output. The design token serves as the source definition, while the CSS variable becomes the runtime implementation.

A token definition in JSON:

{
  "color": {
    "primary": {
      "value": "#3B82F6",
      "type": "color"
    }
  }
}

Transforms into a CSS variable:

:root {
  --color-primary: #3B82F6;
}

This relationship means CSS variables are one manifestation of design tokens, not an alternative to them. The token system provides the source of truth and transformation pipeline, while CSS variables provide the runtime mechanism for web applications.

Organizations building only for web might question whether the token abstraction layer adds value. The answer depends on complexity. Single-theme, single-brand web applications might manage CSS variables directly. Multi-theme, multi-brand, or cross-platform systems benefit from the abstraction that design tokens provide.

Key Considerations

• CSS variables are implementation; design tokens are specification
• Design tokens enable multi-platform output from a single source
• CSS variables provide runtime dynamism that static tokens lack
• Token transformations can target CSS variables as one output format
• CSS variables support cascading and scoping that tokens must account for
• Both approaches can coexist, with tokens generating the variables
• Documentation should clarify the relationship for team members
• Build processes add complexity but enable platform flexibility

Common Questions

When should CSS variables be used directly?

Direct CSS variable authoring suits simpler scenarios. Small projects, single-platform applications, or teams without multi-platform needs may find the token abstraction layer unnecessary.

CSS variables also excel for dynamic values that change at runtime based on user interaction or state. A token system generates static outputs at build time, so truly dynamic styling might supplement token-generated variables with additional runtime variables.

When direct CSS variable authoring leads to inconsistency, duplication across files, or difficulty tracking design decisions, the structure that design tokens provide becomes valuable. The transition point varies by team and project complexity.

Can CSS variables replace design tokens?

CSS variables can replace design tokens for web-only projects that lack complex theming or branding requirements. In this constrained context, CSS variables provide sufficient structure for consistent styling.

CSS variables cannot replace design tokens when the system must target multiple platforms. Native mobile applications cannot consume CSS variables. Design tools cannot directly import CSS files. The cross-platform transformation capability that design tokens provide has no CSS variable equivalent.

Even for web-only systems, design tokens provide additional structure that pure CSS variables lack: type information, documentation metadata, validation rules, and tool-supported naming conventions. These benefits may justify design tokens regardless of platform diversity.

How does theming differ between the two approaches?

CSS variable theming works by redefining variable values within different scopes. A dark theme might be applied via a class or attribute that changes variable definitions:

:root {
  --color-background: #ffffff;
}

[data-theme="dark"] {
  --color-background: #1a1a1a;
}

Design token theming works by defining different token sets for each theme, which transform into the appropriate CSS variable definitions. The token system might maintain separate files for light and dark themes that produce the scoped CSS above.

The end result can be identical, but the authoring experience differs. Token systems typically provide better tooling for managing theme variations, validating contrast, and ensuring completeness across themes. Direct CSS variable theming requires manual discipline to maintain these qualities.

Summary

Design tokens and CSS variables operate at different levels of abstraction that complement rather than compete. Design tokens provide platform-agnostic design specifications that transform into platform-specific outputs. CSS variables provide the web platform’s native mechanism for runtime styling values. In mature web design systems, tokens generate CSS variables, combining the source-of-truth benefits of tokens with the runtime capabilities of CSS custom properties.