If you've worked on a design system of any serious size, you've felt the pain. A designer updates the primary brand color in Figma, but the developer has to hunt through six different code repositories to find where that hex value is hardcoded. The marketing team launches a new campaign that needs a slightly different accent palette, and suddenly your pristine design system sprouts a dozen one-off custom components. Someone on the mobile team changes the border radius on buttons for iOS, but the web team never gets the memo, and six months later you're looking at two completely different-looking products wearing the same brand name.
This is the problem design tokens were built to solve. And honestly, it's one of those rare solutions that actually delivers on its promises — when done right.
I've spent the better part of the last few years building, breaking, and rebuilding design token systems across multiple products and teams. What I've learned is that the technical implementation is actually the easy part. The hard part — the part that separates token systems that teams love from token systems that everyone quietly ignores — is the naming, the structure, the governance, and the adoption strategy. This article is everything I wish someone had told me when I started.
Table of Contents
- What Are Design Tokens, Really?
- Why Design Tokens Matter More Than You Think
- The Anatomy of a Design Token
- Naming Conventions: The Single Most Important Decision You'll Make
- Token Tiers: Global, Alias, and Component Tokens
- Theming and Multi-Brand Support with Design Tokens
- Tooling and Automation: Keeping Design and Code in Sync
- Getting Your Team to Actually Use Design Tokens
- Common Mistakes and How to Avoid Them
- The Future of Design Tokens: W3C Standards and Beyond
- References
What Are Design Tokens, Really?
Let's start with the simplest possible definition: design tokens are the atomic units of visual design decision. They're the values that define your interface — colors, typography scales, spacing units, border radii, shadow depths, animation durations, and everything else that makes up the visual language of a product.
But that's the technical definition. The more honest definition is this: design tokens are a contract between designers and developers. They're the shared language that lets a designer say "use the primary interactive color here" without caring whether that color is #0066FF or a CSS custom property or a platform-specific UIColor, and they let a developer implement that instruction without having to open a design file to figure out what the designer meant.
The concept of design tokens was popularized by Salesforce's Lightning Design System around 2016, and it's been picked up by nearly every major design system since — Google's Material Design 3, Shopify's Polaris, Adobe's Spectrum, and hundreds of internal systems at companies you've never heard of.
At their core, design tokens are just key-value pairs. The key is a semantic name that describes what the token represents, and the value is the actual visual property. But the beauty of the system is that those keys stay consistent across every platform, environment, and tool, while the values can change based on context — themes, platforms, accessibility needs, or even user preferences.
Why Design Tokens Matter More Than You Think
I've talked to dozens of teams who say "we have a design system" and what they actually mean is "we have a Figma file with some components and a shared color palette." That's a start, but it's not a design system. It's a collection of assets. The difference between assets and a system is whether the decisions are centralized and propagated automatically.
Design tokens are what make that propagation possible. Here's why they matter:
Consistency at Scale
When your color palette exists as hardcoded hex values in a dozen different files, changes are unreliable. Someone updates the primary blue in the web app but forgets to update it in the iOS app, and suddenly your brand looks different on every platform. With tokens, you change the value in one place, and it ripples everywhere. I've seen teams reduce visual inconsistencies by over 80% in the first quarter after implementing a proper token system.
Platform Agnosticism
Your team probably ships to web, iOS, and Android at minimum. Each platform has its own way of expressing design values — CSS custom properties, Android XML resources, iOS asset catalogs. Design tokens abstract away those differences. You define the values once in a platform-agnostic format (JSON or YAML), and your build pipeline generates the platform-specific files automatically. This alone can save hours of manual translation work per week.
Theming Made Possible
Without tokens, supporting dark mode, high contrast mode, or multiple brand themes requires duplicating entire component libraries. With tokens, themes are just alternative value sets. The same component, referencing the same token names, can render in light mode, dark mode, or a third-party brand theme by swapping the value file. Material Design 3's color system is a masterclass in this — their entire theming engine is built on a carefully designed token hierarchy.
Designer-Developer Handoff
The single biggest source of friction I've observed on product teams is the handoff gap. The designer picks a color, the developer guesses which color that is, and both are wrong 30% of the time. When both design tools and code reference the same token names, that ambiguity disappears. The designer says "use token color-primary-500" and the developer does exactly that. No guessing, no back-and-forth, no "I thought it was the darker blue."
Accessibility Enforcement
Tokens can carry more than just aesthetic values. You can bake accessibility constraints into your token system. For example, your "text-primary" token on a light background can be defined to always pass WCAG AA contrast ratios against its paired background token. When the values are generated programmatically, you can enforce these constraints at the token level rather than hoping individual designers check contrast ratios on every component.
The Anatomy of a Design Token
Every design token has the same basic structure, but how you organize that structure makes all the difference. Let me break down the components.
The Name
The token name is the most important part. It's the interface between the designer's intent and the developer's implementation. A good token name tells you exactly what the token does, where it should be used, and how it relates to other tokens. A bad token name creates confusion that multiplies as your system grows.
Good token names are:
- Semantic — they describe the purpose, not the value. "color-primary-500" is better than "color-blue-500" because it tells you what to use it for, not what it looks like.
- Hierarchical — they follow a consistent structure that makes them easy to browse and group.
- Unique — no two tokens should have the same name, even if they have the same value.
- Predictable — given the pattern, anyone on the team should be able to guess the name of a token they haven't seen before.
The Value
The value is the actual design property. It can be a color (hex, RGB, HSL, or OKLCH), a dimension (px, rem, em, pt), a duration (ms), an easing curve, a shadow definition, a font stack, or a number. Modern token systems are increasingly using OKLCH for colors because it provides better perceptual uniformity than hex or sRGB — meaning a 10% lightness change looks like a 10% lightness change to the human eye.
The Type
Each token has a type that defines what kind of value it holds. The W3C Design Tokens Community Group has proposed a standardized set of token types that includes color, dimension, font family, font weight, duration, cubic bezier, number, shadow, gradient, stroke style, border, transition, and typography. Typing your tokens is important because it enables validation and transformation. You can't accidentally assign a color value to a spacing token, and your build pipeline can convert dimensions from pixels to rem automatically.
Metadata
Advanced token systems include metadata like descriptions, usage guidelines, deprecation warnings, and WCAG compliance annotations. This metadata doesn't affect the visual output, but it makes the token system more usable and maintainable. A token that says "color-action-primary-hover — WCAG AA 4.5:1 on color-surface-primary — Use for hover state of primary action buttons" is far more useful than a bare key-value pair.
Naming Conventions: The Single Most Important Decision You'll Make
I need to be direct about this. Your naming convention will either make the system a joy to use or a frustrating mess that everyone quietly ignores. The biggest debate in the token community is abstract vs. semantic naming. I have strong opinions here, so I'm going to lay them out clearly.
Abstract Naming (What It Is)
Abstract naming defines tokens based on their visual properties rather than their usage. For example: "color-blue-500" or "size-8". These tokens describe what the value is, not where it should be used.
Pros: These tokens are stable. A blue-500 will always be blue-500, even if brand guidelines change. They're also composable — you can create new combinations without creating new tokens.
Cons: They don't tell you how to use them. A new designer joining the team has no idea whether they should use blue-500 or blue-600 for button backgrounds. This leads to inconsistent usage that defeats the purpose of having a token system in the first place.
Semantic Naming (What It Does)
Semantic naming defines tokens based on their purpose. For example: "color-action-primary" or "spacing-inset-md". These tokens describe where the value should be used and what it should communicate.
Pros: They're self-documenting. Anyone on the team can look at "color-text-primary" and know exactly what to use it for. They prevent misuse because the name constrains the usage context.
Cons: They're less stable. When you rebrand, the values change, but the names stay the same. This is actually a feature, not a bug, but it takes some getting used to. They also require more tokens because you need one for every usage context.
My Recommendation: Use Both in a Tiered System
After building token systems across several orgs, I've settled on a two-tier approach that balances both worlds. You maintain a set of primitive tokens (abstract, value-based) and a set of semantic tokens (purpose-based) that reference the primitives.
The primitives are the raw materials. They don't change often and they're purely descriptive. "color-blue-600" is an abstract token. The semantic tokens are the decisions. They reference the primitives and describe usage. "color-action-primary-bg" references "color-blue-600" and says "use this for primary action backgrounds."
This tiered approach gives you the best of both worlds. The primitives provide stability and composability, while the semantic tokens provide guidance and prevent misuse. When you rebrand, you change the primitive values, and all the semantic tokens that reference them update automatically. When you need to add a new component, you can reference existing primitives or create new ones as needed.
Naming Pattern Examples
Here's the naming convention I've found most effective after years of iteration:
Primitive tokens: [category]-[modifier]-[scale]
- color-blue-500
- color-neutral-100
- size-4, size-8, size-12
- font-size-300, font-size-400
Semantic tokens: [category]-[context]-[property]-[state]
- color-action-primary-bg
- color-action-primary-hover
- color-text-secondary
- spacing-inset-lg
- border-radius-button
- font-size-body-large
The catch is that semantic token names end up long and specific. That's deliberate. A name like "color-surface-primary-default" is a lot harder to accidentally use as a text color than something shorter and more ambiguous. And preventing misuse is the whole point.
Token Tiers: Global, Alias, and Component Tokens
Beyond the primitive/semantic split, I think about tokens in three tiers. Each tier corresponds to a different stage in the design-to-development pipeline.
Global Tokens (The Foundation)
Global tokens are the raw primitives. They're the smallest, most atomic tokens in your system. They don't reference any other tokens, and they don't have any usage context. They're the building blocks that everything else references.
Examples: color-neutral-100, type-scale-03, spacing-200, shadow-l, ease-out-quad
These tokens should be few and intentional. Every global token you add increases the complexity of your system. I've seen systems with 500+ global tokens, and they're almost always systems where nobody was willing to say "no" to a new color. A healthy global token set is typically 50-100 tokens for a single-brand system.
Alias Tokens (The Bridge)
Alias tokens are semantic mappings from a global token to a specific usage context. They connect the "what" to the "where." They're the tokens that designers reach for most often, because they describe what they're trying to achieve.
Examples: color-action-primary-bg references color-blue-500, color-text-on-primary references color-neutral-100, spacing-stack-sm references spacing-200
Alias tokens are where your design system's personality lives. Two systems with the same global tokens can have completely different alias tokens because they make different design decisions. This is also where theming happens — themes are just different mappings from alias tokens to global tokens.
Component Tokens (The Implementation)
Component tokens are scoped to specific components. They're the most specific tokens in your system, and they shouldn't be reused outside their component context. They reference alias tokens or global tokens to define the complete visual appearance of a component.
Examples: button-primary-bg references color-action-primary-bg, card-border-radius references border-radius-card, input-border-color-default references color-border-input
Component tokens are controversial. Some teams argue they're too specific and create maintenance burden. I've found them valuable for two reasons: they make component implementations self-contained (you can change a button's appearance without affecting anything else), and they make it possible to generate component documentation automatically from the token definitions.
Theming and Multi-Brand Support with Design Tokens
One of the most powerful applications of design tokens is theming. If your product supports dark mode, multiple brand variants, or user-customizable interfaces, tokens are the infrastructure that makes it feasible rather than a maintenance nightmare.
How Theming Works with Tokens
The fundamental insight is that themes are just alternative value sets for your alias tokens. The token names stay the same, but the values change based on the active theme. The component code doesn't know or care which theme is active — it just references token names, and the token system resolves the values based on the current context.
For a light/dark mode toggle, you maintain two theme files. The light theme maps alias tokens to lighter values, and the dark theme maps the same alias tokens to darker values. The same component code renders correctly in both modes because it's not referencing specific colors — it's referencing token names that resolve differently per theme.
Handling Multiple Brands
Multi-brand systems are more complex but follow the same pattern. Each brand has its own set of global tokens (brand-specific colors, fonts, spacing preferences) and its own alias token mappings. The component tokens stay the same across brands because the components are the same — only the visual treatment changes.
This is where the tiered token structure really pays off. If Brand A and Brand B share the same component library but have different visual identities, you only need to maintain two sets of global and alias tokens. The component tokens are shared, and the component code is identical. I've seen this approach reduce the per-brand maintenance cost by 60-70% compared to maintaining separate design systems for each brand.
Practical Considerations for Theming
Here are a few things I've learned the hard way about theming with tokens:
- Don't create a theme for every minor variation. If most of your tokens are the same across themes, you're better off with a single theme and a few overridable variables. The overhead of maintaining multiple theme files scales with the number of differences, not the number of themes.
- Test all themes with every component. If a component looks broken in dark mode, the issue is usually a missing or incorrectly mapped token. Automated visual regression testing across themes catches these issues before they ship.
- Plan for media queries and user preferences. The prefers-color-scheme media query, contrast preferences, and reduced motion preferences should all be part of your theming strategy. Tokens make it possible to respect these preferences without duplicating component logic.
- Consider dynamic theming. Some products allow users to create custom themes or choose accent colors. This is possible with tokens if you design your system with enough flexibility, but it requires careful planning to prevent users from creating inaccessible or broken combinations.
Tooling and Automation: Keeping Design and Code in Sync
Design tokens are only useful if they're actually used consistently across design tools and code. That requires tooling. Let me walk through the current ecosystem and how to build a pipeline that works for your team.
Token Storage and Format
I recommend storing your tokens in JSON or YAML files in a dedicated repository. This is the single source of truth for your design decisions. The W3C Design Tokens Format is emerging as the standard, and I'd recommend adopting it even if your tools don't fully support it yet — the format is stable and well-designed, and tool support is growing rapidly.
Your token repository should be version-controlled and have a review process for changes. This might sound bureaucratic, but token changes affect every product that uses your design system. A pull request that changes "color-primary-500" from blue to green should be treated with the same seriousness as a change to a shared API.
Design Tool Integration
Right now, Figma is the dominant design tool, and several excellent plugins exist for managing design tokens within it. Token Studio is the most popular option — it lets you create, edit, and organize tokens directly in Figma, and it can sync tokens to and from JSON files. Penpot, the open-source alternative to Figma, made headlines in 2025 by becoming the first design tool to implement native design token support using the W3C standard, and more tools are following suit.
The key workflow is: tokens are defined in code (the JSON repository), synced into the design tool, used by designers to build components and screens, and any changes made in the design tool are synced back to the code repository. This bidirectional sync is the holy grail, and while it's not perfectly smooth yet, the tools are getting closer every quarter.
Code Generation
This is where the real automation magic happens. Your token repository feeds into a build pipeline that generates platform-specific output files. For web, this might be CSS custom properties. For iOS, it's Swift or Objective-C files. For Android, it's XML resource files. For design tools, it's a JSON file that plugins can consume.
A typical build pipeline looks like this:
- Developer commits a change to the tokens JSON file
- CI/CD pipeline picks up the change
- Style Dictionary or a similar tool processes the tokens and generates platform-specific output files
- Generated files are published as a package to the platform's package manager (npm, CocoaPods, etc.)
- Product teams update their dependency and get the new tokens automatically
Style Dictionary, created by Amazon, is the most mature tool for this. It reads tokens in a structured JSON format and outputs platform-specific files. You define the tokens once and configure how they should be transformed for each platform. It handles everything from simple value substitution to complex transformations (like converting pixel values to points for iOS or rem for web).
Versioning and Distribution
Tokens should be versioned and distributed like any other software dependency. Use semantic versioning: major version bumps for breaking changes (renamed or removed tokens), minor versions for new tokens, and patch versions for value changes that don't affect the API. This lets product teams control when they adopt token changes, which is crucial for larger organizations where simultaneous updates are impractical.
Getting Your Team to Actually Use Design Tokens
Here's the uncomfortable truth: you can build the most elegant token system imaginable, and if your team doesn't use it, it's worthless. Token adoption is a change management problem, not a technical one.
Start Small and Prove Value
Don't try to tokenize your entire design system in one go. Pick a small, focused area — buttons are a classic starting point — and tokenize it completely. Show the team how much easier it is to maintain that component when changes are made through tokens. Use the metrics: how much faster are changes to implement? How many inconsistencies were eliminated? With concrete evidence, you can build momentum for expanding the token system.
Make It Easier to Use Tokens Than Not To
This is the single most important principle of token adoption. If using tokens requires extra steps, extra thinking, or extra context-switching, people will find ways around it. The tooling should make token usage the path of least resistance.
For designers, this means tokens should be available as dropdowns in the properties panel, not as a separate panel they have to remember to open. For developers, tokens should be auto-completable in their IDE, with documentation a hover away. If you're asking people to memorize token names, you've already lost.
Document Everything, But Keep It Discoverable
Formal documentation is important, but it's not where people will look first. The most effective documentation is embedded in the tools people already use. Token names should be descriptive enough that they rarely need explanation. When they do need explanation, the metadata should be accessible directly in the design tool or IDE. Put the documentation where the work happens, not in a separate wiki that nobody reads.
Create a Governance Process
Every token system needs a decision-maker who can say "no" to new tokens. Without governance, the token count grows until it becomes unmanageable. I've seen systems where the number of tokens doubled every quarter because nobody was willing to reject requests for new colors, spacing values, or component variants.
Establish a clear process for proposing new tokens, including the justification, the expected usage, and the impact on the existing system. Not every visual variation needs its own token. Sometimes the right answer is "use the existing spacing tokens" or "that's a one-off for a specific campaign, not a pattern worth tokenizing."
Celebrate Wins Publicly
When a team uses tokens to ship a theme change in hours instead of weeks, make sure everyone knows about it. When a new designer joins and is productive on day one because the token system is intuitive, share that story. Social proof is a powerful adoption driver, and nothing convinces skeptics like seeing their peers succeed with the new system.
Common Mistakes and How to Avoid Them
I've made almost every mistake you can make with design tokens. Here are the ones I see most often, so you can avoid them.
Over-Engineering the Taxonomy
I once spent three weeks designing a token taxonomy that was so comprehensive it had six levels of hierarchy. It was beautiful. It was also completely unusable. Nobody could remember the token names, and the system was so rigid that it broke every time we needed to do something slightly different.
The fix: keep your taxonomy to three levels maximum. Category (color, spacing, typography), context (action, surface, text), and property (bg, text, border). If you need more than that, you're probably trying to encode too much information in the name.
Creating Tokens for Everything
Not every design value needs to be a token. If a value is used in exactly one place and never changes, it's probably fine to keep it as a local variable. Tokens are for shared decisions, not every hex value in your codebase. I've seen teams with tokens for the shadow on a specific card component that's used in one view. That's not a pattern — it's noise.
The rule of thumb: if a value is used in two or more places or is likely to change as part of a theme, it should be a token. If it's a one-off that's tightly coupled to a specific component, keep it local.
Ignoring the Developer Experience
Design tokens are inherently a designer-developer collaboration tool, but I've seen teams design their token systems almost entirely from a designer's perspective. The result is a system that's beautiful in Figma but painful to use in code. Long, snake_case token names that are hard to type. Token values that don't map cleanly to CSS properties. A token documentation site that's only accessible to designers.
The fix: include developers in the token design process from day one. Test token names in actual code before locking them in. Generate platform-specific documentation. Make sure the tokens are as easy to use in an IDE as they are in Figma.
Skipping the Migration Plan
You can't introduce tokens overnight. If you have existing products with hardcoded values, the migration to tokens needs to be gradual and carefully planned. I've seen teams try to do a "big bang" token migration that breaks every product simultaneously and takes months to recover from.
The fix: introduce tokens alongside existing values, not as a replacement. New components use tokens by default. Old components are migrated incrementally, one team at a time. Deprecate old patterns gradually, with clear communication about timelines and migration paths.
Not Planning for Token Deprecation
Tokens will become obsolete. Color palettes change, design trends evolve, and usage patterns shift. If you don't have a deprecation policy, your token system accumulates dead tokens that confuse everyone. A dead token is worse than no token — it actively misleads people who don't know it's deprecated.
The fix: every token should have a lifecycle. New tokens are experimental. They graduate to stable after validation. They're deprecated with a 90-day window for migration. Then they're removed. This lifecycle should be transparent in your tooling — deprecated tokens should be visually marked in Figma and generate warnings in code.
The Future of Design Tokens: W3C Standards and Beyond
The design token ecosystem is maturing rapidly, and the most important development is the W3C Design Tokens Community Group's work on an open standard. Let me share what I think this means for the industry.
The W3C Design Tokens Format
The Design Tokens Community Group, formed under the W3C umbrella, has been developing a standardized format for design tokens. The goal is to create a specification that allows tools, platforms, and design systems to exchange tokens predictably. Penpot's implementation of native design tokens marked a significant milestone — it was the first design tool to adopt the W3C standard natively, without needing plugins.
This standardization is huge for the ecosystem. It means that as more tools adopt the format, tokens will become truly portable. You'll be able to move your token system between design tools, generate code for any platform, and integrate with any design system documentation tool, all using the same format. The current fragmentation — where every tool has its own token format and sync mechanism — is a temporary phase.
AI-Generated Token Systems
I'm starting to see early experiments with using AI to generate token systems from design files. The idea is that you can feed a design file into an AI model, and it extracts the patterns — the consistent color usage, the spacing rhythm, the typographic scale — and outputs a token system that captures those patterns. The results aren't perfect yet, but they're getting better. I expect within a year or two, AI will be a standard part of the token system creation workflow, handling the tedious extraction work and letting designers focus on the creative decisions.
Token-Based Responsive Design
One of the more interesting emerging patterns is using tokens to drive responsive design. Instead of breakpoints defined in CSS, you define token sets for different viewport sizes. The same component, referencing the same token names, renders differently on mobile, tablet, and desktop because the token values change based on the viewport. This is still experimental, but it points toward a future where responsiveness is baked into the token system rather than handled separately in layout code.
Tokens as a Product
Several companies are building token management platforms that treat tokens as a product rather than a byproduct of the design system. These platforms offer token editing, versioning, governance workflows, and integration with design tools and code repositories. I expect this to become a standard offering in the design tooling market, similar to how component libraries evolved from internal assets to managed SaaS products.
References
- Integrating Design And Code With Native Design Tokens In Penpot — Smashing Magazine
- Automating Design Systems: Tips And Resources For Getting Started — Smashing Magazine
- Naming Best Practices for Design Tokens — Smashing Magazine
- Design Tokens: The Complete Guide — UXPin Studio
- W3C Design Tokens Community Group
- Token Studio — Figma Plugin for Design Tokens
- Laws of UX — Cognitive Psychology for Design
- Supernova — Design System Documentation Platform
- Nielsen Norman Group — Design Pattern Guidelines
- Figma — UI Design Principles Resource Library
- Google Material Design 3
- Shopify Polaris Design System
- Adobe Spectrum Design System
- Style Dictionary — Amazon's Token Transformation Tool
- Design Tokens Reference — Structure and Formatting Guide
This article was brought to you by Timothy Graf | GrafWeb — UX/UI design theory and practice for product designers, design leaders, and digital product teams. Published by Timothy Graf. GrafWeb CUSO specializes in credit union web solutions at grafwebcuso.com.