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.


What are design tokens?#
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#
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
picker-border-width
border-width-100
alert-dialog-minimum-width
Alias#
A token that references another token, instead of referencing a hard-coded value.
negative-border-color-default
negative-color-900
Component-specific token#
A token used for a particular component.
tooltip-maximum-width
200 px (mobile)
divider-thickness-small
Global token#
A token used across the design system. This is the opposite of a
corner-radius-75
component-height-100
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


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


Layout tokens#
Spectrum’s layout tokens cover all fundamentals, including


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.


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:
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.




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.




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.




Using Spectrum tokens#
For more information, go to the