[part 5/5 — back to top]
Detailed steps to update your apps to support theming
Enabling instances for theming, and planned API changes
Updated Mar 2023:
- You no longer need to fill in a form to enrol your instances to start developing using design tokens
- Themes are now enabled on all instances, including for customers if they have themes tuned on in the Jira labs section of their personal settings
- Getting started now? Awesome! Follow the latest instructions on one page here: Theming Connect Apps – developer.atlassian.com
- Already developing as part of early access? Read the update in this message below
Right now, you need to opt-in to your development instance by letting us know, so that it is manually enrolled in the early access program. All necessary theme configuration CSS files will then be automatically injected into apps, only on those instances, and the DOM of your app will be updated onload.
To reiterate: customers will not see your apps in light/dark theme yet, only you will on those instances
We recognise that automatic configuration within your app’s iframes is not ideal long-term (thanks again for your feedback on this topic!) and we are currently working on an additional API to give you more control over initialising theming. This will make theming an explicit opt-in that you will be able to self-service. This is expected to be available in January. At that point, we plan to enable themed rendering of your apps to customers if you have opted-in in code and they have opted-in via Jira labs.
Don’t want to wait? Want to start migrating your app right now using the current method? Fill in this form to let us know about your development instances, and we’ll enable access.
Once enabled, applications powered by Connect, Forge UIKit, and Forge Custom UI 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 whilst shown in Jira.
<html data-theme="dark" data-color-mode="dark">
<head>
<link rel="stylesheet" type="text/css" href="path/to/css/files.css">
</head>
<body>
<!-- Your app here -->
</body>
</html>
Pay special attention to the data-color-mode="dark" attribute, and also note the data-theme="dark" attribute. These reflect the current theme state of the parent product (Jira). 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" represents the active theme(s), but this is internal behaviour 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. Hence please only rely on data-color-mode as above.
It’s time to 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 which, through a series of questions, will 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:
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.
+import { token } from '@atlaskit/tokens';
import { B400 } from ‘@atlaskit/theme/colors;
-color: B400
+color: token('color.background.selected.bold, B400)
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 Jira.
For more details, read the tokens migration guide on atlassian.design.
Backward compatibility
If you publish a tokenized version of your application during the pilot program, you will need to use fallback colors in addition to design tokens to ensure there are no visual changes exposed to end users, since tokens will not be active for all customers until general availability.
This involves using CSS custom property fallbacks:
/* CSS, Sass, Less */
background: var(--ds-surface-raised, #eeeeee)
/* CSS-in-JS */
import { token } from '@atlaskit/tokens';
import styled from 'styled-components';
const App = styled.div`
background: ${token('elevation.surface.raised', '#eeeeee')};
`;
Whenever a design token is not found, the fallback value will be shown instead. These values should always contain the color in use prior to adopting tokens. If done correctly, your app will appear with no visual changes until we globally enable light/dark themes, at which point tokens will be automatically enabled and shown in your application.
If you are creating new experiences with design tokens, please continue to use both a token and a fallback value. This will be necessary until design tokens are globally enabled as the default color experience across Atlassian products.
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.
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;
}
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 are designed to 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.
Please also review the @atlaskit/tokens changelog to monitor changes to tokens and API.
To simplify the migration and to simplify continuous adoption, we recommend you install and configure the following linters:
For CSS-in-JS we provide the following eslint plugin: @atlaskit/eslint-plugin-design-system
Install: npm i -D @atlaskit/eslint-plugin-design-system
Configure:
// .eslintrc.js
module.exports = {
rules: {
'@atlaskit/design-system/ensure-design-token-usage': ['error', { 'shouldEnsureFallbackUsage': true }],
'@atlaskit/design-system/no-deprecated-design-token-usage': 'warn',
'@atlaskit/design-system/no-unsafe-design-token-usage': ['error', { 'shouldEnsureFallbackUsage': true }],
}
};
For vanilla CSS, Less, Sass we provide the following Stylelint plugin:
Install: npm i -D @atlaskit/stylelint-design-system
Configure:
// .stylelint.js
module.exports = {
rules: {
'design-system/ensure-design-token-usage': true,
'design-system/no-deprecated-design-token-usage': [true, { severity: 'warning' }],
'design-system/no-unsafe-design-token-usage': [true, { shouldEnsureFallbackUsage: true }],
},
plugins: [
'@atlaskit/stylelint-design-system',
],
};
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 .
Known issues and FAQs
Server-side rendering
Currently, support for server-side rendering (SSR) is not yet available. Apps utilising SSR may experience intermittent flashing between light/dark themes when loaded. If you are experiencing this issue, please make sure to let us know the details of your SSR solution so we can take that into account in our upcoming work.
Charts/HTML Canvas
Our design tokens are based on CSS custom properties (aka CSS variables), which makes it challenging to use tokens in JavaScript. For scenarios where knowledge of token values in JS is necessary, such as dynamic data visualisations via HTML Canvas, it’s not yet possible to use tokens. We are working on this and will be sharing a new API to support this early next year.
Illustrations and dark theme images
We are currently creating tools & guidance for switching graphical assets to match the active theme. We’ll share more information on this shortly.
My app uses ADF, how do I render colors in dark theme?
If you have a custom ADF renderer, please let us know. Special handling is required, and we’ll work with you on the details.
An @atlaskit component still appears in light theme even when dark theme is active.
Most @atlaskit components have been instrumented with the new design token API. It’s possible that you are using a version of the component before tokens were added. If this is the case, please upgrade the component to the latest version.
Review the changelog in the “Code” tab of the component’s docs to see which version introduces design tokens. For example: @atlaskit/avatar. If the problem persists after you have upgraded, please let us know.
What if my apps are for both Cloud and Data Center?
The Atlassian Design System represents how we’ll be designing Atlassian products into the future, even as we continue to support Data Centre (DC). We’re continually investing in our Design System, and we recommend you standardise your app’s design on the latest and greatest: the colors, elevations and design guidance that we’re introducing here.
Using design tokens as the starting point will make it easier for you to keep experiences familiar between your app and the parent product, as many customers move to Cloud.
We’re primarily focused on supporting apps in Jira Cloud today. But we’re open to ideas for how we can make it easier in the future for those of you who develop for both Cloud and DC, so please reply and let us know.
…
Once again, thanks for your support and please reply below if you have any questions.
We’ll be adding docs to atlassian.design with all of this info as well, once the planned API changes mentioned above are finalised. Happy tokenising!
[part 5/5 — back to top]
