Have you ever used a website or app where buttons looked different across pages, font sizes were inconsistent, or spacing felt “off?” If so, you’ve seen a lack of design tokens in action.
Now, imagine a big company like Google, Airbnb, or Apple. They have dozens of products across different platforms, with various teams working on them. How do they ensure every button, color, and font size looks the same across all devices — without chaos?
They use design tokens, a secret weapon that ensures a design system is consistent, scalable, and easy to update. Let’s see how you can implement them in real-world projects, along with best practices & how they work.
Table of Contents
- What Is a Design Token?
- The Origins of Design Tokens
- Why Use Design Tokens?
- Classes of Design Tokens
- Types of Design Tokens
- How to Define a Design Token Structure
- Best Practices for Naming Design Tokens
- Best Tools for Managing Design Tokens
- Best Practices for Using Design Tokens
- Design Tokens: The Bottom Line
- Design Tokens: FAQ
What Is a Design Token?
A design token is a reusable, platform-agnostic variable that stores UI properties such as colors, typography, spacing, animations, and assets. Instead of manually defining styles for each platform (web, iOS, or Android), design tokens let developers use a single source of truth, ensuring consistency across different environments.
One of the biggest challenges in cross-platform design is that different operating systems use varying formats for the same style properties. Take a brand’s primary CTA color, for example. The same yellow shade can be represented in multiple ways:
- Hex Code (Web): #FCC821
- RGB (CSS): rgb (252, 200, 33)
- RGBA (CSS with transparency): rgba (252, 200, 33, 1)
- Octal (Android/Flutter): 77144041
Rather than hardcoding each version separately, teams can define a unified token — like brand.cta.primary — which stores all variations of the color. Developers simply reference this token, and it automatically applies the correct format for each platform.
The result? A single update to the token reflects everywhere, eliminating inconsistencies and reducing manual effort.
The Origins of Design Tokens
The concept of design tokens was first introduced at Salesforce by Jina Anne, a former designer at the company who has since become a prominent advocate for design systems.
Faced with the challenge of maintaining brand consistency across Salesforce’s vast ecosystem, Jina and her team developed a structured approach to breaking down UI elements into small, reusable units, which became known as design tokens.
These tokens encapsulated both the visual properties (colors, typography, spacing, etc.) and the corresponding code values, allowing different teams across Salesforce to maintain consistency without manually redefining styles. By centralizing these design decisions, they created a single source of truth, so every product and platform adhered to the same design standards.
Since then, design tokens have evolved into a core principle of modern design systems, widely adopted by major companies looking to streamline collaboration between designers and developers. That, while keeping UI/UX scalable and adaptable across platforms!
Why Use Design Tokens?
1. Consistency across products & platforms
When companies have multiple products — a website, an iOS app, an Android app, and a web app — it’s hard to establish a consistent design language across all platforms. Design tokens solve this by ensuring every platform uses the same set of predefined styles.
2. Faster design & development workflows
With tokens, designers, and developers don’t need to adjust styles manually whenever there’s a brand update. Instead, they update the design token, and all instances automatically reflect the changes.
3. Easier theming & customization
Design tokens enable light/dark modes, accessibility adjustments, and brand-specific customizations with ease. Instead of modifying each style manually, designers can switch themes by swapping a set of tokens.
4. Multi-platform scalability
Design tokens can be exported into multiple formats: CSS variables, SCSS, JSON, iOS (Swift), Android (XML). This allows a single source of truth to be shared across different development environments.
5. Better collaboration between designers & developers
By defining styles as structured data, designers and developers speak a common language, reducing misunderstandings and increasing efficiency.
6. Improved accessibility and inclusive design
Accessibility isn’t a one-time task; it’s an ongoing process of adjusting contrast, spacing, and font sizes to meet standards like WCAG. With tokens, accessibility updates become automatic and consistent. Even better, tokens support dynamic adjustments. Users can enable high-contrast mode, larger fonts, or dark mode — and the UI adapts instantly.
Classes of Design Tokens
Design tokens are typically categorized into three main classes, each serving a unique role in structuring and applying design decisions. This hierarchical approach enables teams to update UI elements globally, adapt to different themes, or fine-tune specific components without disrupting the entire system.
1. Reference tokens: The core building blocks
What They Are:
Reference tokens define all available style options in a design system. These include foundational elements like colors, font sizes, spacing, and other raw values that do not change based on context.
How They Work:
- They store static values such as hex codes for colors, pixel sizes for typography, or numerical values for spacing
- They serve as the base layer for all other tokens, ensuring consistency across the design system
- Some reference tokens may point to other reference tokens, but they never change dynamically based on context (e.g., dark/light mode)
Naming Convention:
All reference tokens begin with the prefix ref.
Use Case:
These are the base values used throughout the design system. If a new brand color is introduced, it can be updated here without affecting component-specific decisions.
2. System tokens: Design decisions and theming
What They Are:
System tokens define how reference tokens are applied within a specific theme or design context. These tokens create the visual character of the UI, determining roles like primary buttons, background colors, and typography hierarchy.
How They Work:
- System tokens map reference tokens to design roles (e.g., sys.color.primary might point to ref.color.blue-500)
- They enable theming by dynamically switching between different reference tokens based on context (e.g., dark mode vs. light mode)
- Rather than using hardcoded values, system tokens refer to reference tokens to maintain flexibility
Naming Convention:
All system tokens begin with the prefix sys.
Use Case:
If a design system has light and dark themes, sys.color.background might reference ref.color.white in light mode, but ref.color.black in dark mode.
3. Component tokens: Styling UI elements
What They Are:
Component tokens define the design properties of UI elements like buttons, cards, and models. They control specific attributes such as padding, border radius, elevation, and states (hover, active, disabled, etc.).
How They Work:
- They inherit values from system or reference tokens, avoiding hardcoded values
- They ensure that updates to a system token cascade down to all components that use it
- If a design decision affects multiple components, a component token should be used instead of manually defining styles in separate files
Naming Convention:
All component tokens begin with the prefix comp.
Use Case:
If the primary brand color changes, updating sys.color.primary automatically updates every button’s background without requiring manual edits in multiple places.
How these token classes work together
The hierarchy of reference, system, and component tokens ensures a structured and scalable design system.
- Reference Tokens define raw values (ref.color.blue-500 → #007bff)
- System Tokens assign meaning (sys.color.primary → ref.color.blue-500)
- Component Tokens apply styles (comp.button.background → sys.color.primary)
By structuring tokens this way, design updates become global, manageable, and error-free.
Types of Design Tokens
Design tokens cover various style properties, allowing organizations to maintain consistency, streamline updates, and scale designs across platforms.
These tokens replace hardcoded values, ensuring UI elements remain visually cohesive, whether on a website, mobile app, or desktop application.
Here are the primary types of design tokens:
1. Color Tokens
Define the color scheme of a design system, including primary and secondary brand colors, text colors, backgrounds, and borders.
Examples:
{
"color-primary": "#007bff",
"color-background": "#f8f9fa",
"color-text-dark": "#212529"
}
2. Typography Tokens
Store font-related properties such as typefaces, font sizes, line heights, and spacing to ensure consistent text styling.
Examples:
{
"font-family-base": "'Inter', sans-serif",
"font-size-heading": "24px",
"line-height-body": "1.5"
}
3. Spacing Tokens
Manage layout spacing, including paddings, margins, and gaps between UI components, promoting a predictable visual rhythm.
Examples:
{
"spacing-small": "4px",
"spacing-medium": "8px",
"spacing-large": "16px"
}
4. Sizing Tokens
Standardize element dimensions such as component widths, button heights, and avatar sizes for a cohesive design system.
Examples:
{
"size-button-height": "48px",
"size-avatar-small": "32px",
"size-container-max": "1200px"
}
5. Border Tokens
Define border properties, such as width, style, and radius, ensuring uniformity across UI elements.
Examples:
{
"border-width-thin": "1px",
"border-radius-medium": "8px",
"border-style-default": "solid"
}
6. Shadow Tokens
Control shadow effects, including color, blur, and spread, to create depth and hierarchy in UI elements.
Examples:
{
"shadow-small": "0 1px 2px rgba(0, 0, 0, 0.1)",
"shadow-medium": "0 2px 4px rgba(0, 0, 0, 0.15)",
"shadow-large": "0 4px 8px rgba(0, 0, 0, 0.2)"
}
7. Opacity Tokens
Define transparency levels for elements, helping to manage overlays, backgrounds, and hover effects.
Examples:
{
"opacity-low": "0.3",
"opacity-medium": "0.6",
"opacity-high": "0.9"
}
8. Breakpoint Tokens
Set the responsive breakpoints that dictate how layouts adjust to different screen sizes.
Examples:
{
"breakpoint-mobile": "480px",
"breakpoint-tablet": "768px",
"breakpoint-desktop": "1024px"
}
9. Duration Tokens
Manage the timing of animations and transitions to create smooth, consistent motion effects across the UI.
Examples:
{
"duration-fast": "150ms",
"duration-default": "300ms",
"duration-slow": "600ms"
}
10. Easing Tokens
Define the acceleration and deceleration of animations, influencing how elements move and interact.
Examples:
{
"easing-default": "cubic-bezier(0.4, 0, 0.2, 1)",
"easing-smooth": "cubic-bezier(0.25, 0.1, 0.25, 1)",
"easing-bounce": "cubic-bezier(0.68, -0.55, 0.27, 1.55)"
}
How to Define a Design Token Structure
There’s no single "correct" way to structure design tokens, but consistency and clarity are key. A well-structured token system makes it easier for teams to scale, maintain, and implement design decisions across platforms.
Many organizations follow a hierarchical approach, similar to Amazon’s Style Dictionary, which organizes tokens into logical layers for better readability and usability.
A structured design token typically follows this format:
- Category: Broad property group (e.g., color, spacing, typography, shadow)
- Type: Defines the specific property (e.g., background, text, border)
- Item: Specifies the element it applies to (e.g., button, card, modal)
- Sub-Item (Optional): Further clarifies variations (e.g., primary, secondary, hover state)
- State (Optional): Defines interaction states (e.g., active, disabled, hover)
Example: If defining a primary button’s background color, the token might be named: color-background-button-primary-active
Or, in a more compact format: color-bg-btn-primary-active
This structure ensures that tokens remain organized, predictable, and scalable across different platforms and teams.
Best Practices for Naming Design Tokens
A well-defined naming convention makes design tokens easy to understand, maintain, and expand as a system evolves. Here are some key principles for creating clear and effective token names:
1. Be descriptive but concise
Token names should convey their purpose without being overly long. Avoid vague or generic names.
Use: color-primary
Avoid: main-blue-color (too specific and redundant)
2. Follow a consistent naming pattern
Establish a structured format that applies to all tokens, making them predictable and easy to find.
Suggested Pattern: [category]-[property]-[modifier]
Examples:
- color-text-primary
- spacing-small
- font-heading-large
3. Avoid ambiguity
A token should clearly define what it represents, reducing room for misinterpretation.
Use: button-background-color (clarifies that it applies to the background)
Avoid: button-color (unclear if it refers to text, background, or border)
4. Focus on function, not values
Avoid including specific values in token names, which limits flexibility when updating styles.
Use: spacing-medium
Avoid: spacing-16px (if spacing changes from 16px to 20px, the token name becomes misleading)
5. Align with brand and company terminology
Ensure token names match the language used internally to maintain clarity across teams.
Example: If your brand uses "compact" and "spacious" instead of "small" and "large," follow that convention:
- spacing-compact
- button-size-spacious
6. Provide context when necessary
If a token could be applied to multiple elements, specify its intended use.
Use: card-background-color (clearly for card components)
Avoid: background-color (too generic)
7. Limit abbreviations for clarity
Shortening names can help, but excessive abbreviations can make tokens harder to understand.
Use: bg for background → bg-color-primary (widely recognized)
Avoid: clr-txt for color text (unnecessarily cryptic)
8. Document your naming conventions
A documented token system ensures that everyone follows the same naming rules.
Example Documentation Rule:
"All color tokens should follow the pattern color-[modifier], where [modifier] defines the use case (e.g., primary, secondary, error). Example: color-primary, color-error."
9. Plan for growth and scalability
Choose a structure that allows for future expansion without requiring massive renaming.
Use: button-size-small, button-size-large
Avoid: button-small (less flexible if more size variants are added later)
Best Tools for Managing Design Tokens
1. Style Dictionary: The universal translator for design tokens
Converts design tokens into multiple formats (CSS, SCSS, JSON, Swift, XML, etc.), making them usable across web, mobile, and desktop applications.
Why It’s Useful:
Centralizes token management and updates all instances automatically. Supports custom transformations, allowing teams to generate platform-specific formats. Reduces manual errors and inconsistencies by automating token conversion.
Best For: Large teams managing tokens across multiple platforms who need automatic conversions and scalability.
2. Figma Tokens Plugin: Bridging the gap between design and code
Allows designers to create, edit, and manage design tokens directly in Figma, then export them for developers.
Why It’s Useful:
Ensures that designers and developers use the same source of truth. Supports dynamic theming (e.g., dark mode, accessibility adjustments). Allows teams to store and sync tokens in JSON format, making it easy to integrate with code.
Best For: UI/UX designers who want a visual way to manage tokens and ensure seamless collaboration with developers.
3. Supernova: A full-featured token management system
Supernova is a comprehensive design token management platform that syncs tokens across design and development teams.
Why It’s Useful:
Converts tokens into multiple formats automatically. Provides a dashboard for managing and documenting design tokens. Integrates with Figma, Style Dictionary, and GitHub, making updates seamless.
Best For: Teams who need a centralized token repository with documentation, version control, and automated token distribution.
4. Adobe Spectrum: A token-based design system
Spectrum is Adobe’s official design system that uses tokens to ensure consistency across all its products.
Why It’s Useful:
Standardizes UI elements across Photoshop, Illustrator, and other Adobe applications. Uses a token-based system to support light and dark modes and accessibility features. Includes tokens for colors, typography, motion, and layout, making UI updates fast and scalable.
Best For: Companies building large-scale design systems with Adobe products.
Best Practices for Using Design Tokens
A well-structured design token system ensures that your UI/UX remains consistent, scalable, and easy to maintain. Here are some of the best practices to follow:
1. Use clear and consistent naming conventions
Why It Matters: A clear naming system makes tokens easier to read, organize, and scale.
- Use: color-primary (simple, clear, and scalable)
- Avoid: blue-500 (hard to interpret and maintain)
Pro Tip: Be descriptive but concise — tokens should communicate intent, not specific values.
2. Organize tokens by category
Why It Matters: Grouping tokens into logical categories makes them easier to find and manage. Here are some common categories:
- Colors: color-primary, color-background, color-text-dark
- Typography: font-size-body, font-weight-bold, line-height-heading
- Spacing: spacing-small, spacing-medium, spacing-large
- Shadows: shadow-light, shadow-medium, shadow-heavy
Pro Tip: Use a hierarchy that aligns with your design system structure.
3. Automate token updates to avoid manual errors
Why It Matters: Manually updating design tokens across different platforms can lead to inconsistencies and outdated styles. The best practices for automation include:
- Using Style Dictionary to convert tokens into different formats automatically
- Integrating tokens with GitHub so updates are tracked and versioned
- Syncing tokens with Figma, Storybook, and code repositories to ensure teams always use the latest values.
Pro Tip: Automate updates using GitHub Actions or CI/CD pipelines to push changes without manual intervention.
4. Store tokens in a centralized repository
Why It Matters: Keeping design tokens in one location ensures that all teams are pulling from the same source of truth.
What you can do:
- Store tokens in JSON or YAML format for easy integration
- Use a shared GitHub or GitLab repository to maintain version control
- Link tokens to Figma, Storybook, or documentation sites so they’re accessible to all teams.
Pro Tip: If your organization uses multiple frameworks, ensure your token system supports all of them (React, Vue, iOS, Android, etc.).
Design Tokens: The Bottom Line
Design tokens are the invisible workhorses of modern design systems: small, structured bits of logic that eliminate chaos and bring order to every pixel on the screen. They cut through inefficiency, ensuring every button, color, and typeface is precisely where it should be — on every platform, in every iteration, without second-guessing.
Think of them as compounding interest in design. A small investment in structured tokens today saves countless hours of manual updates, redesigns, and inconsistencies. They don’t just make workflows smoother; they make scaling effortless. The result? A design system that’s bulletproof, consistent, and built for the long game.
Design Tokens: FAQ
1. What is a design token?
A design token is a reusable design value (e.g., colors, typography, spacing) stored in a structured format like JSON for consistent UI application.
2. How do design tokens differ from CSS variables?
While CSS variables work only in web environments, design tokens are platform-agnostic and can be used across web, mobile, and other digital platforms.
3. What tools can I use to manage design tokens?
Popular tools include Style Dictionary, Figma Tokens Plugin, Supernova, and Adobe Spectrum for token management.
4. How do design tokens improve collaboration?
By providing a single source of truth, design tokens help designers and developers stay aligned, reducing inconsistencies and improving workflow efficiency.
-preview.jpg)
