Hello, Bitbucket Cloud developer community 
Bitbucket Cloud dark mode and user-driven theming are coming later this year, and we are inviting Forge and Connect developers to come along for the journey!
Please take some time to read this Request for Comment (RFC) and provide any feedback as you evaluate the changes. Whether you’ve already had experience with theming or if it’s your first time, we would like to understand any challenges (and hear about your successes!) as you work with Atlassian design tokens.
Summary of project
Bitbucket Cloud 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 when using Bitbucket Cloud.
We are targeting ~October 30, 2024 for a beta launch to all customers. General availability (GA) will follow in early calendar 2025.
Timeline
Here are the milestones for you to keep in mind as you provide feedback on this RFC.
- Publish: August 30, 2024
- Discuss: September 13, 2024
- Resolve: September 30, 2024
Problem
Dark Mode is a highly-voted feature by customers and an expected standard for Atlassian Cloud products, and Bitbucket Cloud is pleased to be following suit.
Later this calendar year (~October 30, 2024) we will be launching a customer beta of user-driven theming, as well as dark mode, in Bitbucket Cloud.
Our new themes will give users better visual contrast between elements, provide more color consistency within Bitbucket and across Atlassian products, and provide accessibility improvements. But it won’t happen automatically across every single Bitbucket Cloud experience.
It’s important that apps contribute to the consistent experience our customers expect. To support a smooth transition, we are proposing that Bitbucket app developers closely follow the guidance recently provided for adoption of tokens in Jira and Confluence apps.
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 an app 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 Bitbucket makes in the future. Customers will see a consistent experience across Bitbucket and all tokenized apps without additional development time on your part.
As of publication of this RFC (August 30, 2024), developers can follow the instructions below to test Connect and Forge apps in dark/light mode. While Bitbucket 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 are aiming to get as much developer feedback and adoption of design tokens as possible in advance of our beta release of theming to all Bitbucket customers on ~October 30, 2024.
General Availability (GA) will follow in early calendar 2025, by which time we hope to see the vast majority of apps having adopted design tokens.
Proposed solution
In alignment with our Jira and Confluence teammates, we are proposing to closely follow the guidance they provided in the ways apps add support for user-driven theming. If you have recently converted apps for Jira or Confluence, 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 appropriate data-theme and data-color-mode attributes to the tag based on the theme defined by Bitbucket. 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 Bitbucket):
<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();
Testing your app in dark mode
- Prior to the customer beta release, the dark/light theme switcher will not appear in the Bitbucket UI. However, we provide a method below to allow developers to fully test their apps in dark/light mode. This method is available starting from the publication of this RFC (August 30, 2024).
- To simulate theme selection (and thereby test your app in dark or light mode), run one of these commands from your browser’s js console, then refresh the page:
// set dark theme
localStorage.setItem('bitbucket.global.theme', 'dark');
// set light theme
localStorage.setItem('bitbucket.global.theme', 'light');
- Once you have set this
localStoragevalue, the setting will persist from page to page. - The above method will work in the majority of cases. However, as of publication of this RFC, some Connect extension points (e.g. the profileTabs module) will require you to run a different js console command in order to simulate dark/light theme selection.
- If you find that the
localStoragemethod above doesn’t work on certain pages, use one of these commands instead:
// set dark theme
window.setTheme('dark');
// set light theme
window.setTheme('light');
- If you receive the message
Uncaught TypeError: window.setTheme is not a function, it means that your developer console is in the wrong context. Ensure you are right clicking inside the iframe that the Connect app is loaded in before opening the js console. - Because these commands are run on the
windowobject, they will only have effect during your current pageview. You will need to run them again if you refresh the page. - During your testing, you will observe that the Bitbucket UI & navigation are in the process of being updated for theme switching. Some areas of the UI are not quite done, so don’t be surprised if you see things that look incomplete. Rest assured that we’re working on it!
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 Bitbucket 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
Prior to the beta release, the default theme for customers will be Original, which will render the soon-to-be legacy Bitbucket colors (i.e. no tokens enabled). So, it will be important to provide your original fallback colors when using design tokens, so that the UI will properly render when no theme has been specified. For @atlaskit components, this is already handled.
Providing fallback colors will also allow you to deploy updates to your app immediately (ahead of the beta release) without any impact on customers.
We plan to remove the Original option in our GA release, so all apps will need to use design tokens before this happens.
Note: By following the instructions in this section, you should be able to complete & deploy changes to your app ahead of time, without requiring you to coordinate a release of your app with the beta launch.
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 also Jira’s guidance on keeping Connect apps up to date with design token changes.
Asks
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 September 13, 2024, 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).
- If possible, make your app ready for dark mode / theme switching ahead of the planned customer beta release date (~October 30, 2024). You can deploy changes to your app as soon as you are ready, from publication of this RFC.
- We are eager to see how design tokens look in as many different Bitbucket experiences as possible, so please share screenshots or videos!
- Ask questions in this post.
Thank you!
Dave Parrish
Product Manager, Bitbucket Cloud
?