AUI, design tokens and original theme - how to handle it

I’m using AUI 9.7.1 and started using design tokens.
I’ve added aui-theme-design-tokens class in BODY and at the beginning of the document I’m calling AP.theming.initializeTheming(). It mostly work as expected.
Problem is when user sets its theme to Original value. At this point there is no data-color-mode set in the HTML tag and all AUI components are missing the style data. This makes page(frame) looking really ugly.
This is much more visible, as each user, that didn’t switch his theme yet, has the theme set to Original

For now I can use ThemeMutationObserver and getGlobalTheme() during page load to add or remove the aui-theme-design-tokens class from BODY when required.
Such solution seems however not natural.
In my own classes I can define css fallback values in case jira’s design tokens are missing, shouldn’t AUI do the same?
Or perhaps AP.theming.initializeTheming() should add/remove the aui-theme-design-tokens class to/from BODY?

Is there any other way to deal with this situation?

1 Like

Hello @ZbigniewPiecuch
The new theming in AUI 9.7.1 has its own documentation page available here: Dark mode - AUI Documentation

Thanks for reply.
I’ve read the provided page and followed the instructions there. This is how I hit the described problem.
I thought setting aui-theme-design-tokens is all I need to do to use tokens.
Unfortunatelly it works only till Original theme is selected by user.

1 Like

Well I think, it’s somewhat desired, as the Original theme sets everything back to the (note the name!) original (legacy) state.
Any feedback though is appreciated, as these features are marked as “experimental”, and we’re aiming to make it easier to use. I linked the official documentation, as I was afraid you were using a wrong JS function; you mentioned AP.theming.initializeTheming(), which I never heard of.
The function you’re expected to run is AJS.DesignTokens.setGlobalTheme() (and its detailed documentation is available on the Design Tokens page:

1 Like

Hello @ZbigniewPiecuch :slight_smile:

It’s also important to know, in which context are trying to use AUI? If this is a plugin for some specific product, can we know the product and version you are trying to use it with?

About theme usage: I’m not sure where AP namespace comes from. In AUI we have Design Tokens library bundled for you, it should be available under AJS.DesignTokens if you include according web-resource ( com.atlassian.auiplugin:design-tokens-api). Though this namespace you can access most of DT functionality, excluding React-related things.

You also have an opportunity to use not bundled Design Tokens version, I assume this might be what is happening in your case.

1 Like

Thank you for taking time to take a look at this. I really appreciate it.

I’m using AUI in kBoards Connect App that I’m developing. It is used on web pages that are called jiraProjectPages.
I reference the aui library with
<script src=""...

The AP.theming.initializeTheming() is used to initialized theming in Connect App as described here.

I understand that setting Original theme sets everything back to the original (legacy) state. Following this statement, after user sets Original theme in Jira, I expected AUI to disregard the aui-theme-design-tokens class in body and work in the legacy mode. It looks like it’s not. So it looks like:

  • theme set to Light - AUI displays everything correctly, design tokens are used
  • theme set to Dark - AUI displays everything correctly, design tokens are used
  • theme set to Original - AUI displays everything incorrectly, looks that AUI tries to use design tokens which are not available

There is additional code in the Connect App required to deal with it. That code monitors theme changes and adds or removes aui-theme-design-tokens class to/from depending if Original theme is set or not.

Maybe I’ve missed some switch or something and there is easier way to deal with it. I will be greatful for any hint.

1 Like

Okay, got it :slight_smile: Thanks so much for reaching us out with this, it will help us improve APIs for sure.

Your assumptions about what’s going on are right and I suggest you use workaround for now, and later you can remove it when we ship fix into AUI or Jira.

AUI design token support is still in experimental state now, and this is one case which we’ll need apparently to work through. For now we expected products to handle aui-theme-design-tokens class themselves, since it’s on them to turn on / off themes usage design tokens and we cannot monitor it in clean and easy way.

This issue can be addressed on product side, but we’ll take a look into it more and decided if we want it to be handled by AUI somehow to avoid this with other products :slight_smile:

Thanks for reaching us out again, this is really important to improve our tooling :pray:


Hello @SiarheiFilinsky , I noticed the same problems with the Original Theme and tried to implement a fallback workaround as you proposed as a solution here.

I figured out that effort is just too high as too many aui variables point to “undefined” design system variables. In my understanding the “Original” Theme is still the default theme for all users. Is this correct? If this is the case, we will postpone dark-mode support rollout until the “Original” Theme selection is removed from the menu or until the problems with undefined variables of the aui in combination with “Original” Theme are removed. I wanted to share this feedback and hope you could share a timeline for “Original” Theme removal.