Adobe Logo

Spectrum

Design tokens

Design tokens are design decisions, translated into data. They act as a “source of truth” to help ensure that product experiences feel unified and cohesive.

Table of contents#

What are design tokens?#

About design tokens#

Design tokens — or tokens, for short — are design decisions, translated into data. They’re ultimately a communication tool: a shared language between design and engineering for communicating detailed information about how to build user interfaces.

Tokens consist of values needed to construct and maintain a design system, such as spacing, color, typography, object styles, animation, and more. They can represent anything that has a design definition, like a color as a RGB value, an opacity as a number, or an animation ease as Bezier coordinates. We use tokens instead of hard-coded values so Spectrum can scale and support the complex ways that Adobe products need to intersect as a cohesive ecosystem.

Diagram illustrating hex value #0265DC token inheritance through blue-900, accent-color-900, and accent-background-color-default into both an accent button component background color and emphasized action button component background color.

Spectrum’s design token system#

Our design token system prioritizes predictability and flexibility. The overall methodology is to have a focused set of tokens rather than all possible tokens for all possible scenarios. However, it's important to note that tokens only provide some — if not most — of the information needed to represent or implement a UI component. The token system is one resource in Spectrum’s offerings rather than a complete knowledge set, and it’s used alongside design and engineering documentation.

Design tokens are directly integrated into our component libraries, UI kits, and other resources. They cover the various options of platform scales, color themes, component states, and much more. We also offer a variety of token types for teams to use directly within their products if they're not using a Spectrum implementation.

Design token types and terminology#

Terminology is key to understanding Spectrum’s design tokens and the concepts behind the token system. There are foundational terms that describe how to use tokens, and how they relate to each other.

Diagram illustrating various design token terms and their relationships to each other. A token named drop-zone-background-color is a component-specific token. This has an alias token named accent-visual-color. That has another alias token named accent-color-800. That is connected to blue-800, which is a global token. And that is equal to a value, hex color #147AF3.

Token (or, design token)#

A design decision, represented as data. Each token has a carefully chosen name that communicates its intention and scope, and follows a set naming convention.

Value#

The data associated with the token name. This could either be another token (called an alias) or a final value (for example: RGBA colors, pixels, percentages).

Token nameValue
picker-border-widthborder-width-100
alert-dialog-minimum-width288 px

Alias#

A token that references another token, instead of referencing a hard-coded value.

Token nameValue (alias)
negative-border-color-defaultnegative-color-900

Component-specific token#

A token used for a particular component.

Token nameValue (alias)
tooltip-maximum-width160 px (desktop)
200 px (mobile)
divider-thickness-small1 px

Global token#

A token used across the design system. This is the opposite of a component-specific token.

Token nameValue (alias)
corner-radius-752 px
component-height-10032 px (desktop)
40 px (mobile)

Examples of design tokens#

Size tokens#

Many of Spectrum’s components use size tokens that follow a t-shirt sizing categorization convention (small, medium, large, extra-large). These are designed to offer a limited number of size options that follow a linear scale: for example, on desktop, each size increases or decreases by 8 px. Since they’re used together to create hierarchy, it’s important to have a limited amount of sizes that work well in combination.

Specific components that need a wider range of sizing options use size tokens that follow a non-linear scale, where each increasing size is a multiple of the previous one. These are only for components that are frequently used inside of other components across a wide range of use cases — like avatars or thumbnails — and therefore require a more flexible range of sizes. They’re named with numerals because they’re not tied to specific t-shirt sizes.

We use detailed specs as part of our token definition process. Here’s some examples of the specs for size tokens for the text field and avatar components:

Example of token specs showing size tokens. Global t-shirt size tokens for the text field component are component-height-75 for small, component-height-100 for medium, component-height-200 for large, and component-height-300 for extra-large. Component-specific size tokens for the avatar component are avatar-size-50, avatar-size-70, avatar-size-100, avatar-size-200, avatar-size-300, avatar-size-400, avatar-size-500, avatar-size-600, and avatar-size-700.Example of token specs showing size tokens. Global t-shirt size tokens for the text field component are component-height-75 for small, component-height-100 for medium, component-height-200 for large, and component-height-300 for extra-large. Component-specific size tokens for the avatar component are avatar-size-50, avatar-size-70, avatar-size-100, avatar-size-200, avatar-size-300, avatar-size-400, avatar-size-500, avatar-size-600, and avatar-size-700.

Color tokens#

Spectrum has both global and alias color tokens. A global color token is written as a specific value that’s part of the color system. An alias color token is written as a particular usage.

Example of token specs for color tokens. Global color token gray-100 is hex values #F8F8F8 for lightest theme, #323232 for dark theme, #1D1D1D for darkest theme, and #F4F6FC for wireframe theme.Example of token specs for color tokens. Global color token gray-100 is hex values #F8F8F8 for lightest theme, #323232 for dark theme, #1D1D1D for darkest theme, and #F4F6FC for wireframe theme.

Layout tokens#

Spectrum’s layout tokens cover all fundamentals, including object styles and spacing.

