Guidelines
What are design tokens?
Design tokens are name and value pairs that represent design decisions about color, spacing, typography, animation, and other visual attributes. They are the building blocks of Telescope components and our product experiences for web and mobile.
What types of design tokens do we use?
Core tokens
Core tokens are the primitive values in our design language. Their names describe their value, rather than their purpose. Some core tokens are referenced by semantic tokens.
Semantic tokens
Semantic tokens describe an intended purpose rather than a specific value. They generally map to core tokens.
How do we choose tokens?
Prefer a semantic token when its intended purpose matches the UI element. Choose it for its meaning, not just because its current value matches the color or other visual attribute you want.
Use a core token when no appropriate semantic token exists. If no existing token fits, discuss the need with Design Systems team.
Why do we use design tokens?
Consistency
Tokens provide a shared set of values based on our brand and a common language for designers and developers. Semantic tokens help us make consistent choices for the same situations across platforms and product areas.
Efficiency
Semantic tokens make decisions easier by describing the intended use. For example,
color-border-interactive-hover identifies the border color for an interactive UI element in its
hover state, without requiring a choice between core colors.
Adaptability
Tokens let us update shared design decisions centrally when our brand or product needs change. Semantic color tokens resolve to values for the active theme, so the same intended purpose can have different values in light, dark, or partner themes. Still review each supported theme for visual suitability and contrast.
How do we name our tokens?
Our core tokens have short and simple names that reference the values they are mapped to. Examples
include spacing2 and opacity20.
Our semantic tokens have names that reference their intended use and follow the naming scheme
attribute-property-role-variant-state. Attribute and role are required, while the other naming
scheme parts are optional.
Attribute
Attribute indicates which visual attribute the token concerns, such as color or shadow.
Property
Property indicates which UI element property the token applies to. background, border, and
shadow speak for themselves, while content refers to both text and icons.
Role
Role indicates the UI element’s role in the UI. The two most used roles are interactive and
static. Use interactive for UI elements that react to a user’s interaction (click/tap).
Use static for UI elements that don’t react to a user’s interaction (click/tap).
Variant
Variant is used for tokens that share the same attribute, property, and role, but have different
values. Frequently used variants are loud and quiet. Use loud when the UI element needs to
stand out.
Use quiet when the UI element needs to attract less attention.
State
State indicates the interactive state of the UI element (e.g. hover, disabled, selected, etc.).
Using design tokens in Figma
Figma libraries
We provide our design tokens as variables through the following Figma libraries:
These libraries are enabled for all design files in Figma, so no installation is required.
Applying tokens
To use our design tokens in your designs, apply them as you would any other Figma variable.