What's new in foundations

How our colors, spacing, and other foundations are changing with design tokens.

We’re making our visual foundations more consistent, accessible, and scalable using design tokens. Read this page to learn what changes to colors and other styles you can expect when you start using tokens.

For code changes, see tokens API changelog.

New color system

Tokens and theming are launching our new color system. Our new system is more accessible and visually consistent than the old colors.

Color ramps for all saturated colors, which are blue, teal, green, lime, yellow, orange, red, magenta, and purple.

Color palette and name changes

The colors values and names have changed across our ramps. Instead of using a letter followed by numbers (such as, N0, B100, G200), the new system uses the full color name followed by numbers (such as Neutral0, Blue100, Green200).

Color names (base tokens) and values have changed from letters and numbers (B100) to full names like Blue100. The exact values on each ramp have changed as well, so you may notice some slight differences between shades in the new and old systems.

For instance, N100 is not the same as Neutral100. You may notice colors changing in light mode as you adopt design tokens.

Learn more about the new colors.

Accessible yellows

Yellows are darker to provide options that follow WCAG AA guidelines for text, icons, borders, and backgrounds (WCAG 1.4.11, WCAG 1.4.3).

Comparison of a yellow flag message, icon, and tag in the old system and in the new system. The newer ones are darker and have more contrast against the white background.

Selected states reinforce our brand colors

Selected states use blue instead of the dark gray to reinforce our brand and make the selection less visually dominating.

Comparison of the old selected state (dark grey, high contrast), with the new (light blue to match our brand).

More consistent text colors

There are now three options for neutral text:

  • color.text: For primary text, such as headings, subheadings, body text, and on colored backgrounds.

  • color.text.subtle: For secondary text, such as navigation, input field labels, and all caps subheadings.

  • color.text.subtlest: For tertiary text, such as meta-data, breadcrumbs, input field placeholder, and helper text.

A form with each text color labeled as a diagram. The form heading uses color.text token, field labels use color.text.subtle, and placeholder text uses color.text.subtlest.

More consistent form fields

Form inputs, such as text field, text area, radio, checkbox, select, and dropdown menu, are now more consistent in appearance. We have dedicated tokens to use on form inputs: color.border.input and color.background.input.

Comparison of radio, checkbox, select menu, and text field before and after changes. The new system fields have more consistent border, fill, and text colors instead of different shades of grey and borders.

Elevations are changing

Our elevation system has also been updated to be more consistent when using shadows and surfaces.

There are now five elevation levels, which differ slightly across light and dark mode.

Learn more about our new elevations.

Examples of the five elevation levels in the UI: Sunken is lowest, then default, raised, and overlay looks highest, with darker shadows beneath. Overflow gives a shadow just on one edge, to imply that more content lies underneath the shadow on scroll.

Note that surfaces look different in dark mode to create contrast and make up for the more subtle shadows on dark surfaces. It's important to pair raised, overlay, and overflow surface colors with shadows for this reason. Refer to our elevation guidelines for token pairing guidance.

The five elevations shown in dark mode. The card surfaces change color slightly, rather than showing elevation through shadows alone.

Less elevations across our UI

Not everything that uses an elevation with a shadow today will continue to do so.

Rather than adding more visual complexity with elevations, consider using a simple border or background to group content. Elevations should be reserved for things that are draggable or lay on top of other surfaces.

A before and after example of some UI cards of a user's task. Before, the cards were slightly raised in appearance, due to a small drop shadow. Now, they look flatter against the background, using a simple border to separate the card content from the background.

Navigation components will no longer use an elevation with a shadow. Instead, use the flat, default elevation with a default border to separate it.

A comparison of the Atlassian top navigation bar using the old elevation style with a slight shadow and the new one with a simple border separating it from the rest of the UI.

New spacing scale

ADS now provides a spacing scale as well as accompanying tokens and tooling to assist in making spacing decisions across our products. Learn more about our spacing scale.

A bar graph is used to represent the size of each of the 14 values of the spacing scale, from 0px on the left hand side to 80px on the right hand side.

What's next

Was this page helpful?

We use this feedback to improve our documentation.