This page explains how to set up and use design tokens and themes in code.
Make sure you’re set up to use the Atlassian Design System. In particular, make sure tokens is installed as a dependency and use our linter tooling to stay up to date.
We’re in the process of rolling out tokens internally (and sometimes externally). Use fallbacks for colors to maintain the current experience until your product is ready for a public release.
For themes to work properly for users, theming must be set up in two places: the Atlassian product application and in any Marketplace apps extending that product experience.
Use the setGlobalTheme method to switch themes globally at runtime in an Atlassian product or stand-alone application.
// Automatic theme switching
setGlobalTheme({light: "light", dark: "legacy-dark", colorMode: 'auto'})
// The above is using setGlobalTheme’s default values, so this also works
setGlobalTheme({})
Make sure theming is set up by inspecting your app HTML. You should see something like this:
<html data-theme="light:light dark:dark spacing:spacing" data-color-mode="light">
Pay special attention to the data-color-mode="dark"
attribute, and also note the data-theme="dark:dark light:light"
attribute. These reflect the current theme state. They also match CSS selectors within the theme files so the appropriate CSS variables can be activated in response to theme changes.
For Connect and Forge apps, see the following dedicated resources:
If your application is using SSR (server-side rendering) ensure themes appear at the right time using our SSR theming utilities.
You can access individual tokens using the CSS custom properties mounted to the page, however, it's best to use the token()
method. This ensures you have proper prefixes, type checking, and linting so you'll know if a token ever changes, is deleted, or is used incorrectly.
The token function takes a dot-separated token name and returns a valid CSS custom property for the corresponding token. This method will warn you if an unknown token is provided.
import { token } from '@atlaskit/tokens';
token('color.background.neutral'); // var(--ds-background-neutral)
token('space.200'); // var(--ds-space-200)
If you're migrating a lot of values to tokens, use our codemod.
You must use fallbacks while tokens are being applied and tested in a product.
Migrating an experience to tokens is done piece-by-piece. While this work is in progress, you must hide the new appearance from users, generally behind a feature flag or user setting. This will prevent users from seeing unfinished and inconsistent colors and themes.
To ensure our experiences remain consistent for users until we are ready to launch, we provide a fallback argument to the token()
 method. This is based on the matching feature from CSS custom properties.
When the CSS custom property is not available at runtime (when the theme CSS is not present in your app), the fallback value will render instead. For colors, the fallback color should be the color visible in your app today. Generally these are imported from the old color palette @atlaskit/theme/colors
.
import { N0 } from '@atlaskit/theme/colors';
import { token } from '@atlaskit/tokens';
token('color.background.neutral', N0); // var(--ds-background-neutral, #FFFFFF)
token('space.200', '16px'); // var(--ds-space-200, 16px)
We also have a Babel plugin to automate setting some fallback values.
Babel plugin
Our Babel plugin to optimizes the runtime performance of tokens. It replaces any calls to the token()
function in @atlaskit/tokens
with the CSS value the function would return:
// Original code
-import { token } from '@atlaskit/tokens';
import { N0 } from '@atlaskit/theme/colors';
-token('test-token', N0);
// Babel plugin output
import { N0 } from "@atlaskit/theme/colors";
+"var(--test-token, ".concat(N0).concat(")");
If there’s no fallback, the plugin can optionally find the token’s value from the default Atlassian light theme, and sets it as the fallback. This can be enabled using the plugin option shouldUseAutoFallback
.
Usage
Add the plugin to your babel configuration:
{
"plugins": ["@atlaskit/tokens/babel-plugin"]
}
As our color system is applied to new products and applications, changes to our tokens will be released regularly. To stay up to date, install our linting support tools:
These will warn you if you’re using deprecated tokens, and will assist in updating your app to the latest tokens.
'@atlaskit/design-system/ensure-design-token-usage': [
'error',
{
domains: ['color', 'spacing'],
shouldEnforceFallbacks: true
}
],
'@atlaskit/design-system/no-unsafe-design-token-usage': ['error', { shouldEnforceFallbacks: true }],
'@atlaskit/design-system/no-deprecated-design-token-usage': 'warn'
Search the list of all design tokens for full descriptions and token values.
See design token code examples.
Browse our token API reference and changelog.
Use the image component to theme images.
Atlassians can get help with tokens in slack.
Partners and other developers who need help with tokens can post in the developer community.
For general help with the Atlassian Design system, contact us.