Migrate to tokens

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

• Make sure you understand the basics of design tokens.

• Learn what’s changing in our colors and foundations.

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

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.

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.

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.

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.

• Use tokens in design

• Use tokens in code

• Learn our new color, elevation, and other foundation guidelines

• Search for tokens in the all tokens list

• Atlassians can reach out in slack for help with tokens migration.

• Other developers who need help with tokens can post in the public developer community.

• For general help with the Atlassian Design System, contact us.