Start using design tokens in your apps, and try dark theme in Jira Cloud

Hey folks, the changes mentioned above will be rolling out on Mon 27 Feb 2023 — please read the thread for more details of actions required. Thanks!

These changes are now live for Connect!

Please go ahead and follow the instructions in the thread below to upgrade, and let us know of any questions or help needed:

Hi Stephen,

I have tried to call the window.AP.theming.initializeTheming() this morning but it doesn’t seem to work as before the changes.
I don’t see in the <html> part of the iframe any data-theme or data-color-mode attribute, so no color theme gets triggered.

If instead I call directly the setGlobalTheme API I see the styles being added to the <head> and the <html> containing the data-color-mode chosen.
The problem is it doesn’t reflect the Jira Personal Settings, because if you choose auto as colorMode it reflects the OS setting.

Am I missing something?

Hey @AndreaSerra,

There was a deployment issue yesterday that meant an older instance of all.js was persisted in prod.
We just fixed that so it should be functional again now. Could you give it a try and let us know if you have any further issues?

Cheers :slight_smile:

Today I’ve tried and it is working good, very nice ! :smiley:

1 Like

We started implementing the dark mode patterns, but noticed a weird behaviour in the dialog iframe. Before (and still) in light mode, the iframe has a seemingly transparent background.

When the dark mode is turned on, the background of the whole iframe becomes filled.

Which persists even after calling AP.theming.initializeTheming()

Is this something we are doing wrong? After inspecting the HTML, the source of the filled iframe background remains unclear…


Something similar to what Leon describes also happens with dashboard gadgets: the iframe is drawn in white, before the actual iframe content loads. This causes 3rd party gadgets to always flash a white rectangle before they manage to enable theming.

Oh, it looks like this is an issue on our side. What I suspect happened is the previously transparent modal has been given a surface token. So when tokens are turned on it displays a coloured background as opposed to being see-through.

I’ll hand this feedback over to the team – Thanks!

1 Like

Hey @DanielDelCore ,

I am a bit confused now - do I have to opt-in somewhere with a specific instance to access this method or should this now be available for everyone - I am confused by the timelines and rollouts.
I further heard at APP week Berlin that Atlassian rolls out features in an incremental approach, so can you can please confirm that this method should be available on all cloud instances - because for me it comes as undefined? But maybe I am also doing something wrong here.


So if you could once again elaborate on the exact steps I have to follow to enable my connect app to invoke this method that would be just awesome.

Thank you very much in advance for your time.

Best regards,


1 Like

Hey @DanielDelCore, i noticed another issue.

When deactivating the Jira theming, AP.theming.initializeTheming() always sets the data-color-mode=“dark” attribute:

Seems like the initializeTheming() function doesnt respect the setting whether theming is enabled or not?

Hi @MartinKistnerDecadis,

I appreciate it’s confusing right now during the roll-out. Yes, right now you need to let us know about your instance(s) to start developing with tokens and theming. I’ll recap…

Today — during early access program:

In the future — we’ll let you know the date:

  • You’ll only need to call window.AP.theming.initializeTheming()
  • Themes will be visible on all instances

Once your instance is enabled, follow the combined instructions we’ve published here:
Theming Connect Apps –
(it combines what’s in the top of this thread + updated API in tokens 1.0.0)

The team are also currently working on improvements to so that all the docs for getting started with design tokens and theming is easier to find. I’ll share when that’s done.

And @LeonRothYasoon: Thanks for letting us know! That issue has been resolved and you should see the fix roll out in about 24 hours.



Thank you very much for taking the time to summarize it again and thank you to all Atlassians working on the change towards a token-based approach I think it’s really great way! @stephenmok :slight_smile:

I now submitted the google docs and would be looking forward to applying tokens to our connect apps.

Will I receive an e-mail when the instances I have submitted are activated for access the method below?


Thank you very much in advance!

1 Like

Hey @MartinKistnerDecadis,

Thanks for signing up!
I’ve just enabled your instance so you should have an email in your inbox detailing next steps.
Feel free to reach out here of via email if you have any further questions.


