Use tokens in code

Learn how to set up and use design tokens in code.

This page explains how to set up and use design tokens and themes in code.

Before you begin

  • 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.

  • It’s normal if colors or values change when you apply tokens. See what’s changing in our foundations.

  • 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.

Set up themes and theme switching

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.

Set up themes for apps (Connect, Forge, Marketplace)

For Connect and Forge apps, see the following dedicated resources:

Server-side rendering

If your application is using SSR (server-side rendering) ensure themes appear at the right time using our SSR theming utilities.

Use tokens

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.

Use fallbacks during rollout

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"]
}

Stay up to date

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:

  • For CSS in JS applications, use ESlint.

  • For CSS (vanilla), Less, Sass, use Stylelint.

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'

What's next

Get help

Was this page helpful?

We use this feedback to improve our documentation.