

If you've spent any time in a design system, you've probably heard the term design token. But between the jargon, the tooling debates, and the varying definitions floating around the internet, it can be hard to get a straight answer to a simple question: what actually is a design token?
This article gives you that answer: in plain language, with a concrete example, and no prior knowledge assumed. By the end, you'll understand what tokens are, the problem they solve, and whether they're worth caring about for your team.
A design token is a named value that stores a design decision.
That's it. At its core, a token is just a key-value pair (a name and a value). Something like:
color-action-primary: #3B82F6
The name (color-action-primary) describes the role that value plays in your design. The value (#3B82F6) is what gets rendered. The name and value together form the token.
Tokens are typically stored in a platform-agnostic format, usually JSON, which means a single definition can be transformed into CSS custom properties, iOS Swift constants, Android XML, or any other format your platforms need.
What makes tokens different from just having a list of colors in a spreadsheet is that they're connected to your product. When a token changes, everything that references it updates automatically. That connection is the whole point.
Before tokens, design values lived in two places: the design tool and the codebase. Neither talked to the other.
A designer would pick a blue (say, #3B82F6) and document it in a style guide. A developer would hardcode #3B82F6 into a button component. Another developer might hardcode it into a link, a tab, a badge. Six months later, the brand team decides the blue should be slightly deeper: #2563EB. Now someone has to find every instance of #3B82F6 across the entire codebase and update them one by one. Some get missed. The product ships with two different blues. Nobody notices for weeks.
This is the hardcoded value problem. It affects every spacing value, every font size, every border radius, every shadow. Each one is a potential inconsistency waiting to happen.
Tokens replace hardcoded values with a single source of truth. Instead of hardcoding #3B82F6 everywhere, components reference a token: color-action-primary. The token holds the value. When the value changes, it changes in one place, and every component that references it updates automatically.
This shift, from scattered hardcoded values to a centrally managed token system, is the foundational idea behind design tokens.
Here's how that works in practice, walking through a single color value from design decision to rendered component.
Step 1: The raw value
You've decided your primary action color is #3B82F6. On its own, this is just a hex value: no meaning, no context, no name.
Step 2: The global token
You give the raw value a name that describes what it is:
blue-500: #3B82F6
This is a global token (sometimes called a primitive token). It's descriptive but carries no implied usage: blue-500 just means "this shade of blue." You might have blue-100 through blue-900 in your palette.
Step 3: The alias token
You create a second token that references the first, and gives the value a role:
color-action-primary: blue-500
This is an alias token (sometimes called a semantic token). color-action-primary doesn't hold a hex value directly; it points to blue-500, which holds the hex value. Now you have a token with meaning: this is the color for primary actions.
Step 4: The component
Your button component references the alias token:
css
.button-primary {
background-color: var(--color-action-primary);
}
The button doesn't know or care what hex value color-action-primary resolves to. It just uses the token. When the brand blue changes from blue-500 to blue-600, you update one token value and every primary button in your product updates with it.
This is a simplified version of how token systems work in practice. There's more nuance in hierarchy and naming (Article 02 covers that in depth), but the core pattern holds at any scale.
CSS custom properties (also called CSS variables) are a browser feature that lets you define reusable values in CSS:
css
:root {
--color-blue: #3B82F6;
}
.button {
background-color: var(--color-blue);
}
Design tokens and CSS custom properties look similar and solve overlapping problems, but they're not the same thing.
CSS custom properties live only in CSS. They're scoped to the web and have no native concept of semantic meaning, platform transformation, or governance. They're a delivery mechanism (a very useful one), but a design token is the decision that sits upstream of the delivery.
A token starts as a platform-agnostic definition (typically JSON). It can be compiled into a CSS custom property for the web, a Swift constant for iOS, an XML value for Android, or a JavaScript object for a React component library. One token, many outputs.
The relationship is: tokens describe the decision; CSS custom properties (or their platform equivalents) deliver it.
If your entire product runs on the web and you only need to share values within CSS, custom properties alone might be enough. The moment you need values to stay consistent across platforms, tools, or teams, or when you need governance, versioning, or documentation, tokens are the right layer.
Article 10 goes deeper on this distinction if you want the full comparison.
Almost any design decision that repeats across your product is a candidate for a token. In practice, the most common categories are:
color: The most intuitive starting point. Palette values, semantic roles (surface, text, border, action), state colors (hover, active, disabled).
Spacing: Padding, margin, gap. Usually defined as a scale (4, 8, 12, 16, 24, 32...) with semantic aliases for common uses (space-component-padding, space-layout-gap).
Typography: Font families, font sizes, line heights, font weights, letter spacing. These are often grouped as composite tokens (a "body" token that bundles size, weight, and line height together).
Border radius: Corner rounding values, from sharp to fully rounded. Small-scale products often get by with two or three values; large systems sometimes need a full scale.
Shadows: Elevation and depth. Box shadow values (offset, blur, spread, color) are often composite tokens representing elevation levels rather than raw shadow properties.
Motion: Duration, easing, and delay values for animations and transitions. Motion tokens are less common in early-stage systems but become important as products grow more sophisticated.
You don't need to tokenize everything at once. Most teams start with color and spacing, get comfortable with the pattern, and expand from there. The goal isn't comprehensive coverage on day one. Build the habit of reaching for a token instead of hardcoding a value.
The benefits of tokens aren't always obvious when you're maintaining a single product with a small team. They become unmistakable when you're managing multiple platforms, brands, or teams.
Consistency: When every platform and every team consumes the same token definitions, visual consistency is structural, not coincidental. There's no version where iOS has a slightly different blue because someone eyeballed it.
Maintainability: Change the value of a token and everything that references it updates. Rebrands, accessibility fixes, seasonal updates: work that once took weeks of find-and-replace across multiple codebases becomes a targeted, low-risk change.
Designer-developer handoff: Tokens create a shared vocabulary. When a designer specifies color-surface-primary and a developer implements color-surface-primary, there's no translation layer. The name is the contract. This reduces the "what color is this exactly?" back-and-forth that slows handoff.
Theming and brand switching: Once your components reference semantic tokens rather than raw values, switching themes (light to dark, Brand A to Brand B) is a matter of swapping which values the tokens resolve to, not rewriting components.
Governance: Tokens give you an auditable, versionable record of design decisions. You can deprecate old tokens, introduce new ones, and track what changed and when, treating your design language with the same rigour as your codebase.
This is the first article in a complete guide to design tokens, written for designers, developers, and the teams that work between them. Here's what each section covers and who it's for.
Section 1 — Foundations (you are here) The conceptual layer: what tokens are, how they're structured, and what the DTCG specification defines. Start here if tokens are new to you or if you want to build a shared vocabulary with your team.
Section 2 — Architecture & naming How to design a token system that scales: the right number of tiers, what to tokenize and what to leave hardcoded, and how to name tokens consistently. For designers and developers building or refining a system.
Section 3 — Multi-brand, theming & dark mode Token architecture for teams managing more than one brand, theme, or product. Covers theming systems, dark mode implementation, and the structural decisions that make them possible. For intermediate teams with multiple visual outputs.
Section 4 — Advanced topics The engineering side of tokens: the full pipeline from design tool to codebase, code implementation across platforms, CSS custom properties, and governance at scale. Primarily for developers and design systems leads.
Section 5 — Design tokens in Figma How to implement, name, and manage tokens using Figma variables, including modes, collections, and exporting to code. For designers working in Figma and developers who collaborate with them.
Section 6 — Doing it in zeroheight How to document, sync, and govern your token system using zeroheight, from initial setup to managing multiple brands and automating token changelogs. For teams using or evaluating zeroheight as part of their token workflow.
The best place to go next depends on where you are. If you're brand new to tokens, Article 02 — How design tokens work: types, structure and hierarchy is the natural next step, taking the concepts introduced here and showing you exactly how a three-tier token system is built.
If you're already familiar with the basics and want to start building, head to Section 2 for the architecture decisions, or Section 5 if you're working in Figma and want to see how variables map to tokens in practice.
