What Are Design Tokens?

The design system revolution of the last decade has brought with it all sorts of tools and strategies to enhance product development workflows.

Design tokens are one of those tools many design systems, including Google’s Material Design 3 and MUI, have adopted to make UI elements easier to implement, manage, and update.

Announcement: UXPin’s design tokens for colors are in beta! Sign up to get notified when they will be officially released: Design tokens in UXPin.

Optimize your design operations across the entire organizations. Use UXPin Merge, a revolutionary design technology for helping teams use React components in design and development. Learn more about Merge.

Reach a new level of prototyping

Design with interactive components coming from your team’s design system.

Discover UXPin Merge

What is a Design Token?

Design tokens contain UI data like colors, fonts, spacing, animations, assets, etc. for styling and building cross-platform user interfaces. Instead of hard-coding static values for every operating system, a design token contains multiple formats, allowing front-end developers to use the same variable, whether they’re building an iOS or Android, and even web application.

One of the challenges with cross-platform product development is that operating systems use different style properties and formats. For example, UXPin’s website uses yellow for CTAs. The hex code for this yellow is #FCC821, which you can represent in several ways:

• RGB (CSS): rgb(252, 200, 33)
• RGBA: rgba(252, 200, 33, 1)
• Octal (Android/Flutter): 77144041

Instead of using these static properties, designers and engineers reference a token like “uxpin.cta.primary,” representing all four color codes. The color will always be the same regardless of the platform or programming language.

Design tokens within CSS

To implement design tokens in CSS, they are often converted into CSS variables (also known as custom properties). CSS variables allow you to define reusable values that can be applied throughout your stylesheet, making it easier to maintain and update styles consistently.

Example of Design Tokens as CSS Variables

/* Define Design Tokens as CSS Variables */
:root {
  --color-primary: #007bff;
  --color-secondary: #6c757d;
  --font-size-base: 16px;
  --font-family-base: 'Arial, sans-serif';
  --spacing-small: 8px;
  --spacing-medium: 16px;
}

/* Applying Design Tokens in CSS */
body {
  font-size: var(--font-size-base);
  font-family: var(--font-family-base);
  color: var(--color-primary);
  padding: var(--spacing-medium);
}

button {
  background-color: var(--color-primary);
  color: var(--color-secondary);
  padding: var(--spacing-small) var(--spacing-medium);
}

Here’s a section you can add to your blog post about Design Tokens within CSS:

Design Tokens within CSS

Design tokens are a crucial part of modern design systems, helping to maintain consistency and scalability across digital products. When used within CSS, design tokens ensure that your styles are cohesive and easy to manage, allowing for a more efficient and streamlined development process.

What are Design Tokens?

Design tokens are the smallest, repeatable elements of a design system that store visual properties such as colors, typography, spacing, and shadows. They act as a bridge between design and code, providing a single source of truth that can be used across various platforms and technologies.

Using Design Tokens in CSS

To implement design tokens in CSS, they are often converted into CSS variables (also known as custom properties). CSS variables allow you to define reusable values that can be applied throughout your stylesheet, making it easier to maintain and update styles consistently.

Example of Design Tokens as CSS Variables

/* Define Design Tokens as CSS Variables */
:root {
  --color-primary: #007bff;
  --color-secondary: #6c757d;
  --font-size-base: 16px;
  --font-family-base: 'Arial, sans-serif';
  --spacing-small: 8px;
  --spacing-medium: 16px;
}

/* Applying Design Tokens in CSS */
body {
  font-size: var(--font-size-base);
  font-family: var(--font-family-base);
  color: var(--color-primary);
  padding: var(--spacing-medium);
}

button {
  background-color: var(--color-primary);
  color: var(--color-secondary);
  padding: var(--spacing-small) var(--spacing-medium);
}

In this example, design tokens for colors, typography, and spacing are defined as CSS variables. These tokens are then applied throughout the CSS to style elements consistently. If you need to update a style, such as changing the primary color, you only need to update the variable definition, and the change will automatically apply everywhere the token is used.

Types of Design Tokens

Organizations use these design tokens for many style properties, including color palette, size, spacing, assets, and drop shadows, to name a few. When we’re at it – here are the primary types of design tokens:

