@atlaskit/ads-mcp 1.7.2 → 1.7.3

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.
Files changed (10) hide show
  1. package/CHANGELOG.md +10 -0
  2. package/dist/cjs/tools/get-guidelines/guidelines-structured-content.codegen.js +2 -2
  3. package/dist/cjs/tools/get-lint-rules/lint-rules-structured-content.codegen.js +6 -2
  4. package/dist/es2019/tools/get-guidelines/guidelines-structured-content.codegen.js +2 -2
  5. package/dist/es2019/tools/get-lint-rules/lint-rules-structured-content.codegen.js +6 -2
  6. package/dist/esm/tools/get-guidelines/guidelines-structured-content.codegen.js +2 -2
  7. package/dist/esm/tools/get-lint-rules/lint-rules-structured-content.codegen.js +6 -2
  8. package/dist/types/tools/get-guidelines/guidelines-structured-content.codegen.d.ts +1 -1
  9. package/dist/types/tools/get-lint-rules/lint-rules-structured-content.codegen.d.ts +1 -1
  10. package/package.json +3 -3
package/dist/es2019/tools/get-lint-rules/lint-rules-structured-content.codegen.js CHANGED
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * Structured content for MCP (JSON) for ESLint rule docs from constellation.
5
5
  *
6
- * @codegen <<SignedSource::dd38be154d0998c5c9a0f636c03ce76e>>
6
+ * @codegen <<SignedSource::56b0eabff2b19771e9bd170012782e79>>
7
7
  * @codegenCommand yarn build structured-docs
8
8
  */
9
9
  /* eslint-disable no-template-curly-in-string */
