Design tokens

Design tokens are design decisions, represented as data, that ensure systematically unified and cohesive product experiences.

Introduction#


What are design tokens?#

Design tokens are all the values needed to construct and maintain a design system — spacing, color, typography, object styles, animation, etc. — represented as data. These can represent anything defined by design: a color as a RGB value, an opacity as a number, an animation ease as Bezier coordinates. They’re used in place of hard-coded values in order to ensure flexibility and unity across all product experiences.

Design tokens are directly integrated into our component libraries and UI kits. They cover the various options of platform scales, color themes, component states, and more.

image illustrating hex value #2680EB, token inheritance through blue 400, cta background color, and button cta background color into cta button component

Design token types#


The following types of design tokens are the building blocks and design decisions that make up the Spectrum design language:

Global tokens#

Global tokens are the primitive values in our design language, represented by context-agnostic names. Our color palette, animation, typography, and dimension values are all recorded as global tokens. These can be directly used, and are inherited by all other token types.

image illustrating hex value #2680EB represented as global token blue 400

Alias tokens#

Alias tokens relate to a specific context or abstraction. Aliases help communicate the intended purpose of a token, and are effective when a value with a single intent will appear in multiple places.

Image illustrating hex value #2680EB, blue 400, represented as alias cta background color.

Component-specific tokens#

Component-specific tokens are an exhaustive representation of every value associated with a component. They often inherit from alias tokens, but are named in a way that allows engineering teams to be as specific as possible in applying tokens in component development.

Image illustrating hex value #2680EB, blue 400, cta background color represented as component token button cta background-color.

Global tokens#


Size tokens#

Global size tokens are used for specifying dimensions and spacing for every Spectrum component. Since Spectrum supports two platform scales, token values automatically adjust between scales, allowing for a single token to be used for each.

Size tokens are anchored around a base value. Each token’s number represents a percentage relative to the base value. For example, size-100 is 100% of the base value, size-400 is 400%, and so on.

Labelled illustration of 8 pixels for desktop and 10 pixels for mobile each with arrows pointing to the same box with text "size-100"
Token nameDesktop scaleMobile scale
size-00 px0 px
size-101 px1 px
size-252 px2 px
size-403 px4 px
size-504 px5 px
size-655 px6 px
size-756 px8 px
size-857 px9 px
size-1008 px (base size)10 px (base size)
size-1159 px11 px
size-12510 px13 px
size-13011 px14 px
size-15012 px15 px
size-16013 px16 px
size-17514 px18 px
size-20016 px20 px

Not all global size tokens are displayed in this chart.

Static size tokens#

Static size tokens are persistent across each platform scale. Global size tokens change at every scale in order to support overall scaling of an application and its components. Static size tokens are used for properties such as border thickness, which are meant to remain the same across platform scales.

Labelled illustration of 8 pixels for desktop and 8 pixels for mobile each with arrows pointing to the same box with text "static-size-100"
Token nameDesktop and mobile scale
static-size-00 px
static-size-101 px
static-size-252 px
static-size-403 px
static-size-504 px
static-size-655 px
static-size-756 px
static-size-857 px
static-size-1008 px
static-size-1159 px
static-size-12510 px
static-size-13011 px
static-size-15012 px
static-size-16013 px
static-size-17514 px
static-size-20016 px

Not all static size tokens are displayed in this chart.

Usage guidelines#


Use global tokens sparingly#

Global tokens are the easiest to reference for the various attributes in Spectrum. While they’re the building blocks of Spectrum, they’re also the token type that is the least tied to the logic of our design language. Only use global tokens when there are no aliases for your use case.

key example showing correct usage of global token. Purple 600 as an online indication border for an avatar
key example showing incorrect usage of global tokens. Blue 500 as cta button background and size 400 as button height

Use aliases wherever they can apply#

Alias tokens are the recommended type to use when building your product with design tokens. Aliases are like a “Rosetta Stone” for understanding Spectrum, and they help to associate meaning, context, and/or 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. Border radius regular and border color light applied to a generic container.
Key example showing incorrect usage of alias tokens. Text color selected applied to fill color of a circle loader.

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 component-specific tokens. Button cta background color and button cta min height applied to a cta button.
Key example showing incorrect usage of component-specific tokens. Checkbox box background color selected token applied to cta button.