Hello Marketplace Partners 
We recently announced and requested comments about user-driven theming coming to Confluence using updated colors and elevations within the Atlassian Design System, powered by a new approach: design tokens. Design tokens will simplify the process for designers and engineers alike to build experiences, make them more easily accessible (such as improving contrast), and support theming — including light/dark themes coming to Confluence Cloud later in 2023.
We’ve been busy incorporating design tokens in Confluence Cloud over the past few months to support new light and dark themes. We’re thrilled to share that these themes are now accessible to preview by Marketplace partners within the Developer Canary Program. These new themes are still a work in progress with gaps that will be progressively filled in the coming months (see specifics below). You’ll be able to try out Confluence in dark theme and see how your app fits in. We are aiming to release theming access to a small percentage of customers between June and July 2023 to get more eyes and hands using theming for broader feedback. We want you, our Marketplace partners, to have the earliest access to get you started with plenty of time for you to adopt before we move into a Beta phase, followed by General Availability (GA) later this year.
How to Enable Themes
- If you’re not already part of the Developer Canary Program, sign up here.
- Open your profile menu from your user avatar in the top right of Confluence, select “Theme”, and choose a theme from the pop-up menu.
Supporting Themes in Apps
Consistent with the guidance provided in our RFC, all apps will need to adopt design tokens in order to render correctly in the new light and dark themes. Apps taking advantage of @atlaskit components will require less effort because design tokens are already incorporated into those components.
- See how to use design tokens in code and reference the JavaScript API
- To view, search and filter through the available design tokens, visit All design tokens
- For CSS, SASS, and LESS, design tokens are used through css variables. For example,
.example {
background: var(--ds-surface-raised, #E0E0E0);
}
- For CSS-in-JS, design tokens would be used through the @atlaskit/tokens npm package. For example,
import { token } from "@atlaskit/tokens";
const example = {
backgroundColor: token("color.background.selected", #DEEBFF),
};
- In both of the above examples, the first value represents the token, or variable, that defines a color when a theme is active. If that variable is not defined (no theme is active), the second value is used as the fallback.
Connect Apps
- Connect apps should follow the approach as detailed in Theming Connect Apps. In particular, Connect apps would need to invoke window.AP.theming.initializeTheming().
- Invoke window.AP.theming.initializeTheming() as early as possible in your application startup to avoid any “flashing” of nonthemed elements before theming is applied. This will apply the appropriate data-theme and data-color-mode attributes to the tag based on the theme defined by Confluence.
- For example,
<html>
<head>
<style>
:root {
background-color: var(--ds-surface);
}
</style>
<script src="https://connect-cdn.atl-paas.net/all.js"></script>
</head>
<body>
<script>
window.AP.theming.initializeTheming();
</script>
</body>
</html>
- After invoking window.AP.theming.initializeTheming(), your app will pull the theme information from Confluence and the HTML tag of your app should look something like:
<html data-theme="dark:dark light:light" data-color-mode="dark">
Forge Apps
- Forge apps using UI Kit without any color customizations will automatically inherit tokens.
- Forge apps using Custom UI will need to apply design tokens as described above. The implementation would follow closely to what was described for Connect apps. See more about Theming Forge Apps. In particular, Forge Custom UI apps would need to invoke view.theme.enable():
- Invoke view.theme.enable() as early as possible in your application startup to avoid any “flashing” of nonthemed elements before theming is applied. This will apply the appropriate data-theme and data-color-mode attributes to the tag based on the theme defined by Confluence, consistent with the solution described above for Connect apps.
import { view } from "@forge/bridge";
view.theme.enable();
NOTE: Currently there is a known issue where Forge Custom UI apps will render in the same theme as Confluence but will not stay in-sync with Confluence if the theme is changed while the Forge app is rendered. We will provide updates when this issue is resolved.
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.
However, we advise against this in nearly every case because a set of colors that don’t use tokens would not stay up to date with any changes we make to Confluence in the future. It might look great on Day 1, but you could have to do the same work all over again on Day 500 (or sooner).
For example,
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;
}
See Bespoke color schemes for more detail.
Backward Compatibility
In the short term, the default theme will be Original, which will render the soon-to-be legacy Confluence colors (i.e. no tokens enabled). So, it’ll be important to provide your original fallback colors when using design tokens so it will still render when no theme has been specified. For @atlaskit components, this is already handled.
NOTE: We plan to remove the Original option in our GA release, so all apps will need to use design tokens before this happens.
Staying Up-To-Date
Design tokens may evolve over time through a lifecycle of active, deprecated, and deleted. All deprecations will be communicated well in advance with clear cutoff dates.
To simplify the migration and adoption, we recommend you install and configure the following linters that will provide warnings and errors for deprecated and deleted tokens. They also have built-in auto-fixers that allow you to update your code via eslint --fix and stylelint --fix.
- For CSS-in-JS we provide an eslint plugin: @atlaskit/eslint-plugin-design-system
- For CSS, SASS, and LESS we provide a Stylelint plugin: @atlaskit/stylelint-design-system
See Staying up to date for more detail.
Current Confluence Gaps
These experiences have not yet been fully converted to use design tokens and as such will look particularly odd using the dark theme. We will be progressively closing these gaps in the weeks and months ahead.
- Global Admin/Settings pages
- Space Admin/Settings pages
- Whiteboards
- Personal Settings
- PDF Export
- Page History
- Page Info
- Atlassian-developed Connect & Forge apps
- Custom illustrations / icons
What’s Next?
Please take the time to review design tokens, the guidance provided here, as well as the linked documentation. If you have questions or concerns, please share them here - we’re listening.
Remember - your tokens will only be activated when you’ve opted-in to theming and when a theme is set in Confluence. Furthermore, this feature will only be enabled for a limited set of customers for the next few months.
Even if you’re not ready to opt-in to theming via the respective Connect and Forge APIs, we hope you’ll start adjusting your apps to use design tokens soon and can try them out in your sites. We’d love to see your progress!
Thank you!
Alex White, Engineering Lead, Confluence Cloud Ecosystem
