Introducing design tokens, new colour foundations and dark mode

Atlassian Ecosystem Design Ecosystem Design Announcements
12

Not necessarily. A lot of data that is available through AP is actually set on the iframe attributes. Although it can of course also be implemented as a query string parameter, the fact that it is implemented using AP does not automatically mean a REST call is required.

For instance

"productContext":{"project.key":"XYZ","project.id":"10000"}

and

"user":{"timeZone":"Europe/Amsterdam"}

can be found on in the iframe name attribute.

Isn’t that overreacting a bit? What are you optimising for? You’re running inside Jira/Confluence, I mean, it’s not like anyone will hold you to the <2s loading :joy:

13

One important use case for our users requires that we can override the theme for a sub-part of the iframe. So whichever mechanism you use to control what the design tokens do, please make sure that different parts of the page can use different themes!

For example, if the theming only works with selectors like [data-theme="dark"] like in your example, then everything is fine. But some parts of the theming would use selectors like html[data-theme="dark"] or [data-theme="dark"] body then it becomes impossible to do override that part in a sub-section.

(Just as an example, one of our apps allow users to export part of the UI as an image, e.g. to put in presentations or printable documents. Even if the user has dark mode enabled, they’ll export will usually need to be in light mode. The user experience would suck if the UI flashed while we are screenshotting. If we can control theming by element, we can just copy part of the UI in a hidden element, with an overridden theme, and export that. There are also other cases, like needing to preview how things will look with a different theme, etc.)

14

A lot of data that is available through AP is actually set on the iframe attributes.

Sure, but the code inside the iframe does not have access to those, because it’s running from a different origin, right? So to access them it needs to postMessage to the parent window, and then wait for the parent window to postMessage a result back. This can take a couple ms in the happy case, but I’ve measured simple stuff like that take dozens (plural!) of seconds (not millis!) when a lot of things are happening at the same time.

(I’ve also seen that Jira sometimes does a REST call to an internal plugins/servlet/ac service, to load info about the app, even in cases where that does not seem necessary for the actual API the iframe called.)

I don’t care if it’s done with URL params or not, but that’s the only no-latency method I know, and I’m kind of paranoid about UI latency :slight_smile:

Isn’t that overreacting a bit? What are you optimising for? You’re running inside Jira/Confluence, I mean, it’s not like anyone will hold you to the <2s loading :joy:

On dashboards there can be a dozen or more iframes, all loading at the same time. (And some of our users like to open several dashboards at the same time.) Just this morning I was debugging an issue where Jira was delaying the delivery of an AP.event for more than 20 seconds due to heavy activity on first page load. We want to at least be able to display a progress bar or loading indicator without blinding users or flashing rectangles everywhere.

15

I don’t think it’s overreacting at all. If somebody has dark mode up and we end up flashing a white background (or the reverse - they have light mode on and we flash up a dark box) for a second - it looks “wrong”. We’ll end up getting support calls and customers will go to the solution that is not supporting dark mode because the experience is not “broken”.

Not looking at how it’s done - just that we are able to retrieve the mode at first render. That can be url props (hopefully not) or an api call that is synchronous.

1 Like
16

Thanks for all of the discussion so far!

Let me (re-)introduce @DanielDelCore, Senior Engineer. You may recognise him from other topics on here, and Dan is directly working on getting design tokens ready for you all. So please keep up the questions and feedback!

Coming back to this one… it’s something we’ve been discussing with the designers on our team.

The new Figma libraries make use of the latest and greatest Figma features (variants, component props, auto layout, etc) and we’ll definitely be publishing updates regularly. What we’re still considering is how regularly.

We know that too-frequent updates can be a double-edged sword because of the lack of inheritance in Figma community files. We’re keen to hear feedback from you and other marketplace partners on this topic — what would be a sweet spot for updates in your workflow?

2 Likes
17

Hey folks,

Happy Halloween to those of you who celebrate! While you were distracted by the spookiness, we published a trick treat. The early preview of design tokens documentation is now live on atlassian.design.

Key pages to check out:

As a reminder, please expect frequent changes over the coming months as we iterate and improve the system. More docs content will also be added as they are finalised.

Go ahead and take a look out at what’s coming, and let us know your questions right here! Our work on tooling is on track, and we’ll be in touch again later this quarter when we’re ready for you to try it out.

Cheers,
Stephen

4 Likes
18

Hi @stephenmok ,
Thank you for the documentation. Is there any documentation how these design tokens can be used with ACE? ACE uses handlebars templates, and I’m wondering how to integrate the design tokens instead of the default AUI.

19

Can we please get an update on how a Connect app or a forge app will know what “mode” the host app/user is in? This entire thread is not useful without that.

20

Before today, all extension points had the attribute data-theme on html.
The jira:issuePanel ist already missing that attribute. Is it possible for Atlassian to change that behavior in one release instead of extension-point-wise? This seems to be hard to maintain for our app development until dark mode is going life.

And please, can we get the secret atlassian theme chrome extension for app development? :slight_smile:

21

Hi @danielwester. Our current solution for Connect apps and Forge Custom UI adds the current theme and mode as data attributes to <html> inside the iframe. This is done automatically and will sync to reflect the same theme as the host (Jira/Confluence). Under the hood it’s using the setGlobalTheme API documented here.

