To migrate your project's legacy tokens to the new tokens, please see the "v2 → v3" tab on the Migration page.
What are tokens
Tokens (also known as Design Tokens) are reusable variables that define design properties like color, typography, and spacing. They represent shared design decisions across the UI, serving as the building blocks for consistent and cohesive experiences. They enable designers and developers to easily create and maintain these experiences using a shared language.
Before using tokens, consider if a different SWAN API is preferable. Using SWAN components directly is more robust to future changes, more maintainable, and ultimately more consistent for customers.
A list of all tokens can be found here: All Tokens
Benefits of tokens include:
- Introduce Semantic Meaning. Tokens simplify design decisions and provide context for how they should be applied to product UI.
- Facilitate Design Changes at Scale. Tokens reduce the effort needed to rollout visual updates across the entire product UI.
- Support Modes. Tokens cater to various product experiences by changing their output when different modes are applied.
- Strengthen Cross-Discipline Alignment. Tokens create a shared language, fostering collaboration and consistency between product designers and engineers.
- Intentionality. We have collaborated with the brand team to define better meaning for our tokens, leading to a more limited but refined token set.
Want to learn more about design tokens? We have curated a course specially for UX designers to understand why using design tokens is important for consistent design practice and scaling a website.
Checkout the Introduction to Design Tokens on 360 learning
Using tokens
Users should use the most semantic token available for the particular use case you are trying to style. e.g. For success-related content, use sem.color.success, not base.color.green. Don’t use a token just because it matches the value.
We aim to offer a standard token for each applicable token category, however, a more semantic token may exist for the particular case you are styling. e.g When styling a container, using sem.border.radius.container over sem.border.radius.standard allows for finer control of visual language changes, even if they currently output the same value.
Tokens are often displayed in a language-agnostic manner, and must be prefixed with 'swan' when used. For example, base.color.transparent is equivalent to $swan-base-color-transparent in SASS, and SwanBaseColorTransparent in JS.
Structure
SWAN has three token tiers. Each tier refers to the tier above it:
- Base tokens are an abstraction over raw values. They represent the scale and options for other tokens to pull from.
- Semantic tokens represent shared design decisions.
- Component tokens represent outlier decisions for necessary SWAN components. Not for public consumption.
Remember, always aim to use a semantic token. Base tokens can be used for exceptions, but they don’t properly propagate decisions, which reduces the efficacy of visual language updates through tokens. Component tokens should never be used and aren’t considered part of our public API.
Emphasis
Most tokens follow SWAN’s standard scale of emphasis to create hierarchy. Steps in the scale don’t exist for every token. “Standard” is the baseline to which other emphasis levels are relative. This is the most common option that should be used by default.
None | Use when paired with interaction states, such as hover or active (see: Color). Also to remove existing styling when necessary. |
Subtle | Use to reduce emphasis relative to other UI, or when the default option is too strong. |
Standard | The default option. |
Strong | Use to increase emphasis relative to other UI, or when the default option is too subtle. |
Intents and concepts
Intents and concepts connect similar components, allowing SWAN to make visual updates to a particular section of UI, rather than needing to update multiple components in tandem.
Intents exist across multiple token categories, they are:
Action | For UI that evokes an action, such as Button, Pagination, ZoomControls, etc. |
Container | For UI that contains content or other components, such as Accordion, Card, Popover, etc. |
Control | For non-text input UI, such as Checkbox, ColorSwatches, ToggleSwitch, etc. |
Input | For text input UI, such as Combobox, Dropdown, TextInput, etc. |
Concepts are more specific to a particular token category. For example, the border category has a partition concept. Recommended for when you have a specialised use case that matches the token.
Categories
When using the most semantic token, please use a token in the applicable category. Don’t use a bg token for text, for example. Tokens that share similar names have purposefully different values depending on the category.
For more detailed information on particular categories, see Color, Space, and Typography
Modes
SWAN currently supports three modes, standardMode, darkMode, and compactMode:
- Standard mode is the default mode used when no other modes are specified.
- Dark mode inverses the color of the UI enabling components to be accessible on darker backgrounds. This mode has been designed to be used in sections of the UI as opposed to entire pages or experiences.
- Compact mode increases the density of the UI allowing more information and actions to be shown. Useful for workspace-type experiences.
For more detailed information on how to use modes, see Modes.
Brands/themes
If you have questions about branding or theming, reach out to us at #help-swan.
Importing tokens
Developers
Tokens are available in the following languages: CSS, SCSS, LESS, Stylus, and Javascript.
All of these tokens point to underlying CSS Custom Properties which can either reference a literal value or another CSS custom variable, to ensure tokens can appropriately react to breakpoints, modes, etc.
The import path for SCSS/LESS/CSS/Stylus is simply:
ShareJavascript is slightly different, and are imported from the main path:
tokensRaw should only be used when CSS Custom Properties aren’t an accepted value, e.g. for third party libraries, or inside of @media rules. These tokens do not respond to modes.
Designers
Tokens are available via Figma variables in the SWAN UI Kit. They can be applied directly to Figma elements such as text, fill, and border. Tokens are also built into all SWAN components and synced with their code counterparts.
Can’t find the right token?
Come chat to us. If there’s a token you need, let’s have a discussion and see if it’s missing from SWAN. Tokens are part of our public API, so the process in our contribution guidelines applies here.
