Read this guide to learn how to migrate an Atlassian product or app to tokens, and what’s changing for designers and developers.

Before you begin

  • Make sure you understand the basics of design tokens.

How to migrate a product or app to tokens

Teams will apply and test tokens across an experience before releasing new colors (dark mode) or other tokens publicly.

Changes for designers

Use our Figma libraries to apply updated colors, design tokens, and themed components to your designs. We also have a Figma plugin to help you migrate design styles to tokens and generate dark-mode previews.

A promotional image showcasing the Atlassian Design Tokens Figma plugin. On the left, a screenshot of the plugin interface shows the tokens view with a search field and filters for finding tokens. On the right, another screenshot of the plugin interface shows the token migration view with pairs of matched tokens. A blue icon with a white Atlassian logo is displayed between the two screenshots, representing the plugin's icon.

As migration continues, you'll also help test and review changes in your product with our Chrome extension (Atlassians only).

Get set up to use tokens in designs.

Changes for developers

To use and apply tokens in code:

  1. Set up theming in your application

  2. Update any design system components to the latest versions (these already have tokens built-in).

  3. Replace any remaining colors or other style values with the new tokens (our codemod speeds this up). See instructions in use tokens in code.

Conversion in code generally looks like this:

// CSS in JS
+import { token } from '@atlaskit/tokens';
import { B400 } from '@atlaskit/theme/colors';

export default () => <div css={{
-  color: B400,
+  color: token('color.background.selected.bold, B400),
}} />
// CSS variables, Sass, Less
.bg-surface {
  background: var(--ds-surface-raised, #eeeeee);
}

Notice that you’ll use an old value as a fallback to preserve the current experience for end users during testing, see about using fallbacks in use tokens in code.

Rolling out color tokens in Marketplace apps and integrations

Before any Atlassian product launches dark mode publicly, we’ll provide support and updates in our developer community so that apps can prepare.

Developer community updates
·

Use our codemod for migration assistance

When you run the codemod, it goes into every single color in the target files and suggests tokens based on context of the surrounding code.

This is what it looks like after running the codemod.

export const DangerMessage = style.div`
-  background-color: ${colors.R50};
+  background-color: ${token('color.background.danger', colors.R50)};

  :hover {
-    background-color: ${colors.R60};
+    background-color: ${token('color.background.danger.hovered', colors.R60)};
  }

  :active {
-    background-color: ${colors.R80};
+    background-color: ${token('color.background.danger.pressed', colors.R80)};
  }
`

Use @atlaskit/codemod-cli to run the codemod cli

# For CSS in JS
npx @atlaskit/codemod-cli --parser tsx --extensions ts,tsx,js <relative-path>

# For vanilla CSS, SASS, Less
npx @atlaskit/codemod-cli --extensions css,scss,less <relative-path>

The CLI will show a list of components and versions. Select @atlaskit/codemod-cli: theme-to-design-tokens (for CSS in JS) or @atlaskit/codemod-cli: css-to-design-tokens (for vanilla CSS) and your code will be migrated.

The codemod only provides token suggestions, so manual review is required after running the codemod.

Test changes with the Chrome extension

To view progress and toggle between themes in a product during migration, use our Chrome extension (Atlassians only).

You can also pin the extension to your browser's toolbar for easy access from the Extension popup.

What's next

Get help


Was this page helpful?
We use this feedback to improve our documentation.