22

Hi @lkimmel. Were you experiencing this on a *.jira-dev.com instance or *.atlassian.net? There shouldn’t have been any data-theme attributes present yet :thinking:

23

I experience that on my instance Log in with Atlassian account
The attribute is missing for issue panels, and jira admin pages, which had that attribute until last week. We developed against them to be prepared :smiley: .
But not for global pages, which still have the data-theme attribute.

24

If I understand you correctly, this means that you are going to inject code into the HTML of the iframe? Given that this is not your HTML to control, that means you are adding it to the HTML element from the all.js include? Or will it be done on iframe onLoad event handler?

So we need to wait for that to load and manipulate the DOM before the data- attribute is set. Also, how will you handle iframe that do not have <html /> root elements? Or will you just use the root element?

To be honest, I think manipulating iframe document is a bad practice and I’m not sure why you would choose this over adding it to the query string or providing an AP method?

3 Likes
25

To add to @remie 's questions - how will you handle redirects? Also - how will it be done in custom ui? Can we get some sample code to demonstrate how you expect a react app to behave? (Since we do have custom components that will have to adapt as well).

2 Likes
26

@stephenmok any chance of getting a pre-release/beta version of the new Atlassian Figma Design Tokens Plugin?

27

@remie

If I understand you correctly, this means that you are going to inject code into the HTML of the iframe? Given that this is not your HTML to control, that means you are adding it to the HTML element from the all.js include? Or will it be done on iframe onLoad event handler?

Currently, all.js will perform all of the orchestration, so apps will not need to configure anything to get theming working. That does mean that we will inject attributes onto the element as well as inject style sheets into the .

These are necessary to be able to trigger CSS selectors (activate a theme) and allow apps to read and respond to the theme state accordingly. For example, if you have brand-specific colours that need to be changed between light/dark modes.

So we need to wait for that to load and manipulate the DOM before the data- attribute is set

I’m not sure if I understand this point, but you shouldn’t need to manipulate the DOM relative to the timing of the data attr. What are the other scenarios where you need to manipulate the DOM? If you can share examples we’ll look into it.

how will you handle iframe that do not have

We have not come across this use case yet, what kind of scenarios would an app not have a element?

@danielwester

how will it be done in custom ui? Can we get some sample code to demonstrate how you expect a react app to behave? (Since we do have custom components that will have to adapt as well).

Both Connect & Forge Custom UI will take a similar approach, they both handle the theme configuration behind the scenes when the app loads. So similar to the above, you’ll see stylesheets containing theme files mounted to the page and attributes attached to the HTML element.

Usage in both Connect & Forge Custom UI will follow the same pattern shown in our docs: https://atlassian.design/components/tokens/examples#button

how will you handle redirects?

Redirects are not a scenario we’ve come across yet in our early explorations. Could you share some context on this for us to look into?

@BrianOffenheim

@stephenmok any chance of getting a pre-release/beta version of the new Atlassian Figma Design Tokens Plugin?

Yeah, we’re planning to share that very soon, within the next month :slight_smile: We’ll update this thread when we have more information.

28

What I meant is that the app needs to wait for all.js to load and manipulate the DOM to set the data theme attribute. Which is latency, especially for server-side rendered apps. If you pass the theme in the query string, we can construct the HTML with the correct data attribute ourselves.

In general, I really really really really want to stress that you should not ever make DOM manipulation to iframe content. Apart from the latency that you are introducing, manipulating iframe document content is a bad practice. This is not your code to manipulate.

Making pro-active changes to DOM elements is not the same as using all.js to provide utility Javascript functions, or applying changes based on options attributes we put on script tags.

I cannot stress this enough. 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.

If you move forward with this, we will have to reconsider using AtlasKit as I do not condone Atlassian to take this crucial design responsibility away from us.

6 Likes
29

The point is that you should not even have to consider this use case. That is the whole premise of an iframe. It is not your code. If I want to use XML+XSLT, which is a completely valid way of creating an iframe document, I should be able to do so.

You are making assumptions about code that is outside of your control. Don’t do that.

5 Likes
30

@DanielDelCore - I’m with Remie on this, and couldn’t have said it better.

You are injecting content into my app, where I “own” the design.
This is not your app to mess with. It is not your decision to change how my app renders. That is entirely on me.

How do you envision this to work if we’ve made customizations to Atlaskit components that we use? And if you’re manipulating the DOM in my page, am I supposed to now keep track of the changes you made? What happens if I decide to re-render the screen, or do other crazy things that wipe out your DOM manipulations?

It also seems, you did not contemplate how this is supposed to work with apps that use server side rendering. 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. To me, this sounds like there is a scenario where the server renders the page in light mode, will potentially get rendered in light mode first, and then has to switch over to Dark mode, because we don’t know from the server side that Dark mode is desired.

6 Likes
31

Consider this simple example scenario: My very popular and useful app needs to display the image of a beautiful celestial body as a background. In light mode it should show the sun, in dark mode it should show a black hole. The app needs to do a REST call to find an appropriate image. When do I do that? Also, I need to render matching UI in the iframe on the server side. What will be displayed in the iframe before the theme is set? What if my iframe opens a server-rendered SVG document instead of HTML?

4 Likes