Upcoming changes in design tokens 1.0.0 — action required soon [edit: now live!]

Hi everyone,

This post is for our Marketplace Partners using design tokens in their apps, and getting ready for dark theme in Jira Cloud. Getting started? Read more: Start using design tokens in your apps, and try dark theme in Jira Cloud

We’ve recently published @atlaskit/tokens@1.0.0 to npm.

This marks the first stable release of the tokens library and incorporates many changes based on your feedback during the Early Access Program (EAP), such as the opt-in mechanism for theming, and production theme loading (not via Unpkg). Some of these are breaking API changes.

Get ready, but please do not upgrade to tokens@1.0.0 yet! (If you do, theming will stop working in your apps.)

Update 27 Feb 2023: :green_circle: These changes are now live for Connect! Please follow the instructions below for actions required and how to upgrade. Thanks! (Changes for Forge are coming soon.)

For Marketplace apps, the tokens package itself is one part of a series of changes. Work is underway on accompanying changes for integration in Jira, and the Connect and Forge APIs. Once those are released, we’ll let you know to upgrade and make changes to your apps.

A note on future releases:
We’re moving quickly during the EAP and early development 0.x versions. The timed changes needed for the 1.0.0 roll-out is a once-off. As we move into stable > 1.0.0 versions, all breaking changes to APIs and design tokens will be communicated well in advance, with clear cut-off dates for deprecations. We will share full details of this lifecycle in the near future.

Read on to the next post, where @acampbell3, engineer on our team, will take you through what’s in 1.0.0 and what actions you’ll need to take soon…

Cheers,
Stephen

1 Like

Following on from @stephenmok’s post above, here are the details of what’s in @atlaskit/tokens@1.0.0 and what changes you’ll soon need to make in your apps…

As mentioned above - Please do not upgrade to tokens@1.0.0 yet

Summary of the changes in @atlaskit/tokens 1.0.0

Tokens 1.0.0 includes a variety of optimisations to the top-level theming logic applied by Jira and other Atlassian applications supporting theming in the future, including:

  • Improved theme loading CSS
  • New APIs structure for top-level config setGlobalTheme() and official APIs for SSR configuration
  • Improved support for OS-level theme switching
  • Internal optimisations and clean-up (We’ve reduced the bundle size of theme files by 62% )

Although many of the changes above do not affect Marketplace apps directly, there are three changes that require actions for apps currently in the Early Access Program (EAP):

  1. New opt-in API for Connect and Forge Custom UI apps
  2. Removal of deprecated tokens from provided theme CSS
  3. Changes to the format of theme data-attributes (for theme observers / custom logic)

Breaking changes — action required

1. New opt-in API for Connect and Forge Custom UI apps

Currently, theme support in apps has been all-or-nothing. If you join the EAP and your instance is added, your apps would receive theme data, CSS files would be loaded, and token CSS variables would be available for your app to use.

However, as you folks pointed out, this meant that apps that used Design System components but had not migrated to dark mode would render in an incomplete mix of light and dark themes.

Thanks to your feedback, we’ve added an opt-in API for theming Connect and Forge Custom UI apps. This allows you to test and iterate on your dark mode experience, while only enabling it for customers when the migration is complete and you’re ready to ship to your customers.

Changes required for your app:

To activate theming in your Connect app, call window.AP.theming.initializeTheming(). This will fetch the current active theme from the host environment (e.g. Jira) and apply it in your app. It will also reactively apply any theme changes that occur in the host environment so that your app and the host are always in sync.

Roll-out sequence:

We’ll let you know the exact date (this will be in the coming weeks) when this opt-in API will be required for you to test theming locally in your apps. During the Early Access Program, you’ll also need to both opt-in your app, and be signed up to the program so we can enable ecosystem theming support for your Jira instance.

At the end of the EAP, this opt-in API will be enabled on all instances, for Jira customers who have enabled theming in their personal Jira settings. If your app has been migrated, you can enable the flag so customers can enjoy your app in dark mode :tada:.
If you’re not yet ready, publish your app without the opt-in.

Update 27 Feb 2023: :green_circle: These changes are now live for Connect! Changes for Forge are coming soon. Experiences continue to appear themed only for instances that are part of the EAP.

2. Removal of deprecated tokens from provided theme CSS

We’ve been iterating on Atlassian’s schema of design tokens, including our naming conventions. There are a number of tokens that are marked as “deprecated” and “deleted” for removal in the next major release (1.0.0). These tokens were still present in app CSS during the last 0.x release of @atlaskit/tokens, but raised warnings when used with our eslint and stylelint plugins.

In @atlaskit/tokens@1.0.0, these tokens have now been removed to reduce bundle size and bloat. These tokens will no longer be present in the CSS in Connect or Forge Custom UI apps, and will not render as expected.

Changes required for your app:

If your app is using these deprecated tokens, we recommend the following:

  • If your app supports either the eslint or stylelint token rules, configure and run these rules on your app to generate a list of deprecated tokens in your app, and the recommended replacements.
  • Otherwise, manual migration is required; the full list of each deprecated token and its replacement can be found in the changelog for the 1.0.0 release: https://atlassian.design/components/tokens/changelog#100.

We recommend starting work today to prepare — no need to wait until you upgrade your app to 1.0.0, as the replacements are already available!

Roll-out sequence:

We’ll let you know the exact date Jira switches to 1.0.0 (this will be in the coming weeks), at which point those design tokens will no longer be available. This will apply to all Early Access Program instances.

Update 27 Feb 2023: :green_circle: These changes are now live for Connect! Changes for Forge are coming soon.

3. Changes to the format of theme data-attributes (for theme observers / custom logic)

These changes affect you if you are using theme observers and custom logic in your app — no action required if you are only using the design tokens.

