Hi developer community,
Confluence Cloud Dark Mode and user-driven theming are coming! Please take some time to read our Request for Comment (RFC) and provide any feedback as you modify your apps to support themes. We would like to understand any challenges (and hear about your successes!) as you work with Atlassian design tokens.
RFCs are a way for Atlassian to share what we’re working on with our valued developer community.
It’s a document for building shared understanding of a topic. It expresses a technical solution, but can also communicate how it should be built or even document standards. The most important aspect of an RFC is that a written specification facilitates feedback and drives consensus. It is not a tool for approving or committing to ideas, but more so a collaborative practice to shape an idea and to find serious flaws early.
Please respect our community guidelines : keep it welcoming and safe by commenting on the idea not the people (especially the author); keep it tidy by keeping on topic; empower the community by keeping comments constructive. Thanks!
Summary of Project:
Confluence is joining the ranks of other Atlassian products by adopting user-driven theming enabled by the Atlassian Design System and its design tokens. Once released, users will be able to choose between Light, Dark, and Match System (derived from the browser/OS) theme options.
Here are the milestones for you to provide feedback directly here on the RFC.
- Publish: May 6, 2023
- Discuss: May 26, 2023
- Resolve: June 2, 2023
The Problem
Dark Mode in Confluence is a highly-voted feature by customers and Confluence is listening!
Our new themes give users better visual contrast between elements, provide more color consistency within Confluence and across Atlassian products, and provide accessibility improvements. But it won’t happen automatically across every single Confluence Cloud experience.
It’s important that apps contribute to the consistent experience our customers expect. To support a smooth transition, we want to propose that Confluence app makers closely follow the guidance recently provided for Jira apps to help them adopt design tokens.
NOTE: To learn more about design tokens, see What are design tokens?
We want users who choose a theme to have a great and consistent experience editing and viewing content – regardless if that content is native or comes from apps. This means we will need your support in adopting design tokens into your apps so that the colors in content are consistent. This is especially true in dark mode when a macro is still showing original colors against a dark background.
We also want to point out another benefit of taking the time to implement design tokens now. Not only will your apps be ready to live alongside our new themes, but they will also automatically stay up-to-date with any theming changes/additions Confluence makes in the future. Customers will see a consistent experience across Confluence and all tokenized apps without additional development time on your part.
We are looking to get your feedback now as we aim for an Alpha release to a small number of customers between June and July 2023. We want to get as much of your input as possible and provide plenty of time for you to adopt before we move into a Beta phase, followed by General Availability (GA) later this year. Starting in mid-May, sites within the Developer Canary Program will receive access to theming so that you can start testing your changes. While Confluence won’t be completely converted to design tokens by this time, we feel it’s important to give you this early access to get feedback and plenty of time to adopt tokens. We will announce once this is available.
NOTE: The Confluence adoption and rollout are managed separately from Jira, Trello, and other Atlassian products’ dark mode and theming rollouts. Confluence will maintain an “Original” theme option until GA which gives you the ability to validate your apps still look fine without theming while you’re working through this adoption.
Proposed Solution
In alignment with our Jira teammates, we are proposing to closely follow the guidance they recently provided in the ways apps add support for user-driven theming. If you have recently converted apps for Jira, this will look familiar.
All Apps
- Connect & Forge apps would need to adopt Atlassian design tokens within their apps
- 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/tokensnpm package. For example,
import { token } from "@atlaskit/tokens";
const example = {
backgroundColor: token("color.background.selected.bold", #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 would follow the Jira 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 non-themed elements before theming is applied. This will apply the appropriatedata-themeanddata-color-modeattributes to the<html>tag based on the theme defined by Confluence. - For example,
- Invoke
<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(), the HTML tag of your app should look something like (pulling this theme information from Confluence):
<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. Specifically, how to opt-in:
import { view } from "@forge/bridge";
view.theme.enable();
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 on Jira’s guidance.
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.
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 on Jira’s guidance.
Actions
We’re here to support this transition. Here’s how community members can help:
- Take the time to absorb the information provided above and ask questions. We ask that all comments for this post be added by May 26, 2023, but that won’t be the end of the conversation.
- As you work through each step with your apps, provide feedback to us (both good and bad).
- We are eager to see how design tokens look in as many different Confluence experiences as possible, so please share screenshots or videos!
- Ask questions here and in the community.
Thank you!
Alex White, Engineering Lead, Confluence Cloud Ecosystem
