RFC-11: Dark Mode & Theming is coming to Confluence Cloud

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
.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.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 appropriate data-theme and data-color-mode attributes to the <html> 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(), 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.

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
:dark_sunglasses:

18 Likes

Hello again, developer community :wave:

We wanted to let you know that we are listening here and if you have any comments or questions, please let us know.

We ask that comments about Confluence theming and dark mode be added by May 26.

Thanks!

2 Likes

Hi @AlexWhite,

Apologies that you have not yet received any response to your RFC. I’ve also posted a reminder in the informal Marketplace vendor Slack channel(s).

To be honest, this might be a bit of an overload. A lot of partners are still working on, and struggling with, implementing design tokens for Jira dark mode (see Start using design tokens in your apps, and try dark theme in Jira Cloud)

2 Likes

@AlexWhite thank you for providing this documentation.
Is there guidance how to integrate the new theming with AUI? I know AUI also has dark mode, and struggle to identify how we could integrate this.

Hi, @AlexWhite!

I started to replace @atlaskit/theme with @atlaskit/tokens in one of our apps and it worked pretty smoothly. The token picker (on the page where all design tokens are listed) and the codemod were especially helpful. :+1:

I’ve only noticed a few issues:

  • For some tokens, the Confluence UI uses other color values than those defined in @atlaskit/tokens. For example, --ds-surface is DarkNeutral100 instead of DarkNeutral0 for the dark theme (see the app background in the screenshot below).
  • The “Original” option in the theme switcher doesn’t seem to work for apps. When “Original” is selected, data-color-mode is set to dark.
  • In some cases, the codemod generates invalid JavaScript code (see the code snippet below).
  • What’s the purpose of the view.theme.enable function? Theme selection and switching seems to work without it, as long as setGlobalTheme is called.
  • It would be helpful if Forge apps could choose different icons depending on the current theme, for example in dynamicProperties functions for content byline items. To be able to do that, the theme would have to be included in the payload or context passed to the handler function.

css={[
  {
    zIndex: layers.layer(),
-   background: "white",
+   background: {token("color.background.input", "white")} // <- Invalid syntax.
  },
  elevation.e200()
]}
1 Like

Thanks for taking a look and sharing your feedback @klaussner!

As for your issues, let me address each and let me know if you need any clarifications:

  • For some tokens, the Confluence UI uses other color values than those defined in @atlaskit/tokens. For example, --ds-surface is DarkNeutral100 instead of DarkNeutral0 for the dark theme (see the app background in the screenshot below).

Confluence recently adopted the not-as-dark dark token values that Jira adopted about a month or so ago after they had received feedback that the dark mode was too dark. The reason why Connect and Forge apps are still showing the darker dark is because the app support for these changes is currently in review by our design system team. It should be a matter of days before this becomes consistent.

  • The “Original” option in the theme switcher doesn’t seem to work for apps. When “Original” is selected, data-color-mode is set to dark.

Based on your screenshot, I am assuming you are seeing this behavior in a Forge app? If that’s the case, there is an issue currently where a Forge Custom UI app will reflect the Confluence theme upon initial render but will not change with Confluence. This will be resolved soon. Does this scenario fit what you’re experiencing?

  • In some cases, the codemod generates invalid JavaScript code (see the code snippet below).

There are definitely some issues and shortcomings with the codemod. We’ve relayed some of these issues back to the design system ourselves. It’s not perfect but usually it saves a lot of time even fixing minor syntax or incorrect token issues along the way.

  • What’s the purpose of the view.theme.enable function? Theme selection and switching seems to work without it, as long as setGlobalTheme is called.

The purpose of view.theme.enable() is to enable theming to sync from Confluence. Apps should not invoke setGlobalTheme themselves since Confluence should be driving that. Apps should use this opt-in theming API to render in whichever theme Confluence is currently set to. The caveat being the current issue w/ Forge Custom UI mentioned above. The nice thing about this approach is that app developers can adopt tokens (with fallback colors) and if they don’t invoke view.theme.enable(), the app won’t follow Confluence theming. This allows developers to make apps ready for theming without enabling it until they are ready for customers to see it.

  • It would be helpful if Forge apps could choose different icons depending on the current theme, for example in dynamicProperties functions for content byline items. To be able to do that, the theme would have to be included in the payload or context passed to the handler function.

This is possible using the Image component from @atlaskit. The component allows you to provide a srcDark so that a different image will display if dark is the active color mode. If you need something more custom or to handle logic outside of images, you can either tap into the useThemeObserver React hook or the non-React equivalent ThemeMutationObserver

3 Likes

Thanks for the question, @marc.

At the moment AUI doesn’t directly utilize design tokens but there is working being done now to migrate its variables to use tokens. This is expected to be released in an upcoming 9.x version of AUI. After this is released and partners utilize this version, elements using AUI classes will have support for light and dark theming baked in.

1 Like

Hello again! We are still open for comments on our approach for 2 more days. Thanks for those who have been following along and for those who have already provided comments.

We have a separate post with many of these same details and announcing a preview of Confluence theming to our partners enrolled in the Developer Canary Program. We’d love to start seeing your apps in beautiful shades of dark :new_moon:

1 Like

Thank you for the detailed answer, @AlexWhite!

This is possible using the Image component from @atlaskit.

Sorry if that was unclear. I didn’t mean icons or images inside the app, but icons that are defined in the app manifest. For example, the icon property of a Confluence content byline item accepts only a single URL or path:

confluence:contentBylineItem:
	key: example
	icon: <URL or path> # <- Theme can't be used here.

Thanks for clarifying, @klaussner.

I discussed this particular question with our Design System team and reviewed some discussions with the Ecosystem Platform team. The solution for dynamically changing the icon based on theme has not yet been solidified and our recommendation at this time is to utilize a single icon which displays well in both light and dark color modes. This can be achieved directly via color choice or by using a light border around a darker icon which allows for it to be distinguished in dark mode.

We’ll follow-up when we can provide any more specific guidance.

1 Like

Thanks for taking the time to review our proposal for user-driven theming for apps in Confluence Cloud. There were no significant issues raised with our proposal so we will plan to continue with the solution. We hope by keeping consistent with the approach laid out by the Atlassian Design System (ADS) and Jira that preparing your Confluence Cloud apps for theming is more familiar and takes less time to implement and maintain. Please continue the discussion in our recent announcement which communicated the opening of Confluence theming for the Developer Canary Program to preview.

Thank you!
Alex White, Engineering Lead, Confluence Cloud Ecosystem
:dark_sunglasses:

1 Like