Announcing Confluence Cloud Theming Preview for Developer Canary Program

Hello Marketplace Partners :wave:

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

  1. If you’re not already part of the Developer Canary Program, sign up here.
  2. 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.

.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.

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

5 Likes

Dear @AlexWhite

thanks for sharing this information.

I have two concrete questions:

  1. Can you already foresee how the solution will look like for icons - e.g. the ones shown in the side-bar for custom content? We currently use SVGs for those which Confluence wraps inside an img tag => no styling goes down to the SVG.
  2. Our UIs are based on AUI not atlaskit. We will for sure use the dark mode of AUI but for this it would be very helpful to get the color-mode back from window.AP.theming.initializeTheming(). In case this is not possible is there any alternative apart from a mutation observer checking when data-color-mode is added to the html tag?

Thank you and best regards

Andreas

2 Likes

Thanks for the question, @andreas1

Some answers to your questions:

  1. 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 app 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.

  2. At the moment AUI doesn’t directly utilize design tokens but there is working being done now to migrate its variables to use tokens. And its existing themes will be ported to use design 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.

As an aside, if you need access to the current color mode from your app, you can utilize useThemeObserver in React code and ThemeMutationObserver in non-React code.