Introducing design tokens, new colour foundations and dark mode

@DanielDelCore is there any provision for the app to programmatically select a the theme (i.e., override the global setting), both for the whole app iframe or for a sub-tree of the document? I can’t find anything like that in the docs.

I found it. The extension used to be mirrored in this repo. The linked files might be out-of-date. To make it run: Check out the repo. Switch to the directory. Remove prettier references from package.json (Atlassian prettier config is in a private repo). Install babel-loader@8 directly into this directory. Run “npm run build-chrome-extension”. Then load …/dist/tokens-browser-extension/ as Chrome extension in developer mode.


@Atlassian: Why do we have to do this kind of Reverse Engineering? Can you please share the up-to-date version of this Chrome extension?


Hey all, lots to unpack here, I’ll try my best to address everything but forgive me if anything is missed.

Firstly, just a reminder that we are very early in the integration process. The details we’ve shared above are for the MVP, but we fully expect your feedback to help shape the end product, this is why we created this post. We’re still learning and open to making changes so please continue sharing your feedback. From what I’ve read so far, these are all fair concerns and I’ll make sure they’re captured. I’m keen to work with you folks to understand more, so feel free to share specifics here or we can reach out via email if you’re interested.

If I don’t want to apply theming to my apps, I should be able to do this without having to be concerned about Atlassian injecting code into MY document and altering behaviour of components.

Is there a reason why the Design System Team is not going for a more unopinionated approach and allow the consumer to decide how to implement theming?

@remie @danielwester, this is totally understandable, with the current automatic orchestration it would activate tokens in Atlaskit components even if your app is not ready or willing to be themed. I can see how that would be a problem. The original intent of this was to make it so there was very minimal configuration overhead necessary to use tokens. But I think, given these points, we should revisit that.

How would you feel about having one or more AP methods trigger & listen to it instead, even if it does modify attributes on the HTML element?

It is not your decision to change how my app renders. That is entirely on me.

I agree with this, similar to the point above, we can make it a deliberate opt-in.

Will you document the data attributes that you’re setting as 100% expected behaviour so that we can rely on it?

@danielwester The changes we do make to the page will be limited to HTML data attributes and style tag insertions, but will not change the way your custom UI renders if it is not also using our design tokens. We’ll try to keep this as passive as possible. And yes, these will be well-documented and dependable behaviours.

If our app uses server-side rendering, this now means that the page gets rendered, then all.js loads and does its thing, and then theming is supposed to kick in after that.

We’ve not tackled SSR yet, we need to make some changes to factor it in, but I would expect this to work with some additional configuration. I’m going to talk to a few folks internally this week to see how we can approach it and get back to you.

Can we get the secret atlassian theme chrome extension for app development?

Why do we have to do this kind of Reverse Engineering? Can you please share the up-to-date version of this Chrome extension?

Great find @julianwolf & @lkimmel, the chrome extension is something we are planning to share with everyone as a theming development tool, it allows global theme switching from anywhere in the App.

At this time we have not publically shared the extension, but we plan to do so once theming is opened up to the ecosystem and is ready for developers to begin migrating their apps.

Thanks again for jumping into this post, the team and I will continue to monitor the comments here and try our best to answer to the best of our ability.



Any updates on the Design Tokens plugin for Figma? Excited to put this to use!

Hi everyone,

We’re really excited to announce that we’re launching early access for you to try light/dark themes in Jira Cloud today, and also get started with updating your apps to use design tokens and theming! This includes:

  • Light/dark theme ready for you to preview via Jira labs
  • New Figma libraries and plugin to help you design with tokens now available
  • Detailed steps for update your apps to support theming — including how to enable your development instances, and planned API changes based on your feedback (thanks!)

Read all about it over here:


1 Like

Thanks for this feature!

Can I ask why the text and background colors are not named symmetrically? I’m worried about how tokens will work together. Every time I use a text color, it will be against a background color. Without symmetry there, I could easily use a pair of colors that works now, but doesn’t maintain WCAG AA in the future if the colors behind the tokens are changed.

For example, why do I use color.text.inverse on top of color.background.neutral.bold (and why is neutral bold named oxymoronically?)

A naming scheme like color.background.neutral.inverse would be intuitive to use with color.text.neutral.inverse (and would invite the existence of color.text.brand for use with color.background.brand too, instead of reusing color.text.inverse against multiple background colors which might diverge at any time in the future). Even if color.text.neutral.inverse and color.text.brand are the same white at the moment, they aren’t the same token.

Am I missing something?


1 Like

@stephenmok / @DanielDelCore is there a migration guide? As in, the recommended token that goes with the current theme color?

As in, if I am currently using colors.N20, what token should I use instead?

In addition, is there a reference anywhere where I can find how tokens are to be used to match Jira designs? For instance, if I want to replicate the project sidebar, how can I find which token is used for a sidebar? The tokens are currently not part of the final generated CSS that I can inspect in my browser. If I look it up in the inspector, it will say var(--ds-surface, #FAFBFC), but that does not translate to a token.

Any way for the css that’s injected not to come from but from an Atlassian provided cdn? We’re not able to support since it kinda goes against Atlassian security guidelines (it’s not a domain that we control).


Note that some years ago was hacked and injected rubbish into every site that loaded from it, this isn’t a site that should ever be used.


Also, we had actual support cases from clients who did not get any styling because their internal network automatically blocked

1 Like

Hey folks :wave:

Unpkg is currently in use as a temporary mechanism for loading themes as we finalize our implementation in parallel to the early access program (EAP). It is only intended for the EAP and will only be visible in the development instances which have been enrolled into the program and not visible to your customers.

The team is actively working to remove the usage of unpkg for obvious reasons, we expect to have a solution in place within the next couple of weeks.

This is definitely a blocker for moving out of EAP, so I want to assure you that no customers will be served resources from unpkg.



Hey @remie,

Our migration guide can be found here: Migrate to tokens - Tokens - Atlassian Design System

Tokens are not a 1:1 match between the old and the new, so some manual reconciling is required. I encourage you to try to find the best semantic match for a token, rather than colour-matching. Consider the existing colour (N10), property type (background) and interaction state (hover) there should be a token to suit your needs.

In your case N10 is a light neutral colour. Assuming it’s for the side navigation, which is a large containing element, we would recommend a surface token (see migration guide for information on surfaces). For example, that might resolve to elevation.surface.sunken.

That being said, the naming scheme is going to continue to evolve over time, and we’re going to try to make it as intuitive as possible. @hitsthings’s feedback is totally valid and we’ll feed that back to the team. (this has actually come up before).

If you have trouble deciding which token to use we provide an interactive Token picker, which is a Q&A-style decision tree. If you follow the prompts it should give output an appropriate token.

The tokens are currently not part of the final generated CSS that I can inspect in my browser. If I look it up in the inspector, it will say var(--ds-surface, #FAFBFC) , but that does not translate to a token.

It’s possible to inspect the component via If you navigate to the component page and enable the new light or dark themes with the theme switcher in the top navigation, you will then be able to see the variable values in the inspector.

For example, the side-nav can be found here:

That being said, would you be interested in enrolling into our ecosystem EAP to give tokens a try directly in your app? You’ve shared some good feedback on the API already so far so could be beneficial for you to participate more directly. More information here.

1 Like

within the next couple of weeks.

So… it’s been 3 weeks (yes there has been a pesky holiday in between there) - what’s the eta?

Hi @danielwester, we have made some pretty significant changes to our core API over the break to allow us to inject the themes without the need for unpkg. I can’t tell you with absolute certainty how much longer it will be, but it’s on our critical path so know that we’re moving as fast as we can to unblock you.

1 Like

Hi @DanielDelCore,

Are you guys doing anything to allow apps to force a certain theme in iframes programmatically? For example, for dashboard gadgets, we’d like to set the dark mode programmatically in wallboards and in other use cases (in some use cases it makes sense to force the light mode). A generic mechanism to allow apps to set the theme programmatically would be the best. Thanks.

1 Like

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

1 Like

Sure, but the code inside the iframe does not have access to those, because it’s running from a different origin, right?

Accessing window.AP._data.options.productContext does work, it’s actually beneficial in some cases where using the regular AP call returns stale data.

Hey everyone,
I am just wondering what the expected behavior of how the new styles should be applied to apps in Forge should they be auto-applied or do i have to opt-in because I am getting here two different behaviors for two of our Forge apps (timesheet check and smart fields for jira) running under the same entry point.

Best regards :slight_smile:

Thanks for sharing @MartinKistnerDecadis.

Are these apps running on the same instance? If not I will have to update the feature flag for you :slight_smile:

In the meantime, could you try inspecting the app which isn’t working to see if data-theme is attached to the <HTML /> element like so: <HTML data-theme="dark">?

You should also be able to see CSS files ending in atlassian-dark.css or atlassian-light.css. It might be that the network requests are blocked by your CSP policy since these themes are (temporarily) being served via UNPKG.


This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.