

If you've looked at how design tokens are implemented on the web, you've probably noticed that they often end up as CSS custom properties: the --color-action-primary: #3B82F6 declarations you see in :root. And if you've noticed that, you've probably wondered: are design tokens just CSS variables by another name?
They're not. But the confusion is understandable, because CSS custom properties are where design tokens live in a web browser, not what design tokens are. The distinction matters, and this article makes it clear.
CSS custom properties are a native browser feature that lets you define reusable values in CSS and reference them throughout your stylesheets:
css
:root {
--color-blue: #3B82F6;
--space-4: 4px;
}
.button {
background-color: var(--color-blue);
padding: var(--space-4) calc(var(--space-4) * 2);
}
They're powerful for several reasons. They inherit through the DOM, which means changing a value at the root level updates every element that references it. They can be overridden at any scope: a [data-theme="dark"] attribute on the root element can redefine a property for the whole page, while a scoped override applies only within a specific container. And they're dynamic: they can be read and written via JavaScript at runtime, making them the natural mechanism for theme switching.
For web interfaces, CSS custom properties are an excellent tool for managing design values consistently. So what's missing?
CSS custom properties are, by definition, CSS. That's both their strength and their limitation.
They only exist on the web. A React Native app, an iOS codebase, an Android project, a Flutter UI: none of these can consume CSS custom properties. If your product spans multiple platforms, you need a way to express the same design decisions in formats those platforms understand: Swift constants, Kotlin resource files, Compose theme values, JavaScript objects. CSS custom properties can't do that.
They have no semantic layer by default. A CSS custom property is just a named value. There's nothing in the format itself that distinguishes a raw palette color (--blue-500) from a semantic role (--color-action-primary) from a component-level decision (--button-background). You can create that structure yourself (and you should) but the format doesn't enforce or support it.
They have no tooling integration. CSS custom properties don't know what they're for. You can't ask your codebase which components use --color-action-primary, automatically generate documentation from CSS variable declarations, or plug your color values into Figma. The values exist in CSS and nowhere else.
They have no governance. Adding a CSS custom property is a two-second operation with no review, no documentation trail, and no way to know whether a similar property already exists. At scale, this produces sprawl: redundant variables, inconsistent naming, and values that drift out of sync with the design.
None of these are criticisms of CSS custom properties; they're not trying to solve those problems. But design systems at any meaningful scale need to solve them.
Design tokens are a layer of abstraction that sits above any specific output format. A token is a named design decision stored in a format-agnostic source (typically JSON, often conforming to the DTCG specification) that can be transformed into whatever format a given platform needs.
That abstraction adds four things that CSS custom properties don't provide:
Platform-agnosticism. The same token source can be compiled into CSS custom properties for the web, Swift constants for iOS, resource values for Android, and JavaScript objects for React Native. One source of truth, multiple platform outputs. When a color changes, you update it once and rebuild, and every platform gets the update.
A structured semantic layer. Token systems are typically organized into tiers: global tokens (raw values), alias tokens (semantic roles), and component tokens (specific decisions). This hierarchy is encoded in the token source, not left to naming conventions in a CSS file. The structure is explicit and enforceable.
Tooling integration. Token formats like DTCG JSON are machine-readable in a way that CSS is not. Tools like Style Dictionary, Theo, and Token Transformer can read a token source and do things with it: generate documentation, validate naming conventions, produce platform outputs, sync values with design tools. Figma Variables can map directly to a token source, keeping design and code in sync without manual handoffs.
Governance. Because tokens live in a structured, version-controlled source file, changes go through a review process. You can see what changed, who changed it, and why. You can document the intent of a token alongside its value. You can set up validation to catch naming violations or missing platform values before they ship.
Design tokens and CSS custom properties aren't in competition. They work together. In a typical web implementation, the pipeline looks like this:
Token source (JSON)
"color-action-primary": {
"$value": "#3B82F6",
"$type": "color"
}
↓ transformed by Style Dictionary
CSS output
--color-action-primary: #3B82F6;
↓ referenced in component CSS
.button-primary {
background-color: var(--color-action-primary);
}
The CSS custom property is the delivery mechanism for the browser. The token is the source of truth that everything else derives from, including, on other platforms, Swift constants, Android resource values, and everything else.
This is why modifying design values directly in the CSS output is the wrong approach. The CSS is generated, not authored. Changes made there will be overwritten the next time the token pipeline runs. The source of truth is the token file; the CSS is an artifact.
CSS custom properties deliver design tokens to the browser. Design tokens define your design decisions in a platform-agnostic, tooling-integrated, governable way, with CSS custom properties as one of many possible outputs.
If you're building a single-platform web product and you need something lightweight right now, you can start with well-structured CSS custom properties and retrofit a token layer later. The naming conventions are compatible and the migration path is manageable. But if you're working across platforms, integrating with a design tool, or building something you expect to maintain for years, start with tokens. The CSS custom properties follow automatically.
The question "tokens or CSS variables?" is ultimately the wrong framing. The right question is: where do your design decisions live, and can your whole stack consume them?
Article 11 — The design token pipeline: from design tool to codebase goes deep on the build pipeline that takes a token source and produces platform-specific outputs — how transformation works, how to configure Style Dictionary for multiple platforms, and how to extend it for custom output formats.
For how CSS custom properties fit into a full theming implementation — including scope, inheritance, and theme switching — Article 08 — Theming with design tokens covers those patterns in full.