Example of token specs showing various layout tokens for the text field component. Rounding is token corner-radius-100. Border is token border-width-100. Spacing tokens are component-edge-to-text-75 for size small, component-edge-to-text-100 for size medium, component-edge-to-text-200 for size large, and component-edge-to-text-300 for size extra large.Example of token specs showing various layout tokens for the text field component. Rounding is token corner-radius-100. Border is token border-width-100. Spacing tokens are component-edge-to-text-75 for size small, component-edge-to-text-100 for size medium, component-edge-to-text-200 for size large, and component-edge-to-text-300 for size extra large.

How Spectrum names design tokens#

Spectrum names design tokens very intentionally and strategically. This naming practice is part of the token system’s larger goals: to create a focused set of tokens, and to help more people understand and work with tokens in product design and development.

Naming principles#

  • Human-readable. Our tokens are communication tools that humans need to be able to readily understand. They use language and terminology already existing within Spectrum, and values are written as descriptively as possible. We do this to support our diverse array of product stakeholders — not just designers and engineers — who have varying levels of familiarity with and comfort using design tokens.

  • Flat structure. We use a flat structure — not a nested or tree structure — so that we aren’t prioritizing a particular coding construct. This is also so that token names can have a narrative, conversational feel.

  • Predictable and flexible. We follow a token naming structure that maps to a natural language convention and uses a set vocabulary. This allows us to communicate complex information in a way that’s predictable but can accommodate new updates and changes in the design system.

Naming structure#

We use a 3-part structure for coming up with token names: context, common unit, and clarification. It’s based on a common model for human language and narrative-building where the information communicated becomes increasingly granular. Token names start with broad context, then go into more specific detail.

Chart showing the 3-part structure for how Spectrum names design tokens. The first part is the context, which is the most broad idea in what needs to be communicated in the name. Examples of this are a component, a system constant like a border or a background, or a color. The second part is the common unit, which is the most consistent idea. Examples of this are sizing, spacing, styling, or text. The third part is clarification, which is the most specific or detailed idea. Examples of this are a t-shirt size, and index or value, or a user-initiated state.Chart showing the 3-part structure for how Spectrum names design tokens. The first part is the context, which is the most broad idea in what needs to be communicated in the name. Examples of this are a component, a system constant like a border or a background, or a color. The second part is the common unit, which is the most consistent idea. Examples of this are sizing, spacing, styling, or text. The third part is clarification, which is the most specific or detailed idea. Examples of this are a t-shirt size, and index or value, or a user-initiated state.

Naming structure examples#

Not all token names need to have context, common unit, and clarification together — but they all follow the same order. You can think of the most specific piece of information in the hierarchy as equated to the property to set. Here’s some examples:

gray-100: gray is a color. gray-100 is a more specific color, which points to a specific value in the Spectrum color system.

Color token name gray-100 broken down into its context (gray) and clarification (100 value).

checkbox-control-size-small: A checkbox is a component, and the most high-level or broad concept. A control is a common (consistent) unit; there are many different kinds of controls in the system.

control-size is also a common unit because there is more than one component that includes a control, with a predetermined number of sizes. small is a particular size from a set of available sizes (t-shirt sizes), so it’s the most detailed information being communicated in the token name.

Color token name checkbox-control-size-small broken down into its context (checkbox), common units (control, and control-size), and clarification (small).

action-button-edge-to-hold-icon-large: An action-button is a component. The component layout (in this example, phrased descriptively as the edge of the action button to the hold icon) is a spacing construct, and is a common unit. large is a particular size from a set of available sizes (t-shirt sizes), and is the most detailed piece of information for this token.

Color token name action-button-edge-to-hold-icon-large broken down into its context (action-button), common unit (edge-to-hold-icon) and clarification (large).

Usage guidelines#

Using global tokens#

Only use global tokens when there are no available aliases for your use case. Global tokens are easy to reference and are the building blocks of Spectrum, but they’re also the least tied to the logic of our design language.

Key example showing correct usage of a global token. Token accent-background-color-default used for the background color of an accent button component.
Key example showing incorrect usage of a global token. Token blue-900 used for the background color of an accent button component.

Use aliases wherever they can apply#

Alias tokens are the recommended type to use when building your product with design tokens. They’re a shared language for understanding Spectrum, and they help to associate meaning, context, and intent to the design tokens you’re applying to your product.

Using aliases is a good way to ensure that your product can evolve alongside Spectrum as the design system evolves, and to minimize future maintenance for your product.

Key example showing correct usage of alias tokens. Tokens corner-radius-100 and disabled-border-color applied to a generic container.
Key example showing incorrect usage of alias tokens. 4 px and gray-300 applied to a generic container.

Use component-specific tokens for their respective component#

When building Spectrum verified components, use component-specific tokens. This ensures that as a component’s design evolves, you won’t have to retrace any higher-level design decisions that informed the updates.

It’s not recommended to use component-specific tokens interchangeably with other components, unless one is derivative of the other.

Key example showing correct usage of a component-specific token. Token progress-bar-thickness-small applied to a progress bar component.
Key example showing incorrect usage of a component-specific token. Token slider-track-thickness applied to a progress bar component.

Using Spectrum tokens#

Spectrum tokens inform many other Spectrum resources. Adobe product teams don’t use the output of them directly, but instead use common UI frameworks, which includes the implementation of tokens into components.

For more information, go to the README for the Spectrum tokens GitHub to find more detailed documentation about tokens, component schemas, the output JSON data model, and more. There’s also guides for getting started as well as guidelines on authoring and contribution.