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 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 typography

To bring Atlassian Sans and Atlassian Mono web fonts into your product, we use a set of <link> tags that establish an early connection to the Atlassian DS-CDN and preload essential font assets. This ensures that fonts are available as soon as possible, preventing layout shifts and flash of unstyled text. All assets are cached for one year.

These tags should be placed in the <head> of all HTML responses and sent to the browser as early as possible, allowing font downloads to begin potentially while server-side rendering (SSR) continues.

<link 
  rel="preconnect" 
  href="https://ds-cdn.{ENVIRONMENT}.frontend.public.atl-paas.net" />
<link 
  rel="preload" 
  href="https://ds-cdn.{ENVIRONMENT}.frontend.public.atl-paas.net/assets/fonts/atlassian-sans/v2/AtlassianSans-latin.woff2" 
  as="font" type="font/woff2" crossorigin />
<link 
  rel="preload stylesheet" 
  href="https://ds-cdn.{ENVIRONMENT}.frontend.public.atl-paas.net/assets/font-rules/v3/atlassian-fonts.css" 
  as="style" crossorigin />

Replace {ENVIRONMENT} with the appropriate value for where your code is running.

Production (PROD) - ds-cdn.prod-east - Stable, production-ready font versions.
Staging (STG) - ds-cdn.stg-east - May contain new font versions not yet in production.
Development (DEV) - ds-cdn.adev - Latest development versions, may change frequently.

How It Works

<link rel="preconnect">: Hints browsers to establish an early connection to the CDN to reduce latency.
<link rel="preload" as="font">: Ensures the browser starts downloading Atlassian Sans (Latin subset) right away regardless of content as this is used by ~91% of Atlassian users.
<link rel="preload stylesheet" as="style">: Loads the CSS that defines Atlassian Sans (all languages) and Atlassian Mono. Any font files required by the page will automatically be downloaded. If no additional files are required, nothing is downloaded.

If your product is onboarded to the typography system, switch to refreshed theme to enable Atlassian Sans and Mono. You can use Atlassian fonts with native style declarations as well.

<AppProvider defaultTheme={{ typography: 'typography-refreshed' }}>

setGlobalTheme({ typography: 'typography-refreshed', ... })

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.

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 product migrations and are not recommended anymore.

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 in the products that previously used them

If fallback values were used during migration to tokens, it is essential to remove them from the codebase after migration is over and themes are enabled. This would help to improve performance and streamline your codebase.

Benefits of Removing Fallbacks

Reduced Critical CSS Size: Eliminating fallbacks minimizes the critical CSS size, enhancing application performance by reducing load times.
Simplified Development: Developers no longer need to manage or reference fallback values, decreasing cognitive load and saving time.

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 product. Fallbacks can only be safely removed for token categories with active themes (e.g color or space 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 option to align with forceAutoFallbackExemptions for any themes that are not yet enabled (note that currently border.radius tokens are automatically exempted).
  - Use --forceUpdate option 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 product and therefore would like to remove fallbacks gradually starting with the ones that won’t have UI impact if removed.
  - Use --addEslintComments option 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 rule with fallbackUsage: 'none' to prevent new fallbacks from being added (https://www.npmjs.com/package/@atlaskit/eslint-plugin-design-system).

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

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.