@atlaskit/eslint-plugin-design-system 9.6.0 → 10.0.0

package/constellation/no-physical-properties/usage.mdx

@@ -1,9 +1,9 @@
 # no-physical-properties
 
-Disallows using physical properties. Physical properties
-prevent correct support for different reading modes and languages and
-should be avoided. Rule will autofix applicable physical properties
-to instead use [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values/Basic_concepts_of_logical_properties_and_values).
+Disallows using physical properties. Physical properties prevent correct support for different
+reading modes and languages and should be avoided. Rule will autofix applicable physical properties
+to instead use
+[logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_logical_properties_and_values/Basic_concepts_of_logical_properties_and_values).
 
 ## Examples
 
@@ -13,22 +13,22 @@ This rule checks for physical property usage inside of `css` function calls.
 
 ```js
 css({
-  left: 0,
-  right: 0,
-  top: 0,
-  bottom: 0,
+    left: 0,
+    right: 0,
+    top: 0,
+    bottom: 0,
 });
 ```
 
 ```js
 css({
-  marginLeft: 0,
+    marginLeft: 0,
 });
 ```
 
 ```js
 css({
-  textAlign: 'left',
+    textAlign: 'left',
 });
 ```
 
@@ -36,18 +36,18 @@ css({
 
 ```js
 css({
-  inset: 0,
+    inset: 0,
 });
 ```
 
 ```js
 css({
-  marginInlineStart: 0,
+    marginInlineStart: 0,
 });
 ```
 
 ```js
 css({
-  textAlign: 'start',
+    textAlign: 'start',
 });
 ```

package/constellation/no-styled-tagged-template-expression/usage.mdx

@@ -1,8 +1,11 @@
 # no-styled-tagged-template-expression
 
-Disallows any `styled` tagged template expressions that originate from a CSS-in-JS library, including `@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
+Disallows any `styled` tagged template expressions that originate from a CSS-in-JS library,
+including `@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
 
-Tagged template expressions are difficult to parse correctly (which can lead to more frequent build failures or invalid CSS generation), have limited type safety, and lack syntax highlighting. These problems can be avoided by using the preferred call expression syntax instead.
+Tagged template expressions are difficult to parse correctly (which can lead to more frequent build
+failures or invalid CSS generation), have limited type safety, and lack syntax highlighting. These
+problems can be avoided by using the preferred call expression syntax instead.
 
 The `--fix` option on the command line automatically fixes problems reported by this rule.
 
@@ -14,21 +17,21 @@ The `--fix` option on the command line automatically fixes problems reported by
 import { styled } from '@compiled/react';
 
 const InlinedStyles = styled.div`
-  color: blue;
+    color: blue;
 `;
 
 const MultilineStyles = styled.div`
-  color: blue;
-  font-weight: 500;
+    color: blue;
+    font-weight: 500;
 `;
 
 const ComposedStyles = styled(InlinedStyles)`
-  font-weight: 500;
+    font-weight: 500;
 `;
 
 const DynamicStyles = styled.div`
-  color: ${(props) => props.color};
-  ${(props) => (props.disabled ? 'opacity: 0.8' : 'opacity: 1')}
+    color: ${(props) => props.color};
+    ${(props) => (props.disabled ? 'opacity: 0.8' : 'opacity: 1')}
 `;
 ```
 
@@ -38,23 +41,23 @@ const DynamicStyles = styled.div`
 import { styled } from '@compiled/react';
 
 const InlinedStyles = styled.div({
-  color: 'blue',
+    color: 'blue',
 });
 
 const MultilineStyles = styled.div({
-  color: 'blue',
-  fontWeight: 500,
+    color: 'blue',
+    fontWeight: 500,
 });
 
 const ComposedStyles = styled(InlinedStyles)({
-  fontWeight: 500,
+    fontWeight: 500,
 });
 
 const DynamicStyles = styled.div(
-  {
-    color: (props) => props.color,
-  },
-  (props) => (props.disabled ? 'opacity: 0.8' : 'opacity: 1'),
+    {
+        color: (props) => props.color,
+    },
+    (props) => (props.disabled ? 'opacity: 0.8' : 'opacity: 1'),
 );
 ```
 
@@ -64,15 +67,16 @@ const DynamicStyles = styled.div(
 
 By default, this rule will check `styled` usages from:
 
-- `@atlaskit/css`
-- `@atlaskit/primitives`
-- `@compiled/react`
-- `@emotion/react`
-- `@emotion/core`
-- `@emotion/styled`
-- `styled-components`
+-   `@atlaskit/css`
+-   `@atlaskit/primitives`
+-   `@compiled/react`
+-   `@emotion/react`
+-   `@emotion/core`
+-   `@emotion/styled`
+-   `styled-components`
 
-To change this list of libraries, you can define a custom set of `importSources`, which accepts an array of package names (strings).
+To change this list of libraries, you can define a custom set of `importSources`, which accepts an
+array of package names (strings).
 
 ```tsx
 // [{ importSources: ['other-lib'] }]
@@ -85,8 +89,8 @@ export const Component = styled.div``;
 
 ## Limitations
 
-- Comments are not fixable.
-- Component selectors are not fixable for `styled-components`.
+-   Comments are not fixable.
+-   Component selectors are not fixable for `styled-components`.
 
 Do not migrate to this object syntax manually, it is invalid `styled-components`.
 
@@ -106,25 +110,26 @@ Instead, style the button directly—make it clear that you're styling that butt
 ```tsx
 const buttonStyles = css({ color: 'blue' });
 const Wrapper = styled.div({
-  color: 'red',
+    color: 'red',
 });
 
 <Wrapper>
-  <button css={buttonStyles} />
+    <button css={buttonStyles} />
 </Wrapper>;
 ```
 
-If that's not feasible, you can use data attributes, but these will result in failing the UI Styling Standard around nested styles, pushing the error down the road.
+If that's not feasible, you can use data attributes, but these will result in failing the UI Styling
+Standard around nested styles, pushing the error down the road.
 
 ```tsx
 const Wrapper = styled.div({
-  color: 'red',
-  '[data-component-selector="my.button"]': {
-    color: 'blue',
-  },
+    color: 'red',
+    '[data-component-selector="my.button"]': {
+        color: 'blue',
+    },
 });
 
 <Wrapper>
-  <button data-component-selector="my.button" />
+    <button data-component-selector="my.button" />
 </Wrapper>;
 ```

package/constellation/no-unsafe-design-token-usage/usage.mdx

@@ -1,11 +1,12 @@
 # no-unsafe-design-token-usage
 
-Using design tokens in an unsafe way risks the health of the system and will effect how fast your codebase can migrate between versions.
+Using design tokens in an unsafe way risks the health of the system and will effect how fast your
+codebase can migrate between versions.
 
 ## Examples
 
-This rule will mark design token usage that is not statically and locally analyzable,
-as well as design tokens that are considered deleted.
+This rule will mark design token usage that is not statically and locally analyzable, as well as
+design tokens that are considered deleted.
 
 ## Incorrect
 
@@ -29,7 +30,7 @@ import { token } from '@atlaskit/tokens';
 css({ boxShadow: token('elevation.shadow.card') });
 
 css`
-  color: ${(token('color.text.highemphasis'), N20)};
+    color: ${(token('color.text.highemphasis'), N20)};
 `;
 ```
 
@@ -39,9 +40,9 @@ This rule comes with options to aid in migrating to design tokens.
 
 ### fallbackUsage
 
-- `forced`: Fallback values must always be provided
-- `none`: Fallback values must never be provided. (Fixer will remove is provided)
-- `optional`: Fallbacks are optional
+-   `forced`: Fallback values must always be provided
+-   `none`: Fallback values must never be provided. (Fixer will remove is provided)
+-   `optional`: Fallbacks are optional
 
 ### shouldEnforceFallbacks (deprecated)
 

package/constellation/no-unsafe-style-overrides/usage.mdx

@@ -1,8 +1,11 @@
 # no-unsafe-style-overrides
 
-Unsafe style overrides cause friction and incidents when internals of the component you're overriding change. They're inherently unbounded and everything is API that can change at a moments notice.
+Unsafe style overrides cause friction and incidents when internals of the component you're
+overriding change. They're inherently unbounded and everything is API that can change at a moments
+notice.
 
-Instead, lean on composition, primitive components, and safe style overrides via the `xcss` prop where component authors declare what styles they want to support.
+Instead, lean on composition, primitive components, and safe style overrides via the `xcss` prop
+where component authors declare what styles they want to support.
 
 ## Examples
 
@@ -33,7 +36,7 @@ import { ButtonItem } from '@atlaskit/side-navigation';
 
 ```tsx
 <Button>
-  <strong>foo</strong>
+    <strong>foo</strong>
 </Button>
 ```
 
@@ -41,9 +44,9 @@ import { ButtonItem } from '@atlaskit/side-navigation';
 const styles = css({ padding: 'var(--ds-space-100)' });
 
 <Box as="a" xcss={styles}>
-  <Stack>
-    <Inline />
-    <Inline />
-  </Stack>
+    <Stack>
+        <Inline />
+        <Inline />
+    </Stack>
 </Box>;
 ```

package/constellation/no-unsupported-drag-and-drop-libraries/usage.mdx

@@ -1,10 +1,16 @@
 # no-unsupported-drag-and-drop-libraries
 
-We encourage the use of Pragmatic drag and drop to power all drag and drop experiences - from table to external files. Pragmatic drag and drop is a performance optimised drag and drop framework that has been designed to power any drag and drop experience on any tech stack. Please avoid using alternative drag and drop libraries as it will lead to poorer performance, increased maintenance costs, (likely) worse accessibility and fragmented user experiences. See https://staging.atlassian.design/components/pragmatic-drag-and-drop/
+We encourage the use of Pragmatic drag and drop to power all drag and drop experiences - from table
+to external files. Pragmatic drag and drop is a performance optimised drag and drop framework that
+has been designed to power any drag and drop experience on any tech stack. Please avoid using
+alternative drag and drop libraries as it will lead to poorer performance, increased maintenance
+costs, (likely) worse accessibility and fragmented user experiences. See
+https://staging.atlassian.design/components/pragmatic-drag-and-drop/
 
 ## Examples
 
-Libraries such as `react-beautiful-dnd` and `@atlassian/jira-dnd` that are no longer supported, as well as external libraries such as `react-dnd` and `react-sortable-hoc`.
+Libraries such as `react-beautiful-dnd` and `@atlassian/jira-dnd` that are no longer supported, as
+well as external libraries such as `react-dnd` and `react-sortable-hoc`.
 
 ### Incorrect
 

package/constellation/prefer-primitives/usage.mdx

@@ -1,6 +1,7 @@
 # prefer-primitives
 
-Using primitives allows you to delete bespoke component code and replace it with ready made solutions made by the Atlassian Design System Team.
+Using primitives allows you to delete bespoke component code and replace it with ready made
+solutions made by the Atlassian Design System Team.
 
 ## Examples
 
@@ -26,6 +27,6 @@ This rule marks code as violations when it may be able to be replaced with a pri
 
 ```js
 <Component>
-  <Box xcss={someStyles}></Box>
+    <Box xcss={someStyles}></Box>
 </Component>
 ```

package/constellation/use-button-group-label/usage.mdx

@@ -1,10 +1,12 @@
 # use-button-group-label
 
-ButtonGroup should have an accessible name or a reference to it, so that upon opening, users of assistive technologies could have contextual information of interaction with current element.
+ButtonGroup should have an accessible name or a reference to it, so that upon opening, users of
+assistive technologies could have contextual information of interaction with current element.
 
 ## Examples
 
-This rule will indicate user with warning to strongly recommend usage of either `label` or `titleId` prop.
+This rule will indicate user with warning to strongly recommend usage of either `label` or `titleId`
+prop.
 
 ### Incorrect
 

package/constellation/use-drawer-label/usage.mdx

@@ -1,10 +1,12 @@
 # use-drawer-label
 
-Drawer should have an accessible name or a reference to it, so that upon opening, users of assistive technologies could have contextual information of interaction with current element.
+Drawer should have an accessible name or a reference to it, so that upon opening, users of assistive
+technologies could have contextual information of interaction with current element.
 
 ## Examples
 
-This rule will indicate user with warning to strongly recommend usage of either `label` or `titleId` prop.
+This rule will indicate user with warning to strongly recommend usage of either `label` or `titleId`
+prop.
 
 ### Incorrect
 

package/constellation/use-heading/usage.mdx

@@ -1,6 +1,7 @@
 # use-heading
 
-Using primitives allows you to delete bespoke component code and replace it with ready made solutions made by the Atlassian Design System Team.
+Using primitives allows you to delete bespoke component code and replace it with ready made
+solutions made by the Atlassian Design System Team.
 
 ## Examples
 
@@ -20,9 +21,11 @@ This rule marks code as violations when it can be replaced 1:1 with a heading co
 
 ```jsx
 <div>
-  <Heading size="xlarge">text</Heading>
-  <p>content</p>
+    <Heading size="xlarge">text</Heading>
+    <p>content</p>
 </div>
 ```
 
-Currently, the rule is extremely defensive, only reporting on `h1`, `h2`, `h3`, `h4`, `h5` and `h6` elements that don't have any props outside of `key`, `id` and `data-testid`. We're only targeting instances that are the first child of their siblings.
+Currently, the rule is extremely defensive, only reporting on `h1`, `h2`, `h3`, `h4`, `h5` and `h6`
+elements that don't have any props outside of `key`, `id` and `data-testid`. We're only targeting
+instances that are the first child of their siblings.

package/constellation/use-heading-level-in-spotlight-card/usage.mdx

@@ -1,6 +1,7 @@
 # use-heading-level-in-spotlight-card
 
-The `SpotlightCard` component in `@atlaskit/onboarding` will be requiring the `headingLevel` prop in future releases.
+The `SpotlightCard` component in `@atlaskit/onboarding` will be requiring the `headingLevel` prop in
+future releases.
 
 ## Examples
 
@@ -15,6 +16,6 @@ The `SpotlightCard` component in `@atlaskit/onboarding` will be requiring the `h
 
 ```tsx
 <SpotlightCard heading="Heading" headingLevel={2}>
-  Spotlight card contents
+    Spotlight card contents
 </SpotlightCard>
 ```

package/constellation/use-href-in-link-item/usage.mdx

@@ -1,6 +1,7 @@
 # use-href-in-link-item
 
-The `LinkItem` component in `@atlaskit/menu` will be requiring the `href` prop in future releases. If no valid `href` prop is required, consider using the `ButtonItem` component.
+The `LinkItem` component in `@atlaskit/menu` will be requiring the `href` prop in future releases.
+If no valid `href` prop is required, consider using the `ButtonItem` component.
 
 ## Examples
 

package/constellation/use-popup-label/usage.mdx

@@ -0,0 +1,56 @@
+# use-popup-label
+
+Popup should have an accessible name or a reference to it when `role="dialog"`, so that upon
+opening, users of assistive technologies could have contextual information of interaction with
+current element.
+
+## Examples
+
+This rule will indicate user with warning to strongly recommend usage of either `label` or `titleId`
+prop.
+
+### Incorrect
+
+```tsx
+<Popup role="dialog">
+ ^^^^^^ Missing either `label` or `titleId` prop.
+  Popup content
+</Popup>
+
+<Popup role="dialog" label>
+                     ^^^^^ `label` prop is missing value.
+  Popup content
+</Popup>
+
+<Popup role="dialog" label="">
+                     ^^^^^ `label` prop is missing accessible name value.
+  Popup content
+</Popup>
+
+<Popup role="dialog" titleId>
+                     ^^^^^^^ `titleId` prop is missing reference value.
+  <h1 id="popup-title">Popup content title</hi>
+</Popup>
+
+<Popup role="dialog" titleId="">
+                     ^^^^^^^ `titleId` prop is missing reference value.
+  <h1 id="popup-title">Popup content title</hi>
+</Popup>
+
+<Popup role="dialog" titleId="popup-title" label="">
+                     ^^^^^^^               ^^^^^ 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.
+  <h1 id="popup-title">Popup content title</hi>
+</Popup>
+```
+
+### Correct
+
+```tsx
+<Popup role="dialog" label="Popup content title">
+  Popup content
+</Popup>
+
+<Popup role="dialog" titleId="popup-title">
+  <h1 id="popup-title">Popup content title</hi>
+</Popup>
+```

package/constellation/use-primitives/usage.mdx

@@ -1,6 +1,7 @@
 # use-primitives
 
-Using primitives allows you to delete bespoke component code and replace it with ready made solutions made by the Atlassian Design System Team.
+Using primitives allows you to delete bespoke component code and replace it with ready made
+solutions made by the Atlassian Design System Team.
 
 ## Examples
 
@@ -33,45 +34,45 @@ const someStyles = xcss({
 
 Currently, the rule is extremely defensive, only reporting on `css` styles that contain:
 
-- one, and only one, style property from this list:
+-   one, and only one, style property from this list:
 
-  - padding
-  - paddingBlock
-  - paddingBlockEnd
-  - paddingBlockStart
-  - paddingBottom
-  - paddingInline
-  - paddingInlineEnd
-  - paddingInlineStart
-  - paddingLeft
-  - paddingRight
-  - paddingTop
-  - margin
-  - marginBlock
-  - marginBlockEnd
-  - marginBlockStart
-  - marginBottom
-  - marginInline
-  - marginInlineEnd
-  - marginInlineStart
-  - marginLeft
-  - marginRight
-  - marginTop
+    -   padding
+    -   paddingBlock
+    -   paddingBlockEnd
+    -   paddingBlockStart
+    -   paddingBottom
+    -   paddingInline
+    -   paddingInlineEnd
+    -   paddingInlineStart
+    -   paddingLeft
+    -   paddingRight
+    -   paddingTop
+    -   margin
+    -   marginBlock
+    -   marginBlockEnd
+    -   marginBlockStart
+    -   marginBottom
+    -   marginInline
+    -   marginInlineEnd
+    -   marginInlineStart
+    -   marginLeft
+    -   marginRight
+    -   marginTop
 
-- and where the style value is one of:
-  - 0px
-  - 2px
-  - 4px
-  - 6px
-  - 8px
-  - 12px
-  - 16px
-  - 20px
-  - 24px
-  - 32px
-  - 40px
-  - 48px
-  - 64px
-  - 80px
+-   and where the style value is one of:
+    -   0px
+    -   2px
+    -   4px
+    -   6px
+    -   8px
+    -   12px
+    -   16px
+    -   20px
+    -   24px
+    -   32px
+    -   40px
+    -   48px
+    -   64px
+    -   80px
 
 If these conditions are not met, then no violation will be reported.

package/constellation/use-primitives-text/usage.mdx

@@ -1,10 +1,12 @@
 # use-primitives-text
 
-Using primitives allows you to delete bespoke component code and replace it with ready made solutions made by the Atlassian Design System Team.
+Using primitives allows you to delete bespoke component code and replace it with ready made
+solutions made by the Atlassian Design System Team.
 
 ## Examples
 
-This rule marks code as violations when it can be replaced 1:1 with one or multiple primitive components.
+This rule marks code as violations when it can be replaced 1:1 with one or multiple primitive
+components.
 
 ### Incorrect
 
@@ -28,4 +30,6 @@ This rule marks code as violations when it can be replaced 1:1 with one or multi
 <Text as="em">text</Text>
 ```
 
-Currently, the rule is extremely defensive, only reporting on `span`, `p`, `strong` and `em` elements that don't have any props outside of `key`, `id` and `data-testid`. For `span` elements we're only targeting instances that almost certainly only have text as children.
+Currently, the rule is extremely defensive, only reporting on `span`, `p`, `strong` and `em`
+elements that don't have any props outside of `key`, `id` and `data-testid`. For `span` elements
+we're only targeting instances that almost certainly only have text as children.

package/constellation/use-tokens-space/usage.mdx

@@ -2,7 +2,9 @@
 
 ## Examples
 
-This rule marks code as violations when a space token should be used. It will auto-fix values that can be mapped 1:1 with an ADS space token. Values that can't be mapped to a token will still be reported, however no auto-fix will happen.
+This rule marks code as violations when a space token should be used. It will auto-fix values that
+can be mapped 1:1 with an ADS space token. Values that can't be mapped to a token will still be
+reported, however no auto-fix will happen.
 
 ### Incorrect
 
@@ -23,8 +25,10 @@ const someStyles = css({
 })
 ```
 
-See the list of available space tokens on the [ADS website](https://atlassian.design/foundations/spacing#space-tokens).
+See the list of available space tokens on the
+[ADS website](https://atlassian.design/foundations/spacing#space-tokens).
 
 For Atlassians:
 
-- See the [Token Migration Guide](https://go.atlassian.com/space-token-migration) for instructions on how to migrate to tokens when a suggestion is not provided by the ESLint rule.
+-   See the [Token Migration Guide](https://go.atlassian.com/space-token-migration) for instructions
+    on how to migrate to tokens when a suggestion is not provided by the ESLint rule.

package/constellation/use-tokens-typography/usage.mdx

@@ -2,14 +2,22 @@
 
 Enforces the use of design tokens for typography properties.
 
-Using design tokens results in a harmonious experience for end users whilst providing theming and consistency.
-Typography tokens are strongly recommended to further align our experiences and make future changes easier.
-
-Note: This rule is fairly defensive when it comes to replacing values with tokens. It will only run over style blocks that contain a fontSize property. It will then attempt to match that font size to a token. If multiple matching tokens are found it then tries to match on font weight. If a token can be found to match the font size but not font weight, the token is applied and then a font weight token override is applied to ensure the tokenised styles match the original. One main exception is line height - **this rule will match against tokens that have a different line height**. Letter spacing values are also ignored.
+Using design tokens results in a harmonious experience for end users whilst providing theming and
+consistency. Typography tokens are strongly recommended to further align our experiences and make
+future changes easier.
+
+Note: This rule is fairly defensive when it comes to replacing values with tokens. It will only run
+over style blocks that contain a fontSize property. It will then attempt to match that font size to
+a token. If multiple matching tokens are found it then tries to match on font weight. If a token can
+be found to match the font size but not font weight, the token is applied and then a font weight
+token override is applied to ensure the tokenised styles match the original. One main exception is
+line height - **this rule will match against tokens that have a different line height**. Letter
+spacing values are also ignored.
 
 ## Examples
 
-Using anything other than design tokens such as hardcoded values or legacy theme constants will be considered violations.
+Using anything other than design tokens such as hardcoded values or legacy theme constants will be
+considered violations.
 
 ### Incorrect
 
@@ -43,4 +51,5 @@ css({ font: token('font.body') });
 
 ## Options
 
-`shouldEnforceFallbacks`: Set to `false` to ensure token fallback values are not added. Defaults to `true`.
+`shouldEnforceFallbacks`: Set to `false` to ensure token fallback values are not added. Defaults to
+`true`.

package/constellation/use-visually-hidden/usage.mdx

@@ -1,6 +1,7 @@
 # use-visually-hidden
 
-Using the visually hidden component allows you to delete bespoke or legacy theme code and replace it with a ready made solution by the Atlassian Design System Team.
+Using the visually hidden component allows you to delete bespoke or legacy theme code and replace it
+with a ready made solution by the Atlassian Design System Team.
 
 ## Examples