What Is a Design Token?
A design token is a named value that stores one design decision, such as a color, spacing, font size, or border radius, in a single central place. Instead of hardcoding a hex color like #1A73E8 across dozens of files, designers and developers reference a token like color-primary. Because the value lives in one definition, changing it updates everywhere it is used. Tokens act as the shared vocabulary that keeps design tools and code in sync, making a brand consistent, themeable, and easier to maintain across a growing website or product.
- What it is
- A named variable that holds a single design decision like a color or spacing value
- Purpose
- One source of truth so design and code stay consistent
- Common types
- Color, typography, spacing, radius, shadow, breakpoint, and motion values (Material Design)
- Format
- Often stored as JSON and exported to CSS, iOS, and Android (W3C Design Tokens draft)
- Key benefit
- Change a value once and it updates everywhere, enabling instant theming
What a design token represents #
A design token captures a single design decision as a named value that can be reused anywhere. Rather than scattering a specific blue, a 16-pixel gap, or a particular font size throughout your files, you define each once and give it a meaningful name, then reference that name everywhere the value is needed. Tokens cover the small, repeated choices that make up a visual system: colors, spacing, type sizes, border radii, shadows, and breakpoints. Their power is centralization. Because color-primary or space-md is defined in one place, updating the brand blue or tightening spacing means editing a single definition rather than hunting through hundreds of files. Tokens are the connective tissue of a design system, giving designers and developers one shared language for the same decisions. We use them to keep a brand coherent from the first mockup through to production code, and they are foundational to the systematic work we do in /services/branding-design and /services/ui-ux-design.
Why hardcoding values causes problems #
Without tokens, design values get hardcoded, the same hex color or pixel size typed directly wherever it is needed. This works at first but decays fast. When the brand color changes, someone must find and update every occurrence, and inevitably a few are missed, leaving inconsistent shades across pages. Slight variations creep in, one button uses #1A73E8, another #1976D2, and the interface loses coherence. Spacing drifts as developers eyeball gaps instead of reusing standard steps. Over months, a site accumulates dozens of near-duplicate values with no single meaning, making redesigns painful and error-prone. Tokens prevent this by making the correct value the easy value to use: reference color-primary and you cannot get the shade wrong. This discipline is what keeps a site looking intentional as it grows, and it is a core reason we build design systems rather than styling pages ad hoc in /services/web-design, where consistency directly affects how professional a small business appears.
Types of design tokens #
Tokens come in families matching the decisions a design system needs to make. Color tokens define brand, text, background, border, and state colors. Typography tokens hold font families, sizes, weights, and line heights. Spacing tokens define a consistent scale, often steps like 4, 8, 16, 24 pixels, so gaps and padding stay rhythmic. Radius tokens set corner rounding, shadow tokens define elevation, and breakpoint tokens mark the screen widths where layouts shift. Motion tokens can even standardize animation durations and easing. Many systems layer tokens into tiers: primitive tokens like blue-500 hold raw values, while semantic tokens like color-action-primary describe purpose and reference the primitives. This separation lets you change what blue-500 is, or swap which primitive color-action-primary points to, without touching every component. Structuring tokens this way is part of the thoughtful groundwork we lay in /services/ui-ux-design, so the visual language scales cleanly as new pages and features are added.
From JSON to every platform #
A major strength of design tokens is that they can be stored in a neutral format, commonly JSON, and then transformed into whatever each platform needs. The W3C is standardizing a Design Tokens format so tools can share definitions reliably. From one JSON source, a build tool such as Style Dictionary can generate CSS custom properties for the web, resource files for Android, and Swift constants for iOS, ensuring every platform draws from identical values. Update the JSON, regenerate, and the change flows everywhere at once. This is invaluable for brands that live on a website and native apps simultaneously, because it eliminates the drift that happens when each platform maintains its own copy of the palette. Even for a web-only small business, the JSON-to-CSS pipeline keeps design tools and code aligned. We set up this kind of token pipeline when building maintainable front ends in /services/web-app-development, so a single brand decision propagates consistently rather than being re-entered by hand in several places.
{
"color": {
"primary": { "value": "#1A73E8" },
"text": { "value": "#1A1A1A" }
},
"space": {
"sm": { "value": "8px" },
"md": { "value": "16px" }
}
}How tokens enable theming and dark mode #
Because tokens centralize values and separate meaning from raw color, they make theming almost effortless. Dark mode is the classic example: define semantic tokens like color-background and color-text, then provide one set of values for the light theme and another for dark. Switching themes simply swaps which values the tokens resolve to, and the entire interface updates coherently, no per-component edits required. The same mechanism powers brand variations, high-contrast accessibility modes, or white-label products where one codebase serves multiple brands. Without tokens, supporting even a single dark mode means hunting through countless hardcoded colors, an error-prone slog. With semantic tokens, a theme is just a mapping. This flexibility is increasingly expected by users and, in the case of high-contrast modes, supports accessibility. We build token-based theming into projects so that adding a new theme later is a configuration task rather than a rewrite, complementing the consistent brand foundations established in /services/branding-design.
Tokens and consistency at scale #
As a website grows past a handful of pages, consistency becomes hard to maintain by willpower alone. Design tokens make consistency structural rather than aspirational. Every developer who reaches for space-md gets the same spacing; every use of color-primary is the same blue. New pages built by different people still look like they belong together, because they draw from the same named values. This matters enormously for a small business trying to look established and trustworthy: inconsistent spacing and clashing shades read as amateurish, while a coherent system reads as professional. Tokens also speed up work, developers stop guessing values and reference the system, and designers and developers stop arguing about pixels because the decisions are already made and named. This shared source of truth is why design systems built on tokens outlast the individuals who created them. It underpins the durable, scalable interfaces we aim for in /services/ui-ux-design and carry through into implementation.
Keeping design and code in sync #
One of the oldest problems in web work is design and code drifting apart: the mockup says one thing, the built site says another, and no one is sure which is right. Design tokens close that gap by giving both a single shared reference. Modern design tools like Figma support variables that map directly to code tokens, so a color named in the design file corresponds to the same token in the codebase. When the token changes, both the design source and the production site update from the same definition, keeping them honest. This shared vocabulary also smooths handoff: developers implement against named tokens rather than eyedropping colors from a screenshot, reducing mistakes and back-and-forth. For small businesses, the practical result is a site that actually matches what was designed and stays matching as it evolves. Establishing this design-to-code link is a deliberate part of how we run projects in /services/web-design, so the finished site is a faithful, maintainable expression of the intended brand.
Getting started with tokens #
Adopting tokens does not require an enterprise system. A small business can start by auditing the values already in use, colors, spacing, font sizes, then consolidating them into a tidy set of named tokens, resolving near-duplicates into single canonical values. Group them sensibly: a small color palette, a spacing scale, a type scale. Store them in one place, CSS custom properties are the simplest for a web-only site, or JSON if multiple platforms are involved, and reference tokens everywhere instead of raw values from then on. Add semantic names for purpose-driven decisions so theming stays easy later. The upfront tidy-up pays off immediately in easier updates and visible consistency. We often introduce tokens during a website redesign, when the visual language is being defined fresh anyway, so the new site is built on a maintainable foundation from day one. This groundwork is part of the systematic approach behind /services/branding-design and every interface we ship.
FAQ
What is a design token in simple terms?
It is a named value for a single design decision, like a color, spacing size, or font size, stored in one central place. Instead of typing a hex code everywhere, you reference a name like color-primary. Change the value once and it updates everywhere the token is used.
How are design tokens different from CSS variables?
They overlap but differ in scope. A design token is the design decision itself, often stored platform-neutrally in JSON and shared between design tools and multiple platforms. CSS variables are one way to implement tokens on the web. Tokens are the concept; CSS custom properties are a web delivery format for them.
Do small businesses need design tokens?
Even small sites benefit. Tokens keep colors and spacing consistent, make brand updates a one-line change, and enable dark mode easily. You do not need an enterprise system, just a tidy set of named values referenced everywhere, which makes a growing site look professional and far easier to maintain.
How do design tokens enable dark mode?
By separating meaning from raw values. You define semantic tokens like color-background and color-text, then provide light and dark values for each. Switching themes swaps which values the tokens resolve to, updating the whole interface at once without editing individual components, because everything references the tokens.
What format are design tokens stored in?
Often JSON, which is neutral and toolable, and the W3C is standardizing a Design Tokens format. From JSON, build tools generate CSS custom properties for web, plus resources for iOS and Android, so every platform shares identical values. Web-only projects may store tokens directly as CSS variables.
What are semantic versus primitive tokens?
Primitive tokens hold raw values, like blue-500 equals a specific hex code. Semantic tokens describe purpose, like color-action-primary, and reference a primitive. This layering lets you change what a color means or which primitive it points to without editing every component, keeping large systems flexible and easy to re-theme.
How Local Web Advisor checks this for you
Is your own website getting web design right?
Our free AI audit scans your site and tells you — in plain English — exactly what to fix for web design and seven other areas, with the business impact and the fix for each. No login needed to start.
Run my free website audit →Was this helpful?