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):
- New opt-in API for Connect and Forge Custom UI apps
- Removal of deprecated tokens from provided theme CSS
- 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 
.
If you’re not yet ready, publish your app without the opt-in.
Update 27 Feb 2023: 
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: 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:
- 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: 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
We’ll post here with more information.
