What are Design Tokens?
Design tokens are names and values that drive our design decisions. They help guide designers and engineers in these design decisions throughout our products. From colour and fonts to spacing and media queries, design tokens are there to help you.
Why tokens?
Tokens provide a series of small, repeatable design decisions. These decisions allow for maintainability, consistency and more accessible cross-platform themes throughout Octopus Deploy.
For example, we can opt for a single colour token instead of coding one colour value in various ways. This token is theme-responsive and will have consistent usage across many spaces. An example of this is color.background.primary.
Design Token types
We divide our Design Token system into two main categories:
- Global - core tokens that drive all our design decisions (e.g. colour scales and text styles).
- Themed - tokens that control specific components and variables such as light and dark mode.
Global tokens
Global tokens are our primitive values represented by context-agnostic names. They are named after their design aspect or style (e.g. colour, text or space).
The next part of the name is a value type (e.g. numeric scales 100-900 or names small-large). Theme tokens inherit these, so they must never change or be directly used in designs or code.
Below is an example list of our global tokens and corresponding values:
|
Token name |
Token value |
|---|---|
|
color |
100, 200, 300, 400, 500, 600, 700, 800, 900 |
|
text |
xLarge, large, base, medium, small, xSmall |
|
space |
0, 2, 4, 6, 8, 12, 16, 24, 32, 40, 48, 56, 64, 72, 80 |
|
borderRadius |
none, xSmall2, small4, medium6, large8, xLarge16, circle |
Theme tokens
Theme tokens are styled variables created for specific, contextual use. They describe a series of physical design decisions where that style should apply in the UI. These are created by referencing global tokens as their base. Naming of these tokens allows easy understanding of their context and usage.
We divide theme tokens into two distinct groups:
- Generic: designed for high reuse in common areas throughout the UI
- Semantic: designed for context-specific scenarios and/or components
Theme tokens are also theme responsive. This means they will change colour in light or dark mode with only one token required.
Naming theme tokens
The naming of theme tokens follows a strict taxonomy of five values. Each value refers to a unique descriptive property. These are expressed as category, ui-intent, property, variant and state (if required).
The table below will help you with best practise construction of a theme token.
|
Value |
Description |
Value |
|---|---|---|
|
Category |
The global style being referenced. |
color , typography , border-radius,space |
|
UI Intent |
UI element being targeted. Reserved for semantic theme tokens. |
navigation, body, heading, table, modal, menu |
|
Property |
Visual property the token will apply to. |
text, background, icon, border |
|
Variant |
Hierarchal context or scale value. |
primary , secondary, tertiary, subtle, info, success, warning, danger heading, body, label, base, medium, xSmall |
|
State |
The state of the element. |
default, hover, pressed , active, focused, disabled |
Resources
You can learn more about Design Tokens with some helpful resources we recommend:
Design tokens cheatsheet
A Design System’s strength comes from knowing how and when to apply options (like purple-40 or color-warning) correctly to contexts (like…
What the #&%$ are Design Tokens?
This video will help you conceptualise and understand how Design Tokens work in a product development context.
Communicating design system decisions with design tokens
Translating designs into products is hard! Learn how design tokens make building products easier for both designers and developers.