Theming Connect Apps

When developing Connect apps, incorporating Atlassian's design tokens can be highly beneficial. To familiarize yourself with design tokens, refer to the Atlassian Design System documentation. This describes the naming conventions used, as well as the advantages they offer.

In addition to enabling features like dark theme and improved accessibility, design tokens make it easy for you to design and build apps that match the parent Atlassian product — such as Jira, Confluence, or Bitbucket — and do it once. They also allow your apps to automatically change appearance when the user selects a different theme.

The adoption of design tokens described here is now supported on Jira, Confluence, and Bitbucket apps. Users can select their own theme, choosing between light, dark, and match browser. Changing themes will change the entire color set of the parent product. Apps that don't use design tokens will not follow the user-initiated change.

With design tokens, colors in your app will react to the active theme of the parent product to appear closely integrated and provide a consistent, familiar experience for customers. But not only that, as the Atlassian Design System is continually improved upon and colors iterated on, you’ll easily benefit from them too.

You can start using design tokens in apps powered by Connect by enabling the opt-in theming API.

Opt-in Theming API

The opt-in API allows you to test and iterate on your experience, while only enabling it for customers when the migration is complete and you’re ready to ship to your customers.

To activate theming in your Connect app, call window.AP.theming.initializeTheming(). This will fetch the current active theme from the parent product (Jira, Confluence, or Bitbucket) and apply it in your app. It will also reactively apply theme changes that occur in the host environment so that your app and the host are always in sync.

It is important to call the initializeTheming() method as early as possible to avoid any flashes or inconsistencies between themes. We recommend the following approach:

1
2
<html>
  <head />
  <body>
    <script>
      window.AP.theming.initializeTheming();
    </script>
    ... rest of your APP
  </body>
</html>

Using Design Tokens

Once enabled, applications powered by Connect should now have access to the design tokens API without additional configuration or dependencies.

Verify that it is enabled by inspecting the HTML of your application while shown in the parent product.

1
2
<html data-theme="dark:dark light:light" data-color-mode="dark">
  <head>
    <style data-theme="dark">
      /* Dark theme CSS */
    </style>
  </head>
  <body>
    <!-- Your app here -->
  </body>
</html>

Pay special attention to the data-color-mode="dark" attribute, and also note the data-theme="dark:dark light:light" attribute. These reflect the current theme state of the parent product. They also match CSS selectors within the theme files so the appropriate CSS variables can be activated in response to theme changes.

  • data-color-mode="dark" represents the color “mode” of the theme, with possible values today being light, dark or auto. This attribute tells your application what “type” of theme is active on the page, so that images and theme overrides may be applied consistently.
  • data-theme="dark:dark light:light" represents the active theme(s), but this is internal behavior and should not be read or modified in any way, since the names and shape of this attribute may change at any time as we add more themes.
  • For example, if an additional theme high-contrast-light is introduced, the color mode will still be light, telling your application that it should respect a “light” color scheme and render light image variants accordingly. So you should only rely on data-color-mode as above.

Update colors to design tokens

All that is left is to use tokens in place of colors throughout your application.

To view, search and filter through the available design tokens, visit the “All design tokens” section on atlassian.design. This page includes a “Token picker” tool that will ask a series of questions to help you find the right token for your use case.

For examples of how design tokens can be used in components, and common pairings of background and text colors, view the design token examples.

Design tokens are CSS custom properties so for vanilla CSS, Sass and Less, we recommend accessing design tokens in the following way:

1
2
.example {
  background: var(--ds-surface-raised);
}

For CSS-in-JS, we strongly recommend you install @atlaskit/tokens as a dependency and use the tokens() function, which provides additional type safety.

1
2
import { token } from "@atlaskit/tokens";

const example = {
  color: token("color.background.selected.bold"),
};

Please make sure to keep the @atlaskit/tokens package up to date to ensure the tokens suggested are accurate and match the version of tokens injected into your application from the parent product.

For more details, read the tokens migration guide on atlassian.design.

Bespoke color schemes

If your application uses colors that correspond to your unique brand, it is still possible to theme your app by querying the html[data-color-mode] attribute and styling your applications with your own tokens.

1
2
html[data-color-mode="light"] {
  --my-custom-background-token: white;
  --my-custom-text-token: black;
}

html[data-color-mode="dark"] {
  --my-custom-background-token: black;
  --my-custom-text-token: white;
}

If you have an existing dark mode implementation, this attribute can be used to turn it on or off to match the parent product.

Please note, this approach may cause color discrepancies between your app and the parent product, so it’s recommended to use it sparingly.

Staying up to date

Our design tokens will evolve over time, moving through a lifecycle of active, deprecated, and deleted, eventually being fully removed from the theme (no longer functional). Tokens will be marked as deprecated in a minor version, soft-deleted (functional but will raise errors) in the following minor, and deleted in the next major release of the tokens library. All breaking changes to APIs and design tokens will be communicated well in advance, with clear cut-off dates for deprecations.

To simplify the migration and to simplify continuous adoption, we recommend you install and configure the following linters:

These linters will warn and error for deprecated and deleted tokens respectively. They also have built-in auto-fixers that allow you to update your entire app to the latest tokens automatically via eslint --fix and stylelint "**/*.css" --fix.

For the full design tokens reference, please refer to the Design Tokens documentation on atlassian.design.

Surface background colors

In some scenarios you may find that the background color of the element your application is rendered on does not match or differs between in different locations and themes. For example, if your app is rendered inside of a modal or elevated card and dark mode is enabled.

To work around this, we make a special css variable available to your application with the appropriate background color reflecting the current surface your app is rendered on. This variable is updated whenever the surface changes, so you can use it to style your app accordingly.

1
2
import { token } from "@atlaskit/tokens";

const AppStyles = {
  backgroundColor: token("utility.elevation.surface.current"),
};

Rate this page: