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.
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:
Set up theming in your application
Update any design system components to the latest versions (these already have tokens built-in).
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.
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 @hypermod/cli --packages="@atlaskit/tokens#theme-to-design-tokens" --experimental-loader --parser tsx <relative-path>
# For vanilla CSS, SASS, Less
npx @hypermod/cli --packages="@atlaskit/tokens#css-to-design-tokens" --extensions css,scss,less <relative-path>
The CLI will show a list of components and versions. Select @hypermod/cli: theme-to-design-tokens
 (for CSS in JS) or @hypermod/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
Learn our new color, elevation, and other foundation guidelines
Search for tokens in the all tokens list
Get help
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.