1. Color Tokens: Define the color palette used in a design system. Examples include primary colors, secondary colors, background colors, text colors, border colors, etc.
   • Examples:
     • color-primary: #007bff
     • color-background: #f8f9fa
2. Typography Tokens: Specify text-related properties. These include font families, font sizes, line heights, letter spacing, and font weights.
   • Examples:
     • font-family-body: 'Roboto', sans-serif
     • font-size-heading: 24px
3. Spacing Tokens: Govern the spacing system, including margins, paddings, and gaps. They ensure consistent spacing throughout the design.
   • Examples:
     • spacing-small: 4px
     • spacing-large: 16px
4. Sizing Tokens: Define sizes for components and elements. These can include widths, heights, and maximum and minimum sizes.
   • Examples:
     • size-button-height: 48px
     • size-avatar-small: 32px
5. Border Tokens: Specify border properties, such as width, style, and radius.
   • Examples:
     • border-width-thin: 1px
     • border-radius-medium: 8px
6. Shadow Tokens: Describe the shadow effects used in the design system, including color, offset, blur, and spread.
   • Examples:
     • shadow-small: 0 1px 2px rgba(0, 0, 0, 0.1)
     • shadow-large: 0 4px 8px rgba(0, 0, 0, 0.2)
7. Opacity Tokens: Define the opacity levels for elements.
   • Examples:
     • opacity-low: 0.3
     • opacity-high: 0.9
8. Breakpoints Tokens: Specify the breakpoints for responsive design, dictating how the design adapts to different screen sizes.
   • Examples:
     • breakpoint-mobile: 480px
     • breakpoint-desktop: 1024px
9. Duration Tokens: Govern the timing of animations and transitions.
   • Examples:
     • duration-short: 200ms
     • duration-long: 600ms
10. Easing Tokens: Define the easing functions for animations and transitions.
    • Examples:
      • easing-in-out: cubic-bezier(0.4, 0, 0.2, 1)
      • easing-bounce: cubic-bezier(0.68, -0.55, 0.27, 1.55)

Where did Design Tokens Come from?

It is said that design tokens were pioneered by Salesforce. In a 2014 article published in Salesforce Designer, Salesforce UX VP Sönke Rohde described how the company uses design tokens to apply the same design principles across multiple platforms and software.

“At Salesforce, we face this very challenge, and we came up with an agnostic solution: we define our design in a single location and use a system to cascade it down to all platforms. We call it our Single Source of Truth. It’s basically a set of JSON files which contain name-value pairs describing our design tokens.” excerpt from Living Design System by Sönke Rohde.

Instead of using static style properties, engineers reference the design token, which pulls the correct value, depending on the platform, from a JSON file. To automate this process, Salesforce developed Theo–“an abstraction for transforming and formatting design tokens.”

What is the Difference between Atomic Design and Tokens?

Atomic design and design tokens are both concepts used in design systems, but they address different aspects of design consistency and scalability.

Atomic design is a methodology for creating design systems developed by Brad Frost. It breaks down user interfaces into smaller, reusable components called atoms, molecules, organisms, templates, and pages (in ascending order of complexity). Atoms are the basic building blocks like buttons, input fields, icons, etc. Molecules are combinations of atoms, organisms are combinations of molecules, and so on.

Design tokens are a set of variables that define design properties such as colors, typography, spacing, etc., in a design system. They are abstract representations of visual design decisions. Rather than hardcoding specific values (like a hex code for a color) directly into UI components, design tokens provide a centralized way to manage and update design properties across an entire design system.

Design tokens deal with the abstraction and management of design properties. They abstract design decisions into variables, allowing for easier maintenance, scalability, and consistency. They provide a single source of truth for design-related values.

3 Design Tokens Examples

Here are three examples of design tokens for typography. These tokens help ensure that typography styles are consistent across different components and platforms.

Design Token Example #1: Font Family

{
  "font-family": {
    "base": "Roboto, Arial, sans-serif",
    "heading": "Montserrat, Arial, sans-serif",
    "monospace": "'Courier New', Courier, monospace"
  }
}

Design Token Example #2: Font Size

