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 @atlaskit/tokens is installed as a dependency and use our linting rules to stay up to date.

Set up themes and theme switching

For themes to work properly for users, theming must be set up in two places: the Atlassian application and in any Marketplace apps extending that app experience.

Use the setGlobalTheme method to switch themes globally at runtime in an Atlassian app 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 typography:typography" 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 Atlassian fonts

To bring Atlassian Sans and Atlassian Mono web fonts into your app, follow our setup guide (Atlassians only).

The typography theme is enabled by default when using setGlobalTheme().

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)
token('font.body');                 // var(--ds-font-body)

If you're migrating a lot of values to tokens, use our codemod.

Migration to tokens

The token() function accepts two arguments: the first is the token, and the second is an optional fallback value (the value that is rendered when the theme is not set up). During the theme rollout (i.e., migration from raw values to tokens), it is recommended to use the function without specifying fallback value. In such cases, this value will be automatically supplied by the build-time Babel plugin, ensuring that properties have valid values even if the theme is not yet enabled.

At times, token values may not perfectly align with the raw values used in the codebase. To maintain consistent user experience, it is recommended to use the values provided by tokens whenever possible. However, if no appropriate token exists for a specific value that must be retained, it is preferable to leave the value unchanged (without converting it to a token) rather than adding it as a fallback.

Fallback values were mostly used historically for large app migrations and are not recommended anymore.

Design tokens are the new way to apply visual foundations in Atlassian app experiences. We’re rolling out tokens to standardize colors, elevations, spacing, and other styles in Atlassian apps.

Babel plugin

Our build-time Babel plugin is required to optimize the runtime performance of tokens by replacing any calls to the token() function in @atlaskit/tokens with the corresponding CSS value the function would return.

If no fallback is provided, the plugin automatically retrieves the token value from the default Atlassian light theme and sets it as the fallback. This behavior can be disabled by setting the plugin second option shouldUseAutoFallback to false.

// Original code
-import { token } from '@atlaskit/tokens';
-token('space.200');

// Babel plugin output
+var(--ds-space-200, 1rem);

By default, the plugin is configured to ignore explicit fallback values optionally provided in the second argument of the token() function. This behavior can be overridden by explicitly setting the plugin configuration option shouldForceAutoFallback to false.

Usage

Add the plugin to your babel configuration:

// babel.config.json
{
  "plugins": ["@atlaskit/tokens/babel-plugin"]
}

If your codebase uses Compiled, then add the plugin to its configuration as well:

// .compiledscssrc
"transformerBabelPlugins": ["@atlaskit/tokens/babel-plugin"],

Removing existing token fallbacks

If fallback values were used during the migration to tokens, it is essential to remove them from the codebase once migration is complete and themes are enabled. This helps to improve performance by reducing the critical CSS size and simplifies development efforts.

Prerequisites

Ensure the following before proceeding:

Babel plugin enabled: The @atlaskit/tokens/babel-plugin should be active with shouldUseAutoFallback set to true. This ensures fallback values are automatically handled during build time.
Themes enabled: Verify that ADS themes are applied in your app. Fallbacks can only be safely removed for token categories with active themes (e.g color, space, or typography tokens).

Steps for fallback removal

Implicit Fallback Removal:
- Update your Babel plugin configuration to include shouldForceAutoFallback: true. This setting forces the plugin to ignore any explicit fallbacks in the code, using default theme values instead.
- Define forceAutoFallbackExemptions for token categories that do not currently have an active theme. This ensures the preservation of existing token fallbacks rendered in the app, preventing unintended UI changes.
Explicit fallback removal:
- Install the codemod: https://www.npmjs.com/package/@atlaskit/codemod-cli
- Run the codemod to remove fallback values from your codebase:npx @atlaskit/codemod-cli --preset remove-token-fallbacks /absolute/path/to/code --extensions tsx,ts,js,jsx --forceUpdate --addEslintComments --skipTokens color,font
- Use --skipTokens to align with forceAutoFallbackExemptions for any themes that are not yet enabled (note that currently radius tokens are automatically exempted).
- Use --forceUpdate to remove fallbacks regardless of their values. Without the option it would preserve fallbacks that differ from the token value. Omitting this option is only valuable when you don’t have shouldForceAutoFallback enabled or are unsure if themes are enabled in the app and therefore would like to remove fallbacks gradually starting with the ones that won’t have UI impact if removed.
- Use --addEslintComments to automatically add eslint suppressions for the fallbacks that shouldn’t be removed, such as the ones configured in forceAutoFallbackExemptions.
Use ESLint to ensure fallbacks are not used in the future. This can be done by enabling the @atlaskit/design-system/no-unsafe-design-token-usage ESLint rule with fallbackUsage: 'none' to prevent new fallbacks from being added.

Stay up to date

As our color system is applied to new apps, 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

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.

Get help

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.

Was this page helpful?

We use this feedback to improve our documentation.