https://atlassian.design/assets/927929c78ce1/component---src-pages…s-in-code-index-tsx-f2416d1c78469c0f5631.js

1"use strict";(self.webpackChunk_atlaskit_website_constellation=self.webpackChunk_atlaskit_website_constellation||[]).push([[2042],{240689:function(e,n,t){t.r(n),t.d(n,{default:function(){return u}});var a=t(286326),i=t(194348),l=t(896434),s=t(429786),o=t(976795);const r=["components"];function d(){return d=Object.assign?Object.assign.bind():function(e){for(var n=1;n<arguments.length;n++){var t=arguments[n];for(var a in t)({}).hasOwnProperty.call(t,a)&&(e[a]=t[a])}return e},d.apply(null,arguments)}const p={_frontmatter:{title:"Use tokens in code",description:"Learn how to set up and use design tokens in code."}};function m(e){let{components:n}=e,t=function(e,n){if(null==e)return{};var t,a,i=function(e,n){if(null==e)return{};var t={};for(var a in e)if({}.hasOwnProperty.call(e,a)){if(-1!==n.indexOf(a))continue;t[a]=e[a]}return t}(e,n);if(Object.getOwnPropertySymbols){var l=Object.getOwnPropertySymbols(e);for(a=0;a<l.length;a++)t=l[a],-1===n.indexOf(t)&&{}.propertyIsEnumerable.call(e,t)&&(i[t]=e[t])}return i}(e,r);return(0,l.mdx)("wrapper",d({},p,t,{components:n,mdxType:"MDXLayout"}),(0,l.mdx)("p",null,"This page explains how to set up and use\n",(0,l.mdx)("a",{parentName:"p",href:"https://atlassian.design/tokens/design-tokens"},"design tokens and themes")," in code."),(0,l.mdx)("h2",{id:"before-you-begin"},"Before you begin"),(0,l.mdx)("p",null,"Make sure you’re\n",(0,l.mdx)("a",{parentName:"p",href:"https://atlassian.design/get-started/develop"},"set up to use the Atlassian Design System"),". In\nparticular, make sure ",(0,l.mdx)("inlineCode",{parentName:"p"},"@atlaskit/tokens")," is installed as a dependency and use our\n",(0,l.mdx)("a",{parentName:"p",href:"https://atlassian.design/components/eslint-plugin-design-system/usage"},"linting rules")," to stay up to\ndate."),(0,l.mdx)("p",null,"Installing ",(0,l.mdx)("inlineCode",{parentName:"p"},"@atlaskit/tokens")," alone does not mount the theme CSS required by design tokens—make sure\nto follow the setup below."),(0,l.mdx)("h2",{id:"set-up-themes-and-theme-switching"},"Set up themes and theme switching"),(0,l.mdx)("p",null,"For themes to work properly, theming must be initialized by the Atlassian application and by any\nMarketplace app that extends its experience."),(0,l.mdx)("p",null,"Your application must initialize ADS theming. For client-rendered applications that are not already\nusing ",(0,l.mdx)("inlineCode",{parentName:"p"},"AppProvider")," or another supported theme initializer, call\n",(0,l.mdx)("a",{parentName:"p",href:"https://atlassian.design/components/tokens/code#setglobalthemethemestate"},(0,l.mdx)("inlineCode",{parentName:"a"},"setGlobalTheme"))," once at\nstartup. The example below uses the current default configuration."),(0,l.mdx)(s.A,{language:"jsx",text:o.p1,shouldWrapLongLines:!0,mdxType:"C

1odeBlock"}),(0,l.mdx)("br",null),(0,l.mdx)("p",null,"These values are the current defaults, so this shorthand is equivalent:"),(0,l.mdx)(s.A,{language:"jsx",text:o.gU,shouldWrapLongLines:!0,mdxType:"CodeBlock"}),(0,l.mdx)("br",null),(0,l.mdx)("p",null,"Make sure theming is set up by inspecting your app HTML. You should see something like this:"),(0,l.mdx)(s.A,{language:"html",text:o.IO,shouldWrapLongLines:!0,mdxType:"CodeBlock"}),(0,l.mdx)("br",null),(0,l.mdx)("p",null,"Pay special attention to the ",(0,l.mdx)("inlineCode",{parentName:"p"},'data-color-mode="dark"')," attribute, and also note the\n",(0,l.mdx)("inlineCode",{parentName:"p"},'data-theme="dark:dark light:light ..."')," attribute. These reflect the current theme state. They also\nmatch CSS selectors within the theme files so the appropriate CSS variables can be activated in\nresponse to theme changes."),(0,l.mdx)("h3",{id:"set-up-atlassian-fonts"},"Set up Atlassian fonts"),(0,l.mdx)("p",null,"To bring ",(0,l.mdx)("a",{parentName:"p",href:"https://atlassian.design/foundations/typography"},"Atlassian Sans and Atlassian Mono")," web\nfonts into your app, follow our\n",(0,l.mdx)("a",{parentName:"p",href:"https://go.atlassian.com/set-up-fonts"},"setup guide (Atlassians only)"),"."),(0,l.mdx)("p",null,"The typography theme is enabled by default when using ",(0,l.mdx)("inlineCode",{parentName:"p"},"setGlobalTheme()"),"."),(0,l.mdx)("h3",{id:"set-up-themes-for-apps-connect-forge-marketplace"},"Set up themes for apps (Connect, Forge, Marketplace)"),(0,l.mdx)("p",null,"For Connect and Forge apps, see the following dedicated resources:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://developer.atlassian.com/cloud/jira/platform/connect-theming/"},"Theming Connect apps")),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("a",{parentName:"li",href:"https://developer.atlassian.com/platform/forge/design-tokens-and-theming/"},"Theming Forge apps"))),(0,l.mdx)("h3",{id:"server-side-rendering"},"Server-side rendering"),(0,l.mdx)("p",null,"If your application is using SSR (server-side rendering) ensure themes appear at the right time\nusing our\n",(0,l.mdx)("a",{parentName:"p",href:"https://atlassian.design/components/tokens/code#server-side-rendering-ssr-utilities"},"SSR theming utilities"),"."),(0,l.mdx)("h2",{id:"use-tokens"},"Use tokens"),(0,l.mdx)("p",null,"You can access individual tokens using the CSS custom properties mounted to the page, however, it's\nbest to use the ",(0,l.mdx)("inlineCode",{parentName:"p"},"token()")," method. This ensures you have proper prefixes, type checking, and linting\nso you'll know if a token ever changes, is deleted, or is used incorrectly."),(0,l.mdx)("p",null,"The ",(0,l.mdx)("inlineCode",{parentName:"p"},"token()")," function takes a dot-separated token name and returns a valid CSS custom property for\nthe corresponding token. This method will warn you if an unknown token is provided."),(0,l.mdx)(s.A,{language:"jsx",text:o.jj,shouldWrapLongLines:!0,mdxType:"C

1odeBlock"}),(0,l.mdx)("br",null),(0,l.mdx)("p",null,"If you're migrating a lot of values to tokens,\n",(0,l.mdx)("a",{parentName:"p",href:"https://atlassian.design/tokens/migrate-to-tokens#use-our-codemod-for-migration-assistance"},"use our codemod"),"."),(0,l.mdx)("h3",{id:"migration-to-tokens"},"Migration to tokens"),(0,l.mdx)("p",null,"The ",(0,l.mdx)("inlineCode",{parentName:"p"},"token()")," function accepts two arguments: the first is the token, and the second is an optional\nfallback value (the value that is rendered when the theme is not set up). During the theme rollout\n(i.e., migration from raw values to tokens), it is recommended to use the function without\nspecifying fallback value. In such cases, this value will be automatically supplied by the\nbuild-time Babel plugin, ensuring that properties have valid values even if the theme is not yet\nenabled."),(0,l.mdx)("p",null,"At times, token values may not perfectly align with the raw values used in the codebase. To maintain\nconsistent user experience, it is recommended to use the values provided by tokens whenever\npossible. However, if no appropriate token exists for a specific value that must be retained, it is\npreferable to leave the value unchanged (without converting it to a token) rather than adding it as\na fallback."),(0,l.mdx)("p",null,"Fallback values were mostly used historically for large app migrations and are not recommended\nanymore."),(0,l.mdx)("p",null,"Design tokens are the new way to apply visual foundations in Atlassian app experiences. We’re\nrolling out tokens to standardize colors, elevations, spacing, and other styles in Atlassian apps."),(0,l.mdx)("h4",{id:"babel-plugin"},"Babel plugin"),(0,l.mdx)("p",null,"Our build-time Babel plugin is required to optimize the runtime performance of tokens by replacing\nany calls to the ",(0,l.mdx)("inlineCode",{parentName:"p"},"token()")," function in ",(0,l.mdx)("inlineCode",{parentName:"p"},"@atlaskit/tokens")," with the corresponding CSS value the\nfunction would return."),(0,l.mdx)("p",null,"If no fallback is provided, the plugin automatically retrieves the token value from the default\nAtlassian light theme and sets it as the fallback. This behavior can be disabled by setting the\nplugin second option ",(0,l.mdx)("inlineCode",{parentName:"p"},"shouldUseAutoFallback")," to ",(0,l.mdx)("inlineCode",{parentName:"p"},"false"),"."),(0,l.mdx)(s.A,{language:"diff",text:o.nY,shouldWrapLongLines:!0,mdxType:"C

1odeBlock"}),(0,l.mdx)("br",null),(0,l.mdx)("p",null,"By default, the plugin is configured to ignore explicit fallback values optionally provided in the\nsecond argument of the token() function. This behavior can be overridden by explicitly setting the\nplugin configuration option ",(0,l.mdx)("inlineCode",{parentName:"p"},"shouldForceAutoFallback")," to ",(0,l.mdx)("inlineCode",{parentName:"p"},"false"),"."),(0,l.mdx)("p",null,(0,l.mdx)("strong",{parentName:"p"},"Usage")),(0,l.mdx)("p",null,"Add the plugin to your babel configuration:"),(0,l.mdx)(s.A,{language:"json",text:o.qH,shouldWrapLongLines:!0,mdxType:"CodeBlock"}),(0,l.mdx)("br",null),(0,l.mdx)("p",null,"If your codebase uses ",(0,l.mdx)("a",{parentName:"p",href:"https://compiledcssinjs.com/docs/installation#babel"},"Compiled"),", then add the\nplugin to its configuration as well:"),(0,l.mdx)(s.A,{language:"json",text:o.SK,shouldWrapLongLines:!0,mdxType:"CodeBlock"}),(0,l.mdx)("br",null),(0,l.mdx)("h3",{id:"removing-existing-token-fallbacks"},"Removing existing token fallbacks"),(0,l.mdx)("p",null,"If fallback values were used during the migration to tokens, it is essential to remove them from the\ncodebase once migration is complete and themes are enabled. This helps to improve performance by\nreducing the critical CSS size and simplifies development efforts."),(0,l.mdx)("h4",{id:"prerequisites"},"Prerequisites"),(0,l.mdx)("p",null,"Ensure the following before proceeding:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("strong",{parentName:"li"},"Babel plugin enabled"),": The ",(0,l.mdx)("inlineCode",{parentName:"li"},"@atlaskit/tokens/babel-plugin")," should be active with\n",(0,l.mdx)("inlineCode",{parentName:"li"},"shouldUseAutoFallback")," set to ",(0,l.mdx)("inlineCode",{parentName:"li"},"true"),". This ensures fallback values are automatically handled\nduring build time."),(0,l.mdx)("li",{parentName:"ul"},(0,l.mdx)("strong",{parentName:"li"},"Themes enabled"),": Verify that ADS themes are applied in your app. Fallbacks can only be safely\nremoved for token categories with active themes (e.g color, space, or typography tokens).")),(0,l.mdx)("h4",{id:"steps-for-fallback-removal"},"Steps for fallback removal"),(0,l.mdx)("ol",null,(0,l.mdx)("li",{parentName:"ol"},(0,l.mdx)("p",{parentName:"li"},(0,l.mdx)("strong",{parentName:"p"},"Implicit Fallback Removal"),":"),(0,l.mdx)("ul",{parentName:"li"},(0,l.mdx)("li",{parentName:"ul"},"Update your Babel plugin configuration to include ",(0,l.mdx)("inlineCode",{parentName:"li"},"shouldForceAutoFallback: true"),". This setting\nforces the plugin to ignore any explicit fallbacks in the code, using default theme values\ninstead."),(0,l.mdx)("li",{parentName:"ul"},"Define ",(0,l.mdx)("inlineCode",{parentName:"li"},"forceAutoFallbackExemptions")," for token categories that do not currently have an active\ntheme. This ensures the preservation of existing token fallbacks rendered in the app,\npreventing unintended UI changes."))),(0,l.mdx)("li",{parentName:"ol"},(0,l.mdx)("p",{parentName:"li"},(0,l.mdx)("strong",{parentName:"p"},"Explicit fallback removal"),":"),(0,l.mdx)("ul",{parentName:"li"},(0,l.mdx)("li",{parentName:"ul"},"Install the codemod: ",(0,l.mdx)("a",{parentName:"li",href:"https://www.npmjs.com/package/@atlaskit/codemod-cli"},"https://www.npmjs.com/package/@atlaskit/codemod-cli")),(0,l.mdx)("li",{parentName:"ul"},"Run the codemod to remove fallback values from your codebase:",(0,l.mdx)(s.A,{language:"shell",text:o.Fy,shouldWrapLongLines:!0,mdxType:"C

1odeBlock"})),(0,l.mdx)("li",{parentName:"ul"},"Use ",(0,l.mdx)("inlineCode",{parentName:"li"},"--skipTokens")," to align with ",(0,l.mdx)("inlineCode",{parentName:"li"},"forceAutoFallbackExemptions")," for any themes that are not yet\nenabled (note that currently radius tokens are automatically exempted)."),(0,l.mdx)("li",{parentName:"ul"},"Use ",(0,l.mdx)("inlineCode",{parentName:"li"},"--forceUpdate")," to remove fallbacks regardless of their values. Without the option it would\npreserve fallbacks that differ from the token value. Omitting this option is only valuable when\nyou don’t have ",(0,l.mdx)("inlineCode",{parentName:"li"},"shouldForceAutoFallback")," enabled or are unsure if themes are enabled in the app\nand therefore would like to remove fallbacks gradually starting with the ones that won’t have\nUI impact if removed."),(0,l.mdx)("li",{parentName:"ul"},"Use ",(0,l.mdx)("inlineCode",{parentName:"li"},"--addEslintComments")," to automatically add eslint suppressions for the fallbacks that\nshouldn’t be removed, such as the ones configured in ",(0,l.mdx)("inlineCode",{parentName:"li"},"forceAutoFallbackExemptions"),"."))),(0,l.mdx)("li",{parentName:"ol"},(0,l.mdx)("p",{parentName:"li"},"Use ESLint to ensure fallbacks are not used in the future. This can be done by enabling the\n",(0,l.mdx)("inlineCode",{parentName:"p"},"@atlaskit/design-system/no-unsafe-design-token-usage"),"\n",(0,l.mdx)("a",{parentName:"p",href:"https://www.npmjs.com/package/@atlaskit/eslint-plugin-design-system"},"ESLint rule")," with\n",(0,l.mdx)("inlineCode",{parentName:"p"},"fallbackUsage: 'none'")," to prevent new fallbacks from being added."))),(0,l.mdx)("h2",{id:"stay-up-to-date"},"Stay up to date"),(0,l.mdx)("p",null,"As our color system is applied to new apps, changes to our tokens will be released regularly. To\nstay up to date, install our linting support tools:"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},"For CSS in JS applications, use\n",(0,l.mdx)("a",{parentName:"li",href:"https://atlassian.design/components/eslint-plugin-design-system/usage"},"ESLint"),"."),(0,l.mdx)("li",{parentName:"ul"},"For CSS (vanilla), Less, Sass, use\n",(0,l.mdx)("a",{parentName:"li",href:"https://atlassian.design/components/stylelint-design-system/usage"},"Stylelint"),".")),(0,l.mdx)("p",null,"These will warn you if you’re using deprecated tokens, and will assist in updating your app to the\nlatest tokens."),(0,l.mdx)(s.A,{language:"js",text:o.qQ,shouldWrapLongLines:!0,mdxType:"C

1odeBlock"}),(0,l.mdx)("h2",{id:"whats-next"},"What's next"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},"Search the list of ",(0,l.mdx)("a",{parentName:"li",href:"https://atlassian.design/components/tokens/all-tokens"},"all design tokens")," for\nfull descriptions and token values."),(0,l.mdx)("li",{parentName:"ul"},"See design token ",(0,l.mdx)("a",{parentName:"li",href:"https://atlassian.design/components/tokens/examples"},"code examples"),"."),(0,l.mdx)("li",{parentName:"ul"},"Browse our ",(0,l.mdx)("a",{parentName:"li",href:"https://atlassian.design/components/tokens/code"},"token API reference and changelog"),"."),(0,l.mdx)("li",{parentName:"ul"},"Use the ",(0,l.mdx)("a",{parentName:"li",href:"https://atlassian.design/component/image"},"image component")," to theme images.")),(0,l.mdx)("h2",{id:"get-help"},"Get help"),(0,l.mdx)("ul",null,(0,l.mdx)("li",{parentName:"ul"},"Atlassians can get help with tokens in ",(0,l.mdx)("a",{parentName:"li",href:"https://go.atlassian.com/help-design-system"},"Slack"),"."),(0,l.mdx)("li",{parentName:"ul"},"Partners and other developers who need help with tokens can post in the\n",(0,l.mdx)("a",{parentName:"li",href:"https://community.developer.atlassian.com/"},"developer community"),"."),(0,l.mdx)("li",{parentName:"ul"},"For general help with the Atlassian Design system,\n",(0,l.mdx)("a",{parentName:"li",href:"https://atlassian.design/contact-us"},"contact us"),".")))}m.isMDXComponent=!0;var u=()=>a.createElement(i.A,{categorySlug:"use-tokens-in-code",title:"Use tokens in code",description:"Learn how to set up and use design tokens in code.",entries:[]},a.createElement(m,null))}}]);
2//# sourceMappingURL=component---src-pages-foundations-tokens-use-tokens-in-code-index-tsx-f2416d1c78469c0f5631.js.map