Dark theme EAP in Confluence Data Center

[jhronik]

Hi everyone,

We’re pleased to introduce early access to dark theme for Confluence Data Center!

Dark theme will be officially rolled out to customers as part of an upcoming Confluence Data Center release after May 2024. You can follow our community announcements and release notes for details about the offical release.

Users will be able to choose between light or dark theme as their preferred interface to help them better focus on their screen, reduce eye strain, and improve contrast for better accessibility. You can read more about the benefits of dark theme in our earlier announcement.

How to enable dark theme in Confluence

Once you’ve installed the EAP (8.8.0-beta1 download available from Preparing for Confluence 8.8), you can switch to dark theme by following these steps:

1. Enable the theme.switcher dark feature.
2. Select your avatar in the top right corner of the screen
3. Click on Theme and then select Dark.

If you’re already using dark theme on your device, you can select Match system and Confluence will automatically switch to dark theme.

If you need more details on how to enable a dark features, refer to Dark Features in Confluence.

Original theme vs. light theme

You’ll notice that the theme options also include Original and Light. While they both have the same “light“ user interface, they are technically different.

Original theme is the current view of Confluence, using colors that you’re familiar with. Customers may want to continue using original theme until the apps they use have adopted the new design tokens. This theme is a transitional measure and we intend to remove it once we’re confident that your apps have no issues adopting the new light and dark themes.

Light and dark themes use design tokens – name and value pairings for repeatable design decisions.

For example, a design token might be a color or a font style. To learn more about design tokens, see What are design tokens?

How to prepare your apps for dark theme

To achieve a consistent experience for all users, we need your support. Adopting design tokens in your apps is key to this and will ensure that colors are reflected correctly everywhere in Confluence. Below are guides to support developers and designers in this change.

After you’ve adjusted your apps to dark theme, you may also want to update the screenshots on Atlassian’s Marketplace to highlight the new experience to customers.

I’m a developer

A complete guide on how to prepare your app for dark theme: Preparing your Data Center app for dark theme.

The editor from Confluence 8.8.0 will internally use design tokens, including in the content.

<iframe> tags

<iframe> tags and content using the Confluence rendering pipeline will have the theming resources and theme activation provided by Confluence by default. Internally, it uses:

• URL query parameters to pass the theme of the parent page in the <iframe> tag’s src attribute:

atlThemeColorMode = light | dark
atlThemeDark = dark
atlThemeLight = light | original
atlThemeMatchUa = false | true

• Server-side rendering of the HTML attributes by the atlassian-theme plugin. See HTML API for details
• Theming resources and design token API provided by web-resources

com.atlassian.auiplugin:aui-design-tokens-themes
com.atlassian.auiplugin:design-tokens-api

• Event listener to the theme changes provided by web-resource

com.atlassian.confluence.plugins.confluence-frontend:theme-switcher-listener

An <iframe> tag loading an external site needs to handle the dark theme support using the above URL query parameters and listening for the theme change event using theme.change message type inside the <iframe>:

window.addEventListener("message", (event) => {
    try {
        const {type, colorMode, darkThemeKey: dark, lightThemeKey: light} = JSON.parse(event.data);
        if (type !== "theme.change") return;
        // Activate the new theme
        window.AJS.DesignTokens.setGlobalTheme({ colorMode: colorMode.toLowerCase(), dark, light });
    }
    catch (e) {
        // Handle error
    }
});

I’m a designer

See this guide on the new design tokens for dark theme: Migrate to tokens

Interaction with existing Confluence features

Customizing Color Schemes will only apply customizations in the Original and Light themes. Dark theme does not yet support custom colors.

Need help?

If you need any assistance with dark theme or have feedback you’d like to share, please reach out to us by leaving a comment under this post.