@@ -49,7 +49,7 @@ export const lintRulesMcpStructuredContent = [{
49
49
  ruleName: 'icon-label',
50
50
  description: 'Icon labels are used to describe what the icon is so the visually impaired can be described what the'
51
51
  }, {
52
- content: '{"ruleName":"index","description":"---","content":"---\\norder: 0\\n---\\n\\nThis plugin contains rules that should be used when working with the\\n[Atlassian Design System](https://atlassian.design).\\n\\n## Rules\\n\\n<!-- START_RULE_TABLE_CODEGEN -->\\n<!-- @codegenCommand yarn workspace @atlaskit/eslint-plugin-design-system codegen -->\\n\\n| Rule | Description | Recommended | Fixable | Suggestions |\\n| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------- | ----------- |\\n| <a href=\\"/components/eslint-plugin-design-system/consistent-css-prop-usage/usage\\">consistent-css-prop-usage</a> | Ensures consistency with `css` and `xcss` prop usages | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/enforce-inline-styles-in-select/usage\\">enforce-inline-styles-in-select</a> | Disallow unsupported CSS selectors in styles prop for @atlaskit/select and require inline styles only | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/ensure-avatar-tag-avatar-props/usage\\">ensure-avatar-tag-avatar-props</a> | Ensures AvatarTag avatar prop does not include controlled props (size, borderColor, appearance) which are managed internally. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/ensure-design-token-usage/usage\\">ensure-design-token-usage</a> | Enforces usage of design tokens rather than hard-coded values. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/ensure-design-token-usage-preview/usage\\">ensure-design-token-usage/preview</a> | Enforces usage of pre-release design tokens rather than hard-coded values. | | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/ensure-icon-color/usage\\">ensure-icon-color</a> | Enforces that upcoming icon components have a color prop set, to enable a migration of the default value. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/ensure-proper-xcss-usage/usage\\">ensure-proper-xcss-usage</a> | Enforces proper xcss usage: migrate from xcss() to cssMap() and use cssMap objects with specific keys. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/expand-motion-shorthand/usage\\">expand-motion-shorthand</a> | Expands `transition` and `animation` CSS shorthand properties into their individual sub-properties, so individual values can be replaced with motion tokens. | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/icon-label/usage\\">icon-label</a> | Enforces accessible usage of icon labels when composed with Atlassian Design System components. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/lozenge-badge-tag-labelling-system-migration/usage\\">lozenge-badge-tag-labelling-system-migration</a> | Helps migrate Lozenge isBold prop, Badge appearance values, and SimpleTag/RemovableTag components as part of the Labelling System Phase 1 migration. | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-banned-imports/usage\\">no-banned-imports</a> | Disallow importing banned modules. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-css-map-scoped/usage\\">no-css-map-scoped</a> | Disallows usage of the experimental `cssMapScoped` API from `@compiled/react`. This API is internal and is not part of the public Compiled CSS-in-JS interface. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-css-tagged-template-expression/usage\\">no-css-tagged-template-expression</a> | Disallows any `css` tagged template expressions that originate from Emotion, Styled Components or Compiled | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-dark-theme-vr-tests/usage\\">no-dark-theme-vr-tests</a> | Disallow using dark colorScheme in VR tests. | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-deprecated-apis/usage\\">no-deprecated-apis</a> | Disallow using deprecated APIs. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-deprecated-design-token-usage/usage\\">no-deprecated-design-token-usage</a> | Disallow using deprecated design tokens. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-deprecated-imports/usage\\">no-deprecated-imports</a> | Disallow importing deprecated modules. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-direct-use-of-web-platform-drag-and-drop/usage\\">no-direct-use-of-web-platform-drag-and-drop</a> | Disallow using direct use of native drag and drop (please use Pragmatic drag and drop) | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-emotion-primitives/usage\\">no-emotion-primitives</a> | Ensures usage of Compiled Primitives import instead of Emotion entrypoint. | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-empty-styled-expression/usage\\">no-empty-styled-expression</a> | Forbids any styled expression to be used when passing empty arguments to styled.div() (or other JSX elements). | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-exported-css/usage\\">no-exported-css</a> | Forbid exporting `css` function calls. Exporting `css` function calls can result in unexpected behaviour at runtime, and is not statically analysable. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-exported-keyframes/usage\\">no-exported-keyframes</a> | Forbid exporting `keyframes` function calls. Exporting `css` function calls can result in unexpected behaviour at runtime, and is not statically analysable. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-anchor/usage\\">no-html-anchor</a> | Discourage direct usage of HTML anchor elements in favor of Atlassian Design System link components. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-button/usage\\">no-html-button</a> | Discourage direct usage of HTML button elements in favor of Atlassian Design System button components. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-checkbox/usage\\">no-html-checkbox</a> | Discourage direct usage of HTML checkbox elements in favor of the Atlassian Design System checkbox component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-code/usage\\">no-html-code</a> | Discourage direct usage of HTML code elements in favor of the Atlassian Design System code component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-heading/usage\\">no-html-heading</a> | Discourage direct usage of HTML heading elements in favor of Atlassian Design System heading components. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-image/usage\\">no-html-image</a> | Discourage direct usage of HTML image elements in favor of the Atlassian Design System image component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-radio/usage\\">no-html-radio</a> | Discourage direct usage of HTML radio elements in favor of the Atlassian Design System radio component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-range/usage\\">no-html-range</a> | Discourage direct usage of HTML range elements in favor of the Atlassian Design System range component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-select/usage\\">no-html-select</a> | Discourage direct usage of HTML select elements in favor of the Atlassian Design System select component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-text-input/usage\\">no-html-text-input</a> | Discourage direct usage of HTML text input elements in favor of the Atlassian Design System textfield component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-textarea/usage\\">no-html-textarea</a> | Discourage direct usage of HTML textarea elements in favor of the Atlassian Design System textarea component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-icon-spacing-prop/usage\\">no-icon-spacing-prop</a> | Disallows usage of the deprecated spacing prop on new icons. Use Flex with cssMap for spacing instead. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-invalid-css-map/usage\\">no-invalid-css-map</a> | Checks the validity of a CSS map created through cssMap. This is intended to be used alongside TypeScript\'s type-checking. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-keyframes-tagged-template-expression/usage\\">no-keyframes-tagged-template-expression</a> | Disallows any `keyframe` tagged template expressions that originate from Emotion, Styled Components or Compiled | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-margin/usage\\">no-margin</a> | Disallow using the margin CSS property. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-modal-label/usage\\">no-modal-label</a> | Disallows usage of the `label` prop on Atlassian Design System modal dialog. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-nested-styles/usage\\">no-nested-styles</a> | Disallows use of nested styles in `css` functions. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-physical-properties/usage\\">no-physical-properties</a> | Disallow physical properties and values in `css` and `cssMap` function calls. | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-placeholder/usage\\">no-placeholder</a> | Placeholders should not be used. If information should be given to the user about the proper type or formatting of a value, this should be included using a helper message that is associated to the input instead. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-readonly-or-disabled-inputs/usage\\">no-readonly-or-disabled-inputs</a> | Inputs should almost always be interactive. Disabled and read-only inputs can usually be replaced by a more user-friendly design pattern. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-separator-with-list-elements/usage\\">no-separator-with-list-elements</a> | Warn when the `separator` prop is used with `as=\\"li\\"`, `as=\\"ol\\"`, or `as=\\"dl\\"` in the Inline component. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-styled-tagged-template-expression/usage\\">no-styled-tagged-template-expression</a> | Disallows any `styled` tagged template expressions that originate from Emotion, Styled Components or Compiled | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-to-match-snapshot/usage\\">no-to-match-snapshot</a> | Disallow using toMatchSnapshot() in favor of toMatchInlineSnapshot(). See https://hello.atlassian.net/wiki/spaces/DST/pages/6105892000/DSTRFC-038+-+Removal+of+.toMatchSnapshot for rationale. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-unsafe-design-token-usage/usage\\">no-unsafe-design-token-usage</a> | Enforces design token usage is statically and locally analyzable. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-unsafe-inline-snapshot/usage\\">no-unsafe-inline-snapshot</a> | Enforce guardrails on toMatchInlineSnapshot usage: snapshots must not exceed 100 lines and must not contain internal implementation details like className or style attributes. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-unsafe-style-overrides/usage\\">no-unsafe-style-overrides</a> | Discourage usage of unsafe style overrides used against the Atlassian Design System. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-unsupported-drag-and-drop-libraries/usage\\">no-unsupported-drag-and-drop-libraries</a> | Disallow importing unsupported drag and drop modules. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-unused-css-map/usage\\">no-unused-css-map</a> | Detects unused styles in cssMap objects to help keep code clean. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/prefer-primitives/usage\\">prefer-primitives</a> | Increase awareness of primitive components via code hints. Strictly used for education purposes and discoverability. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-button-group-label/usage\\">use-button-group-label</a> | Ensures button groups are described to assistive technology by a direct label or by another element. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-character-counter-field/usage\\">use-character-counter-field</a> | Suggests using CharacterCounterField or CharacterCounter when Textfield or Textarea components have maxLength or minLength props. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-correct-field/usage\\">use-correct-field</a> | Ensure makers use appropriate field component for their respective form elements. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-cx-function-in-xcss/usage\\">use-cx-function-in-xcss</a> | Enforces cx function use to combine styles in xcss. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-datetime-picker-calendar-button/usage\\">use-datetime-picker-calendar-button</a> | Encourages makers to use calendar button in Atlassian Design System\'s date picker and datetime picker components. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-drawer-label/usage\\">use-drawer-label</a> | Encourages to provide accessible name for Atlassian Design System Drawer component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-field-message-wrapper/usage\\">use-field-message-wrapper</a> | Encourage use of message wrapper component when using form message components. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-heading/usage\\">use-heading</a> | Encourage the usage of heading components. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-heading-level-in-section-message/usage\\">use-heading-level-in-section-message</a> | The `SectionMessage` component in `@atlaskit/section-message` needs to be the correct level within the document flow. This is not something that can be automated and requires contextual knowledge of what is present in the experience. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-heading-level-in-spotlight-card/usage\\">use-heading-level-in-spotlight-card</a> | Inform developers of eventual requirement of `headingLevel` prop in `SpotlightCard` component. The heading level should be the appropriate level according to the surrounding context. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-href-in-link-item/usage\\">use-href-in-link-item</a> | Inform developers of eventual requirement of `href` prop in `LinkItem` component. Elements with a `link` role require an `href` attribute for users to properly navigate, particularly those using assistive technologies. If no valid `href` is required for your use case, consider using a `ButtonItem` instead. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-latest-xcss-syntax/usage\\">use-latest-xcss-syntax</a> | Enforces usage of space design tokens rather than hard-coded values in xcss. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-latest-xcss-syntax-typography/usage\\">use-latest-xcss-syntax-typography</a> | Prohibits use of unsafe styling properties in xcss. Please use Text/Heading primitives instead. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-menu-section-title/usage\\">use-menu-section-title</a> | Encourages makers to provide accessible title for Atlassian Design System Menu Section component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-modal-dialog-close-button/usage\\">use-modal-dialog-close-button</a> | Encourages makers to use close button in Atlassian Design System\'s modal dialog component. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-modal-title/usage\\">use-modal-title</a> | Encourages makers to include `ModalTitle` within `ModalHeader` when using Atlassian Design System modal dialog. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-onboarding-spotlight-label/usage\\">use-onboarding-spotlight-label</a> | Ensures onboarding spotlight dialogs are described to assistive technology by a direct label or by another element. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-popup-label/usage\\">use-popup-label</a> | Encourages to provide accessible name for Atlassian Design System Popup component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-primitives-text/usage\\">use-primitives-text</a> | Encourage the usage of text components. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-should-render-to-parent/usage\\">use-should-render-to-parent</a> | Encourages makers to use the `shouldRenderToParent` where possible in Atlassian Design System `Popup` and `DropdownMenu` components. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-simple-field/usage\\">use-simple-field</a> | Encourage use of simple field for better developer experience and accessibility. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-simple-form/usage\\">use-simple-form</a> | Encourage use of simple form for better developer experience and accessibility. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-spotlight-package/usage\\">use-spotlight-package</a> | Discourage the use of @atlaskit/onboarding in favor of @atlaskit/spotlight. | | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-tag-group-label/usage\\">use-tag-group-label</a> | Ensures tag groups are described to assistive technology by a direct label or by another element. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-textfield-autocomplete/usage\\">use-textfield-autocomplete</a> | Enforce that Textfield components with type=\\"email\\", \\"tel\\", or \\"url\\" have an appropriate autocomplete value for WCAG 2.2 SC 1.3.5 compliance (Identify Input Purpose). | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-tokens-motion/usage\\">use-tokens-motion</a> | Enforces usage of motion design tokens rather than hard-coded duration and easing values. | | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-tokens-shape/usage\\">use-tokens-shape</a> | Enforces usage of shape design tokens rather than hard-coded values. | | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-tokens-space/usage\\">use-tokens-space</a> | Enforces usage of space design tokens rather than hard-coded values. | | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-tokens-typography/usage\\">use-tokens-typography</a> | Enforces usage of design tokens for typography properties rather than hard-coded values. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-visually-hidden/usage\\">use-visually-hidden</a> | Enforce usage of the visually hidden component. | Yes | Yes | |\\n\\n<!-- END_RULE_TABLE_CODEGEN -->\\n\\n\\n## Props\\n\\nUse the recommended config to get reasonable defaults recommended by the Atlassian Design System:\\n\\n```diff\\nmodule.exports = {\\n extends: [\\n+ \'plugin:@atlaskit/design-system/recommended\',\\n ],\\n};\\n```\\n\\nWe don\'t recommended maintaining your own configuration. If you do not use our config you will need\\nto specify individual rules and configuration. Add the plugin to your `eslint.config.cjs` file.\\n\\n```diff\\nmodule.exports = {\\n plugins: [\\n+ \'@atlaskit/design-system\',\\n ],\\n};\\n```\\n\\nEnable the rules that you would like to use.\\n\\n```diff\\nmodule.exports = {\\n rules: [\\n+ \'@atlaskit/design-system/no-deprecated-apis\': \'error\',\\n ],\\n};\\n```\\n"}',
52
+ content: '{"ruleName":"index","description":"---","content":"---\\norder: 0\\n---\\n\\nThis plugin contains rules that should be used when working with the\\n[Atlassian Design System](https://atlassian.design).\\n\\n## Rules\\n\\n<!-- START_RULE_TABLE_CODEGEN -->\\n<!-- @codegenCommand yarn workspace @atlaskit/eslint-plugin-design-system codegen -->\\n\\n| Rule | Description | Recommended | Fixable | Suggestions |\\n| ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------- | ----------- |\\n| <a href=\\"/components/eslint-plugin-design-system/consistent-css-prop-usage/usage\\">consistent-css-prop-usage</a> | Ensures consistency with `css` and `xcss` prop usages | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/enforce-inline-styles-in-select/usage\\">enforce-inline-styles-in-select</a> | Disallow unsupported CSS selectors in styles prop for @atlaskit/select and require inline styles only | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/ensure-avatar-tag-avatar-props/usage\\">ensure-avatar-tag-avatar-props</a> | Ensures AvatarTag avatar prop does not include controlled props (size, borderColor, appearance) which are managed internally. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/ensure-design-token-usage/usage\\">ensure-design-token-usage</a> | Enforces usage of design tokens rather than hard-coded values. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/ensure-design-token-usage-preview/usage\\">ensure-design-token-usage/preview</a> | Enforces usage of pre-release design tokens rather than hard-coded values. | | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/ensure-icon-color/usage\\">ensure-icon-color</a> | Enforces that upcoming icon components have a color prop set, to enable a migration of the default value. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/ensure-proper-xcss-usage/usage\\">ensure-proper-xcss-usage</a> | Enforces proper xcss usage: migrate from xcss() to cssMap() and use cssMap objects with specific keys. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/expand-motion-shorthand/usage\\">expand-motion-shorthand</a> | Expands `transition` and `animation` CSS shorthand properties into their individual sub-properties, so individual values can be replaced with motion tokens. | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/icon-label/usage\\">icon-label</a> | Enforces accessible usage of icon labels when composed with Atlassian Design System components. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/lozenge-badge-tag-labelling-system-migration/usage\\">lozenge-badge-tag-labelling-system-migration</a> | Helps migrate Lozenge isBold prop, Badge appearance values, and SimpleTag/RemovableTag components as part of the Labelling System Phase 1 migration. | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-banned-imports/usage\\">no-banned-imports</a> | Disallow importing banned modules. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-css-map-scoped/usage\\">no-css-map-scoped</a> | Disallows usage of the experimental `cssMapScoped` API from `@compiled/react`. This API is internal and is not part of the public Compiled CSS-in-JS interface. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-css-tagged-template-expression/usage\\">no-css-tagged-template-expression</a> | Disallows any `css` tagged template expressions that originate from Emotion, Styled Components or Compiled | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-dark-theme-vr-tests/usage\\">no-dark-theme-vr-tests</a> | Disallow using dark colorScheme in VR tests. | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-deprecated-apis/usage\\">no-deprecated-apis</a> | Disallow using deprecated APIs. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-deprecated-design-token-usage/usage\\">no-deprecated-design-token-usage</a> | Disallow using deprecated design tokens. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-deprecated-imports/usage\\">no-deprecated-imports</a> | Disallow importing deprecated modules. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-direct-use-of-web-platform-drag-and-drop/usage\\">no-direct-use-of-web-platform-drag-and-drop</a> | Disallow using direct use of native drag and drop (please use Pragmatic drag and drop) | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-emotion-primitives/usage\\">no-emotion-primitives</a> | Ensures usage of Compiled Primitives import instead of Emotion entrypoint. | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-empty-styled-expression/usage\\">no-empty-styled-expression</a> | Forbids any styled expression to be used when passing empty arguments to styled.div() (or other JSX elements). | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-exported-css/usage\\">no-exported-css</a> | Forbid exporting `css` function calls. Exporting `css` function calls can result in unexpected behaviour at runtime, and is not statically analysable. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-exported-keyframes/usage\\">no-exported-keyframes</a> | Forbid exporting `keyframes` function calls. Exporting `css` function calls can result in unexpected behaviour at runtime, and is not statically analysable. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-anchor/usage\\">no-html-anchor</a> | Discourage direct usage of HTML anchor elements in favor of Atlassian Design System link components. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-button/usage\\">no-html-button</a> | Discourage direct usage of HTML button elements in favor of Atlassian Design System button components. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-checkbox/usage\\">no-html-checkbox</a> | Discourage direct usage of HTML checkbox elements in favor of the Atlassian Design System checkbox component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-code/usage\\">no-html-code</a> | Discourage direct usage of HTML code elements in favor of the Atlassian Design System code component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-heading/usage\\">no-html-heading</a> | Discourage direct usage of HTML heading elements in favor of Atlassian Design System heading components. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-image/usage\\">no-html-image</a> | Discourage direct usage of HTML image elements in favor of the Atlassian Design System image component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-radio/usage\\">no-html-radio</a> | Discourage direct usage of HTML radio elements in favor of the Atlassian Design System radio component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-range/usage\\">no-html-range</a> | Discourage direct usage of HTML range elements in favor of the Atlassian Design System range component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-select/usage\\">no-html-select</a> | Discourage direct usage of HTML select elements in favor of the Atlassian Design System select component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-text-input/usage\\">no-html-text-input</a> | Discourage direct usage of HTML text input elements in favor of the Atlassian Design System textfield component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-html-textarea/usage\\">no-html-textarea</a> | Discourage direct usage of HTML textarea elements in favor of the Atlassian Design System textarea component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-icon-spacing-prop/usage\\">no-icon-spacing-prop</a> | Disallows usage of the deprecated spacing prop on new icons. Use Flex with cssMap for spacing instead. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/no-invalid-css-map/usage\\">no-invalid-css-map</a> | Checks the validity of a CSS map created through cssMap. This is intended to be used alongside TypeScript\'s type-checking. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-keyframes-tagged-template-expression/usage\\">no-keyframes-tagged-template-expression</a> | Disallows any `keyframe` tagged template expressions that originate from Emotion, Styled Components or Compiled | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-margin/usage\\">no-margin</a> | Disallow using the margin CSS property. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-modal-label/usage\\">no-modal-label</a> | Disallows usage of the `label` prop on Atlassian Design System modal dialog. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-nested-styles/usage\\">no-nested-styles</a> | Disallows use of nested styles in `css` functions. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-physical-properties/usage\\">no-physical-properties</a> | Disallow physical properties and values in `css` and `cssMap` function calls. | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-placeholder/usage\\">no-placeholder</a> | Placeholders should not be used. If information should be given to the user about the proper type or formatting of a value, this should be included using a helper message that is associated to the input instead. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-readonly-or-disabled-inputs/usage\\">no-readonly-or-disabled-inputs</a> | Inputs should almost always be interactive. Disabled and read-only inputs can usually be replaced by a more user-friendly design pattern. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-separator-with-list-elements/usage\\">no-separator-with-list-elements</a> | Warn when the `separator` prop is used with `as=\\"li\\"`, `as=\\"ol\\"`, or `as=\\"dl\\"` in the Inline component. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-styled-tagged-template-expression/usage\\">no-styled-tagged-template-expression</a> | Disallows any `styled` tagged template expressions that originate from Emotion, Styled Components or Compiled | | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-to-match-snapshot/usage\\">no-to-match-snapshot</a> | Disallow using toMatchSnapshot() in favor of toMatchInlineSnapshot(). See https://hello.atlassian.net/wiki/spaces/DST/pages/6105892000/DSTRFC-038+-+Removal+of+.toMatchSnapshot for rationale. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-unsafe-design-token-usage/usage\\">no-unsafe-design-token-usage</a> | Enforces design token usage is statically and locally analyzable. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-unsafe-inline-snapshot/usage\\">no-unsafe-inline-snapshot</a> | Enforce guardrails on toMatchInlineSnapshot usage: snapshots must not exceed 100 lines and must not contain internal implementation details like className or style attributes. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-unsafe-style-overrides/usage\\">no-unsafe-style-overrides</a> | Discourage usage of unsafe style overrides used against the Atlassian Design System. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-unsupported-drag-and-drop-libraries/usage\\">no-unsupported-drag-and-drop-libraries</a> | Disallow importing unsupported drag and drop modules. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/no-unused-css-map/usage\\">no-unused-css-map</a> | Detects unused styles in cssMap objects to help keep code clean. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/prefer-primitives/usage\\">prefer-primitives</a> | Increase awareness of primitive components via code hints. Strictly used for education purposes and discoverability. | | | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-button-group-label/usage\\">use-button-group-label</a> | Ensures button groups are described to assistive technology by a direct label or by another element. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-character-counter-field/usage\\">use-character-counter-field</a> | Suggests using CharacterCounterField or CharacterCounter when Textfield or Textarea components have maxLength or minLength props. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-correct-field/usage\\">use-correct-field</a> | Ensure makers use appropriate field component for their respective form elements. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-cx-function-in-xcss/usage\\">use-cx-function-in-xcss</a> | Enforces cx function use to combine styles in xcss. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-datetime-picker-calendar-button/usage\\">use-datetime-picker-calendar-button</a> | Encourages makers to use calendar button in Atlassian Design System\'s date picker and datetime picker components. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-drawer-label/usage\\">use-drawer-label</a> | Encourages to provide accessible name for Atlassian Design System Drawer component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-field-message-wrapper/usage\\">use-field-message-wrapper</a> | Encourage use of message wrapper component when using form message components. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-heading/usage\\">use-heading</a> | Encourage the usage of heading components. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-heading-level-in-section-message/usage\\">use-heading-level-in-section-message</a> | The `SectionMessage` component in `@atlaskit/section-message` needs to be the correct level within the document flow. This is not something that can be automated and requires contextual knowledge of what is present in the experience. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-heading-level-in-spotlight-card/usage\\">use-heading-level-in-spotlight-card</a> | Inform developers of eventual requirement of `headingLevel` prop in `SpotlightCard` component. The heading level should be the appropriate level according to the surrounding context. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-href-in-link-item/usage\\">use-href-in-link-item</a> | Inform developers of eventual requirement of `href` prop in `LinkItem` component. Elements with a `link` role require an `href` attribute for users to properly navigate, particularly those using assistive technologies. If no valid `href` is required for your use case, consider using a `ButtonItem` instead. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-latest-xcss-syntax/usage\\">use-latest-xcss-syntax</a> | Enforces usage of space design tokens rather than hard-coded values in xcss. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-latest-xcss-syntax-typography/usage\\">use-latest-xcss-syntax-typography</a> | Prohibits use of unsafe styling properties in xcss. Please use Text/Heading primitives instead. | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-menu-section-title/usage\\">use-menu-section-title</a> | Encourages makers to provide accessible title for Atlassian Design System Menu Section component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-modal-dialog-close-button/usage\\">use-modal-dialog-close-button</a> | Encourages makers to use close button in Atlassian Design System\'s modal dialog component. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-modal-title/usage\\">use-modal-title</a> | Encourages makers to include `ModalTitle` within `ModalHeader` when using Atlassian Design System modal dialog. | Yes | | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-onboarding-spotlight-label/usage\\">use-onboarding-spotlight-label</a> | Ensures onboarding spotlight dialogs are described to assistive technology by a direct label or by another element. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-popup-label/usage\\">use-popup-label</a> | Encourages to provide accessible name for Atlassian Design System Popup component. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-pressable-motion/usage\\">use-pressable-motion</a> | Suggests semantic motion tokens when Pressable or native buttons change interactive colours through local static styles. | | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-primitives-text/usage\\">use-primitives-text</a> | Encourage the usage of text components. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-should-render-to-parent/usage\\">use-should-render-to-parent</a> | Encourages makers to use the `shouldRenderToParent` where possible in Atlassian Design System `Popup` and `DropdownMenu` components. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-simple-field/usage\\">use-simple-field</a> | Encourage use of simple field for better developer experience and accessibility. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-simple-form/usage\\">use-simple-form</a> | Encourage use of simple form for better developer experience and accessibility. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-spotlight-package/usage\\">use-spotlight-package</a> | Discourage the use of @atlaskit/onboarding in favor of @atlaskit/spotlight. | | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-tag-group-label/usage\\">use-tag-group-label</a> | Ensures tag groups are described to assistive technology by a direct label or by another element. | Yes | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-textfield-autocomplete/usage\\">use-textfield-autocomplete</a> | Enforce that Textfield components with type=\\"email\\", \\"tel\\", or \\"url\\" have an appropriate autocomplete value for WCAG 2.2 SC 1.3.5 compliance (Identify Input Purpose). | Yes | Yes | |\\n| <a href=\\"/components/eslint-plugin-design-system/use-tokens-motion/usage\\">use-tokens-motion</a> | Enforces usage of motion design tokens rather than hard-coded duration and easing values. | | | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-tokens-shape/usage\\">use-tokens-shape</a> | Enforces usage of shape design tokens rather than hard-coded values. | | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-tokens-space/usage\\">use-tokens-space</a> | Enforces usage of space design tokens rather than hard-coded values. | | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-tokens-typography/usage\\">use-tokens-typography</a> | Enforces usage of design tokens for typography properties rather than hard-coded values. | Yes | Yes | Yes |\\n| <a href=\\"/components/eslint-plugin-design-system/use-visually-hidden/usage\\">use-visually-hidden</a> | Enforce usage of the visually hidden component. | Yes | Yes | |\\n\\n<!-- END_RULE_TABLE_CODEGEN -->\\n\\n\\n## Props\\n\\nUse the recommended config to get reasonable defaults recommended by the Atlassian Design System:\\n\\n```diff\\nmodule.exports = {\\n extends: [\\n+ \'plugin:@atlaskit/design-system/recommended\',\\n ],\\n};\\n```\\n\\nWe don\'t recommended maintaining your own configuration. If you do not use our config you will need\\nto specify individual rules and configuration. Add the plugin to your `eslint.config.cjs` file.\\n\\n```diff\\nmodule.exports = {\\n plugins: [\\n+ \'@atlaskit/design-system\',\\n ],\\n};\\n```\\n\\nEnable the rules that you would like to use.\\n\\n```diff\\nmodule.exports = {\\n rules: [\\n+ \'@atlaskit/design-system/no-deprecated-apis\': \'error\',\\n ],\\n};\\n```\\n"}',
53
53
  ruleName: 'index',
54
54
  description: '---'
55
55
  }, {
@@ -312,6 +312,10 @@ export const lintRulesMcpStructuredContent = [{
312
312
  content: '{"ruleName":"use-popup-label","description":"Popup should have an accessible name or a reference to it when `role=\\"dialog\\"`, so that upon","content":"# use-popup-label\\n\\nPopup should have an accessible name or a reference to it when `role=\\"dialog\\"`, so that upon\\nopening, users of assistive technologies could have contextual information of interaction with\\ncurrent element.\\n\\n## Examples\\n\\nThis rule will indicate user with warning to strongly recommend usage of either `label` or `titleId`\\nprop.\\n\\n### Incorrect\\n\\n```tsx\\n<Popup role=\\"dialog\\">\\n ^^^^^^ Missing either `label` or `titleId` prop.\\n Popup content\\n</Popup>\\n\\n<Popup role=\\"dialog\\" label>\\n ^^^^^ `label` prop is missing value.\\n Popup content\\n</Popup>\\n\\n<Popup role=\\"dialog\\" label=\\"\\">\\n ^^^^^ `label` prop is missing accessible name value.\\n Popup content\\n</Popup>\\n\\n<Popup role=\\"dialog\\" titleId>\\n ^^^^^^^ `titleId` prop is missing reference value.\\n <h1 id=\\"popup-title\\">Popup content title</hi>\\n</Popup>\\n\\n<Popup role=\\"dialog\\" titleId=\\"\\">\\n ^^^^^^^ `titleId` prop is missing reference value.\\n <h1 id=\\"popup-title\\">Popup content title</hi>\\n</Popup>\\n\\n<Popup role=\\"dialog\\" titleId=\\"popup-title\\" label=\\"\\">\\n ^^^^^^^ ^^^^^ Do not include both `titleId` and `label` properties. Use `titleId` if the label text is available in the DOM to reference it, otherwise use `label` to provide accessible name explicitly.\\n <h1 id=\\"popup-title\\">Popup content title</hi>\\n</Popup>\\n```\\n\\n### Correct\\n\\n```tsx\\n<Popup role=\\"dialog\\" label=\\"Popup content title\\">\\n Popup content\\n</Popup>\\n\\n<Popup role=\\"dialog\\" titleId=\\"popup-title\\">\\n <h1 id=\\"popup-title\\">Popup content title</hi>\\n</Popup>\\n```\\n"}',
313
313
  ruleName: 'use-popup-label',
314
314
  description: 'Popup should have an accessible name or a reference to it when `role="dialog"`, so that upon'
315
+ }, {
316
+ content: "{\"ruleName\":\"use-pressable-motion\",\"description\":\"Encourages semantic motion tokens when local static styles change interactive colours on `Pressable`\",\"content\":\"# use-pressable-motion\\n\\nEncourages semantic motion tokens when local static styles change interactive colours on `Pressable`\\nor native `<button>` elements.\\n\\nIt supports Pressable imports from `@atlaskit/primitives/compiled`,\\n`@atlaskit/primitives/compiled/pressable`, and `@atlaskit/primitives/pressable`. It recognises\\nstyles created with `css`, `cssMap`, and `xcss`. Use `&:hover` and `&:active` with `css` or\\n`cssMap`; use `:hover` and `:active` with `xcss`. Pass styles to Pressable with `xcss` and to native\\nbuttons with `css`.\\n\\nFor button motion, the rule detects `backgroundColor` and colour-only `background` changes. For\\nlist-item motion, it also detects `color`, `borderColor`, and `textDecorationColor`. It offers\\neditor suggestions for button and list-item motion; choose the family that matches the surface's\\nsemantics. Suggestions add `motion.button.*` or `motion.listitem.*` tokens for hover and pressed\\nstates, but the rule does not autofix code.\\n\\nThe rule does not infer semantics, follow imported or dynamic styles, or overwrite an existing\\n`transition`.\\n\\n## Pressable example\\n\\n```tsx\\nimport { token } from '@atlaskit/tokens';\\nimport { Pressable } from '@atlaskit/primitives/compiled';\\nimport { xcss } from '@atlaskit/primitives/xcss';\\n\\nconst styles = xcss({\\n\\ttransition: token('motion.button.hovered'),\\n\\t':hover': { backgroundColor: 'color.background.neutral.hovered' },\\n\\t':active': {\\n\\t\\tbackgroundColor: 'color.background.neutral.pressed',\\n\\t\\ttransition: token('motion.button.pressed'),\\n\\t},\\n});\\n\\n<Pressable xcss={styles} />;\\n```\\n\\n## Native button example\\n\\n```tsx\\nimport { css } from '@compiled/react';\\nimport { token } from '@atlaskit/tokens';\\n\\nconst styles = css({\\n\\ttransition: token('motion.button.hovered'),\\n\\t'&:hover': { backgroundColor: token('color.background.neutral.hovered') },\\n\\t'&:active': {\\n\\t\\tbackgroundColor: token('color.background.neutral.pressed'),\\n\\t\\ttransition: token('motion.button.pressed'),\\n\\t},\\n});\\n\\n<button css={styles}>Save</button>;\\n```\\n\\nFor custom button guidance, see the\\n[Pressable motion documentation](https://atlassian.design/components/primitives/pressable/usage#apply-motion-to-pressable).\\n\"}",
317
+ ruleName: 'use-pressable-motion',
318
+ description: 'Encourages semantic motion tokens when local static styles change interactive colours on `Pressable`'
315
319
  }, {
316
320
  content: '{"ruleName":"use-primitives-text","description":"Using primitives allows you to delete bespoke component code and replace it with ready made","content":"# use-primitives-text\\n\\nUsing primitives allows you to delete bespoke component code and replace it with ready made\\nsolutions made by the Atlassian Design System Team.\\n\\n## Examples\\n\\nThis rule marks code as violations when it can be replaced 1:1 with one or multiple primitive\\ncomponents.\\n\\n### Incorrect\\n\\n```jsx\\n<span>text</span>\\n^^^^^^\\n<p>text</p>\\n^^^\\n<strong>text</strong>\\n^^^^^^^^\\n<em>text</em>\\n^^^^\\n```\\n\\n### Correct\\n\\n```jsx\\n<Text>text</Text>\\n<Text as=\\"p\\">text</Text>\\n<Text as=\\"strong\\">text</Text>\\n<Text as=\\"em\\">text</Text>\\n```\\n\\nCurrently, the rule is extremely defensive, only reporting on `span`, `p`, `strong` and `em`\\nelements that don\'t have any props outside of `key`, `id` and `data-testid`. For `span` elements\\nwe\'re only targeting instances that almost certainly only have text as children.\\n\\n## Options\\n\\n`enableUnsafeAutofix`: Rule creates errors with autofixes instead of suggestions. Defaults to\\n`false`.\\n\\n`enableUnsafeReport`: Rule reports errors for native elements that are not autofixable. Defaults to\\n`true`.\\n"}',
317
321
  ruleName: 'use-primitives-text',
package/dist/esm/tools/get-guidelines/guidelines-structured-content.codegen.js CHANGED
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * Structured content for content guidelines from design-system-docs foundations content.
5
5
  *
6
- * @codegen <<SignedSource::744810b00561c03e60666df4de7c08ef>>
6
+ * @codegen <<SignedSource::aa5784a7458f992053193083e044771b>>
7
7
  * @codegenCommand yarn build structured-docs
8
8
  */
9
9
 
@@ -65,7 +65,7 @@ export var guidelinesStructuredContent = [{
65
65
  content: 'import {\n\tTokenElevationBackgroundChangeExample,\n\tTokenElevationChangeExample,\n} from \'../../../components/interactive-elevations\';\n\n\n\n\n\nElevations are the layered surfaces that form the foundation of the UI. They create a blank canvas\nwhere other UI will be placed, such as text, icons, backgrounds, and borders.\n\n![](./_assets/elevation-layers.png)\n\nMost elevations consist of surfaces and shadows. Together, surfaces and shadows give the impression\nof lift or depth. Elevations can guide focus through layering, or indicate that the UI can be\nscrolled, slid, or dragged.\n\n## Applying elevations\n\nThe elevations use [design tokens](https://atlassian.design/tokens/design-tokens) to apply different\nsurface levels. The highest two elevation surfaces, raised and overlay, are paired with shadows to\ncreate more depth.\n\n![](./_assets/applying-elevations-light.png)\n\n### Elevations in dark theme\n\nShadows can be harder to see in dark mode, so dark mode elevations also rely on different surface\ncolors. Imagine that the surfaces are distantly lit from the front — the higher the elevation, the\nlighter the surface looks.\n\n![](./_assets/applying-elevations-dark-1.png)\n\nRaised and overlay surfaces are still paired with shadows for added depth and consistency in dark\nmode.\n\n![](./_assets/applying-elevations-dark-2.png)\n\n## Types of elevations\n\nThere are four basic elevation levels:\n\n1. [Sunken](#sunken)\n2. [Default](#default)\n3. [Raised](#raised)\n4. [Overlay](#overlay)\n\nThere is also one "[overflow](#overflow)" elevation for special cases.\n\n### Sunken\n\nSunken is the lowest elevation available. The sunken surface creates a backdrop (or well) where\nother content sits. Columns on a Kanban board are a good example of the sunken elevation.\n\nOnly use sunken surfaces on the default surface level. Don’t apply sunken elevations on raised or\noverlay elevations. To differentiate areas of the UI in other ways, use whitespace or borders\ninstead.\n\n![](./_assets/elevation-sunken-1.png)\n\n#### Using `elevation.surface.sunken` vs `color.background.neutral`\n\nAlthough `elevation.surface.sunken` and `color.background.neutral` tokens may appear similar in\nlight mode, they behave differently in dark mode. Here are the main differences between the two:\n\n`elevation.surface.sunken` is an opaque (solid) token that darkens in both light and dark modes. Use\nthis token as a backdrop to group content or elements together (such as a kanban board) on the\ndefault surface.\n\n![](./_assets/elevation-sunken-2.png)\n\n`color.background.neutral` is a token that uses a transparent color. It darkens in light mode and\nlightens in dark mode. Use this token when you need the background to adapt to different elevations,\nwhich is relevant in dark mode since surfaces change depending on what elevation you’re on.\n\n![](./_assets/elevation-sunken-3.png)\n\n### Default\n\nThe default elevation is the baseline with respect to all other layers. It represents a flat UI\nsurface with no visual lift, such as a Confluence page.\n\nUse `elevation.surface` as the starting point for body content when building a UI. To create flat\ncards, pair with a border.\n\n![](./_assets/elevation-surface-1.png)\n\n### Raised\n\nRaised elevations sit slightly higher than default elevations. They are reserved for cards that can\nbe moved, such as Jira and Trello cards. In special circumstances, they can be used for cards as a\nway to provide additional heirarchy or emphasis.\n\nAlways pair `elevation.surface.raised` with `elevation.shadow.raised`. This is particularly\nimportant in dark mode, where raised surfaces are lighter to help differentiate elevations.\n\n![](./_assets/elevation-raised-1.png)\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tUse raised elevations intentionally. If using for emphasis, limit to one section or focal point\n\t\tof the screen.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tRaised elevations can create visual noise, so don’t use to group content when a border or white\n\t\tspace would suffice.\n\t</DoDont>\n</DoDontGrid>\n\n### Overlay\n\nOverlay is the highest elevation available. It is reserved for a UI that sits over another UI, such\nas modals, dialogs, dropdown menus, floating toolbars, and floating single-action buttons.\n\nAlways pair `elevation.surface.overlay` with `elevation.shadow.overlay`. This is important in dark\nmode, where overlay surfaces are lighter to help differentiate elevations.\n\nOverlays can stack on top of other overlays.\n\n![](./_assets/elevation-overlay-1.png)\n\n### Overflow\n\nOverflow is a shadow indicating content has [scrolled](#scrolled) outside a view. It can be used for\nvertical or horizontal scroll. An example of overflow shadows is the horizontal scroll in tables on\na Confluence page.\n\n![](./_assets/elevation-overflow-1.png)\n\nIf box shadows are not technically feasible, use the combination of\n`elevation.shadow.overflow.spread` and `elevation.shadow.overflow.perimeter` to replicate the\noverflow shadow.\n\n## Interaction states\n\n### Hovered and pressed\n\nElevations use surface color changes to communicate hovered and pressed states. Use the hovered and\npressed elevation tokens to create these visual changes.\n\n![](./_assets/elevation-hovered.png)\n\nTransitions between elevations can be used as an alternative to hovered and pressed tokens, but only\nfor default and raised elevations (not overlays):\n\n- Transition to overlay elevation on hover\n- Transition to raised elevation on press\n\nThis approach should be used sparingly to avoid excessive animation. It should not be used for very\nsmall UI, as elevation changes are harder to see than surface color changes at this size.\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tUse the recommended hovered and pressed tokens for interaction states on elevations.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tDon’t combine elevation transitions and hovered and pressed tokens for interactive states. Use\n\t\tone or the other.\n\t</DoDont>\n</DoDontGrid>\n\n#### Background change example\n\n<TokenElevationBackgroundChangeExample />\n\n#### Elevation change example\n\n<TokenElevationChangeExample />\n\n### Dragged\n\nUse the overlay elevation for any UI that is being dragged. Once moved, it returns to its original\nelevation.\n\n![](./_assets/elevation-dragged-1.png)\n\n### Scrolled\n\nWhen scrollable content exceeds the available area, a border or [overflow](#overflow) shadow can be\napplied at the point the content is cut off to indicate there is hidden content that can be scrolled\nback into view.\n\nA border is the default approach for scrolled content and can be seen in modal sticky headers and\nfooters, and top and side navigation.\n\n![](./_assets/elevation-scrolled.png)\n\n[Overflow](#overflow) shadows are reserved for experiences where a border might be easily missed,\nsuch as in very small UI or tables that use borders to separate cells.\n\nBoth approaches should apply the appropriate surface token where the content is being hidden.\n\n## All elevation tokens and values\n\nFor the full list of elevation 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## Best practices\n\n### Follow the recommended surface and shadow pairings\n\nRaised and overlay elevations have dedicated surface and shadow pairings.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: pairingDo, alt: \'\' }}>\n\t\tWhen creating elevations, always pair matching surface and shadow tokens.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: pairingDont, alt: \'\' }}>\n\t\tDon\'t mix different shadow and surface elevation tokens.\n\t</DoDont>\n</DoDontGrid>\n\n### Replace elevation surfaces with background colors only when required\n\nElevation surfaces use our\n[neutral palettes](https://atlassian.design/foundations/color#neutral-colors). If a different color\nis needed, surface tokens can be swapped for any solid background token. When using background\ntokens, align to the behavior of\n[interaction states for color tokens](https://atlassian.design/foundations/color#interaction-states).\n\n![](./_assets/background-colors.png)\n\n### Avoid excessive use of raised and overlay elevations\n\nThe shadows and surfaces of raised and overlay elevations can create busy UI if not applied\nintentionally. Follow the recommended guidance when considering these elevations.\n\n<DoDontGrid>\n\t<DoDont type="do" image={{ url: groupingDo, alt: \'\' }}>\n\t\tLimit the use of overlay elevations by grouping related buttons together in a floating toolbar\n\t\tif they are required to sit over another UI.\n\t</DoDont>\n\t<DoDont type="dont" image={{ url: groupingDont, alt: \'\' }}>\n\t\tDon’t have more than one floating button next to each other.\n\t</DoDont>\n</DoDontGrid>\n\n### Check contrast ratios\n\nAlways make sure your elevation and background choices are accessible.\n\n<DoDontGrid>\n\t<DoDont type="do">\n\t\tCheck the contrast ratio for UI on overlay surfaces in dark mode to ensure it meets\n\t\taccessibility requirements.\n\t</DoDont>\n\t<DoDont type="dont">\n\t\tDon\'t assume that because UI is accessible in light mode, it will be in dark mode. Some UI may\n\t\tneed tweaking.\n\t</DoDont>\n</DoDontGrid>\n\n## Z-index\n\nThe z-index determines the stacking order of elements. Elements with a higher z-index always sit in\nfront of elements with a lower z-index.\n\nDifferent UI can have the same elevation style, but each UI should apply a different z-index to\nindicate the layer(s) order in a stack (or where the elements touch).\n\n| Z-index | Example usage | Elevation level |\n| ------- | --------------------------------------------------------------------------------- | --------------- |\n| 100 | None | None |\n| 200 | [Atlassian navigation](https://atlassian.design/components/atlassian-navigation/) | Default |\n| 300 | [Inline dialog](https://atlassian.design/components/inline-dialog/) | Overlay |\n| 400 | [Popup](https://atlassian.design/components/popup/) | Overlay |\n| 500 | [Blanket](https://atlassian.design/components/blanket/) | None |\n| 510 | [Modal](https://atlassian.design/components/modal-dialog/) | Overlay |\n| 600 | [Flag](https://atlassian.design/components/flag/) | Overlay |\n| 700 | [Spotlight](https://atlassian.design/components/onboarding/) | Overlay |\n| 800 | [Tooltip](https://atlassian.design/components/tooltip/) | None |\n\n## Related\n\n- Learn about the basics of [design tokens](https://atlassian.design/tokens/design-tokens).\n- See the list of [all design tokens](https://atlassian.design/components/tokens/all-tokens) for\n full descriptions and values for all tokens.',
66
66
  keywords: ['elevation', 'shadow', 'depth', 'z-index', 'layering', 'design tokens']
67
67
  }, {
68
- content: '## Overview\n\nGrid is a system for arranging content consistently within the main content area of an Atlassian\napp.\n\nIn Figma, grids are typically set up using\n[layout guides](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides). In the\nAtlassian Design System, we offer a purpose-built Figma grid for structuring content within the\napp\'s main content area. Engineers implement equivalent layouts using a combination of\n[primitives](/components/primitives/overview) such as box, stack, and inline.\n\nThe [layout](/components/navigation-system/layout) component (in code and Figma) defines everything\naround the main content area, including navigation and panels.\n\n<img\n\tsrc={layoutAnatomy}\n\tsrcDark={layoutAnatomyDark}\n\talt="Layout component anatomy showing the top nav, side nav, main, and panel. Grid sits within main."\n/>\n\n## Grid basics\n\nOur Figma grid has three basic elements:\n\n- **Columns** divide the main content area into 12 equal parts for horizontal structure.\n- **Gutters** are the gaps between columns, providing consistent separation between content.\n- **Margins** are the empty space between the outer columns and the edge of the main content area.\n They give content breathing room.\n\n<img\n\tsrc={gridAnatomy}\n\tsrcDark={gridAnatomyDark}\n\talt="Figma grid anatomy showing columns, gutters, and margins."\n/>\n\nBy aligning content to the columns, our grid accommodates a variety of layouts within the main\ncontent area.\n\n<img\n\tsrc={columnSpan}\n\tsrcDark={columnSpanDark}\n\talt="Diagram showing content arrangement spanning 12, 6, or 4 grid columns."\n/>\n\nContent in the main content area can also span fewer columns, centered within the grid.\n\n<img\n\tsrc={columnOffset}\n\tsrcDark={columnOffsetDark}\n\talt="Diagram showing content arrangement center-aligned on the grid and spanning 8, 10, or 12 grid columns."\n/>\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: gridBasicsDo,\n\t\t\turlDarkMode: gridBasicsDoDark,\n\t\t\talt: \'Example of content aligning to the grid columns.\',\n\t\t}}\n\t>\n\t\tAlign content within the app\'s main content area across any number of columns required.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: gridBasicsDont,\n\t\t\turlDarkMode: gridBasicsDontDark,\n\t\t\talt: \'Example of content overflowing into grid gutters and margins, breaking visual alignment.\',\n\t\t}}\n\t>\n\t\tDon\'t allow content to overflow into gutters or margins. This breaks visual alignment and makes\n\t\tlayouts unpredictable.\n\t</DoDont>\n</DoDontGrid>\n\n## Aligning to the grid\n\nWithin the main content area, align content containers to the grid columns. Examples include cards,\nimages, text blocks, tables, and forms.\n\nSmall elements, like buttons and icons, do not need to align to this grid. Use\n[space tokens](/foundations/spacing#space-tokens) to manage the space between and within them\ninstead.\n\n<img\n\tsrc={spacingTokens}\n\tsrcDark={spacingTokensDark}\n\talt="Example showing cards aligned to grid columns. The horizontally placed input field and buttons, as well as the content within the card, do not align to the grid columns and are instead managed with space tokens."\n/>\n\nThe same applies within content containers. Only top-level containers need to align to the grid. Use\nspace tokens for the elements inside them, such as cards and table columns.\n\n<img\n\tsrc={contentContainers}\n\tsrcDark={contentContainersDark}\n\talt="Example showing kanban columns aligned to the grid, but the cards within them using space tokens."\n/>\n\nOverlays like modals, tooltips, and dropdown menus also sit outside the grid, as they float above\nthe page content.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: alignContentDo,\n\t\t\turlDarkMode: alignContentDoDark,\n\t\t\talt: \'Example of content containers aligning to the grid columns.\',\n\t\t}}\n\t>\n\t\tAlign content containers to our grid columns, such as cards, images, text blocks, tables, and\n\t\tforms.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: alignContentDont,\n\t\t\turlDarkMode: alignContentDontDark,\n\t\t\talt: \'Example of buttons and icons incorrectly aligned to the grid columns instead of using space tokens.\',\n\t\t}}\n\t>\n\t\tDon\'t align small elements, such as buttons or icons, to the grid. Instead, use space tokens to\n\t\tmanage their spacing.\n\t</DoDont>\n</DoDontGrid>\n\n## Nested grids\n\nSpace tokens are the recommended approach for aligning content within containers, but you can also\napply an internal grid.\n\nThe underlying concepts are the same: columns, gutters, and margins. Our Figma grid is only intended\nfor the main content area. To set up a grid inside a container,\n[create your own](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides) using\nvalues from our [spacing scale](/foundations/spacing#space-tokens).\n\n<img\n\tsrc={nestedGrid}\n\tsrcDark={nestedGridDark}\n\talt="Example showing a card sitting on the main grid. The card has its own nested grid."\n/>\n\n## Grid breakpoints\n\nAt each breakpoint, the gutter width, margin width, and number of columns adjust within the main\ncontent area.\n\n<img\n\tsrc={gridBreakpoints}\n\tsrcDark={gridBreakpointsDark}\n\talt="Example showing how the grid changes across three breakpoint ranges: m to xl, xs to s, and xxs."\n/>\n\nThese are our default values for the grid in the main content area. Check your app or local system\nfor the specific grid values in use, as they may differ.\n\n<BreakpointsTable />\n\n### Designing for multiple breakpoints\n\nDesign for at least 2 screen sizes, preferably more. One of these should be mobile.\n\n| Device | Breakpoint | Width (px) | Height (px) | Good | Better | Best |\n| ------- | ---------- | ---------- | ----------- | ---- | ------ | ---- |\n| Mobile | `xxs` | 320 | 568 | ✓ | ✓ | ✓ |\n| Tablet | `s` | 768 | 1024 | - | - | ✓ |\n| Desktop | `l` | 1440 | 900 | - | ✓ | ✓ |\n| Desktop | `xl` | 1920 | 1080 | ✓ | ✓ | ✓ |\n\nBreakpoints also affect layout areas like navigation and panels. See the\n[layout component](/components/navigation-system/layout) for details.\n\n## Grid types\n\nThere are two types of grid:\n\n- **Fixed grids** have a maximum width and sit centered in the main content area. This is the\n default option.\n- **Fluid grids** fill the available space in the main content area. Use fluid grids when content\n expands horizontally and has no natural maximum width. Use them sparingly. At very large\n viewports, text lines can become too long and visual relationships between elements may break\n down.\n\nWhen the main content area is smaller than the maximum width, such as at smaller breakpoints, fixed\ngrids behave the same as fluid grids.\n\n<img\n\tsrc={gridTypes}\n\tsrcDark={gridTypesDark}\n\talt="Side-by-side comparison of fixed and fluid grids on desktop and mobile viewports."\n/>\n\n### Fixed grids\n\nThere are two fixed grid options:\n\n- **Fixed-wide** has a maximum width of 1296px (including margins). Use this as the default for most\n experiences.\n- **Fixed-narrow** has a maximum width of 864px (including margins). Use this for long-form content\n to limit line length and increase readability. Some internal elements, such as headers, may break\n out of the grid to span across the page.\n\n<img\n\tsrc={fixedGridTypes}\n\tsrcDark={fixedGridTypesDark}\n\talt="Side-by-side comparison of fixed-wide and fixed-narrow grids."\n/>\n\n### Choosing a grid type\n\n| Grid type | Maximum width (margins included) | Use when | Examples |\n| -------------------- | -------------------------------- | ----------------------------------------------------------- | --------------------------------------- |\n| Fixed-wide (default) | 1296px | Content benefits from structure but doesn\'t need full width | Dashboards, directories, search results |\n| Fixed-narrow | 864px | Long-form reading is the primary activity | Blogs, articles, documentation |\n| Fluid | No maximum | Content expands horizontally with no natural maximum width | Kanban boards, whiteboards |\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fixedWideDo,\n\t\t\turlDarkMode: fixedWideDoDark,\n\t\t\talt: \'Example using a fixed-wide grid for a table directory.\',\n\t\t}}\n\t>\n\t\tUse fixed-wide grids for structured content, such as dashboards, search results, and\n\t\tdirectories.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fixedWideDont,\n\t\t\turlDarkMode: fixedWideDontDark,\n\t\t\talt: \'Example using a fixed-wide grid for long-form content.\',\n\t\t}}\n\t>\n\t\tDon\'t use fixed-wide grids for long-form content like blogs and articles. Long line lengths\n\t\timpair readability.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fixedNarrowDo,\n\t\t\turlDarkMode: fixedNarrowDoDark,\n\t\t\talt: \'Example using a fixed-narrow grid for long-form content.\',\n\t\t}}\n\t>\n\t\tUse fixed-narrow grids for long-form content, such as blogs and articles.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fixedNarrowDont,\n\t\t\turlDarkMode: fixedNarrowDontDark,\n\t\t\talt: \'Example using a fixed-narrow grid for a kanban board.\',\n\t\t}}\n\t>\n\t\tDon\'t use fixed-narrow grids for content that needs more horizontal space. Use fixed-wide or\n\t\tfluid instead.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fluidDo,\n\t\t\turlDarkMode: fluidDoDark,\n\t\t\talt: \'Example using a fluid grid for a kanban board.\',\n\t\t}}\n\t>\n\t\tUse fluid grids for content that expands horizontally, such as kanban boards and whiteboards.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fluidDont,\n\t\t\turlDarkMode: fluidDontDark,\n\t\t\talt: \'Example using a fluid grid for a table directory.\',\n\t\t}}\n\t>\n\t\tDon\'t use fluid grids for structured content with a natural width, such as dashboards or\n\t\tdirectories. Elements lose their visual relationship at large viewports.\n\t</DoDont>\n</DoDontGrid>\n\n## Applying grid\n\nThe default grid is already built into the Figma layout component.\n\n1. Select your grid type from the component properties panel.\n2. Choose your breakpoint from the responsive menu in the appearance panel.\n\n<img\n\tsrc={applyingGrid}\n\tsrcDark={applyingGridDark}\n\talt="Screenshot of the Figma layout component with the properties panel showing grid type and responsive selectors."\n/>\n\nYou can also use this grid outside of the layout component. Select it from the assets panel in the\nADS Foundations library, or\n[create your own](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides) using\nyour app\'s values.\n\n**Tip:** Use **Shift + G** (Mac) or **Control + G** (Windows) to show or hide the grid in Figma.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: gridSpanDo,\n\t\t\turlDarkMode: gridSpanDoDark,\n\t\t\talt: \'Example of the grid spanning the main content area only.\',\n\t\t}}\n\t>\n\t\tSpan only the main content area. Exclude the side nav and panel.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: gridSpanDont,\n\t\t\turlDarkMode: gridSpanDontDark,\n\t\t\talt: \'Example of the grid spanning the side nav and main area.\',\n\t\t}}\n\t>\n\t\tDon\'t span the grid across navigation or panel areas.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: breakpointSettingDo,\n\t\t\turlDarkMode: breakpointSettingDoDark,\n\t\t\talt: \'Screenshot of the Figma responsive setting in the appearance panel.\',\n\t\t}}\n\t>\n\t\tChange the breakpoint from the responsive setting in the appearance panel.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: breakpointSettingDont,\n\t\t\turlDarkMode: breakpointSettingDontDark,\n\t\t\talt: \'Example of manually resizing the grid component.\',\n\t\t}}\n\t>\n\t\tDon\'t change the breakpoint by resizing the grid or layout component. The linked grid styles\n\t\twill map incorrectly.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: breakpointViewportDo,\n\t\t\turlDarkMode: breakpointViewportDoDark,\n\t\t\talt: \'Breakpoint set to the full viewport width.\',\n\t\t}}\n\t>\n\t\tSet the grid breakpoint to the full viewport width.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: breakpointViewportDont,\n\t\t\turlDarkMode: breakpointViewportDontDark,\n\t\t\talt: \'Breakpoint set to the content area width only.\',\n\t\t}}\n\t>\n\t\tDon\'t set the breakpoint based on the main content area width. Breakpoints are based on the full\n\t\tviewport width.\n\t</DoDont>\n</DoDontGrid>\n\n## Grid and auto layout\n\nGrid is a layout guide, a visual reference for aligning content to columns. To build layouts that\nadjust as the breakpoint changes, use\n[auto layout](https://help.figma.com/hc/en-us/articles/360040451373-Guide-to-auto-layout) to\nposition content along the grid columns.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: autoLayoutDo,\n\t\t\turlDarkMode: autoLayoutDoDark,\n\t\t\talt: \'Screenshot of Figma auto layout settings.\',\n\t\t}}\n\t>\n\t\tUse auto layout to build responsive layouts that align to the grid.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: autoLayoutDont,\n\t\t\turlDarkMode: autoLayoutDontDark,\n\t\t\talt: \'Example of manually positioning content in Figma.\',\n\t\t}}\n\t>\n\t\tDon\'t use absolute positioning or drag-to-place content without auto layout. Manual placement\n\t\tdoesn\'t adapt to changing breakpoints and breaks responsive layouts.\n\t</DoDont>\n</DoDontGrid>\n\n## Related\n\n- [Layout](/components/navigation-system/layout) is the component that defines the outer structure\n of an app, including navigation, panels, and the main content area.\n- [Primitives](/components/primitives/overview) are the box, stack, and inline primitives used to\n build equivalent layouts in code.\n- [Spacing](/foundations/spacing) uses space tokens to ensure consistent alignment and separation\n between elements.\n- [ADS Figma libraries](/get-started/design/figma-libraries/atlassians) contain the pre-built grid\n with default Atlassian breakpoint values.\n- [Auto layout in Figma](https://help.figma.com/hc/en-us/articles/360040451373-Guide-to-auto-layout)\n is Figma\'s guide to building responsive layouts that align to grid columns.',
68
+ content: '## Overview\n\nGrid is a system for arranging content consistently within the main content area of an Atlassian\napp.\n\nIn Figma, grids are set up using\n[Figma layout guides](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides).\nThe code equivalent is built using a combination of [primitives](/components/primitives/overview)\nsuch as box, stack, and inline.\n\nFor everything outside of the main content area, including navigation and panel, see the\n[layout component](/components/navigation-system/layout).\n\n<img\n\tsrc={layoutAnatomy}\n\tsrcDark={layoutAnatomyDark}\n\talt="Layout component anatomy showing the top nav, side nav, main, and panel. Grid sits within main."\n/>\n\n## Grid basics\n\nThe Figma grid component has three basic elements:\n\n- **Columns** divide the main content area into 12 equal parts for horizontal structure.\n- **Gutters** are the gaps between columns, providing consistent separation between content.\n- **Margins** are the empty space between the outer columns and the edge of the main content area.\n They give content clear space.\n\n<img\n\tsrc={gridAnatomy}\n\tsrcDark={gridAnatomyDark}\n\talt="Figma grid component anatomy showing columns, gutters, and margins."\n/>\n\nAligning content to the columns supports a variety of layouts in the main content area. For example,\ncontent can span 12, 6, or 4 columns.\n\n<img\n\tsrc={columnSpan}\n\tsrcDark={columnSpanDark}\n\talt="Diagram showing content arrangement spanning 12, 6, or 4 grid columns."\n/>\n\nContent can also sit centered within the grid. For example, a centered block can span 8, 10, or 12\ncolumns.\n\n<img\n\tsrc={columnOffset}\n\tsrcDark={columnOffsetDark}\n\talt="Diagram showing content arrangement center-aligned on the grid and spanning 8, 10, or 12 grid columns."\n/>\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: gridBasicsDo,\n\t\t\turlDarkMode: gridBasicsDoDark,\n\t\t\talt: \'Example of content aligning to the grid columns.\',\n\t\t}}\n\t>\n\t\tAlign content within the app\'s main content area across any number of columns required.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: gridBasicsDont,\n\t\t\turlDarkMode: gridBasicsDontDark,\n\t\t\talt: \'Example of content overflowing into grid gutters and margins, breaking visual alignment.\',\n\t\t}}\n\t>\n\t\tDon\'t allow content to overflow into gutters or margins. This breaks visual alignment and makes\n\t\tlayouts unpredictable.\n\t</DoDont>\n</DoDontGrid>\n\n## How to choose what to align to the grid\n\nWithin the main content area, align content containers to the grid columns. Examples include cards,\nimages, text blocks, tables, and forms.\n\nSmall elements, like buttons and icons, do not need to align to this grid. Use\n[space tokens](/foundations/spacing#space-tokens) to manage the space between and within them\ninstead.\n\n<img\n\tsrc={spacingTokens}\n\tsrcDark={spacingTokensDark}\n\talt="Example showing cards aligned to grid columns. The horizontally placed input field and buttons, as well as the content within the card, do not align to the grid columns and are instead managed with space tokens."\n/>\n\nThe same applies within content containers. Only top-level containers need to align to the grid. Use\nspace tokens for the elements inside them, such as cards and table columns.\n\n<img\n\tsrc={contentContainers}\n\tsrcDark={contentContainersDark}\n\talt="Example showing kanban columns aligned to the grid, but the cards within them using space tokens."\n/>\n\nOverlays like modals, tooltips, and dropdown menus also sit outside the grid, as they float above\nthe page content.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: alignContentDo,\n\t\t\turlDarkMode: alignContentDoDark,\n\t\t\talt: \'Example of content containers aligning to the grid columns.\',\n\t\t}}\n\t>\n\t\tAlign content containers to our grid columns, such as cards, images, text blocks, tables, and\n\t\tforms.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: alignContentDont,\n\t\t\turlDarkMode: alignContentDontDark,\n\t\t\talt: \'Example of buttons and icons incorrectly aligned to the grid columns instead of using space tokens.\',\n\t\t}}\n\t>\n\t\tDon\'t align small elements, such as buttons or icons, to the grid. Instead, use space tokens to\n\t\tmanage their spacing.\n\t</DoDont>\n</DoDontGrid>\n\n## Nested grids\n\nSpace tokens are recommended for aligning content within containers, but you can also apply an\ninternal grid.\n\nWhile the underlying concepts are the same for columns, gutters, and margins, our grid component in\nFigma is only intended for the main content area. When setting up a grid inside a container, use our\n[space tokens](/foundations/spacing#space-tokens).\n\n[Create your own Figma layout guides](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides).\n\n<img\n\tsrc={nestedGrid}\n\tsrcDark={nestedGridDark}\n\talt="Example showing a card sitting on the main grid. The card has its own nested grid."\n/>\n\n## Grid breakpoints\n\nBreakpoints are based on the viewport width, not the width of the main content area. Showing or\nhiding the side navigation or a panel does not change which breakpoint the grid uses.\n\nThese are our default values for the grid in the main content area. Check your app or local system\nfor the specific grid values in use, as they may differ.\n\n<BreakpointsTable />\n\nAt each breakpoint, the gutter width, margin width, and number of columns adjust within the main\ncontent area. Breakpoints also affect layout areas like navigation and panels. For details see the\n[layout component](/components/navigation-system/layout).\n\nDesign for at least two device sizes from the table above, and preferably more. Always include\nmobile (`xxs`).\n\n<img\n\tsrc={gridBreakpoints}\n\tsrcDark={gridBreakpointsDark}\n\talt="Example showing how the grid changes across three breakpoint ranges: m – xl, xs – s, and xxs."\n/>\n\n## Grid types\n\nThere are two types of grid:\n\n- **Fixed grids** have a maximum width and sit centered in the main content area. This default\n option comes in two sizes: fixed-wide and fixed-narrow.\n- **Fluid grids** fill the available space in the main content area. Use fluid grids when content\n expands horizontally and has no natural maximum width. Use sparingly, because at very large\n viewports, text lines can become too long and visual relationships between elements may break\n down.\n\nWhen the main content area is smaller than the maximum width, such as at smaller breakpoints, fixed\ngrids behave the same as fluid grids.\n\n<img\n\tsrc={gridTypes}\n\tsrcDark={gridTypesDark}\n\talt="Side-by-side comparison of fixed and fluid grids on desktop and mobile viewports."\n/>\n\n### Fixed grids\n\nThere are two fixed grid options:\n\n- **Fixed-wide** has a maximum width of 1296px (including margins). Use this as the default for most\n experiences.\n- **Fixed-narrow** has a maximum width of 864px (including margins). Use this for long-form content\n such as blogs and articles, to limit line length and increase readability. Some internal elements,\n such as headers, may break out of the grid to span across the page.\n\n<img\n\tsrc={fixedGridTypes}\n\tsrcDark={fixedGridTypesDark}\n\talt="Side-by-side comparison of fixed-wide and fixed-narrow grids."\n/>\n\n### Choosing between fixed and fluid grids\n\n| Grid type | Maximum width (margins included) | Use when | Examples |\n| -------------------- | -------------------------------- | ----------------------------------------------------------- | --------------------------------------- |\n| Fixed-wide (default) | 1296px | Content benefits from structure but doesn\'t need full width | Dashboards, directories, search results |\n| Fixed-narrow | 864px | Long-form reading is the primary activity | Blogs, articles, documentation |\n| Fluid | No maximum | Content expands horizontally with no natural maximum width | Kanban boards, whiteboards |\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fixedWideDo,\n\t\t\turlDarkMode: fixedWideDoDark,\n\t\t\talt: \'Example using a fixed-wide grid for a table directory.\',\n\t\t}}\n\t>\n\t\tUse fixed-wide grids for structured content, such as dashboards, search results, and\n\t\tdirectories.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fixedWideDont,\n\t\t\turlDarkMode: fixedWideDontDark,\n\t\t\talt: \'Example using a fixed-wide grid for long-form content.\',\n\t\t}}\n\t>\n\t\tDon\'t use fixed-wide grids for long-form content like blogs and articles. Long line lengths\n\t\timpair readability.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fixedNarrowDo,\n\t\t\turlDarkMode: fixedNarrowDoDark,\n\t\t\talt: \'Example using a fixed-narrow grid for long-form content.\',\n\t\t}}\n\t>\n\t\tUse fixed-narrow grids for long-form content, such as blogs and articles.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fixedNarrowDont,\n\t\t\turlDarkMode: fixedNarrowDontDark,\n\t\t\talt: \'Example using a fixed-narrow grid for a kanban board.\',\n\t\t}}\n\t>\n\t\tDon\'t use fixed-narrow grids for content that needs more horizontal space. Use fixed-wide or\n\t\tfluid instead.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: fluidDo,\n\t\t\turlDarkMode: fluidDoDark,\n\t\t\talt: \'Example using a fluid grid for a kanban board.\',\n\t\t}}\n\t>\n\t\tUse fluid grids for content that expands horizontally, such as kanban boards and whiteboards.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: fluidDont,\n\t\t\turlDarkMode: fluidDontDark,\n\t\t\talt: \'Example using a fluid grid for a table directory.\',\n\t\t}}\n\t>\n\t\tDon\'t use fluid grids for structured content with a natural width, such as dashboards or\n\t\tdirectories. Elements lose their visual relationship at large viewports.\n\t</DoDont>\n</DoDontGrid>\n\n## Applying grid\n\nThe default grid is already built into the Figma layout component.\n\n1. Select your grid type from the component properties panel.\n2. Choose your breakpoint from the responsive menu in the appearance panel.\n\n<img\n\tsrc={applyingGrid}\n\tsrcDark={applyingGridDark}\n\talt="Screenshot of the Figma layout component with the properties panel showing grid type and responsive selectors."\n/>\n\nYou can also use this grid outside of the layout component. Select it from the assets panel in the\nADS Foundations library, or\n[create your own](https://help.figma.com/hc/en-us/articles/360040450513-Create-layout-guides) using\nyour app\'s values.\n\n**Tip:** Use **Shift + G** (Mac) or **Control + G** (Windows) to show or hide the grid in Figma.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: gridSpanDo,\n\t\t\turlDarkMode: gridSpanDoDark,\n\t\t\talt: \'Example of the grid spanning the main content area only.\',\n\t\t}}\n\t>\n\t\tSpan only the main content area. Exclude the side nav and panel.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: gridSpanDont,\n\t\t\turlDarkMode: gridSpanDontDark,\n\t\t\talt: \'Example of the grid spanning the side nav and main area.\',\n\t\t}}\n\t>\n\t\tDon\'t span the grid across navigation or panel areas.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: breakpointSettingDo,\n\t\t\turlDarkMode: breakpointSettingDoDark,\n\t\t\talt: \'Screenshot of the Figma responsive setting in the appearance panel.\',\n\t\t}}\n\t>\n\t\tChange the breakpoint from the responsive setting in the appearance panel.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: breakpointSettingDont,\n\t\t\turlDarkMode: breakpointSettingDontDark,\n\t\t\talt: \'Example of manually resizing the grid component.\',\n\t\t}}\n\t>\n\t\tDon\'t change the breakpoint by resizing the grid or layout component. The linked grid styles\n\t\twill map incorrectly.\n\t</DoDont>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: breakpointViewportDo,\n\t\t\turlDarkMode: breakpointViewportDoDark,\n\t\t\talt: \'Breakpoint set to the full viewport width.\',\n\t\t}}\n\t>\n\t\tSet the grid breakpoint to the full viewport width.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: breakpointViewportDont,\n\t\t\turlDarkMode: breakpointViewportDontDark,\n\t\t\talt: \'Breakpoint set to the content area width only.\',\n\t\t}}\n\t>\n\t\tDon\'t set the breakpoint based on the main content area width. Breakpoints are based on the full\n\t\tviewport width.\n\t</DoDont>\n</DoDontGrid>\n\n## Grid and auto layout\n\nGrid is a layout guide and a visual reference for aligning content to columns. To build layouts in\nFigma that adjust as the breakpoint changes, use auto layout to position content along the grid\ncolumns.\n\n<DoDontGrid>\n\t<DoDont\n\t\ttype="do"\n\t\timage={{\n\t\t\turl: autoLayoutDo,\n\t\t\turlDarkMode: autoLayoutDoDark,\n\t\t\talt: \'Screenshot of Figma auto layout settings.\',\n\t\t}}\n\t>\n\t\tUse auto layout to build responsive layouts that align to the grid.\n\t</DoDont>\n\t<DoDont\n\t\ttype="dont"\n\t\timage={{\n\t\t\turl: autoLayoutDont,\n\t\t\turlDarkMode: autoLayoutDontDark,\n\t\t\talt: \'Example of manually positioning content in Figma.\',\n\t\t}}\n\t>\n\t\tDon\'t use absolute positioning or drag-to-place content without auto layout. Manual placement\n\t\tdoesn\'t adapt to changing breakpoints and breaks responsive layouts.\n\t</DoDont>\n</DoDontGrid>\n\n## Related\n\n- [Layout](/components/navigation-system/layout) is the component that defines the outer structure\n of an app, including navigation, panels, and the main content area.\n- [Primitives](/components/primitives/overview) are the box, stack, and inline primitives used to\n build equivalent layouts in code.\n- [Spacing](/foundations/spacing) uses space tokens to ensure consistent alignment and separation\n between elements.\n- [ADS Figma libraries](/get-started/design/figma-libraries/atlassians) contain the pre-built grid\n with default Atlassian breakpoint values.\n- [Auto layout in Figma](https://help.figma.com/hc/en-us/articles/360040451373-Guide-to-auto-layout)\n is Figma\'s guide to building responsive layouts that align to grid columns.',
69
69
  keywords: ['grid', 'layout', 'responsive', 'spacing', 'alignment', 'design system']
70
70
  }, {
71
71
  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![](./_assets/icon_sizing_options.png)\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![](./_assets/Keyline_shapes.png)\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).',