Introducing design tokens, new colour foundations and dark mode

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:

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.