1 Like

Hi @stephenmok, @DanielDelCore! We’re still not seeing the correct behavior on our instances, any news about the deployment of the fixes?

Since we’re on the subject: I realize that this is still beta code and stuff can break. But it is extremely important that it should break only for users that have enabled theming in their lab features! If we can’t trust the code will not affect the clients who don’t enable (or know about) theming, then we can’t deploy the code to production at all, so nobody can beta test our app theming even if they want to.

The part of the code that checks the lab feature and does absolutely nothing if it’s disabled needs to be rock-solid.

1 Like

There is no window.AP.theming method, it comes as undefined. Please help

@DanielDelCore thanks a lot :slight_smile:

Hey @bbutnaru @GauriYadav :wave:

Could you both confirm that you have been enrolled into the program? If so, could you share your company name so I can reach out via email? Or feel free to reply directly to your enrollment confirmation email and I’ll jump in.

There is no window.AP.theming method, it comes as undefined.

Currently, this method is only available in enabled development instances and will be undefined in production until we lift our feature flag, so please be sure to null-check before using the method in prod.

We’re still not seeing the correct behaviour on our instances, any news about the deployment of the fixes?

We’re currently working through the bugs raised by @LeonRothYasoon and others as a top priority, aiming to publish them within a week or so given no other blockers are found.

But it is extremely important that it should break only for users that have enabled theming in their lab features!

Agreed, it’s absolutely essential that all users (labs or otherwise) have completely functional experiences, we’ll treat any production issues as official incidents. Your emphasis on stability is completely justified which is why we are intentionally moving slowly but surely to ensure we get it right before we go to prod :slight_smile:


1 Like

Hey @DanielDelCore

not sure if this is intended, but the --ds-surface token always returns a static color. Given that you can open issues in the modal (e.g. from boards) where the issue background is lighter, our apps using --ds-surface now appear too dark:

Is this intended meaning we should apply a different background token ourselves when opened in the modal?

Hi partners,

In the future — we’ll let you know the date:

  • You’ll only need to call window.AP.theming.initializeTheming()
  • Themes will be visible on all instances

The future I mentioned above is just about here!

Progressively during next week, beginning Mon 27 Mar 2023, we will be enabling theming of Marketplace apps built with Connect across all customer instances of Jira Cloud. (Support for apps built with Forge will follow soon, and I’ll let you know that date once confirmed.)

From that point, any Marketplace partner will be able to start developing with design tokens and theming immediately — no need to fill in the form to enrol in early access. Go go go! :smiley:

Customers will see Marketplace apps themed if both of these are true:

  • They have turned on light/dark themes in Jira labs in their personal settings; and
  • Your Connect app calls window.AP.theming.initializeTheming()

This means you should take care to not ship to customers in production until you’re ready any version of your app that calls initializeTheming(). Otherwise, customers will see the partially-themed app you’re working still on.

We’ll update what we’re communicating to customers so they know the first themed Marketplace apps will start to show up, but the message will continue to be that it’s a work in progress and you’re all working hard on getting your apps ready!

Separately, a heads-up that we’re acting on feedback from both customers and partners and are making tweaks to improve the colours used in both light and dark themes, so expect to see more of that in the coming weeks.

As always, please reply and let me & the team know with your questions!



Thanks for the update, Stephen! Our app is mostly ready, the only thing that’s keeping us from deploying the code to production is uncertainty about how it will interact with the initializeTheming part. One issue with the progressive deployment of new features is that it’s hard to be sure that what we’re seeing during tests is the same thing customers see.

Is there some way of ensuring that some of our test instances are always in the first deployment cohort (so we can test the feature in advance) and that other instances are always in the last deployment cohort (so we can investigate if a customer who did not get the feature yet has issues), for this particular deployment?

(We have both some EAP instances and a premium instance on the “bundled” release track, which are supposed to be that. But we have very little visibility in what is deployed where and when, and we’ve seen changes bypass both. So in practice we need to be extremely conservative with releases, for fear a customer will get behavior that we can’t reproduce.)