Introduction
Design tokens are the foundational elements of our design system that store visual design attributes. They help us maintain consistency across platforms while enabling flexibility for different brand expressions. This documentation covers how to use our design tokens across the React Library, Spec Library, and Design Library.
Color Tokens
Guide
Color tokens are named entities that store specific color values in our design system. They create a layer of abstraction that allows for consistent color application while making system-wide updates more manageable.
Our color tokens follow a hierarchical structure:
Global Tokens: Represent the raw color values (e.g., color.blue.500)
Semantic Tokens: Convey purpose rather than visual attributes (e.g., color.background.primary)
Component Tokens: Specific to individual components (e.g., button.background.primary)
Token Naming Convention
Our tokens follow this pattern:
{category}.{concept}.{property}.{scale/state}
For example:
color.background.primary
color.text.error.hover
spacing.component.medium
Text Color Tokens
This table excludes hover and active tokens
Token | Example |
|---|---|
| Modal title, section title |
| Secondary button |
| Onboarding, modal paragraphs |
| Input label |
| Tab, view switcher |
| Onboarding, modal paragraphs |
| Info icon |
| Input placeholder |
| Paragraphs |
| Primary button |
| Info banner |
| Link text, icon |
| Success banner |
| Success text, icon |
| Warning banner |
| Warning icon |
| Warning text |
| Error or Alert banner |
| Error text, icon |
| Destructive text, icon |
| Header title |
| Header link, input text |
| Paragraph text |
| Secondary links, icon |
| Secondary paragraph text |
| Input label icon |
| Input label icon |
| Input placeholder |
| Nav menu tag |
Border Color Tokens
This table excludes hover and active tokens
Token | Example |
|---|---|
| Horizontal separator, table separator |
| Vertical separator, second level line |
| Button, input field, usually paired with base-alt |
| Checkboxes, radios, toggles |
| Tooltips, dropdown menus |
| Tooltips that are dark in both themes |
| Active input field |
| Primary button group separator |
| Focus states |
| ... |
| Warning input field |
| Error input field |
| Destructive button group separator |
| Active search |
| Separators |
| Active menu item separator |
| Header search menu |
Background Color Tokens
This table excludes hover and active tokens
Token | Example |
|---|---|
| Button, input, table placed on body or base alt. |
| Button, input, table placed on base. |
| Page background. |
| Active view switcher tab. |
| ... |
| ... |
| Slider handle. |
| Expanded row, table filter. |
| Neutral tag, neutral step badge. |
| Checkbox, radio, toggle. |
| ... |
| Dark tooltips in both themes. |
| Selected side menu page. |
| Banner, label, completed step. |
| Primary button, badge. |
| Focus states. |
| Banner, tag. |
| Success badge. |
| Banner, tag. |
| Warning badge. |
| Banner, tag. |
| Error badge. |
| Destructive button. |
| Header background. |
| Search background. |
| Selected nav menu item. |
| Primary nav menu badges. |
| Success nav menu badges. |
| Warning nav menu badges. |
| Error nav menu badges. |
| Nav menu tag. |
Opacity Tokens
Token | Example |
|---|---|
| Disabled components |
| Modal, tutorial underlay |
| ... |
| ... |
| Loading underlay |
Shadow Tokens
Token | Example |
|---|---|
| Popover, dropdown |
| Left side fixed column |
| Right side fixed column |
| Sticky footers |
| Focused inputs |
Themes
Our design system supports multiple themes through token aliasing. Each theme maintains the same token names but maps to different values depending on the active theme.
Available Themes
Light (default before 25.5)
Dark
High Contrast (default after 25.5)
Spacing Tokens
Currently, the only tokens used in production are the basic spacing tokens.
Token | Size |
|---|---|
| 5px |
| 10px |
| 15px |
| 20px |
| 30px |
| 40px |
Figma
Our Figma libraries leverage design tokens through Figma variables. This ensures that designs created in Figma use the same values that will be implemented in the final product.
Using Tokens in Figma
Accessing Design Tokens
Open your Figma file
Click on the "Variables" icon in the right sidebar (diamond shape)
Browse available variables organized by category (colors, spacing, etc.)
Hover over a variable to preview its current value
Applying Tokens to Properties
Select an element in your design
In the property panel (right side), locate the property you want to modify (fill, stroke, etc.)
Click the four-dot icon to the right of the property
Select "Choose variable" from the dropdown
Browse and select the appropriate token variable
Creating New Elements with Tokens
When creating new shapes, text, or other elements
Apply variables to their properties instead of using static values
For text elements, apply typography tokens to ensure consistent font styles
Working with Composite Tokens
Some properties may reference multiple tokens
For example, a shadow might use opacity, blur, and color tokens together
Apply these through component properties when available
Theme Switching
Our design system supports dynamic theme switching across all platforms and implementations. Development teams will handle the technical implementation of theme switching in applications, but designers should design with theme adaptability in mind.
Changing Themes in Figma
Designers can preview and test designs across different themes using Figma's built-in variable mode switching:
Access the Variables Panel
Open your Figma design file
Click on the "Variables" icon in the right sidebar
The Variables panel will display all available variable collections
Switch Between Themes
Look for the "Mode" dropdown at the top of the Variables panel
Select from available themes: "Light" (default), "Dark", or "High Contrast"
Your design will update in real-time to reflect the selected theme
Testing Theme Compatibility
Create a dedicated artboard for each theme variant
Use components that reference design tokens (variables)
Duplicate screens and switch modes to compare appearances
Verify accessible contrast ratios in each theme
Theme Switching in Prototypes
You can create interactive theme switching in Figma prototypes:
Create a theme toggle component
Set up variable mode switching interactions
Connect the toggle to mode changes in your prototype
Test the user flow of changing theme
Variable vs Styles
Design Tokens as Variables
Design tokens implemented as variables provide:
A single source of truth
Consistent naming conventions
Easier theme switching
Simplified maintenance
In Figma, variables represent our design tokens and allow for dynamic changes across themes.
Figma Variables vs Styles
Variables (Recommended)
Store individual property values
Support multiple themes through modes
Can be used across multiple properties
Enable algebraic operations (e.g., spacing calculations)
Allow for inheritance and aliases
Styles (Limited Use)
Combine multiple properties into one preset
Cannot adapt to theme changes without manual updates
Less flexible for system-wide changes
Useful for complex, composite elements
When to Use Variables vs Styles in Figma
Use Variables for:
Color values
Spacing measurements
Typography properties
Border radii
Shadow values
Opacity settings
Use Styles for:
Complex text formatting not fully covered by variables
Effect combinations that need to be applied together
Legacy designs not yet converted to the variable system
Converting Styles to Variables
When migrating from styles to variables:
Identify the token values in each style
Create equivalent variables
Replace style references with variable references
Test across all theme modes