Migrate to tokens
How apps and teams move from old style values to design tokens.Read this guide to learn how to migrate an Atlassian 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 an 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 app 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 raw CSS values (e.g. colors, padding, or typography values) with the 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';
export default () => <div css={{
- color: B400,
+ color: token('color.background.selected.bold),
}} />// CSS variables, Sass, Less
.bg-surface {
background: var(--ds-surface-raised, #eeeeee);
}Rolling out color tokens in Marketplace apps and integrations
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 = styled.div`
- background-color: ${colors.R50};
+ background-color: ${token('color.background.danger')};
:hover {
- background-color: ${colors.R60};
+ background-color: ${token('color.background.danger.hovered')};
}
:active {
- background-color: ${colors.R80};
+ background-color: ${token('color.background.danger.pressed')};
}
`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 an app 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
- 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
Get help
- Atlassians can get help with token migrations in Slack.
- Other developers who need help with tokens can post in the public developer community.
- For general help with the Atlassian Design system, contact us.