@atlaskit/ads-mcp 1.10.10 → 1.10.11
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +10 -0
- package/dist/cjs/tools/get-guidelines/guidelines-structured-content.codegen.js +7 -7
- package/dist/cjs/tools/plan/list-plan-tool.js +1 -1
- package/dist/cjs/tools/search-components/list-search-components-tool.js +1 -1
- package/dist/es2019/tools/get-guidelines/guidelines-structured-content.codegen.js +7 -7
- package/dist/es2019/tools/plan/list-plan-tool.js +1 -1
- package/dist/es2019/tools/search-components/list-search-components-tool.js +1 -1
- package/dist/esm/tools/get-guidelines/guidelines-structured-content.codegen.js +7 -7
- package/dist/esm/tools/plan/list-plan-tool.js +1 -1
- package/dist/esm/tools/search-components/list-search-components-tool.js +1 -1
- package/dist/types/tools/get-guidelines/guidelines-structured-content.codegen.d.ts +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,15 @@
|
|
|
1
1
|
# @atlaskit/ads-mcp
|
|
2
2
|
|
|
3
|
+
## 1.10.11
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- [`be9d6ed7167a7`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/be9d6ed7167a7) -
|
|
8
|
+
Add semantic guidance for selected, focused, hovered, and pressed states.
|
|
9
|
+
- [`894cb86918ab5`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/894cb86918ab5) -
|
|
10
|
+
Document canonical Figma design sources in ADS component discovery and planning guidance.
|
|
11
|
+
- Updated dependencies
|
|
12
|
+
|
|
3
13
|
## 1.10.10
|
|
4
14
|
|
|
5
15
|
### Patch Changes
|
|
@@ -9,7 +9,7 @@ exports.guidelinesStructuredContent = void 0;
|
|
|
9
9
|
*
|
|
10
10
|
* Structured content for content guidelines from design-system-docs foundations content.
|
|
11
11
|
*
|
|
12
|
-
* @codegen <<SignedSource::
|
|
12
|
+
* @codegen <<SignedSource::1b96ec67cc0ed9ff8b2fe3bd5f02fc67>>
|
|
13
13
|
* @codegenCommand yarn build structured-docs
|
|
14
14
|
*/
|
|
15
15
|
|
|
@@ -20,8 +20,8 @@ var guidelinesStructuredContent = exports.guidelinesStructuredContent = [{
|
|
|
20
20
|
content: '## About border tokens\n\nBorders define boundaries and add emphasis using a combination of width and color tokens. Width\ntokens control a border\'s prominence, while color tokens provide its meaning. Pair these tokens to\ncommunicate an element’s purpose, such as a simple divider, or a visible interactive state.\n\n## Border width tokens and usage guidelines\n\nUse border width tokens to provide a clear and intentional way to apply width across different\nstates and use cases.\n\n<Stack space="space.200">\n\t<BorderTable />\n\t<Text>* Token values are subject to change and should be used as an indication only.</Text>\n</Stack>\n\n### Default border width\n\nThe `border.width` token is the default value for all standard borders and dividers. It establishes\nthe baseline thickness for components that require a subtle, defining outline, ensuring they are\nvisually distinct.\n\n\n\n### Selected states\n\nUse the `border.width.selected` token to show users which option they’ve selected from a group.\nApply this token to highlight a user\'s choice, such as an active tab or a chosen item in a list.\n\n\n\n### Focus ring\n\nUse the `border.width.focused` token to define the thickness of the focus ring. Apply this token to\nshow keyboard users where they are on the page. When users press Tab to move through an interface,\nthe token highlights the active element they can interact with. This helps make your interface\naccessible to everyone.\n\n\n\n## Border color and width pairing\n\nCreate borders by pairing width and color tokens. Choose:\n\n- width tokens to control how thick and visible your border appears\n- color tokens to show what the border means, like its state or importance\n\nAlways pair the right width token with the right color token to keep your interface consistent and\nclear for users.\n\n\n\n### Visual indicator for selected state\n\nAlways pair the `border.width.selected` token with the `color.border.selected` token, to show users\nwhich items they’ve selected. Use this combination to consistently highlight selected elements, like\nan active tab or a chosen list item, throughout the interface.\n\n\n\n### Required pairing for focus state\n\nAlways pair the `border.width.focused` token with the `color.border.focused` token to define the\nthickness of the focus ring.\n\nUse this combination to consistently highlight elements that receive keyboard focus, so users always\nknow which element is active and ready for interaction.\n\nTo ensure consistency and accessibility when adding a focused state to your components, follow these\nstandards:\n\n- **Code:** Use the\n [Focusable component](https://atlassian.design/components/primitives/focusable/examples) to wrap\n all interactive elements requiring focus.\n- **Design:** Use the\n [Focus Ring component (Atlassians only)](https://go.atlassian.com/focus-ring-component) from the\n Atlassian Design System Figma library.\n\n\n\nIt’s important to consider contrast when using different accent colors in your UI. For subtle\nbackgrounds, pair them with an accent border to meet the 3:1 contrast requirement for accessibility.\n\n[More about accent colors](https://atlassian.design/foundations/color/accents#use-borders-for-more-contrast-around-subtle-backgrounds)\n\n',
|
|
21
21
|
keywords: ['border', 'stroke', 'outline', 'design tokens', 'visual hierarchy']
|
|
22
22
|
}, {
|
|
23
|
-
content: '## Color anatomy\n\n### Saturated colors\n\nSaturated colors can infuse meaning to an experience, highlight UI, or create associations with\nsimilar colored UI.\n\n<img\n\tsrc={colorSaturatedPaletteLight}\n\talt="Color ramps for all saturated colors, which are blue, teal, green, lime, yellow, orange, red, magenta, and purple."\n/>\n\n### Neutral colors\n\nNeutral colors apply to most backgrounds, text, and shapes in our experiences. They don’t typically\nhave a meaning associated with them, though they can imply things like disabled states.\n\n<img\n\tsrc={colorNeutralPaletteLight}\n\talt="There are dedicated neutrals for both light and dark mode."\n/>\n\nColor ramp for light neutrals, and a separate color ramp for dark neutrals.\n\n### Alpha colors\n\nAlpha colors have varying levels of transparency or opacity. Transparency helps UI adapt to\ndifferent background colors and elevations.\n\n<img\n\tsrc={colorAlphaPaletteLight}\n\talt="Light and dark alpha neutral ramps with a circle appearing behind part of the ramps, which demonstrate the transparent quality of the colors."\n/>\n\nIf you aren\'t using design tokens, see our\n[color palette page](https://atlassian.design/foundations/color/color-palette) for hex codes and\nRGBa values.\n\n## Applying color with design tokens\n\nFor most Atlassian app experiences, colors are applied using\n[design tokens](https://atlassian.design/tokens/design-tokens). This means rather than choosing a\ncertain shade or value, you’ll choose a design token to apply colors.\n\nFor the full list of color design tokens and their values, see our\n[design token reference list](https://atlassian.design/components/tokens/all-tokens). Every token\ncomes with a description to help you ensure you’re using the correct one.\n\n<img\n\tsrc={colorTokensInScreenLight}\n\talt="Screenshot of a Jira board mapped to different token examples. The board title uses “color.text”, task icon uses “color.icon.accent.green”, and the button background uses “color.background.brand.bold."\n/>\n\nAll color design tokens start with the word “color”, followed by the property that it\'s applied to,\nsuch as a background, border, or icon.\n\n<img\n\tsrc={colorApplyingColor2Light}\n\talt="The design token name, “color.background.danger.bold.hovered”, broken down into parts. The property is “background”, and the modifier is “danger.bold.hovered."\n/>\n\nAfter the property name, the token may have one or more modifiers that represent the different parts\nof our color system: color role, emphasis level, and interaction state.\n\n## Color roles\n\nColor roles describe the intention behind the color. For example, color roles are applied to buttons\nto differentiate between primary, secondary, warning, or dangerous actions.\n\n<img\n\tsrc={colorRolesLight}\n\talt="Examples of color roles applied to button backgrounds. Primary button uses the brand color role, default button uses the neutral color role, warning button uses the warning color role, and danger uses the danger color role."\n/>\n\n<ColorRolesTable />\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: colorRoleDoLight, alt: \'\' }}>\n\t\tUse the right color role for your situation.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: colorRoleDontLight, alt: \'\' }}>\n\t\tDon’t use an accent when the color has semantic meaning.\n\t</DoDont>\n</DoDontGrid>\n\n## Emphasis levels\n\nEmphasis determines the amount of contrast a color has against the default surface. Emphasis can\nrange from subtlest to boldest. Bolder colors have more contrast against the default surface, which\nadds more attention than subtle colors.\n\n<img\n\tsrc={colorEmphasisLevelStatusLight}\n\talt="Comparing differences between bold and default lozenges. Bold lozenges have much more contrast than the default lozenges.Comparing differences between default, subtle, and subtlest text. Default text has the highest contrast, subtlest has the least."\n/>\n<img\n\tsrc={colorEmphasisLevelsTextLight}\n\talt="Comparing differences between default, subtle, and subtlest text. Default text has the highest contrast, subtlest has the least."\n/>\n\n### Use inverse tokens on bold backgrounds\n\nInverse tokens are designed to show on bold backgrounds. There are inverse tokens for text, borders,\nand icons on bold backgrounds.\n\nFor bold warning backgrounds, which are yellow, there are special `warning.inverse` tokens designed\nto pass WCAG AA contrast requirements.\n\n<img\n\tsrc={colorEmphasisLevelInverseLight}\n\talt="A danger banner and warning banner with text. The danger banner text is using “color.text.inverse”, and the warning banner text is using “color.text.warning.inverse."\n/>\n\n## Interaction states\n\nStates communicate the status of an interactive element.\n\n<img\n\tsrc={colorInteractionStatesLight}\n\talt="Button interaction states, which include default, hovered, and pressed states."\n/>\nUse hovered, pressed, selected, focused, or disabled tokens to create visual changes related to\ninteraction states.\n\n### Hovered and pressed for icons\n\nThere are no dedicated hovered and pressed tokens for icons. Instead, we recommend using a subtle\nneutral background to indicate state changes.\n\n<img\n\tsrc={colorInteractionStatesIconsLight}\n\talt="Icon interaction states. The default icon background uses “color.background.neutral.subtle”, the hovered icon background uses “color.background.neutral.subtle.hovered”, and the pressed icon background uses “color.background.neutral.subtle.pressed."\n/>\n\n## Accessibility in color\n\nWe comply with WCAG AA standard contrast ratios:\n\n- **Must pass 3:1 contrast:** Any UI essential to understanding the experience and text 24px or\n larger ([WCAG 1.4.11](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html))\n- **Must pass 4.5:1:** Text smaller than 24px\n ([WCAG 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html))\n\nSee our [color accessibility](https://atlassian.design/foundations/accessibility#colors) guidance\nfor more information.\n\n## Designing in dark mode\n\nDesign tokens currently support two color themes: light and dark. Each color design token maps to a\ndifferent value for each theme so their appearance differs depending on which theme is being used.\n\n- To learn the basics of tokens and themes, go to\n [design tokens](https://atlassian.design/tokens/design-tokens).\n- For detailed mappings from light to dark colors, see\n [picking colors for dark mode](https://atlassian.design/foundations/color/color-palette#picking-colors-for-dark-mode).\n Note that if you are using design tokens, you shouldn’t have to map your own values.\n\n## Related\n\n- Learn about the basics of [design tokens](https://atlassian.design/tokens/design-tokens).\n- If you need hex codes, RGBA values, or dark mode mappings, see our\n [color palettes](https://atlassian.design/foundations/color/color-palette).\n- For guidance on color usage in charts, read our\n [data visualization color guideline](https://atlassian.design/foundations/color/data-visualization-color).\n- See the list of [all design tokens](https://atlassian.design/components/tokens/all-tokens) for\n full descriptions and values for all tokens.',
|
|
24
|
-
keywords: ['color', '
|
|
23
|
+
content: '## Color anatomy\n\n### Saturated colors\n\nSaturated colors can infuse meaning to an experience, highlight UI, or create associations with\nsimilar colored UI.\n\n<img\n\tsrc={colorSaturatedPaletteLight}\n\talt="Color ramps for all saturated colors, which are blue, teal, green, lime, yellow, orange, red, magenta, and purple."\n/>\n\n### Neutral colors\n\nNeutral colors apply to most backgrounds, text, and shapes in our experiences. They don’t typically\nhave a meaning associated with them, though they can imply things like disabled states.\n\n<img\n\tsrc={colorNeutralPaletteLight}\n\talt="There are dedicated neutrals for both light and dark mode."\n/>\n\nColor ramp for light neutrals, and a separate color ramp for dark neutrals.\n\n### Alpha colors\n\nAlpha colors have varying levels of transparency or opacity. Transparency helps UI adapt to\ndifferent background colors and elevations.\n\n<img\n\tsrc={colorAlphaPaletteLight}\n\talt="Light and dark alpha neutral ramps with a circle appearing behind part of the ramps, which demonstrate the transparent quality of the colors."\n/>\n\nIf you aren\'t using design tokens, see our\n[color palette page](https://atlassian.design/foundations/color/color-palette) for hex codes and\nRGBa values.\n\n## Applying color with design tokens\n\nFor most Atlassian app experiences, colors are applied using\n[design tokens](https://atlassian.design/tokens/design-tokens). This means rather than choosing a\ncertain shade or value, you’ll choose a design token to apply colors.\n\nFor the full list of color design tokens and their values, see our\n[design token reference list](https://atlassian.design/components/tokens/all-tokens). Every token\ncomes with a description to help you ensure you’re using the correct one.\n\n<img\n\tsrc={colorTokensInScreenLight}\n\talt="Screenshot of a Jira board mapped to different token examples. The board title uses “color.text”, task icon uses “color.icon.accent.green”, and the button background uses “color.background.brand.bold."\n/>\n\nAll color design tokens start with the word “color”, followed by the property that it\'s applied to,\nsuch as a background, border, or icon.\n\n<img\n\tsrc={colorApplyingColor2Light}\n\talt="The design token name, “color.background.danger.bold.hovered”, broken down into parts. The property is “background”, and the modifier is “danger.bold.hovered."\n/>\n\nAfter the property name, the token may have one or more modifiers that represent the different parts\nof our color system: color role, emphasis level, and interaction state.\n\n## Color roles\n\nColor roles describe the intention behind the color. For example, color roles are applied to buttons\nto differentiate between primary, secondary, warning, or dangerous actions.\n\n<img\n\tsrc={colorRolesLight}\n\talt="Examples of color roles applied to button backgrounds. Primary button uses the brand color role, default button uses the neutral color role, warning button uses the warning color role, and danger uses the danger color role."\n/>\n\n<ColorRolesTable />\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: colorRoleDoLight, alt: \'\' }}>\n\t\tUse the right color role for your situation.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: colorRoleDontLight, alt: \'\' }}>\n\t\tDon’t use an accent when the color has semantic meaning.\n\t</DoDont>\n</DoDontGrid>\n\n## Emphasis levels\n\nEmphasis determines the amount of contrast a color has against the default surface. Emphasis can\nrange from subtlest to boldest. Bolder colors have more contrast against the default surface, which\nadds more attention than subtle colors.\n\n<img\n\tsrc={colorEmphasisLevelStatusLight}\n\talt="Comparing differences between bold and default lozenges. Bold lozenges have much more contrast than the default lozenges.Comparing differences between default, subtle, and subtlest text. Default text has the highest contrast, subtlest has the least."\n/>\n<img\n\tsrc={colorEmphasisLevelsTextLight}\n\talt="Comparing differences between default, subtle, and subtlest text. Default text has the highest contrast, subtlest has the least."\n/>\n\n### Use inverse tokens on bold backgrounds\n\nInverse tokens are designed to show on bold backgrounds. There are inverse tokens for text, borders,\nand icons on bold backgrounds.\n\nFor bold warning backgrounds, which are yellow, there are special `warning.inverse` tokens designed\nto pass WCAG AA contrast requirements.\n\n<img\n\tsrc={colorEmphasisLevelInverseLight}\n\talt="A danger banner and warning banner with text. The danger banner text is using “color.text.inverse”, and the warning banner text is using “color.text.warning.inverse."\n/>\n\n## Interaction states\n\nStates communicate the status of an interactive element.\n\n<img\n\tsrc={colorInteractionStatesLight}\n\talt="Button interaction states, which include default, hovered, and pressed states."\n/>\nUse hovered, pressed, selected, focused, or disabled tokens to create visual changes related to\ninteraction states.\n\n### Keep selected and focused states distinct\n\nA selected state persists after an interaction to show someone’s current choice. A focused state\nshows where keyboard or input focus is currently located.\n\n- Use `color.background.selected`, `color.text.selected`, `color.icon.selected`, or\n `color.border.selected` to communicate selection.\n- Use `color.border.focused` only for focus indicators.\n- Don’t use link, brand, or focused tokens to communicate selection.\n- When an element is both selected and focused, preserve the selected treatment and add the focus\n indicator.\n\nPair selected colors with another visual cue, such as a checkmark, underline, border, or change in\nshape. This helps people identify selection without relying on color alone.\n\n### Layer hovered and pressed states onto the current state\n\nHovered and pressed states are temporary. Use the matching `hovered` or `pressed` token for the\nelement’s current state, and keep a selected item recognizable during interaction.\n\n### Hovered and pressed for icons\n\nThere are no dedicated hovered and pressed tokens for icons. Instead, we recommend using a subtle\nneutral background to indicate state changes.\n\n<img\n\tsrc={colorInteractionStatesIconsLight}\n\talt="Icon interaction states. The default icon background uses “color.background.neutral.subtle”, the hovered icon background uses “color.background.neutral.subtle.hovered”, and the pressed icon background uses “color.background.neutral.subtle.pressed."\n/>\n\n## Accessibility in color\n\nWe comply with WCAG AA standard contrast ratios:\n\n- **Must pass 3:1 contrast:** Any UI essential to understanding the experience and text 24px or\n larger ([WCAG 1.4.11](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html))\n- **Must pass 4.5:1:** Text smaller than 24px\n ([WCAG 1.4.3](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html))\n\nSee our [color accessibility](https://atlassian.design/foundations/accessibility#colors) guidance\nfor more information.\n\n## Designing in dark mode\n\nDesign tokens currently support two color themes: light and dark. Each color design token maps to a\ndifferent value for each theme so their appearance differs depending on which theme is being used.\n\n- To learn the basics of tokens and themes, go to\n [design tokens](https://atlassian.design/tokens/design-tokens).\n- For detailed mappings from light to dark colors, see\n [picking colors for dark mode](https://atlassian.design/foundations/color/color-palette#picking-colors-for-dark-mode).\n Note that if you are using design tokens, you shouldn’t have to map your own values.\n\n## Related\n\n- Learn about the basics of [design tokens](https://atlassian.design/tokens/design-tokens).\n- If you need hex codes, RGBA values, or dark mode mappings, see our\n [color palettes](https://atlassian.design/foundations/color/color-palette).\n- For guidance on color usage in charts, read our\n [data visualization color guideline](https://atlassian.design/foundations/color/data-visualization-color).\n- See the list of [all design tokens](https://atlassian.design/components/tokens/all-tokens) for\n full descriptions and values for all tokens.',
|
|
24
|
+
keywords: ['color', 'selected state colors', 'focus indicator colors', 'hovered and pressed states', 'contrast', 'palette', 'brand', 'design tokens', 'themes']
|
|
25
25
|
}, {
|
|
26
26
|
content: 'Accents don\'t communicate any specific meaning to users, unlike success, warning, or other\n[color roles](https://atlassian.design/foundations/color#color-roles).\n\nUse accent colors where users choose a color for their content (in\n[color pickers](https://atlassian.design/foundations/color/color-picker-swatches)), or in\nexperiences where color helps categorize content.\n\n<img\n\tsrc={accentsWhiteboardLight}\n\talt="Color ramps for all saturated colors, which are blue, teal, green, lime, yellow, orange, red, magenta, and purple."\n/>\n\n## Color options\n\nThere are 10 accent colors available: blue, teal, green, lime, yellow, purple, magenta, red, orange,\nand gray.\n\n<img src={accentsColorsLight} alt="Tags shown in the 10 accent colors." />\n\n## Applying accent colors\n\nEach accent color has dedicated [design tokens](https://atlassian.design/tokens/design-tokens) that\ncan be applied to backgrounds, text, borders and icons. The full list of tokens is available in\n[design token reference list](https://atlassian.design/components/tokens/all-tokens).\n\nIf you aren\'t sure whether to use an accent token, consider whether the color could be swapped for\nanother without changing the experience or meaning behind it.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: accentsRoleDo, alt: \'\' }}>\n\t\tUse accent tokens for any experience where the color is just one of many colors, and changing it\n\t\twould have no impact on the experience.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: accentsRoleDont, alt: \'\' }}>\n\t\tDon\'t use accent tokens when the color has a specific meaning in our system, such as\n\t\tinformation, warning, or success.\n\t</DoDont>\n</DoDontGrid>\n\n## Emphasis levels\n\nAccent tokens come in multiple shades, which can either provide different emphasis levels for visual\nhierarchy or be used to provide more color options for user-generated content.\n\n### Background accent tokens\n\nBackground accent tokens have four emphasis levels ranging from subtlest to bolder.\n\n<img\n\tsrc={accentsBackgroundAccentTokensLight}\n\talt="A color picker with four shades per color. There is a label pointing to each shade of purple. From most subtle to boldest, the labels say color.background.accent.purple.subtlest, color.background.accent.purple.subtler, color.background.accent.purple.subtle, and color.background.accent.purple.bold."\n/>\n\n### Text accent tokens\n\nText accent tokens have two emphasis levels – default and bolder.\n\n<img\n\tsrc={accentsTextAccentTokensLight}\n\talt="Examples of text in different colors. A label points to text in a lighter magenta that says color.text.accent.magenta.default. Another label points to text with a darker shade that says color.text.accent.magenta.bolder."\n/>\n\n### Icon accent tokens\n\nIcon accent tokens have two emphasis levels – default and bolder.\n\n<img\n\tsrc={accentsIconsLight}\n\talt="Examples of icons in different colors. A label points to an icon in a lighter magenta that says color.icon.accent.magenta.default. Another label points to an icon with a darker shade that says color.icon.accent.magenta.bolder."\n/>\n\n## Accent color accessibility\n\nWhen pairing accent text or icon colors against backgrounds, make sure they meet\n[minimum contrast requirements](https://atlassian.design/foundations/color#accessibility-in-color).\n\n- Pair default or bolder accent text or icons with subtlest and subtler accent backgrounds\n- Pair bolder accent text or icons with subtle accent backgrounds\n- Pair inverse text or icons with bolder accent backgrounds\n\nIf you\'re pairing text or icon tokens outside of these recommendations, ensure they meet the minimum\ncontrast requirements against the background.\n\n<img\n\tsrc={accentsColorAccessibility2Light}\n\talt="Visualization of how various teal text and background pairings can look. Default and bolder text appears on a subtlest background, default and bolder text appears on a subtler background, bolder text appears on a subtle background, and inverse text appears on a bolder background.Visualization of how various teal icon and background pairings can look. Default accent icons or icons using accent text appear on a subtlest background, an icon using accent text appears on a subtler or subtle background, and an inverse icon appears on a bolder background.\n"\n/>\n<img\n\tsrc={accentsColorAccessibilityLight}\n\talt="Visualization of how various teal text and background pairings can look. Default and bolder text appears on a subtlest background, default and bolder text appears on a subtler background, bolder text appears on a subtle background, and inverse text appears on a bolder background.Visualization of how various teal icon and background pairings can look. Default accent icons or icons using accent text appear on a subtlest background, an icon using accent text appears on a subtler or subtle background, and an inverse icon appears on a bolder background.\n"\n/>\n\n## Best practices\n\n### Avoid yellow\n\nYellow presents a unique challenge for accessibility and can appear more like brown. Consider using\na different accent color in its place, such as orange.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: accentsAvoidYellowDoLight, alt: \'\' }}>\n\t\tConsider using accent tokens other than yellow, such as orange.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: accentsAvoidYellowDontLight, alt: \'\' }}>\n\t\tAvoid using yellow accent tokens, as these become brown to meet contrast requirements.\n\t</DoDont>\n</DoDontGrid>\n\n### Use borders for more contrast around subtle backgrounds\n\nPair subtler accent backgrounds with accent borders if your\n[experience needs to pass 3:1 contrast](https://atlassian.design/foundations/color#accessibility-in-color).\n\nBolder accent backgrounds meet these requirements on their own. For data visualization, use our\n[chart tokens](https://atlassian.design/foundations/color/data-visualization-color#custom-charts)\ninstead.\n\n<img\n\tsrc={accentsBorderTokenLight}\n\talt="View of a calendar event with a label pointing to the border color that says color.border.accent.magenta. Another label points to the background color that says color.background.accent.magenta.subtler."\n/>\n\n### Avoid mixing different accent colors\n\nMaintain visual harmony by combining foreground and background elements with colors from the same\nfamily.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: accentsMixingColorsDoLight, alt: \'\' }}>\n\t\tPair accent background and foreground elements (text, icons, or borders) from the same color to\n\t\tcreate harmonious experiences.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: accentsMixingColorsDontLight, alt: \'\' }}>\n\t\tDon\'t mix accent backgrounds with different colored foreground elements (text, icons, or\n\t\tborders).\n\t</DoDont>\n</DoDontGrid>',
|
|
27
27
|
keywords: ['accent colors', 'status colors', 'semantic colors', 'success', 'warning', 'error']
|
|
@@ -29,7 +29,7 @@ var guidelinesStructuredContent = exports.guidelinesStructuredContent = [{
|
|
|
29
29
|
content: '## The palette\n\n<ColorPaletteRamps />\n\n## Picking colors for dark mode\n\nNeutral colors are set up in a way that makes it easy to convert a light theme to a dark theme. If\nyou use our [design tokens](https://atlassian.design/tokens/design-tokens) to apply colors, this\nmapping is done for you.\n\nThere is a light neutral ramp and an equivalent dark neutral ramp. Neutral100 in the light neutral\nramp should equate to DarkNeutral100 in the dark neutral ramp.\n\n<img\n\tsrc={paletteNeutralMapping}\n\talt="How light neutral ramp maps to dark neutral ramp in light and dark mode respectively."\n/>\n\nSaturated colors are also easy to convert from a light theme to a dark theme using symmetry. We\ncurrently have 10 swatches set up in each palette. If the swatches are divided in half, each half\nbecomes a mirror.\n\n<img\n\tsrc={paletteSaturatedMapping}\n\talt="How colors in the blue ramp maps across light and dark mode."\n/>\n\nFor instance, if a button color is 700 in light theme, it will be 400 in dark theme. If a section\nmessage background is 100 in light theme, it will be 1000 in dark theme. Design tokens will handle\nthese conversions for you.\n\n<img\n\tsrc={paletteJiraBoard}\n\talt="Screenshot of a Confluence page, which is shown half in light mode and half in dark mode. The button background uses B700 in light mode and B400 in dark mode. The section message background uses B100 in light mode and B1000 in dark mode."\n/>\n\nUsing symmetry is a great place to start and will cover most use cases. However, it may not work for\nall use cases and color mapping can be adjusted accordingly.\n\n## Dedicated to\n\nThese colors have been dedicated to honor the memory of Rosie and Alexandria, and will be woven into\nAtlassian apps and design for years to come.\n\n<ColorPaletteDedication />',
|
|
30
30
|
keywords: ['color palette', 'color system', 'brand colors', 'primary', 'secondary']
|
|
31
31
|
}, {
|
|
32
|
-
content: "Color pickers let users choose colors for elements in their content.\n\nUse design tokens for color pickers to ensure the colors work across different themes and\nexperiences.\n\n<img\n\tsrc={colorPickerExampleLight}\n\talt=\"Confluence page in edit mode with the text color picker open.\"\n/>\n\n## Choosing tokens for color pickers\n\n- [Text color pickers](#text-color-pickers)\n- [Background color pickers](#background-color-pickers)\n- [Chart color pickers](#chart-color-pickers)\n\nA range of colors and shades are available. Determine which ones to include based on the needs of\nyour experience.\n\n### Text color pickers\n\nThere are two accent shades of each text color for a total of 18 text token color options. See the\navailable [text accent tokens](https://atlassian.design/components/tokens/all-tokens#color-text) in\nthe design tokens list.\n\n<img\n\tsrc={colorPickerTextLight}\n\talt=\"A text color picker with two shades per color. There is a label pointing to each shade of purple as well as the white color option. From most bold to subtle, the labels say color.text.accent.purple.bolder, color.text.accent.purple.default, and color.text.inverse.\"\n/>\n\nIf you need additional text colors, you can add a third row of colors using our\n[accent icon colors](https://atlassian.design/components/tokens/all-tokens#color-icon). These meet\nthe right contrasts for large-scale text (at least 18px bold or 24px).\n\n### Background color pickers\n\nThere are four accent shades of each background color for a total of 36 background color options.\nSee the available\n[background accent tokens](https://atlassian.design/components/tokens/all-tokens#color-background)\nin the design tokens list.\n\n<img\n\tsrc={colorPickerBackgroundsLight}\n\talt=\"A background color picker with four shades per color. There is a label pointing to each shade of purple as well as the default color option. From most subtle to bold, the labels say color.background.accent.purple.subtlest, color.background.accent.purple.subtler, color.background.accent.purple.subtle, color.background.accent.purple.bolder, and elevation.surface.\"\n/>\n\n### Chart color pickers\n\nThere are three accent shades of each chart color for a total of 27 chart color options. See the\navailable [chart accent tokens](https://atlassian.design/components/tokens/all-tokens#color-chart)\nin the design tokens list.\n\n<img\n\tsrc={colorPickerChartLight}\n\talt=\"A chart color picker with three shades per color. There is a label pointing to each shade of purple. From most subtle to bold, the labels say color.chart.purple.bold, color.chart.purple.bolder, and color.chart.purple.boldest.\"\n/>\n\n## Best practices\n\n### Use tokens appropriate to the type of picker\n\nText tokens should be used for text color pickers, and background tokens should be used for\nbackground color pickers.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype=\"do\"\n\t\timage={{\n\t\t\turl: colorPickerChartRoleDo,\n\t\t\talt: 'Color picker showing chart tokens being used for a chart color picker',\n\t\t}}\n\t>\n\t\tUse design tokens appropriate to the type of picker.\n\t</DoDont>\n\t<DoDont\n\t\ttype=\"dont\"\n\t\timage={{\n\t\t\turl: colorPickerChartRoleDont,\n\t\t\talt: 'Color picker showing background tokens incorrectly being used for a chart color picker',\n\t\t}}\n\t>\n\t\tDon't use design tokens solely based on how the color looks.\n\t</DoDont>\n</DoDontGrid>\n\n### Ensure there are accessible color pairing options\n\nConsider how colors will be applied by customers to ensure appropriate options are available to\nsupport the creation of accessible content.\n\nFor example, check how text and background colors will be used together to ensure the emphasis\nlevels required for accessible pairings are available.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype=\"do\"\n\t\timage={{\n\t\t\turl: colorPickerAccessibleRoleDo,\n\t\t\talt: 'Color picker with text and background color options that can create accessible contrast ratios when paired together',\n\t\t}}\n\t>\n\t\tProvide color options that can be paired in a way that meets accessible contrasts.\n\t</DoDont>\n\t<DoDont\n\t\ttype=\"dont\"\n\t\timage={{\n\t\t\turl: colorPickerAccessibleRoleDont,\n\t\t\talt: 'Color picker with limited color options that cannot create accessible contrast ratios when paired together',\n\t\t}}\n\t>\n\t\tDon't offer colors in color pickers that do not support the creation of accessible content.\n\t</DoDont>\n</DoDontGrid>\n\n### Avoid yellow\n\nWhile yellow accent and chart tokens are available, we recommend not including them in your color\npicker.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype=\"do\"\n\t\timage={{\n\t\t\turl: colorPickerAvoidYellowTextDo,\n\t\t\talt: 'Color picker showing orange text color option instead of yellow',\n\t\t}}\n\t>\n\t\tConsider using accent tokens other than yellow, such as orange.\n\t</DoDont>\n\t<DoDont\n\t\ttype=\"dont\"\n\t\timage={{\n\t\t\turl: colorPickerAvoidYellowTextDont,\n\t\t\talt: 'Color picker showing yellow text color that appears brown due to contrast requirements',\n\t\t}}\n\t>\n\t\tAvoid using yellow accent tokens, as these become brown to meet contrast requirements.\n\t</DoDont>\n</DoDontGrid>\n\n### Use theme agnostic color descriptions\n\nAlways provide text descriptions for color options in a picker. Text descriptions should be included\nin a tooltip.\n\nUse emphasis levels to describe different shades of the same color, from subtlest to boldest. When\napplied to a background color picker, this might appear like:\n\n- Subtlest {color}\n- Subtler {color}\n- Subtle {color}\n- Bold {color}\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype=\"do\"\n\t\timage={{\n\t\t\turl: colorPickerAgnosticColorDo,\n\t\t\talt: 'Color picker with tooltips showing theme-agnostic descriptions like subtle blue and bold blue',\n\t\t}}\n\t>\n\t\tUse color descriptions that work across light and dark themes, such as 'subtle' and 'bold'.\n\t</DoDont>\n\t<DoDont\n\t\ttype=\"dont\"\n\t\timage={{\n\t\t\turl: colorPickerAgnosticColorDont,\n\t\t\talt: 'Color picker with tooltips showing theme-specific descriptions like light blue and dark blue',\n\t\t}}\n\t>\n\t\tDon't use terms such as 'light' and 'dark' to describe colors, as these descriptions become\n\t\tinaccurate between light and dark themes.\n\t</DoDont>\n</DoDontGrid>\n\nWhen defining text descriptions for inverse or default surface color options, use \"default\" as the\ncolor description where possible. In cases where this doesn't make sense, such as for inverse text,\nthe description can be changed dynamically between light and dark mode.\n\n<img\n\tsrc={colorPickerAgnosticColorLight}\n\talt=\"Color picker in both light mode and dark mode. One swatch option says 'White' in light mode and 'Black' in dark mode.\"\n/>",
|
|
32
|
+
content: "Color pickers let users choose colors for elements in their content.\n\nUse design tokens for color pickers to ensure the colors work across different themes and\nexperiences.\n\n<img\n\tsrc={colorPickerExampleLight}\n\talt=\"Confluence page in edit mode with the text color picker open.\"\n/>\n\n## Choosing tokens for color pickers\n\n- [Text color pickers](#text-color-pickers)\n- [Background color pickers](#background-color-pickers)\n- [Chart color pickers](#chart-color-pickers)\n\nA range of colors and shades are available. Determine which ones to include based on the needs of\nyour experience.\n\n### Text color pickers\n\nThere are two accent shades of each text color for a total of 18 text token color options. See the\navailable [text accent tokens](https://atlassian.design/components/tokens/all-tokens#color-text) in\nthe design tokens list.\n\n<img\n\tsrc={colorPickerTextLight}\n\talt=\"A text color picker with two shades per color. There is a label pointing to each shade of purple as well as the white color option. From most bold to subtle, the labels say color.text.accent.purple.bolder, color.text.accent.purple.default, and color.text.inverse.\"\n/>\n\nIf you need additional text colors, you can add a third row of colors using our\n[accent icon colors](https://atlassian.design/components/tokens/all-tokens#color-icon). These meet\nthe right contrasts for large-scale text (at least 18px bold or 24px).\n\n### Background color pickers\n\nThere are four accent shades of each background color for a total of 36 background color options.\nSee the available\n[background accent tokens](https://atlassian.design/components/tokens/all-tokens#color-background)\nin the design tokens list.\n\n<img\n\tsrc={colorPickerBackgroundsLight}\n\talt=\"A background color picker with four shades per color. There is a label pointing to each shade of purple as well as the default color option. From most subtle to bold, the labels say color.background.accent.purple.subtlest, color.background.accent.purple.subtler, color.background.accent.purple.subtle, color.background.accent.purple.bolder, and elevation.surface.\"\n/>\n\n### Chart color pickers\n\nThere are three accent shades of each chart color for a total of 27 chart color options. See the\navailable [chart accent tokens](https://atlassian.design/components/tokens/all-tokens#color-chart)\nin the design tokens list.\n\n<img\n\tsrc={colorPickerChartLight}\n\talt=\"A chart color picker with three shades per color. There is a label pointing to each shade of purple. From most subtle to bold, the labels say color.chart.purple.bold, color.chart.purple.bolder, and color.chart.purple.boldest.\"\n/>\n\n## Best practices\n\n### Use tokens appropriate to the type of picker\n\nText tokens should be used for text color pickers, and background tokens should be used for\nbackground color pickers.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype=\"do\"\n\t\timage={{\n\t\t\turl: colorPickerChartRoleDo,\n\t\t\talt: 'Color picker showing chart tokens being used for a chart color picker',\n\t\t}}\n\t>\n\t\tUse design tokens appropriate to the type of picker.\n\t</DoDont>\n\t<DoDont\n\t\ttype=\"dont\"\n\t\timage={{\n\t\t\turl: colorPickerChartRoleDont,\n\t\t\talt: 'Color picker showing background tokens incorrectly being used for a chart color picker',\n\t\t}}\n\t>\n\t\tDon't use design tokens solely based on how the color looks.\n\t</DoDont>\n</DoDontGrid>\n\n### Ensure there are accessible color pairing options\n\nConsider how colors will be applied by customers to ensure appropriate options are available to\nsupport the creation of accessible content.\n\nFor example, check how text and background colors will be used together to ensure the emphasis\nlevels required for accessible pairings are available.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype=\"do\"\n\t\timage={{\n\t\t\turl: colorPickerAccessibleRoleDo,\n\t\t\talt: 'Color picker with text and background color options that can create accessible contrast ratios when paired together',\n\t\t}}\n\t>\n\t\tProvide color options that can be paired in a way that meets accessible contrasts.\n\t</DoDont>\n\t<DoDont\n\t\ttype=\"dont\"\n\t\timage={{\n\t\t\turl: colorPickerAccessibleRoleDont,\n\t\t\talt: 'Color picker with limited color options that cannot create accessible contrast ratios when paired together',\n\t\t}}\n\t>\n\t\tDon't offer colors in color pickers that do not support the creation of accessible content.\n\t</DoDont>\n</DoDontGrid>\n\n### Avoid yellow\n\nWhile yellow accent and chart tokens are available, we recommend not including them in your color\npicker.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype=\"do\"\n\t\timage={{\n\t\t\turl: colorPickerAvoidYellowTextDo,\n\t\t\talt: 'Color picker showing orange text color option instead of yellow',\n\t\t}}\n\t>\n\t\tConsider using accent tokens other than yellow, such as orange.\n\t</DoDont>\n\t<DoDont\n\t\ttype=\"dont\"\n\t\timage={{\n\t\t\turl: colorPickerAvoidYellowTextDont,\n\t\t\talt: 'Color picker showing yellow text color that appears brown due to contrast requirements',\n\t\t}}\n\t>\n\t\tAvoid using yellow accent tokens, as these become brown to meet contrast requirements.\n\t</DoDont>\n</DoDontGrid>\n\n### Use theme agnostic color descriptions\n\nAlways provide text descriptions for color options in a picker. Text descriptions should be included\nin a tooltip.\n\nUse emphasis levels to describe different shades of the same color, from subtlest to boldest. When\napplied to a background color picker, this might appear like:\n\n- Subtlest \\{color\\}\n- Subtler \\{color\\}\n- Subtle \\{color\\}\n- Bold \\{color\\}\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype=\"do\"\n\t\timage={{\n\t\t\turl: colorPickerAgnosticColorDo,\n\t\t\talt: 'Color picker with tooltips showing theme-agnostic descriptions like subtle blue and bold blue',\n\t\t}}\n\t>\n\t\tUse color descriptions that work across light and dark themes, such as 'subtle' and 'bold'.\n\t</DoDont>\n\t<DoDont\n\t\ttype=\"dont\"\n\t\timage={{\n\t\t\turl: colorPickerAgnosticColorDont,\n\t\t\talt: 'Color picker with tooltips showing theme-specific descriptions like light blue and dark blue',\n\t\t}}\n\t>\n\t\tDon't use terms such as 'light' and 'dark' to describe colors, as these descriptions become\n\t\tinaccurate between light and dark themes.\n\t</DoDont>\n</DoDontGrid>\n\nWhen defining text descriptions for inverse or default surface color options, use \"default\" as the\ncolor description where possible. In cases where this doesn't make sense, such as for inverse text,\nthe description can be changed dynamically between light and dark mode.\n\n<img\n\tsrc={colorPickerAgnosticColorLight}\n\talt=\"Color picker in both light mode and dark mode. One swatch option says 'White' in light mode and 'Black' in dark mode.\"\n/>",
|
|
33
33
|
keywords: ['color picker', 'color swatches', 'text color tokens', 'background color tokens', 'chart color tokens', 'color selection', 'accessible colors', 'color contrast', 'design tokens', 'theme agnostic colors']
|
|
34
34
|
}, {
|
|
35
35
|
content: "import {\n\tBrandAndNeutralChartTokensTable,\n\tCategoricalChartTokensTable,\n\tSemanticChartTokensTable,\n} from '@af/design-system-docs-ui';\n\nData visualization is the representation of information in pictorial or graphical format, such as\ncharts, graphs, maps, and diagrams. These visuals aid in the communication of complex data so that\ninsights can be more easily drawn.\n\nBecause color can affect our perception of information, the appropriate use of color is critical in\nmaking a data visualization successful.\n\n## Applying color to data visualizations\n\nColor in Atlassian apps experiences are applied using\n[design tokens](https://atlassian.design/tokens/design-tokens). For data visualization, chart color\ntokens are available to ensure appropriate color contrasts can be met. Use chart tokens for lines,\nbars or other UI representing the data. For elements of the chart interface such as axes and text,\nuse border and text tokens.\n\n<img\n\tsrc={dataVisPageAnalyticsLight}\n\talt=\"In this chart example, the title and legend text uses `color.text`, the chart grid lines uses `color.border`, the threshold line uses `color.chart.neutral`, the line representing chart data uses `color.chart.brand`, and the tick labels uses `color.text.subtle`.\"\n/>\n\n- **Title**: `color.text`\n- **Tick label**: `color.text.subtle`\n- **Threshold or reference line**: `color.chart.neutral`\n- **Legend**: `color.text`\n- **Gridline**: `color.border`\n- **Mark**: `color.chart.brand`\n\n## Types of chart colors\n\n- [Single-color charts](https://atlassian.design/foundations/color/data-visualization-color#single-color-charts)\n- [Categorical](https://atlassian.design/foundations/color/data-visualization-color#categorical)\n- [Status and severity](https://atlassian.design/foundations/color/data-visualization-color#status-and-severity)\n- [Custom charts](https://atlassian.design/foundations/color/data-visualization-color#custom-charts)\n\nSequential and divergent chart colors are not currently supported.\n\n### Single-color charts\n\nFor data visualization requiring only one color, use `color.chart.brand` as the default color\nchoice. This ensures all data visualization embodies our brand's visual language.\n\nIf the data represents status or severity, use the appropriate\n[status or severity color token](https://atlassian.design/foundations/color/data-visualization-color#status-and-severity)\ninstead.\n\nTo highlight one piece of data from a data set, use `color.chart.neutral` for the less important\ninformation so that the important data can stand out.\n\n<img\n\tsrc={dataVisPageAnalyticsLight}\n\talt=\"Bar chart showing unit test coverage over time. Today is highlighted in blue.\"\n/>\n\n<BrandAndNeutralChartTokensTable />\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: dataVisColorRoleDo, alt: '' }}>\n\t\tUse a single color as the default for data visualizations. Only add more colors when needing to\n\t\tdifferentiate between data categories.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: dataVisColorRoleDont, alt: '' }}>\n\t\tDon't use more than one color in your data visualization if the additional colors don't serve\n\t\tany communication purpose.\n\t</DoDont>\n</DoDontGrid>\n\n### Categorical\n\nUse categorical chart colors when you need to differentiate two or more unrelated data categories\nfrom each other.\n\n<img\n\tsrc={dataVisCategoricalChartLight}\n\talt=\"Line chart using categorical colors to represent different conversion rates.\"\n/>\n\nFollow the same sequence as the numbers in the token names. This ensures each color is visually\ndistinct from its neighbors across all color deficiencies. If the display order can't be controlled\n(in line charts for example), provide\n[additional visual indicators](https://atlassian.design/foundations/color/data-visualization-color#dont-rely-on-color-alone).\n\n<CategoricalChartTokensTable />\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: dataVisCategoricalDo, alt: '' }}>\n\t\tLimit the number of colors presented in your data visualization to 5-6 by grouping additional\n\t\tcategories together.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: dataVisCategoricalDont, alt: '' }}>\n\t\tAvoid using more than 5-6 colors in a data visualization. Too many colors can hinder\n\t\tcomprehension.\n\t</DoDont>\n</DoDontGrid>\n\n### Status and severity\n\nThese chart colors use established color associations for status and severity, such as in progress,\nat risk, or high priority. Use these when you want to reinforce meaning through color in your data\nvisualization.\n\nIf more than one set of data exists for a given color association, use bold emphasis to represent\nthe more extreme value. For example, High priority and Highest priority both use danger tokens, but\nHighest uses `color.chart.danger.bold`.\n\nIt's important to note that status and severity colors may be hard for users with color deficiencies\nto tell apart. For this reason, use other\n[visual indicators](https://atlassian.design/foundations/color/data-visualization-color#dont-rely-on-color-alone)\nor consider\n[categorical colors](https://atlassian.design/foundations/color/data-visualization-color#categorical)\nas a better option.\n\n<img src={dataVisStatusSeverityLight} alt=\"Chart representing breakdown by priority.\" />\n\n<SemanticChartTokensTable />\n\n### Custom charts\n\nA generic set of chart color tokens is available to support data visualization experiences where end\nusers can choose their own colors.\n\nThey can also be used to build custom categorical color schemes, although our predefined\n[categorical tokens](https://atlassian.design/foundations/color/data-visualization-color#categorical)\nare recommended for better accessibility and consistency.\n\nThese tokens are available in every hue with three emphasis levels. See all custom chart tokens in\nour [design token reference list](https://atlassian.design/components/tokens/all-tokens#color-chart)\nor get guidance on\n[color picker swatches](https://atlassian.design/foundations/color/color-picker-swatches).\n\n<img src={dataVisCustomChartColorsLight} alt=\"Editing colors on a custom chart in Confluence.\" />\n\n## Interacting with chart data\n\nData visualization often allows users to drill into data by hovering or selecting a data point. Use\nchart hovered tokens to provide visual feedback for these interactions.\n\nAn alternative approach is to fade out data that isn't being interacted with. Use our\n`opacity.disabled` token for this implementation.\n\n<img\n\tsrc={dataVisChartDataLight}\n\talt=\"Two segmented bar chart examples. In the first example, hovering on one of the segments changes its shade. In the second example, hovering on one of the segments applies opacity to everything except the element being hovered on.\"\n/>\n\n## All chart color tokens\n\nFor the full list of chart design tokens and their values, see our\n[design token reference list](https://atlassian.design/components/tokens/all-tokens#color-chart).\nEvery token comes with a description to help you ensure you're using the correct one.\n\n## Chart color accessibility\n\nOur chart colors meet WCAG AA 3:1 contrast ratios when used on any of our\n[elevation surfaces](https://atlassian.design/foundations/elevation#types-of-elevations)\n([WCAG 1.4.11](https://www.w3.org/WAI/WCAG21/Understanding/non-text-contrast.html)).\n\nThe following sections provide more guidance to help you achieve better accessibility.\n\n### Apply a border or space between adjacent colors\n\nWhile these chart colors pass 3:1 contrast ratios against surfaces, they don't against each other.\nFor this reason, apply a space or border (`color.border.inverse`) as a visual separator between data\nelements.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: dataVisAdjacentColorDoLight, alt: '' }}>\n\t\tApply a visual separator between chart colors.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: dataVisAdjacentColorDontLight, alt: '' }}>\n\t\tDon't place chart colors adjacent to each other.\n\t</DoDont>\n</DoDontGrid>\n\n### Don't place text on chart colors\n\nOur chart colors don't support accessible pairings with text, which need at least a 4.5:1 contrast.\nConsider placing text next to the chart element instead.\n\nFor use cases where text is an essential feature (for example, calendar events), consider using our\nother [color tokens](https://atlassian.design/foundations/color) instead.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: dataVisTextChartsDo, alt: '' }}>\n\t\tPosition text nearby chart data.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: dataVisTextChartsDont, alt: '' }}>\n\t\tDon't apply text over chart colors.\n\t</DoDont>\n</DoDontGrid>\n\n### Don't rely on color alone\n\nAvoid using just color to communicate meaning in your data visualization. Incorporate other visual\nindicators such as shapes, line texture, patterns, or direct labels to support users in making sense\nof the data. [Highcharts](https://www.highcharts.com/demo) provide some good examples of these\naccessible chart experiences.\n\nAdditionally, providing the data in alternative formats, such as tables and text-based descriptions,\nwill ensure all users can access the data in their preferred format.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: dataVisLineChartDo, alt: '' }}>\n\t\tIncorporate visual indicators other than color into your data visualization.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: dataVisLineChartDont, alt: '' }}>\n\t\tDon't rely on color alone to communicate meaning in your data visualization.\n\t</DoDont>\n</DoDontGrid>\n\n## Data visualization in dark mode\n\nChart color tokens currently support two color themes: light and dark. Each token maps to a\ndifferent value for each theme so their appearance differs depending on which theme is being used.\n\n- To learn the basics of tokens and themes, go to\n [design tokens](https://atlassian.design/tokens/design-tokens).\n- For detailed mappings from light to dark colors, see\n [picking colors for dark mode](https://atlassian.design/foundations/color/color-palette#picking-colors-for-dark-mode).\n Note that if you are using design tokens, you shouldn't have to map your own values.",
|
|
@@ -77,7 +77,7 @@ var guidelinesStructuredContent = exports.guidelinesStructuredContent = [{
|
|
|
77
77
|
content: 'Icons are symbols designed to represent concepts or specific features. A company\'s iconography style\ncan express a lot about a brand and its values.\n\nAtlassian\'s iconography has rounded corners and curves to align with our typography and other\nrounded UI elements, whilst square end terminals add boldness to create a harmonious app expression\nof Atlassian\'s broader design language.\n\n## Iconography principles\n\nFollow these principles to design and use Atlassian icons in a cohesive, useful, and legible way.\n\n**Design for universal understanding**\n\nDesign icons that use widely recognized symbols and established visual metaphors. Ensure icons are\neasily understood by a diverse audience by avoiding specific cultural or language aspects.\n\n**Balance simplicity and detail to create legibility**\n\nCraft icons that are simple enough for quick recognition, yet detailed enough to convey meaning\neffectively, even at small sizes.\n\n**Maintain visual harmony**\n\nEnsure icons work together as a cohesive system by adhering to consistent size, shape, and style\nguidelines across the entire set.\n\n**Use icons intentionally**\n\nIcons are powerful signifiers that can aid comprehension and help with navigation. They can also add\nclutter or confuse people when used poorly. Use text labels to support icons wherever possible, and\navoid using icons where they aren’t necessary.\n\n## Using Atlassian icons\n\nAtlassian icons are available as a component (React), Figma library, and in our documentation:\n\n- [View Atlassian icons](https://atlassian.design/components/icon)\n- [Icon component usage](https://atlassian.design/components/icon/usage)\n- [Icon tile component](https://atlassian.design/components/icon/icon-tile)\n- [Figma library of Atlassian icons (Atlassian employees only)](https://go.atlassian.com/ads-icons-figma)\n\n## Visual style\n\nAtlassian’s icon style has a 1.5px stroke width with shapes that pair rounded corners with sharp\ninterior corners and square line caps.\n\n### Simplicity and metaphor\n\nWherever possible, use [existing icons](https://atlassian.design/components/icon) to maintain\nconsistency and reinforce visual concepts across Atlassian apps so they become familiar to\ncustomers.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: consistencyDo, alt: \'\' }}>\n\t\tUse an existing icon or visual metaphor for consistency and clarity wherever possible.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: consistencyDont, alt: \'\' }}>\n\t\tCreate a new icon if a suitable one already exists to represent the same metaphor.\n\t</DoDont>\n</DoDontGrid>\n\nUse simplified shapes with the minimum detail required to express a metaphor. The goal of an icon is\nto aid clear, quick comprehension — excess detail can distract and do the opposite. The small size\nof icons makes it harder to see fine details, so optimise for simplicity and legibility.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: simplifiedShapesDo, alt: \'\' }}>\n\t\tUse simple shapes with the minimum detail required to express a metaphor with clarity and\n\t\tlegibility.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: simplifiedShapesDont, alt: \'\' }}>\n\t\tDon’t add excess detail. This may distract and be challenging to understand at a small sizes.\n\t</DoDont>\n</DoDontGrid>\n\nWhen creating a new icon, use symbols that clearly represent a concept. Try to use metaphors with\nclear and established associations wherever possible.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: metaphorsDo, alt: \'\' }}>\n\t\tUse familiar symbols with clear and established associations that clearly represent a concept.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: metaphorsDont, alt: \'\' }}>\n\t\tUse caution when creating an icon that isn’t a widely recognized symbol. It may be confused with\n\t\tanother concept or misunderstood.\n\t</DoDont>\n</DoDontGrid>\n\n### Perspective and angles\n\nShapes should appear straight on or from a full 90 degree profile. Don’t use diagonal perspectives\nto create 3D shapes because these can be hard to discern at a glance, especially for people with\nsome cognitive disabilities.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: perspectiveDo, alt: \'\' }}>\n\t\tUse shapes that appear straight on without dimensionality.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: perspectiveDont, alt: \'\' }}>\n\t\tDon’t use diagonal perspectives to create 3D shapes as they can be hard to discern at a glance.\n\t</DoDont>\n</DoDontGrid>\n\n### Size and spacing\n\nSystem icons are drawn within a 16 × 16px bounding box and are available in two sizes:\n\n#### Medium (16px) — use in most cases\n\nMedium icons are 16 × 16px in size and are the **default** size in our system. This size balances\nharmoniously with body text and the density of Atlassian’s apps.\n\n#### Small (12px) — Use sparingly\n\nSmall icons are 12 × 12px in size and are downscaled from their 16px counterpart. This size should\nbe used sparingly as they aren\'t as legible as 16px icons. Limit usage of 12px icons to the\nfollowing uses:\n\n- **Chevrons** — always use 12px chevrons, particularly within buttons, icon buttons, and dropdowns\n to maintain cohesion with Atlassian\'s visual language.\n\n- **Field validation messaging** — use 12px status icons for information, warnings, and errors.\n\n- **Within small contained elements** — 12px icons balance with small text within tags, badges,\n statuses, and other similar compact elements.\n\n- **App affiliation** — use 12px icons for "Powered by Atlassian Intelligence" or other Atlassian\n app affiliations.\n\n- **Secondary actions** — use 12px icons to communicate hierarchy between primary way-finding icons\n and secondary actions so they don’t compete for attention.\n\n- **Supporting role** — use 12px icons for supporting actions that shouldn\'t draw attention away\n from important content.\n\n\n\nTo apply spacing around an icon, we recommend placing it within a Box primitive with a padding value\napplied from our spacing system.\n\nWhen larger icons sizes are needed for decorative purposes, consider using an\n[icon tile](https://atlassian.design/components/icon/icon-tile) which places the icon on a colored\nbackground tile. Icon tiles are available in multiple sizes and provides accessible icon and\nbackground color pairings.\n\n### Shapes\n\nIcons use consistent shapes to ensure a consistent look and feel across the set. We’ve designed each\nshape for optical scale and balance, so that taller, thinner shapes don’t feel like a different\nscale from shorter or wider shapes.\n\n\n\nWhen designing new icons, you can use our icon template with built-in keyline shapes to guide your\ndesigns.\n\nReusing existing shapes from other icons can also help with consistency across the set. Make sure to\nuse shapes that best represent the object metaphor you are expressing.\n\n### Corners and curves\n\nCurved edges lend to a friendlier feel, but keep internal edges sharp to maintain clarity.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: cornersDo, alt: \'\' }}>\n\t\tWhere possible, keep internal angles sharp.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: cornersDont, alt: \'\' }}>\n\t\tDon’t apply curves on internal anchor points.\n\t</DoDont>\n</DoDontGrid>\n\n### End caps\n\nEnd points should be squared off, not rounded.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: endPointsDo, alt: \'\' }}>\n\t\tSet end point style to "none" to ensure the path aligns with a pixel edge to prevent blurry\n\t\tresults.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: endPointsDont, alt: \'\' }}>\n\t\tDon’t use "round" or "square" stroke end point styles.\n\t</DoDont>\n</DoDontGrid>\n\n### Color\n\nLike most elements in our system, icons use design tokens for colors. Icons can use icon-specific\ncolor tokens or text color tokens for when you\'re matching an icon and text color. You can set the\ncolor of the icon using the\n[icon component](https://atlassian.design/components/icon/code#UNSAFE_IconNew-color).\n\nBoth icon and text color tokens are designed to have enough color contrast against backgrounds and\nsurfaces in Atlassian apps.\n\n## Contribution and adding new icons\n\nCurrently Atlassian teams can contribute icons to our system for new designs and features.\n\n- Before contributing an icon, look at our existing icon library and consider the following\n questions:\n- Is the icon I’m contributing very similar to another system icon?\n- Can I use an existing multi-purpose icon?\n- Could my icon be confused with another concept that exists in apps?\n- Does this design really require an icon at all? Would a text label, button, or other approach\n provide a clearer affordance for customer understanding?\n\nTo contribute a new icon, follow the\n[contribution guide (Atlassian employees only)](https://go.atlassian.com/ads-icon-contribution).\n\n## Related\n\n- Browse all icons and learn how to use them in apps with the\n [icon component](https://atlassian.design/components/icon).',
|
|
78
78
|
keywords: ['iconography', 'icons', 'visual design', 'symbols', 'brand', 'component design']
|
|
79
79
|
}, {
|
|
80
|
-
content: 'import {\n\tTypographyHeadingTable,\n\tTypographyBodyTable,\n\tTypographyMetricTable,\n\tTypographyCodeTable,\n} from \'@af/design-system-docs-ui\';\n\n\n\nimport {\n\tAtlassianLogoCard,\n\tAttributionCards,\n\tPropertyCards,\n\tAppCards,\n} from \'./_logo-asset-cards.partial\';\n\n\n\n\n\n\n\n\n\n<SectionMessage title="Download logos" appearance="information">\n\t<Stack space="space.100">\n\t\t<Text>\n\t\t\tThe full set of app (product) logos are available in{\' \'}\n\t\t\t<Link href="https://orangedam.atlassian.com/">Atlassian Mosaic</Link>.\n\t\t</Text>\n\t\t<Text>\n\t\t\tLogos used to represent third-party integrations are available in{\' \'}\n\t\t\t<Link href="https://atlaskit.stg.atlassian.com/packages/
|
|
80
|
+
content: 'import {\n\tTypographyHeadingTable,\n\tTypographyBodyTable,\n\tTypographyMetricTable,\n\tTypographyCodeTable,\n} from \'@af/design-system-docs-ui\';\n\n\n\nimport {\n\tAtlassianLogoCard,\n\tAttributionCards,\n\tPropertyCards,\n\tAppCards,\n} from \'./_logo-asset-cards.partial\';\n\n\n\n\n\n\n\n\n\n<SectionMessage title="Download logos" appearance="information">\n\t<Stack space="space.100">\n\t\t<Text>\n\t\t\tThe full set of app (product) logos are available in{\' \'}\n\t\t\t<Link href="https://orangedam.atlassian.com/">Atlassian Mosaic</Link>.\n\t\t</Text>\n\t\t<Text>\n\t\t\tLogos used to represent third-party integrations are available in{\' \'}\n\t\t\t<Link href="https://atlaskit.stg.atlassian.com/packages/design-system-experimentation/logo-third-party">\n\t\t\t\tAtlaskit staging (Atlassians only)\n\t\t\t</Link>\n\t\t\t.\n\t\t</Text>\n\t</Stack>\n</SectionMessage>\n\nThis page includes downloadable logo files for use in marketing contexts as well as specific usage\nguidance for app or marketing contexts.\n\nIf you want to add logos to app (product) experiences, use the\n[logo component](https://atlassian.design/components/logo/examples).\n\n## Download the logos\n\nEach downloadable file includes variations of color and layout in approved formats and the below\nelements combined together:\n\n- logomarks – the icon portion of a logo\n- wordmarks – the name of the app (product) or property\n- straplines or other secondary text.\n\nAssets for isolated logomarks are also included.\n\n\n\n### Our iconic Atlassian logo\n\nOur iconic company logo.\n\nInclude `Atlassian` as the alt-text for the logo in digital experiences.\n\n<AtlassianLogoCard />\n\n#### Atlassian app strapline\n\nThe Atlassian logomark and wordmark can be coupled with a list of app (product) names under it.\nFollow the below guidance when using logos that contain straplines:\n\n- Always centre the app names under the logo and don’t scale the logo below 280px wide.\n- Write Atlassian and the app name in the alt-text in digital experiences.\n\n\n\n### Attribution logos\n\nThe attribution logos are a type of lockup that combine app (product) or property logomarks with the\nAtlassian strapline.\n\nThey create consistency in our portfolio, and help customers connect them with our overall Atlassian\nbrand. Follow the below guidance when using attribution logos:\n\n- Only use attribution logos when the Atlassian context is not clear. For example, in\n advertisements, videos, and white papers. You don’t need to use them on Atlassian properties like\n [www.atlassian.com](https://www.atlassian.com) or in app (product) user interfaces.\n- Never compose your own attribution logos or deconstruct the official assets.\n- Write the name of the app (product)/property and Atlassian in the alt-text for in digital\n experiences.\n\n<AttributionCards />\n\n### Property logos\n\nThe Atlassian program and property logos are a lockup of the Atlassian logomark and wordmark and the\nname in Charlie Sans. Follow the below guidance when using property logos:\n\n- On a white background, the program name is rendered in neutral with the logo in primary blue. On\n darker backgrounds, both program and logo are white.\n- Write `Atlassian` and the name of the property as the alt-text in digital experiences.\n\n<PropertyCards />\n\n### App (product) logos\n\nWith the Atlassian System of Work and collections framework our primary products, secondary products\nand plaftform features are now referred to as apps.\n\nWe’ve updated our logos to reflect this change, using marks that symbolize functionality, contained\nin a tile. An app’s glyph is chosen based on the apps functionality; its tile color refers to its\ncollection.\n\nThe logomarks are contained by a tile shape, colored with their associated collection. Follow the\nbelow guidance when using App (product) logos:\n\n- Use when the Atlassian context is clear.\n- If you need to connect the app to Atlassian, use an attribution logo instead. For example, in a\n video or advertisement.\n- Write the name of the apps in the alt-text in digital experiences.\n\nAssets include both isolated logomarks and lockups with wordmarks.\n\n<AppCards />\n\n#### Logomarks\n\nA logomark is a symbol or icon shown without the app (product)/property name or brand workmark. For\nan app (product), this refers to the tile. Follow the below guidance when using logomarks:\n\n- If you’re including the logomark in product experiences, use the\n [icon](https://atlassian.design/components/logo/examples#icon) variant of the logo component.\n- Only use logomarks on their own when the context is very clear and where possible pair with\n descriptive text.\n- Write `Atlassian` or the app/property name in the alt-text in digital experiences.\n\n\n\nLogomarks are paired with native text in top navigations.\n\n\n\nLogomarks are suitable when rendering the app name natively in its environment is more legible and\nuser-friendly.\n\n\n\nLogomarks can be used when environmental restrictions do not allow for proper clearance guidelines\nto be followed for full logos.\n\n#### Logomark shape and size\n\nThe [logo](https://atlassian.design/components/logo) component comes in specific sizes and the\nlogomark has a pre-defined radius. These should not be altered.\n\nThe exception to this is when appearing on external sources such as Apple mobile apps and Google\nMarketplace where specific container shapes need to be used.\n\nLogomarks should never be nested inside additional containers.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: tileRadiusDo, alt: \'\' }}>\n\t\tUse the default radius values that are applied to the backgrounds of app logo icons.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: tileRadiusDont, alt: \'\' }}>\n\t\tDon’t adjust the radius values of the backgrounds of product logo icons.\n\t</DoDont>\n\t<DoDont type="do" image={{ url: containersDo, alt: \'\' }}>\n\t\tAllow breathing room around product logo icons.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: containersDont, alt: \'\' }}>\n\t\tDon’t add unnecessary containers around app logo icons.\n\t</DoDont>\n</DoDontGrid>\n\n### Aligning logos\n\n#### Align logomarks with other elements\n\n- Middle align with the logo mark when the copy is less than the height of the container.\n- Top-align or stack below with center-alignment if it’s taller than the container.\n\n\n\n#### Aligning app (product) logos\n\nWhere app (product) logos are arranged in a vertical or horizontal list, use the height or weight of\nthe logomark portion to align.\n\n \n\n## Logo clearance\n\nWhen displaying logos outside of an app UI, surround them with clear space free of type, graphics,\nand other elements that might cause visual clutter.\n\n#### Ideal clearance — Atlassian logo\n\n \n\n#### Minimum clearance — Atlassian logo\n\nUse the capital "A" of the Atlassian wordmark to define the minimum clearance around the logo.\n\n\n\n#### Ideal clearance — app (product) logo\n\n\n\n#### Minimum clearance — app (product) logo\n\nUse the height and width of the logo wordmark to find the minimum clearance around the logo.\n\n\n\n## Color options\n\nLogos are available in three color options to suit different colored environments – Brand, inverse\nand neutral.\n\n\n\nDon’t edit or place logos in ways that reduce the clarity and legibility of the image.\n\n<DoDontGrid>\n\t<DoDont type="dont" image={{ url: colorDont, alt: \'\' }}>\n\t\tDon’t use unapproved color combinations.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: shadowDont, alt: \'\' }}>\n\t\tDon’t use a drop shadow.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: legibilityDont, alt: \'\' }}>\n\t\tDon’t use the logo on top of complex backgrounds.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: outlineDont, alt: \'\' }}>\n\t\tDon’t outline the logo.\n\t</DoDont>\n</DoDontGrid>',
|
|
81
81
|
keywords: ['logos', 'brand', 'identity', 'logo usage', 'brand guidelines']
|
|
82
82
|
}, {
|
|
83
83
|
content: '## About radius tokens\n\nRadius tokens standardize corner roundness, ensuring consistency and cohesion throughout all of our\napps. Pair radius tokens with radius focus tokens to bring focus to the selected element. This helps\nusers identify which element is active.\n\n## Radius tokens and usage guidelines\n\nUse radius tokens to apply roundness across different states and use cases.\n\n<Stack space="space.200">\n\t<RadiusTable />\n\t<Text>* Token values are subject to change and should be used as an indication only.</Text>\n</Stack>\n\n## Radius examples and usage\n\n### Extra small\n\nUse the `radius.xsmall` token for extra small detail elements like badges, checkboxes, avatar\nlabels, and keyboard shortcuts.\n\n\n\n### Small\n\nUse the `radius.small` token for small elements like labels, lozenges, timestamps, tags, dates,\ntooltip containers, imagery inside tables, and compact buttons.\n\n\n\n### Medium\n\nUse the `radius.medium` token for interactive elements like buttons, inputs, text areas, selects,\nnavigation items, and smart links.\n\n\n\n### Large\n\nUse the `radius.large` token for elements like cards, in-page containers, floating UIs, and dropdown\nmenus.\n\n\n\n### Extra large\n\nUse the `radius.xlarge` token for full-page containers, large containers, modal dialogs, Kanban\ncolumns, and tables.\n\n\n\n### Extra extra large\n\nUse the `radius.xxlarge` token for video players.\n\n\n\n### Full\n\nUse the `radius.full` token for avatars, names, user-related UI, and emoji reactions. This token can\nalso be used for dividers and other pill-shaped elements since it results in a fully round radius.\n\n\n\n### Tile\n\nUse the `radius.tile` token exclusively for tile components, such as icon tile or object tile. This\ntoken should not be used outside of tiles.\n\n\n\n## Radius token for focus state\n\nA component\'s focus state is critical for accessibility. The corner radius of the focus ring must\nalign visually with the component it surrounds.\n\n### Focus state design specifications\n\n\n\nThe focus ring is implemented in two key ways:\n\n1. **Offset**: The focus ring is positioned 2px away from the component\'s bounding box.\n2. **Radius value**: The corner radius of the focus ring is always +2px greater than the component’s\n base corner radius value.\n\n### How to implement the focus ring for code and design\n\nThe focus ring is managed differently between code and design:\n\n- **In code**: When you’re using interactive design system components, focus rings are automatically\n applied. When you’re building custom components, use the\n [focusable component](https://atlassian.design/components/primitives/focusable/examples). The 2px\n visual offset and the radius calculation (component radius +2px) are automatically handled by the\n focusable component\'s logic. This means developers never need to apply a separate radius token for\n the focus state.\n- **In design**: Automatic calculations aren’t possible in design tools, so designers must use a\n dedicated set of tokens to enforce the correct radius relationship. These tokens mirror the\n component radius names but carry the calculated +2px value to ensure visual accuracy in design\n files.\n\n\n\n<Stack space="space.200">\n\t<RadiusFocusTable />\n\t<Text>* Token values are subject to change and should be used as an indication only.</Text>\n</Stack>',
|
|
@@ -92,10 +92,10 @@ var guidelinesStructuredContent = exports.guidelinesStructuredContent = [{
|
|
|
92
92
|
content: "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.\n\n## What are design tokens?\n\nDesign tokens are name and value pairings that represent small, repeatable design decisions. A token\ncan be a color, font style, unit of white space, or even a motion animation designed for a specific\nneed.\n\nFor example, instead of choosing one of many shades of green for an icon, we can apply a design\ntoken that is consistent with all similar usages across our apps: `color.icon.success`.\n\n\n\n## What are themes?\n\nA theme is a collection of token values designed to achieve a certain look or style. Themes are how\nwe switch color schemes and styles everywhere using a single set of tokens.\n\nLight mode, dark mode, and high-contrast mode are all examples of theming. Non-color themes are also\npossible: think cozy/comfortable/compact views, reduced motion, or custom typography styles.\n\n\n\n## Why use design tokens?\n\n- Features like global theming (dark mode), responsive design, and user customization are possible\n with tokens.\n- Design tokens simplify the design and development by streamlining decision making and handover\n between crafts.\n- As Atlassian's visual language evolves, changes can be made once across the system and apps. No\n more finding and replacing hard-coded values everywhere.\n- We have automated tooling to help designers and developers start using tokens faster.\n- Tokens are how we'll implement our newest visual foundations. This will deliver visual consistency\n and other improvements to Atlassian UI.\n\n## How to read design token names\n\nKnowing how to read token names will help you find the right token faster when working in designs\nand in code.\n\n\n\nA design token’s name describes how it should be used, and each part communicates one piece of its\nusage.\n\n1. **Foundation**: The type of visual design attribute or foundational style, such as color,\n elevation, or space.\n2. **Property**: The UI element the token is being applied to, such as a border, background, shadow,\n or other property.\n3. **Modifier**: Additional details about the token’s purpose, such as its color role, emphasis, or\n interaction state. Not every token has a modifier. For example, color.text is our default body\n text color.\n\nNote that token names might look different in different environments and tools:\n\n\n\n## Find and use tokens\n\nFind all of our available design tokens and their usage descriptions in\n[all tokens](https://atlassian.design/components/tokens/all-tokens).\n\nSearch and filter the token list, or use our token picker for extra help.\n\n### Best practices\n\nChoose tokens based on meaning where applicable, not specific values.\n\n<DoDontGrid>\n\t<DoDont type=\"do\" image={{ url: doIconColorImage, alt: '' }}>\n\t\tUse design tokens with names and descriptions that fit your specific situation.\n\t</DoDont>\n\t<DoDont type=\"dont\" image={{ url: dontIconColor, alt: '' }}>\n\t\tDon't use a token just because the colors appear to match. This can break the experience in\n\t\tother themes.\n\t</DoDont>\n</DoDontGrid>\n\nCheck our foundations for [color](https://atlassian.design/foundations/color),\n[elevation](https://atlassian.design/foundations/elevation), and\n[spacing](https://atlassian.design/foundations/spacing) for additional usage guidance.\n\n## Design token examples\n\nUse these examples to get a better understanding of how different tokens work.\n\n### Color tokens\n\nHere’s an example of color design tokens in use: the default text color and the background color for\na \"danger\" button on hover.\n\n\n\nThere are dedicated color tokens for text, links, icons, backgrounds, borders, blankets, charts, and\nskeleton loaders.\n\nFor more on color token usage, see our\n[color foundation](https://atlassian.design/foundations/color).\n\n### Elevation tokens\n\nElevation tokens apply to the perceived surface level and shadow.\n\n\n\nFor more on how and when to apply elevations, see our\n[elevation foundation](https://atlassian.design/foundations/elevation).\n\n### Opacity tokens\n\nOpacity tokens apply transparency to an element. Use `opacity.disabled` for interactive images that\nare disabled (such as disabled avatar), and `opacity.loading` to content sitting underneath a\nloading spinner.\n\n### Space tokens\n\nSpace tokens reduce decision making and allow for consistent spacing between elements in a page\nlayout. These tokens are designed to be use for horizontal and vertical spacing, in a variety of\ncontexts.\n\nFor more on how our spacing system, and how to use space in your designs, see our\n[spacing foundation](https://atlassian.design/foundations/spacing).\n\n\n\n### Typography tokens\n\nTo visually align typography across Atlassian apps, typography tokens include font values, including\nfont family, font size, font weights, and line heights for all text styles.\n\nFor more on how to start working with typography tokens, see our\n[typography foundation](https://atlassian.design/foundations/typography).\n\n\n\n## What's next\n\n- Learn how to [Migrate to tokens](https://atlassian.design/tokens/migrate-to-tokens)\n- [Use tokens in designs](https://atlassian.design/tokens/use-tokens-in-design)\n- [Use tokens in code](https://atlassian.design/tokens/use-tokens-in-code)\n- For additional component examples and code samples, see\n [components examples](https://atlassian.design/components/tokens/examples).",
|
|
93
93
|
keywords: ['design tokens', 'tokens', 'design system', 'theming', 'variables', 'customization']
|
|
94
94
|
}, {
|
|
95
|
-
content: 'import {\n\tcodeMigrateToTokensJS,\n\tcodeMigrateToTokensCSS,\n\tcodeTokensCodemmod,\n\tcodeCodemodCli,\n} from \'../../../../snippets/code/migrate-to-tokens\';\n\nRead this guide to learn how to migrate an Atlassian app to tokens, and what’s changing for\ndesigners and developers.\n\n## Before you begin\n\nMake sure you understand the basics of\n[design tokens](https://atlassian.design/tokens/design-tokens).\n\n## How to migrate an app to tokens\n\nTeams will apply and test tokens across an experience before releasing new colors (dark mode) or\nother tokens publicly.\n\n### Changes for designers\n\nUse our Figma libraries to apply updated colors, design tokens, and themed components to your\ndesigns. We also have a Figma plugin to help you migrate design styles to tokens and generate\ndark-mode previews.\n\n\n\nAs migration continues, you\'ll also help test and review changes in your app with our\n[Chrome extension (Atlassians only)](https://go.atlassian.com/dst-chrome-theme-plugin).\n\nGet set up to [use tokens in designs](https://atlassian.design/tokens/use-tokens-in-design).\n\n### Changes for developers\n\nTo use and apply tokens in code:\n\n1. [Set up theming](https://atlassian.design/tokens/use-tokens-in-code#set-up-themes-and-theme-switching)\n in your application.\n2. Update any design system components to the latest versions (these already have tokens built-in).\n3. Replace raw CSS values (e.g. colors, padding, or typography values) with the tokens (our codemod\n speeds this up). See instructions in\n [use tokens in code](https://atlassian.design/tokens/use-tokens-in-code).\n\nConversion in code generally looks like this:\n\n<CodeBlock language="diff" text={codeMigrateToTokensJS} shouldWrapLongLines />\n<br></br>\n\n<CodeBlock language="css" text={codeMigrateToTokensCSS} shouldWrapLongLines />\n<br></br>\n\n<SectionMessage\n\ttitle="Rolling out color tokens in Marketplace apps and integrations"\n\tappearance="information"\n\tactions={[\n\t\t<SectionMessageAction href="https://community.developer.atlassian.com/t/start-using-design-tokens-in-your-apps-and-try-dark-theme-in-jira-cloud/64147">\n\t\t\tDeveloper community updates\n\t\t</SectionMessageAction>,\n\t\t<SectionMessageAction href="https://developer.atlassian.com/cloud/jira/platform/connect-theming/">\n\t\t\tInstructions for theming connect apps\n\t\t</SectionMessageAction>,\n\t]}\n>\n\tBefore any Atlassian app launches dark mode publicly, we’ll provide support and updates in our\n\tdeveloper community so that apps can prepare.\n</SectionMessage>\n\n#### Use our codemod for migration assistance\n\nWhen you run the\n[codemod](https://developer.atlassian.com/cloud/framework/atlassian-frontend/codemods/intro-to-codemods/),\nit goes into every single color in the target files and suggests tokens based on context of the\nsurrounding code.\n\nThis is what it
|
|
95
|
+
content: 'import {\n\tcodeMigrateToTokensJS,\n\tcodeMigrateToTokensCSS,\n\tcodeTokensCodemmod,\n\tcodeCodemodCli,\n} from \'../../../../snippets/code/migrate-to-tokens\';\n\nRead this guide to learn how to migrate an Atlassian app to tokens, and what’s changing for\ndesigners and developers.\n\n## Before you begin\n\nMake sure you understand the basics of\n[design tokens](https://atlassian.design/tokens/design-tokens).\n\n## How to migrate an app to tokens\n\nTeams will apply and test tokens across an experience before releasing new colors (dark mode) or\nother tokens publicly.\n\n### Changes for designers\n\nUse our Figma libraries to apply updated colors, design tokens, and themed components to your\ndesigns. We also have a Figma plugin to help you migrate design styles to tokens and generate\ndark-mode previews.\n\n\n\nAs migration continues, you\'ll also help test and review changes in your app with our\n[Chrome extension (Atlassians only)](https://go.atlassian.com/dst-chrome-theme-plugin).\n\nGet set up to [use tokens in designs](https://atlassian.design/tokens/use-tokens-in-design).\n\n### Changes for developers\n\nTo use and apply tokens in code:\n\n1. [Set up theming](https://atlassian.design/tokens/use-tokens-in-code#set-up-themes-and-theme-switching)\n in your application.\n2. Update any design system components to the latest versions (these already have tokens built-in).\n3. Replace raw CSS values (e.g. colors, padding, or typography values) with the tokens (our codemod\n speeds this up). See instructions in\n [use tokens in code](https://atlassian.design/tokens/use-tokens-in-code).\n\nConversion in code generally looks like this:\n\n<CodeBlock language="diff" text={codeMigrateToTokensJS} shouldWrapLongLines />\n<br></br>\n\n<CodeBlock language="css" text={codeMigrateToTokensCSS} shouldWrapLongLines />\n<br></br>\n\n<SectionMessage\n\ttitle="Rolling out color tokens in Marketplace apps and integrations"\n\tappearance="information"\n\tactions={[\n\t\t<SectionMessageAction href="https://community.developer.atlassian.com/t/start-using-design-tokens-in-your-apps-and-try-dark-theme-in-jira-cloud/64147">\n\t\t\tDeveloper community updates\n\t\t</SectionMessageAction>,\n\t\t<SectionMessageAction href="https://developer.atlassian.com/cloud/jira/platform/connect-theming/">\n\t\t\tInstructions for theming connect apps\n\t\t</SectionMessageAction>,\n\t]}\n>\n\tBefore any Atlassian app launches dark mode publicly, we’ll provide support and updates in our\n\tdeveloper community so that apps can prepare.\n</SectionMessage>\n\n#### Use our codemod for migration assistance\n\nWhen you run the\n[codemod](https://developer.atlassian.com/cloud/framework/atlassian-frontend/codemods/intro-to-codemods/),\nit goes into every single color in the target files and suggests tokens based on context of the\nsurrounding code.\n\nThis is what it can look like after applying and reviewing the codemod suggestions.\n\n<CodeBlock language="diff" text={codeTokensCodemmod} shouldWrapLongLines />\n<br></br>\n\nUse `@hypermod/cli` to run the codemods.\n\n<CodeBlock language="shell" text={codeCodemodCli} shouldWrapLongLines />\n<br></br>\n\nUse the `theme-to-design-tokens` transform for CSS in JS or `css-to-design-tokens` for vanilla CSS,\nSass, and Less.\n\nThe codemod only provides token suggestions, so manual review is required after running the codemod.\n\n#### Test changes with the Chrome extension\n\nTo view progress and toggle between themes in an app during migration, use our\n[Chrome extension (Atlassians only)](https://go.atlassian.com/dst-chrome-theme-plugin).\n\nYou can also pin the extension to your browser\'s toolbar for easy access from the Extension popup.\n\n## What\'s next\n\n- [Use tokens in design](https://atlassian.design/tokens/use-tokens-in-design)\n- [Use tokens in code](https://atlassian.design/tokens/use-tokens-in-code)\n- Learn our new [color](https://atlassian.design/foundations/color),\n [elevation](https://atlassian.design/foundations/elevation), and other foundation guidelines\n- Search for tokens in the [all tokens list](https://atlassian.design/components/tokens/all-tokens)\n\n## Get help\n\n- Atlassians can get help with token migrations in\n [Slack](https://go.atlassian.com/help-design-system).\n- Other developers who need help with tokens can post in the public\n [developer community](https://community.developer.atlassian.com/).\n- For general help with the Atlassian Design system,\n [contact us](https://atlassian.design/contact-us).',
|
|
96
96
|
keywords: ['migrate tokens', 'token migration', 'refactoring', 'design system adoption']
|
|
97
97
|
}, {
|
|
98
|
-
content: 'import {\n\tcodeSetUpThemes,\n\tcodeHtmlTheme,\n\tcodeUseTokens,\n\tcodeBabelPlugin,\n\tcodeBabelPluginUsage,\n\tcodeBabelPluginCompiled,\n\tcodeFallbackRemovalCodemod,\n\tcodeLintRules,\n} from \'../../../../snippets/code/use-tokens-in-code\';\n\nThis page explains how to set up and use\n[design tokens and themes](https://atlassian.design/tokens/design-tokens) in code.\n\n## Before you begin\n\nMake sure you’re\n[set up to use the Atlassian Design System](https://atlassian.design/get-started/develop). In\nparticular, make sure `@atlaskit/tokens` is installed as a dependency and use our\n[linting rules](https://atlassian.design/components/eslint-plugin-design-system/usage) to stay up to\ndate.\n\n## Set up themes and theme switching\n\nFor themes to work properly for users, theming must be set up in two places: the Atlassian\napplication and in any Marketplace apps extending that app experience.\n\nUse the [setGlobalTheme](https://atlassian.design/components/tokens/code#setglobalthemethemestate)\nmethod to switch themes globally at runtime in an Atlassian app or stand-alone application.\n\n<CodeBlock language="jsx" text={codeSetUpThemes} shouldWrapLongLines />\n<br></br>\n\nMake sure theming is set up by inspecting your app HTML. You should see something like this:\n\n<CodeBlock language="html" text={codeHtmlTheme} shouldWrapLongLines />\n<br></br>\n\nPay special attention to the `data-color-mode="dark"` attribute, and also note the\n`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.\n\n### Set up Atlassian fonts\n\nTo bring [Atlassian Sans and Atlassian Mono](https://atlassian.design/foundations/typography) web\nfonts into your app, follow our\n[setup guide (Atlassians only)](https://go.atlassian.com/set-up-fonts).\n\nThe typography theme is enabled by default when using `setGlobalTheme()`.\n\n### Set up themes for apps (Connect, Forge, Marketplace)\n\nFor Connect and Forge apps, see the following dedicated resources:\n\n- [Theming Connect apps](https://developer.atlassian.com/cloud/jira/platform/connect-theming/)\n- [Theming Forge apps](https://developer.atlassian.com/platform/forge/design-tokens-and-theming/)\n\n### Server-side rendering\n\nIf your application is using SSR (server-side rendering) ensure themes appear at the right time\nusing our\n[SSR theming utilities](https://atlassian.design/components/tokens/code#server-side-rendering-ssr-utilities).\n\n## Use tokens\n\nYou can access individual tokens using the CSS custom properties mounted to the page, however, it\'s\nbest to use the `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.\n\nThe `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.\n\n<CodeBlock language="jsx" text={codeUseTokens} shouldWrapLongLines />\n<br></br>\n\nIf you\'re migrating a lot of values to tokens,\n[use our codemod](https://atlassian.design/tokens/migrate-to-tokens#use-our-codemod-for-migration-assistance).\n\n### Migration to tokens\n\nThe `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.\n\nAt 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.\n\nFallback values were mostly used historically for large app migrations and are not recommended\nanymore.\n\nDesign 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.\n\n#### Babel plugin\n\nOur build-time Babel plugin is required to optimize the runtime performance of tokens by replacing\nany calls to the `token()` function in `@atlaskit/tokens` with the corresponding CSS value the\nfunction would return.\n\nIf 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 `shouldUseAutoFallback` to `false`.\n\n<CodeBlock language="diff" text={codeBabelPlugin} shouldWrapLongLines />\n<br></br>\n\nBy 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 `shouldForceAutoFallback` to `false`.\n\n**Usage**\n\nAdd the plugin to your babel configuration:\n\n<CodeBlock language="json" text={codeBabelPluginUsage} shouldWrapLongLines />\n<br></br>\n\nIf your codebase uses [Compiled](https://compiledcssinjs.com/docs/installation#babel), then add the\nplugin to its configuration as well:\n\n<CodeBlock language="json" text={codeBabelPluginCompiled} shouldWrapLongLines />\n<br></br>\n\n### Removing existing token fallbacks\n\nIf 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.\n\n#### Prerequisites\n\nEnsure the following before proceeding:\n\n- **Babel plugin enabled**: The `@atlaskit/tokens/babel-plugin` should be active with\n `shouldUseAutoFallback` set to `true`. This ensures fallback values are automatically handled\n during build time.\n- **Themes enabled**: Verify that ADS themes are applied in your app. Fallbacks can only be safely\n removed for token categories with active themes (e.g color, space, or typography tokens).\n\n#### Steps for fallback removal\n\n1. **Implicit Fallback Removal**:\n - Update your Babel plugin configuration to include `shouldForceAutoFallback: true`. This setting\n forces the plugin to ignore any explicit fallbacks in the code, using default theme values\n instead.\n - Define `forceAutoFallbackExemptions` for token categories that do not currently have an active\n theme. This ensures the preservation of existing token fallbacks rendered in the app,\n preventing unintended UI changes.\n\n2. **Explicit fallback removal**:\n - Install the codemod: https://www.npmjs.com/package/@atlaskit/codemod-cli\n - Run the codemod to remove fallback values from your codebase:\n <CodeBlock language="shell" text={codeFallbackRemovalCodemod} shouldWrapLongLines />\n - Use `--skipTokens` to align with `forceAutoFallbackExemptions` for any themes that are not yet\n enabled (note that currently radius tokens are automatically exempted).\n - Use `--forceUpdate` to remove fallbacks regardless of their values. Without the option it would\n preserve fallbacks that differ from the token value. Omitting this option is only valuable when\n you don’t have `shouldForceAutoFallback` enabled or are unsure if themes are enabled in the app\n and therefore would like to remove fallbacks gradually starting with the ones that won’t have\n UI impact if removed.\n - Use `--addEslintComments` to automatically add eslint suppressions for the fallbacks that\n shouldn’t be removed, such as the ones configured in `forceAutoFallbackExemptions`.\n\n3. Use ESLint to ensure fallbacks are not used in the future. This can be done by enabling the\n `@atlaskit/design-system/no-unsafe-design-token-usage`\n [ESLint rule](https://www.npmjs.com/package/@atlaskit/eslint-plugin-design-system) with\n `fallbackUsage: \'none\'` to prevent new fallbacks from being added.\n\n## Stay up to date\n\nAs 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:\n\n- For CSS in JS applications, use\n [ESLint](https://atlassian.design/components/eslint-plugin-design-system/usage).\n- For CSS (vanilla), Less, Sass, use\n [Stylelint](https://atlassian.design/components/stylelint-design-system/usage).\n\nThese will warn you if you’re using deprecated tokens, and will assist in updating your app to the\nlatest tokens.\n\n<CodeBlock language="js" text={codeLintRules} shouldWrapLongLines />\n\n## What\'s next\n\n- Search the list of [all design tokens](https://atlassian.design/components/tokens/all-tokens) for\n full descriptions and token values.\n- See design token [code examples](https://atlassian.design/components/tokens/examples).\n- Browse our [token API reference and changelog](https://atlassian.design/components/tokens/code).\n- Use the [image component](https://atlassian.design/component/image) to theme images.\n\n## Get help\n\n- Atlassians can get help with tokens in [Slack](https://go.atlassian.com/help-design-system).\n- Partners and other developers who need help with tokens can post in the\n [developer community](https://community.developer.atlassian.com/).\n- For general help with the Atlassian Design system,\n [contact us](https://atlassian.design/contact-us).',
|
|
98
|
+
content: 'import {\n\tcodeSetUpThemes,\n\tcodeSetUpThemesShorthand,\n\tcodeHtmlTheme,\n\tcodeUseTokens,\n\tcodeBabelPlugin,\n\tcodeBabelPluginUsage,\n\tcodeBabelPluginCompiled,\n\tcodeFallbackRemovalCodemod,\n\tcodeLintRules,\n} from \'../../../../snippets/code/use-tokens-in-code\';\n\nThis page explains how to set up and use\n[design tokens and themes](https://atlassian.design/tokens/design-tokens) in code.\n\n## Before you begin\n\nMake sure you’re\n[set up to use the Atlassian Design System](https://atlassian.design/get-started/develop). In\nparticular, make sure `@atlaskit/tokens` is installed as a dependency and use our\n[linting rules](https://atlassian.design/components/eslint-plugin-design-system/usage) to stay up to\ndate.\n\nInstalling `@atlaskit/tokens` alone does not mount the theme CSS required by design tokens—make sure\nto follow the setup below.\n\n## Set up themes and theme switching\n\nFor themes to work properly, theming must be initialized by the Atlassian application and by any\nMarketplace app that extends its experience.\n\nYour application must initialize ADS theming. For client-rendered applications that are not already\nusing `AppProvider` or another supported theme initializer, call\n[`setGlobalTheme`](https://atlassian.design/components/tokens/code#setglobalthemethemestate) once at\nstartup. The example below uses the current default configuration.\n\n<CodeBlock language="jsx" text={codeSetUpThemes} shouldWrapLongLines />\n<br></br>\n\nThese values are the current defaults, so this shorthand is equivalent:\n\n<CodeBlock language="jsx" text={codeSetUpThemesShorthand} shouldWrapLongLines />\n<br></br>\n\nMake sure theming is set up by inspecting your app HTML. You should see something like this:\n\n<CodeBlock language="html" text={codeHtmlTheme} shouldWrapLongLines />\n<br></br>\n\nPay special attention to the `data-color-mode="dark"` attribute, and also note the\n`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.\n\n### Set up Atlassian fonts\n\nTo bring [Atlassian Sans and Atlassian Mono](https://atlassian.design/foundations/typography) web\nfonts into your app, follow our\n[setup guide (Atlassians only)](https://go.atlassian.com/set-up-fonts).\n\nThe typography theme is enabled by default when using `setGlobalTheme()`.\n\n### Set up themes for apps (Connect, Forge, Marketplace)\n\nFor Connect and Forge apps, see the following dedicated resources:\n\n- [Theming Connect apps](https://developer.atlassian.com/cloud/jira/platform/connect-theming/)\n- [Theming Forge apps](https://developer.atlassian.com/platform/forge/design-tokens-and-theming/)\n\n### Server-side rendering\n\nIf your application is using SSR (server-side rendering) ensure themes appear at the right time\nusing our\n[SSR theming utilities](https://atlassian.design/components/tokens/code#server-side-rendering-ssr-utilities).\n\n## Use tokens\n\nYou can access individual tokens using the CSS custom properties mounted to the page, however, it\'s\nbest to use the `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.\n\nThe `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.\n\n<CodeBlock language="jsx" text={codeUseTokens} shouldWrapLongLines />\n<br></br>\n\nIf you\'re migrating a lot of values to tokens,\n[use our codemod](https://atlassian.design/tokens/migrate-to-tokens#use-our-codemod-for-migration-assistance).\n\n### Migration to tokens\n\nThe `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.\n\nAt 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.\n\nFallback values were mostly used historically for large app migrations and are not recommended\nanymore.\n\nDesign 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.\n\n#### Babel plugin\n\nOur build-time Babel plugin is required to optimize the runtime performance of tokens by replacing\nany calls to the `token()` function in `@atlaskit/tokens` with the corresponding CSS value the\nfunction would return.\n\nIf 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 `shouldUseAutoFallback` to `false`.\n\n<CodeBlock language="diff" text={codeBabelPlugin} shouldWrapLongLines />\n<br></br>\n\nBy 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 `shouldForceAutoFallback` to `false`.\n\n**Usage**\n\nAdd the plugin to your babel configuration:\n\n<CodeBlock language="json" text={codeBabelPluginUsage} shouldWrapLongLines />\n<br></br>\n\nIf your codebase uses [Compiled](https://compiledcssinjs.com/docs/installation#babel), then add the\nplugin to its configuration as well:\n\n<CodeBlock language="json" text={codeBabelPluginCompiled} shouldWrapLongLines />\n<br></br>\n\n### Removing existing token fallbacks\n\nIf 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.\n\n#### Prerequisites\n\nEnsure the following before proceeding:\n\n- **Babel plugin enabled**: The `@atlaskit/tokens/babel-plugin` should be active with\n `shouldUseAutoFallback` set to `true`. This ensures fallback values are automatically handled\n during build time.\n- **Themes enabled**: Verify that ADS themes are applied in your app. Fallbacks can only be safely\n removed for token categories with active themes (e.g color, space, or typography tokens).\n\n#### Steps for fallback removal\n\n1. **Implicit Fallback Removal**:\n - Update your Babel plugin configuration to include `shouldForceAutoFallback: true`. This setting\n forces the plugin to ignore any explicit fallbacks in the code, using default theme values\n instead.\n - Define `forceAutoFallbackExemptions` for token categories that do not currently have an active\n theme. This ensures the preservation of existing token fallbacks rendered in the app,\n preventing unintended UI changes.\n\n2. **Explicit fallback removal**:\n - Install the codemod: https://www.npmjs.com/package/@atlaskit/codemod-cli\n - Run the codemod to remove fallback values from your codebase:\n <CodeBlock language="shell" text={codeFallbackRemovalCodemod} shouldWrapLongLines />\n - Use `--skipTokens` to align with `forceAutoFallbackExemptions` for any themes that are not yet\n enabled (note that currently radius tokens are automatically exempted).\n - Use `--forceUpdate` to remove fallbacks regardless of their values. Without the option it would\n preserve fallbacks that differ from the token value. Omitting this option is only valuable when\n you don’t have `shouldForceAutoFallback` enabled or are unsure if themes are enabled in the app\n and therefore would like to remove fallbacks gradually starting with the ones that won’t have\n UI impact if removed.\n - Use `--addEslintComments` to automatically add eslint suppressions for the fallbacks that\n shouldn’t be removed, such as the ones configured in `forceAutoFallbackExemptions`.\n\n3. Use ESLint to ensure fallbacks are not used in the future. This can be done by enabling the\n `@atlaskit/design-system/no-unsafe-design-token-usage`\n [ESLint rule](https://www.npmjs.com/package/@atlaskit/eslint-plugin-design-system) with\n `fallbackUsage: \'none\'` to prevent new fallbacks from being added.\n\n## Stay up to date\n\nAs 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:\n\n- For CSS in JS applications, use\n [ESLint](https://atlassian.design/components/eslint-plugin-design-system/usage).\n- For CSS (vanilla), Less, Sass, use\n [Stylelint](https://atlassian.design/components/stylelint-design-system/usage).\n\nThese will warn you if you’re using deprecated tokens, and will assist in updating your app to the\nlatest tokens.\n\n<CodeBlock language="js" text={codeLintRules} shouldWrapLongLines />\n\n## What\'s next\n\n- Search the list of [all design tokens](https://atlassian.design/components/tokens/all-tokens) for\n full descriptions and token values.\n- See design token [code examples](https://atlassian.design/components/tokens/examples).\n- Browse our [token API reference and changelog](https://atlassian.design/components/tokens/code).\n- Use the [image component](https://atlassian.design/component/image) to theme images.\n\n## Get help\n\n- Atlassians can get help with tokens in [Slack](https://go.atlassian.com/help-design-system).\n- Partners and other developers who need help with tokens can post in the\n [developer community](https://community.developer.atlassian.com/).\n- For general help with the Atlassian Design system,\n [contact us](https://atlassian.design/contact-us).',
|
|
99
99
|
keywords: ['use tokens', 'token implementation', 'coding', 'development', 'engineering']
|
|
100
100
|
}, {
|
|
101
101
|
content: "Understand how to use design tokens when applying our foundations in your designs.\n\n## Before you begin\n\nMake sure you understand the basics of\n[design tokens](https://atlassian.design/tokens/design-tokens).\n\n## Using tokens in Figma\n\n1. Get access to our Figma libraries with design tokens built-in as styles and in components.\n [Access Figma libraries](https://atlassian.design/get-started/figma-libraries).\n\n2. Install and use the\n [Atlassian Design Tokens Figma plugin](https://www.figma.com/community/plugin/1144189860740169808/Atlassian-Design-Tokens)\n to simplify finding and applying Atlassian design tokens in your designs.\n \n\n3. (Atlassian employees only) Use the Figma plugin convert old design files to use design tokens,\n and to convert your designs to dark mode.\n\n## Review tokens and styles in your app\n\nView new colors and styles in your app during migration using the\n[Chrome plugin (Atlassians only)](https://go.atlassian.com/dst-chrome-theme-plugin).\n\nNew colors and other values won’t be visible until each app officially releases their changes when\nafter testing is complete. The chrome plugin allows you to view the latest tokens behind the scenes\nduring testing.\n\n## What's next\n\n- Search all of our available design tokens and their descriptions in\n [all tokens](https://atlassian.design/components/tokens/all-tokens).\n- For extra help choosing the right token, use our\n [Token picker](https://atlassian.design/components/tokens/all-tokens?isTokenPickerOpen=true).\n- Review new usage guidance in our color, elevation, and spacing\n [foundations](https://atlassian.design/foundations).\n- Check out our\n [design tokens onboarding video resources (for Atlassians only)](https://go.atlassian.com/design-token-onboarding).\n\n## Get help\n\n- Atlassians can get help with tokens in [Slack](https://go.atlassian.com/help-design-system).\n- For general help with the Atlassian Design system,\n [contact us](https://atlassian.design/contact-us).",
|
|
@@ -10,7 +10,7 @@ var _planInputSchema = require("./plan-input-schema");
|
|
|
10
10
|
|
|
11
11
|
var listPlanTool = exports.listPlanTool = {
|
|
12
12
|
name: 'ads_plan',
|
|
13
|
-
description: "Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and optionally **atlaskit_search_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** for a UI task
|
|
13
|
+
description: "Runs **ads_search_tokens**, **ads_search_icons**, **ads_search_components**, and optionally **atlaskit_search_components** in one call and returns a single JSON payload (each section only if that list was non-empty). Use this as the default way to discover ADS **tokens**, **icons**, and **components** for a UI task. Component results preserve optional `designSource.figmaUrl`; for Figma work, follow the canonical-source and property-verification guidance in `ads_search_components`.\n\nWHEN TO USE:\n**Implementing or iterating on a UI**\u2014new screen, feature, or polish\u2014and you need candidate **token** names, **icon** imports, and **ADS component** packages/props in one pass. Also use when exploring ADS building blocks before you write code.\n\nADS-FIRST ROUTING:\nUse `components` for canonical ADS components. Use `atlaskitComponents` only as explicit fallback research for public `@atlaskit/*` packages outside the ADS catalog, or after ADS component search has no useful match. This tool does not auto-populate `atlaskitComponents` from `components`.\n\nAt least one of `tokens`, `icons`, `components`, or `atlaskitComponents` must contain search terms (use `[]` for lists you do not need).\n\nPrefer supplying **multiple** terms per non-empty array when you know them\u2014broader queries improve recall. Some queries return no rows where metadata is thin; try alternate wording.\n\nThis is equivalent to calling the individual search tools; there are no extra merge semantics beyond concatenating results.\n\nExample request:\n```json\n{\n\t\"tokens\": [\"spacing\", \"inverted text\", \"background primary\", \"animation\"],\n\t\"icons\": [\"search\", \"folder\", \"user\"],\n\t\"components\": [\"button\", \"input\", \"select\", \"heading\"],\n\t\"atlaskitComponents\": [\"editor-core\", \"onboarding\", \"page-layout\"]\n}\n```\n\nExample token usage:\n```tsx\nimport { token } from '@atlaskit/tokens';\nconst styles = css({ color: token('color.text'), padding: token('space.100') });\n```\n\nExample icon usage:\n```tsx\nimport AddIcon from '@atlaskit/icon/core/add';\n<AddIcon label=\"Add work item\" size=\"small\" />\n```",
|
|
14
14
|
annotations: {
|
|
15
15
|
title: 'Search ADS tokens, icons, and components to plan what to build',
|
|
16
16
|
readOnlyHint: true,
|
|
@@ -10,7 +10,7 @@ var _searchComponentsInputSchema = require("./search-components-input-schema");
|
|
|
10
10
|
|
|
11
11
|
var listSearchComponentsTool = exports.listSearchComponentsTool = {
|
|
12
12
|
name: 'ads_search_components',
|
|
13
|
-
description: "Searches the bundled Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, and **
|
|
13
|
+
description: "Searches the bundled Atlassian Design System (ADS) component catalog. Returns JSON objects with **name**, **package**, **examples**, **props**, and optional **designSource.figmaUrl** for each match (trimmed payload). When `designSource.figmaUrl` is present, inspect the canonical Figma source before building or implementing the component. Reuse library instances/variables, verify Figma properties against code props, and report unresolved mappings or access; do not infer a missing source.\n\nWHEN TO USE:\n**Selecting which canonical ADS component to use**\u2014package name, examples, and props\u2014before implementation. Use when composing a new view or swapping a primitive. Prefer `ads_plan` when you also need token and icon discovery in one shot.\n\nIf you are looking for a public `@atlaskit/*` scoped package that is not part of the ADS component catalog, use `atlaskit_search_components` for fallback research instead of this ADS-only search.",
|
|
14
14
|
annotations: {
|
|
15
15
|
title: 'Search ADS components',
|
|
16
16
|
readOnlyHint: true,
|