Previously, we communicated the current themes rendered to the page via a space-separated list of themes in the data-theme attribute:

<html data-theme="light dark spacing" data-color-mode="dark"> 
   <!-- the "dark" theme will render as we're in the 'dark' color mode -->
</html>

There are two changes as a result of the 1.0.0 release:

  1. The data-theme attribute now has a new format, matching the object-based format now used by setGlobalTheme and other Javascript utility functions:
- data-theme="light dark spacing" data-color-mode="dark"
+ data-theme="light:light dark:dark spacing:spacing" data-color-mode="dark"

If you are on tokens 0.x and using ThemeMutationObserver or otherwise checking the value of the data-theme attribute, you may need to adjust your logic to prevent regressions after the 1.0.0 roll-out in Jira.
2. ThemeMutationObserver and useThemeObserver in tokens 1.0.0 use a new object syntax. This allows you to access specific parts of the theme configuration:

- const theme = useThemeObserver() 
- // useThemeObserver v0.13.5: 'light'
- // useThemeObserver v1.0.0 {"dark":"dark","light":"light","colorMode":"light"}
+ const { colorMode: theme } = useThemeObserver()
+ // useThemeObserver v1.0.0: 'light'

Changes required for your app:

  • Once tokens 1.0.0 arrives in Jira, update your app to the newest version of @atlaskit/tokens@1.0.0 and extract theme data from the new object syntax.
  • If you want to avoid a temporary regression in your test environment, you can update your logic to handle both of the string formats of data-theme.

Roll-out sequence:

We’ll let you know the exact date Jira switches to 1.0.0 (this will be in the coming weeks), when the theme data-attributes will change. This will apply to all Early Access Program instances.

Update 27 Feb 2023: :green_circle: These changes are now live for Connect! Changes for Forge are coming soon.

A note on future releases

We’re moving quickly during the EAP and early development 0.x versions. The timed changes needed for the 1.0.0 roll-out is a once-off.

As we move into stable >1.0.0 versions, all breaking changes to APIs and design tokens will be communicated well in advance, with clear cut-off dates for deprecations. We will share full details of this lifecycle in the near future.

Other changes based on your feedback — no action required

A new theme loading solution

Previously, theme CSS was provided to ecosystem applications via externally hosted CSS assets. As a temporary solution during the early access program, these CSS files were loaded into ecosystem apps via Unpkg.

In 1.0.0, we have introduced a production-ready Javascript-based lazy loading solution, where CSS assets are bundled by Jira and inserted into <style> tags at the head of the document. You can identify these style elements by the data-theme attribute.

Changes required for your app:

There should be no change required for your app, but be aware that these styles are attached to the <head> of your application if you opt into theming.

CSS syntax support in the theme documentation

We’ve heard feedback from developers who are using our CSS variables directly that the object naming convention used in our documentation added friction to the migration process. We’ve now added a “syntax” toggle to allow you to use whichever format you prefer:

Resources

For the full set of changes, please refer to the Tokens changelog on the Atlassian Design System website for more details: https://atlassian.design/components/tokens/changelog#100

Please reply and let us know your questions!

Cheers,
Andrew

4 Likes

Hey folks! Updating this post to let you know that the changes above will be rolling out to Jira Cloud on Monday the 27th of February.
As mentioned above, this includes:

  1. Introduction of a new opt-in API to render themes in your app
  2. Removal of deprecated tokens from the provided theme CSS in Connect apps
  3. Changes to the format of the data-theme attribute

Let us know if you have any questions about the roll-out.

Update 27 Feb 2023: :green_circle: These changes are now live for Connect! Changes for Forge are coming soon.

Hello again!

We have enabled the new opt-in API for Connect and published tokens v1.0.0 to production for development instances enrolled in the ecosystem EAP. Forge’s opt-in API is forthcoming, details will be shared soon.
You will notice that themed experiences will no longer be visible, to fix this please use the new opt-in API. As mentioned my Andrew above, this is done via the new AP method:

window.AP.theming.initializeTheming();

This method sets up all necessary theming configuration and listens for subsequent theme changes from the parent application. It is important to call the API as soon as possible to avoid any flashes between themes, we recommend the following approach:

<html>
  <head />
  <body>
    <script>window.AP.theming.initializeTheming();</script> 
    ... rest of your APP
  </body>
</html>

For the time being, theming in Connect and Forge UIKit will continue to be behind a feature flag and not visible to end-users until it is removed. From that point onwards, we will allow you to share themed experiences with end-users at your discretion. Timings and details to follow!

3 Likes

Perhaps this is safer:

<script>window?.AP?.theming?.initializeTheming();</script>

:upside_down_face:

4 Likes

@DanielDelCore Please explain how we get enrolled on the ecosystem EAP.

Hey @david,

Full details can be found here: Start using design tokens in your apps, and try dark theme in Jira Cloud - #5 by stephenmok

In short:

  • Fill in this form to let us know about your development instances
  • We will add your development instance(s) to the feature flag
  • Enable dark mode in your personal settings
  • Call <script>window.AP.theming.initializeTheming();</script>
  • Dark mode should now be enabled (this can be confirmed by looking at the HTML attributes data-theme and data-color-mode applied to your HTML element)

We’re planning to remove the feature flag soon so all that will be required is the call to initializeThemeing :slight_smile: We’ll post here with more information.

Cheers.

2 Likes

IMO the text color has too low of a contrast. eg one change shows the improvement: --ds-text: #F7F9F9. Probably other tweaks like that in hidden corners of the product beasts.

Before:

After:

Personally I tend to think there are two distinct dark modes based on the preferences I use.

Atlassian products definitely sit in the text-heavy category…

Non text-heavy (dark):

Text-heavy (dim):

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