{
  "font-size": {
    "base": "16px",
    "small": "14px",
    "large": "24px",
    "heading": {
      "h1": "32px",
      "h2": "28px",
      "h3": "24px"
    }
  }
}

Design Token Example #3: Line Hight

{
  "line-height": {
    "base": "1.5",
    "tight": "1.25",
    "loose": "1.75",
    "heading": {
      "h1": "1.2",
      "h2": "1.3",
      "h3": "1.4"
    }
  }
}

Are Design Tokens Right for You?

Google’s Material Design 3 documentation offers a list of scenarios where design tokens are most helpful:

• You use a design system for more than one platform or product
• You want an easy way to maintain and update your product’s styles
• You plan to update your product design or build new products and features

Material Design also lists two instances where design tokens might be “less helpful:”

• You don’t plan to change your product in the next few years
• Your product does not have a design system

Benefits of Using Design Tokens

We’ve identified three key benefits to using design tokens.

1. Having a Single Source of Truth

Design tokens are most beneficial for creating a single source of truth–which is what drove Salesforce to start using them. Everyone must speak the same design language when multiple product teams, engineers, and UX designers work on the same product.

Design tokens allow teams to speak the same language, no matter their role, platform, programming language, or responsibilities.

2. Maintaining UI Consistency

UI consistency is a significant challenge when designing at scale. It’s not uncommon for designers to accidentally use slightly different sizing, brand colors, and spacing for a single product! These inconsistencies cause usability issues, increasing engineering and UX debt with every release.

Design tokens eliminate these inconsistencies so that every designer uses the same styles and properties–another single source of truth benefit!

3. Getting Flexibility to Scale

Design tokens give products and design systems flexibility to make changes and scale. If teams need to add platform-specific properties, they simply update the design token.

For example, Android uses octal color codes instead of HEX or RGB. To adapt a design system to accommodate Android, the DS team can add octal codes to each design token to maintain a single source of truth.

These tokens allow engineers to deliver new projects significantly faster with fewer errors or inconsistencies.

This flexibility is also helpful when making changes. For example, if a product changes its typeface from Montserrat to Roboto, the team only has to update the typography token to implement a product-wide change.

How to define a design token structure

While there are no rules for defining your design token structure, this example from Amazon’s Style Dictionary makes the most sense. Many organizations use a similar format for their design tokens.

Amazon’s Style Dictionary uses a hierarchical design token structure:

1. Category (color, time, line-height, size, asset, content, etc.)
2. Type
3. Item
4. Sub-Item
5. State

If we wanted to create a design token for a primary active button using this structure, it might look like color_background_button_primary_active or perhaps shortened color-bg-btn-primary-active. This token will contain every type of color code necessary for cross-platform implementation.

The key to a design token structure is consistency. It must use a predictable naming convention so users can easily find tokens and scale the system.

Architecting Tokens with Options and Decisions

UX expert and founder of eightshapes, Nathan Curtis, wrote an excellent article on architecting tokens. Nathan says the first step is to segment your design tokens into Options (or choices) and Decisions.

• Options: Creates the base token values. Tokens define what Style Dictionary describes above as categories–color, time, asset, content, etc.

• Decisions: Decisions use your Options to create properties for components. For example, interactive color, background color, text color, etc.

The benefit of this system is that if you want to change your white to a different shade, replacing the HEX code under the color Option will automatically sync to every design token and associated UI element. 

Nathan’s methodology also makes it easy to scale because you simply use your Options to create more Decisions. You can read Nathan’s full article for detailed instructions on architecting tokens.

Tips on Design Token Naming Conventions

Naming conventions are a crucial aspect of any design system, ensuring clarity, consistency, and ease of use across design and development teams. A well-thought-out naming convention helps communicate the purpose and function of design tokens, components, and styles, making it easier for team members to understand and use the system effectively. Here are some tips for creating effective naming conventions for your design system:

1. Be Descriptive and Concise

Names should clearly describe the element’s purpose or function without being overly verbose. Aim for a balance between specificity and brevity to ensure names are easy to read and understand.

Example:

• Use color-primary instead of main-blue-color.

2. Use Consistent Patterns

Establish a consistent naming pattern or structure that applies across all elements in your design system. This uniformity helps users quickly recognize the type of element they are working with and understand its role in the system.

Example:

• Use a pattern like [category]-[modifier], such as color-primary, spacing-small, or font-heading-large.

3. Avoid Ambiguity

Names should be clear and unambiguous, avoiding terms that could be interpreted in multiple ways. This helps prevent confusion and ensures that everyone on the team understands what each token or component represents.

Example:

• Instead of button-color, use button-background-color to clarify that the token refers to the button’s background color, not its text or border.

4. Reflect the Design Intent

Names should reflect the design intent rather than specific values. This approach allows for more flexibility and scalability, as the underlying values can change without requiring renaming.

Example:

• Use spacing-medium instead of spacing-16px. This way, if you decide to change the medium spacing from 16px to 20px, you don’t have to rename the token.

5. Align with Your Brand and Language

Ensure that your naming conventions align with your brand’s voice and the terminology used within your organization. This alignment creates a cohesive experience for both the design and development teams and ensures consistency in communication.

Example:

• If your brand uses specific terminology for sizes (e.g., compact, regular, spacious), incorporate these terms into your token names, like spacing-compact or button-size-regular.

6. Include Context When Necessary

When tokens or components could be used in multiple contexts, include contextual information in the name to clarify their use. This is particularly important for tokens that might have different values or meanings depending on the context.

Example:

• Use card-background-color instead of just background-color to specify that the token is for card components.

7. Use Common Abbreviations Sparingly

While abbreviations can save space, overusing them can make your names cryptic and harder to understand. Use common abbreviations where they add clarity and avoid using less common or internal jargon that might confuse new team members.

Example:

• bg for background is a common abbreviation and widely understood, so bg-color-primary is acceptable. However, avoid using abbreviations like clr for color.

8. Document Naming Conventions

Document your naming conventions and provide examples in your design system documentation. This helps ensure that everyone on your team understands the rules and follows them consistently.

Example Documentation Excerpt:

• “All color tokens should follow the pattern color-[modifier], where [modifier] describes the usage (e.g., primary, secondary, error). Example: color-primary, color-error.”

9. Plan for Scalability

As your design system evolves, new components and tokens will be added. Choose naming conventions that can easily accommodate growth and changes without requiring extensive renaming or restructuring.

Example:

• Instead of naming a token button-small, which might be limiting, use button-size-small to leave room for adding other size-related tokens, like button-size-large.

How Design Tokens Work in Practice

In an informative article, Design Tokens for Dummies, Louis Chenais outlines a typical design change workflow with vs. without design tokens.

The Traditional Workflow–Without Design Tokens

1. Designer updates a style in a design tool
2. Designer documents the changes for the design handoff
3. Engineer updates the component’s properties (CSS, LESS, SASS, etc.)
4. The design team confirms the changes during quality assurance (QA)

There are several problems with this workflow:

• It creates more work and attention to detail during the design handoff.
• It’s prone to errors and miscommunication.
• Creates more tickets, thus increasing technical debt.
• It costs unnecessary time and money making the changes and fixing any corresponding errors.

The Design Token Way

1. Designer updates a syle in a design tool.
2. A design tokens generator updates a centralized repository creating platform-specific files (JSON/YAML).
3. Engineers pull the new repo, add any new tokens, and automatically update the project’s styles.

Using design tokens reduces documentation for design handoffs and saves programming time for engineers. This automated system significantly reduces human error, streamlining the development and QA process.

A Single Source of Truth With UXPin Merge

As digital products get more complex, designers and engineers must find solutions to integrate workflows–a problem UXPin has solved with our revolutionary Merge technology.

Merge allows you to import a component library from a repository to UXPin’s design editor so designers can use the same UI elements engineers use to develop the final product.

Merge components have the same fidelity and functionality as those in the repository. The design system team can use React props (or Args for our Storybook integration) to restrict changes or provide designers with the flexibility to make design decisions.

Whenever engineers make changes to the repository, they automatically sync to UXPin, notifying designers of the update. Merge comes with version control, allowing designers to switch to an earlier version–helpful for updating older projects.

Take your product development to new heights and create a single source of truth with UXPin Merge. Visit our Merge page for more information and details to request access.