Introducing design tokens, new colour foundations and dark mode

Atlassian Ecosystem Design Ecosystem Design Announcements
1

Hello,

We’re currently working on updating the Atlassian Design System’s UI foundations, including a new colour and elevation system that utilises design tokens, and we want to share this with you first!

Design tokens and the new colour foundations will simplify the process for designers and engineers to build experiences, make them more easily accessible (including improved contrast), and support theming — the all important enabler for dark mode. Design tokens will be in all Atlassian Design System components, as well as throughout front-end platform components in @atlaskit, such as the Editor.

Adopting design tokens will make it easier for you as marketplace partners to build apps that provide a consistent and familiar experience inside Atlassian products by using the exact design tokens that we use ourselves, and seamlessly align on the same colour palette!

We recently announced dark mode is coming to Jira Cloud, shipping in general availability in Q2 (Apr-Jun) 2023. This is a close collaboration between the Atlassian Design System + Jira Cloud teams. We’re all here to support you to onboard to design tokens and get ready for dark mode in your apps on the marketplace — whether they’re built on Forge or Connect.

We understand you’ll need to plan and allocate time in your product roadmaps, so wanted to give you a heads-up of what’s coming soon:

  • This month (Oct 2022), we’ll publish an early preview of our atlassian.design docs to allow time for the community to review and ask questions. This will include info about the new colour system, as well as design tokens. We deliberately want to share this as soon as possible, so keep it mind it will change as we finalise it!
    Update: This is now published – jump to details

  • Progressively over the next quarter (Oct-Dec 2022), we’ll release:

    • Details of how to use design tokens in your apps, for initial development and testing, and later through to production — we’ll be keen to hear your feedback!
    • New Figma libraries that use the new colour palettes and design tokens
    • Tooling to help both designers and engineers migrate existing experiences/apps to use design tokens (such as plugins for Figma, ESLint and Stylelint)

  • There will be a closed alpha and an open beta prior to general availability, and you’ll have access to both of them. Exact timing and details will be shared later this year.

Watch this post and we’ll let you know when each of the above are available!
:new: Update Dec 2022: All of these are now ready — read the details and get started! :tada:

If you have any questions please ask us right here on the forums. My colleagues will also be able to help, so let me introduce:

  • Dafne Rodriguez, Product Manager, Atlassian Design System
  • Lachie Wallman, Program Manager, Atlassian Design System
  • Carlos Khatchikian, Senior Engineering Manager, Jira Cloud — you may have read Carlos’ updates over on the Jira Cloud suggestion for dark mode already!

Thanks everyone for your support. I can’t wait to see you try out the new design tokens, and get dark mode into the hands of our mutual customers!

Cheers,
Stephen

Engineering Manager
Atlassian Design System

11 Likes
2

@stephenmok - you keep using this term “Design Tokens”. What is that and what does that mean? Can you include a definition / examples / anything to shed some light on that term?

1 Like
3

Design Tokens are basically variables (either Javascript or CSS) that replace hard-coded references to styling decisions in each component. By using the variables from the Tokens package, all components will always have an up-to-date look & feel simply by upgrading their version of the package instead of having to update the style references directly in their code.

More resources about design tokens:

5 Likes
4

From a technical perspective - how should we receiving the indicator which mode a user is in?

While I totally understand that the implementation is still in works, knowing the general approach will let us architect in the support into our app ahead of time.

Thanks,

/Daniel

2 Likes
5

@stephenmok Do you have any information on what the plan is in terms of keeping the Figma libraries up to date? The current version is over 1 year old and required me to create a separate library that works with Auto Layout, Text Styles, Color Swatches, etc. as the official library doesn’t.

I’ve come to peace with the fact that working with Atlaskit requires a lot of patience and custom work in order to get a satisfactory result, but it would be good to know wether this newer version will also remain untouched for months/years. Ideally, the library would be updated regularly and bugs would be fixed. I know this might be wishful thinking, but I’d like to be sure before I start working on updating our own custom adaption of Atlaskit again.

1 Like
6

Hey @danielwester,

Currently, our strategy is to attach a data attribute to the DOM, allowing for CSS selectors or JS (we will provide specific APIs for this) to react accordingly :slight_smile: .

For example:

<html data-theme="dark"></html>

[data-theme="dark"] {
/* apply dark theme specific styling here */ 
}

We are still validating our final approach, so this is not set in stone. However for the most part, if you are using design tokens directly this should not be required. It will be more for cases where non-Atlassian colour schemes and branding are in use.

There are some other considerations such as system-level preferences that will be factored into this so we would also expect the use of prefers-color-scheme to be functional at some point as well.

7

Also in the Connect iframe?

That might give strange behavior for apps if dark mode is only partially implemented because Atlaskit/DS components support it but custom components don’t yet.

I would have expected something like AP.context.getTheme()

1 Like
8

Hey @remie ,

If dark mode is only partially implemented because Atlaskit/DS components support it but custom components don’t yet.

That’s correct, as Stephen mentioned above we’re planning to give ecosystem devs & designers plenty of lead time to adopt design tokens via the closed alpha and open beta programs, prior to general availability. This is where we hope to bring Connect and Forge Custom UI apps up to speed to avoid partial experiences wherever possible. We’re planning to share the specifics with the community shortly :slight_smile: .

I would have expected something like AP.context.getTheme()

We will be providing an API that is available to both Forge Custom UI and Connect, but this is a really good suggestion for Connect specifically. I’ve made a note of it, thanks!

Please continue to share thoughts, expectations, and ideas with us, we want the dev/designer experience to be as good as can be!

Cheers.

1 Like
9

Thanks! What I meant was that I interpreted your comment:

as saying that you will also add this to the <HTML /> tag inside the Connect / Forge iframe. Is that correct? Or are you only referring to the host application?

10

Can we make sure whatever is selected that it’s available without any latency? Ie. Having to call back to a backend function in Forge or even just calling a rest end point (in both Connect and Forge) will be not acceptable to our end users since there will be guaranteed users that will see some sort of a variant “flash of unstyled content” if that happens.

Thanks,

/Daniel

2 Likes
11

Seconding daniel, it’s important that AP.context.getTheme() or whatever it’ll be called be synchronous, we need its value instantly to avoid flashing. I’m not even talking about REST calls, even exchanging a message between the iframe and the parent window (like some callback-based APIs do, e.g. AP.getLocation) is too slow. This needs to be passed somehow via the URL so it’s available instantly when the iframe loads.

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: