Design tokens are the new way to apply visual foundations in Atlassian product experiences. We’re rolling out tokens to standardize colors, elevations, spacing, and other styles in Atlassian products.

What are design tokens?

Design tokens are name and value pairings that represent small, repeatable design decisions. A token can be a color, font style, unit of white space, or even a motion animation designed for a specific need.

For example, instead of choosing one of many shades of green for an icon, we can apply a design token that is consistent with all similar usages across our products: color.icon.success.

Diagram pointing to a flag message with a green success icon and a drop shadow. The icon uses the color.icons.success token, and the shadow uses the elevation.shadow.overlay token.

What are themes?

A theme is a collection of token values designed to achieve a certain look or style. Themes are how we switch color schemes and styles everywhere using a single set of tokens.

Light mode, dark mode, and high-contrast mode are all examples of theming. Non-color themes are also possible: think cozy/comfortable/compact views, reduced motion, or custom typography styles.

A jira screen switching between themes: light mode has a white background, darker colored icons, and dark text, and dark mode uses a dark background, light text, and lighter icon colors.

Why use design tokens?

  • Features like global theming (dark mode), responsive design, and user customization are possible with tokens.

  • Design tokens simplify the design and development by streamlining decision making and handover between crafts.

  • As Atlassian's visual language evolves, changes can be made once across the system and products. No more finding and replacing hard-coded values everywhere.

  • We have automated tooling to help designers and developers start using tokens faster.

  • Tokens are how we'll implement our newest visual foundations. This will deliver visual consistency and other improvements to Atlassian UI.

How to read design token names

Knowing how to read token names will help you find the right token faster when working in designs and in code.

A diagram of a design token called "color.background.danger.bold.hovered." The token is split into three parts, which are numbered as follows: 1. color (the foundation) 2. background (the property) and 3. danger.bold.hovered (the modifier).

A design token’s name describes how it should be used, and each part communicates one piece of its usage.

  1. Foundation: The type of visual design attribute or foundational style, such as color, elevation, or space.

  2. Property: The UI element the token is being applied to, such as a border, background, shadow, or other property.

  3. Modifier: Additional details about the token’s purpose, such as its color role, emphasis, or interaction state. Not every token has a modifier. For example, color.text is our default body text color.

Note that token names might look different in different environments and tools:

A diagram showing how a purple color is represented in our token system. A purple color with hex value #5E4DB2 is captured as a base token named 'Purple800', which is then aliased as a semantic design token called 'color.text.discovery'. This design token is represented in Figma as 'color.text.discovery', is applied in code with 'token('color.text.discovery');', and is rendered in production as a CSS variable named 'var(--ds-text-discovery)'.

Find and use tokens

Find all of our available design tokens and their usage descriptions in all tokens.

Search and filter the token list, or use our token picker for extra help.

Best practices

Choose tokens based on meaning where applicable, not specific values.

Do

Use design tokens with names and descriptions that fit your specific situation.

Don’t

Don't use a token just because the colors appear to match. This can break the experience in other themes.

Check our foundations for color, elevation, and spacing for additional usage guidance.

Design token examples

Use these examples to get a better understanding of how different tokens work.

Color tokens

Here’s an example of color design tokens in use: the default text color and the background color for a "danger" button on hover.

A modal dialog with a delete button. The text in the modal uses the color token "color.text" and the background color of the button uses, "color.background.danger.bold.hovered," which is a mid-to-dark red color.

There are dedicated color tokens for text, links, icons, backgrounds, borders, blankets, charts, and skeleton loaders.

For more on color token usage, see our color foundation.

Elevation tokens

Elevation tokens apply to the perceived surface level and shadow.

A flag message is labelled with a surface token for the background, "elevation.surface.overlay," and a shadow token for the drop shadow, "elevation.shadow.overlay." Note that both elevations use the same modifier "overlay", which means they are meant to be used together.

For more on how and when to apply elevations, see our elevation foundation.

Opacity tokens

Opacity tokens apply transparency to an element. Use opacity.disabled for interactive images that are disabled (such as disabled avatar), and opacity.loading to content sitting underneath a loading spinner.

The content in a search dialog is labelled with an overlay token "opacity.loading" because it is sitting underneath the loading spinner.

Space tokens

Space tokens reduce decision making and allow for consistent spacing between elements in a page layout. These tokens are designed to be use for horizontal and vertical spacing, in a variety of contexts.

For more on how our spacing system, and how to use space in your designs, see our spacing foundation.

A simple example of a modal using space tokens. A space.300 token is used on the top and left hand margin, and a space.200 token is used between the title and example text.

Typography tokens

To visually align typography across Atlassian products, typography tokens include font values, including font family, font size, font weights, and line heights for all text styles.

For more on how to start working with typography tokens, see our typography foundation.

An example of a project document, where the Title is labelled as using the "font.heading.medium" token, and the sub headings are labelled as using the "font.heading.small" tokens.

What's next

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