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

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @atlaskit/eslint-plugin-design-system
 
+## 10.0.0
+
+### Major Changes
+
+-   [#96329](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/96329)
+    [`16e879f9ab10`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/16e879f9ab10) -
+    Renamed the `no-html-button-element` rule to `no-html-button`. This rule is not yet in use, so
+    it should not be a breaking change. The new name reflects the broadened scope of the rule to not
+    only include `<button>` elements, but other forms of HTML buttons such as
+    `<input type="button" />` and `role="button"`.
+
+### Minor Changes
+
+-   [#97630](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/97630)
+    [`8cac5287d0c4`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/8cac5287d0c4) -
+    Adding new rule: `no-html-anchor`. This discourages usage of native HTML anchors and favors ADS
+    link components.
+
 ## 9.7.0
 
 ### Minor Changes

package/README.md

@@ -1,6 +1,7 @@
 # Design System ESLint Plugin
 
-This plugin contains rules that should be used when working with the [Atlassian Design System](https://atlassian.design).
+This plugin contains rules that should be used when working with the
+[Atlassian Design System](https://atlassian.design).
 
 ## Installation
 
@@ -20,9 +21,8 @@ module.exports = {
 };
 ```
 
-We don't recommended maintaining your own configuration.
-If you do not use our config you will need to specify individual rules and configuration.
-Add the plugin to your `.eslintrc.js` file.
+We don't recommended maintaining your own configuration. If you do not use our config you will need
+to specify individual rules and configuration. Add the plugin to your `.eslintrc.js` file.
 
 ```diff
 module.exports = {
@@ -62,7 +62,8 @@ module.exports = {
 | <a href="./src/rules/no-empty-styled-expression/README.md">no-empty-styled-expression</a>                                   | Forbids any styled expression to be used when passing empty arguments to styled.div() (or other JSX elements).                                                                                                                                                                                                      | Yes         |         |             |
 | <a href="./src/rules/no-exported-css/README.md">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.                                                                                                                                                              | Yes         |         |             |
 | <a href="./src/rules/no-exported-keyframes/README.md">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.                                                                                                                                                        | Yes         |         |             |
-| <a href="./src/rules/no-html-button-element/README.md">no-html-button-element</a>                                           | Prevent direct usage of HTML button elements and enforce usage of Button and Pressable.                                                                                                                                                                                                                             |             |         |             |
+| <a href="./src/rules/no-html-anchor/README.md">no-html-anchor</a>                                                           | Discourage direct usage of HTML anchor elements in favor of Atlassian Design System link components.                                                                                                                                                                                                                |             |         |             |
+| <a href="./src/rules/no-html-button/README.md">no-html-button</a>                                                           | Discourage direct usage of HTML button elements in favor of Atlassian Design System button components.                                                                                                                                                                                                              |             |         |             |
 | <a href="./src/rules/no-invalid-css-map/README.md">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         |         |             |
 | <a href="./src/rules/no-keyframes-tagged-template-expression/README.md">no-keyframes-tagged-template-expression</a>         | Disallows any `keyframe` tagged template expressions that originate from Emotion, Styled Components or Compiled                                                                                                                                                                                                     |             | Yes     |             |
 | <a href="./src/rules/no-margin/README.md">no-margin</a>                                                                     | Disallow using the margin CSS property.                                                                                                                                                                                                                                                                             |             |         |             |

package/constellation/consistent-css-prop-usage/usage.mdx

@@ -4,22 +4,26 @@ Ensures consistency with css prop usage.
 
 ## Rationale
 
-Every product should be defining styles in the same way, using the same tools, enforced by the same linting rules, which we can then all evolve and scale together.
+Every product should be defining styles in the same way, using the same tools, enforced by the same
+linting rules, which we can then all evolve and scale together.
 
 ## How the rule works
 
 This rule checks for the following cases:
 
-- Styles should not be defined inline; it should instead be in a standalone variable.
-  - The exception for this is style composition (e.g. `<div css={[baseStyles, moreStyles]} />`), which is a way to combine styles from two variables.
-- Styles must be wrapped in a `css` function call.
-- Styles must be defined in the same file as their usage, and not be imported.
-- Styles should not contain spread operators (e.g. `css({ ...spreadStyles })`).
-- Styles must all be defined at the top of the file, or at the bottom of the file.
+-   Styles should not be defined inline; it should instead be in a standalone variable.
+    -   The exception for this is style composition (e.g. `<div css={[baseStyles, moreStyles]} />`),
+        which is a way to combine styles from two variables.
+-   Styles must be wrapped in a `css` function call.
+-   Styles must be defined in the same file as their usage, and not be imported.
+-   Styles should not contain spread operators (e.g. `css({ ...spreadStyles })`).
+-   Styles must all be defined at the top of the file, or at the bottom of the file.
 
-This rule also has an autofixer that enforces and fixes the code (where practical) to meet the above requirements.
+This rule also has an autofixer that enforces and fixes the code (where practical) to meet the above
+requirements.
 
-All the above can also work for custom `css` functions, such as `xcss` (https://atlassian.design/components/primitives/xcss/).
+All the above can also work for custom `css` functions, such as `xcss`
+(https://atlassian.design/components/primitives/xcss/).
 
 This rule has several options - see below.
 
@@ -80,20 +84,21 @@ function Button({ children }) {
 
 ### Correct
 
-**Using the css() function to create a style object and passing it as a variable into the css={...} JSX attribute.**
+**Using the css() function to create a style object and passing it as a variable into the css={...}
+JSX attribute.**
 
 With the following options turned on:
 
-- cssFunctions = ['css']
-- stylesPlacement = 'top'
+-   cssFunctions = ['css']
+-   stylesPlacement = 'top'
 
 ```js
 const containerStyles = css({
-  zIndex: 1,
+    zIndex: 1,
 });
 
 function Button({ children }) {
-  return <button css={containerStyles}>{children}</button>;
+    return <button css={containerStyles}>{children}</button>;
 }
 ```
 
@@ -101,8 +106,8 @@ function Button({ children }) {
 
 With the following options turned on:
 
-- cssFunctions = ['css']
-- stylesPlacement = 'top'
+-   cssFunctions = ['css']
+-   stylesPlacement = 'top'
 
 ```js
 const borderStyles = cssMap({
@@ -119,22 +124,20 @@ function Button({ children }) {
 
 With the following options turned on:
 
-- cssFunctions = ['css']
-- stylesPlacement = 'bottom'
+-   cssFunctions = ['css']
+-   stylesPlacement = 'bottom'
 
 ```js
 function Button({ children }) {
-  return (
-    <button css={[baseContainerStyles, containerStyles]}>{children}</button>
-  );
+    return <button css={[baseContainerStyles, containerStyles]}>{children}</button>;
 }
 
 const baseContainerStyles = css({
-  zIndex: 5,
+    zIndex: 5,
 });
 
 const containerStyles = css({
-  zIndex: 7,
+    zIndex: 7,
 });
 ```
 
@@ -153,35 +156,46 @@ This rule comes with options to support different repository configurations.
 
 ### cssFunctions
 
-An array of function names the linting rule should target. Defaults to `['css', 'xcss']`. The functionality of `cssMap` will be linted regardless of the configuration of `cssFunctions`, as it can be used with either attribute.
+An array of function names the linting rule should target. Defaults to `['css', 'xcss']`. The
+functionality of `cssMap` will be linted regardless of the configuration of `cssFunctions`, as it
+can be used with either attribute.
 
 ### stylesPlacement
 
 Either `top` or `bottom`.
 
-The rule prevents inline styles from being created. This option defines what the error message should say: "(...) styles at the top (...)" or "(...) styles at the bottom (...)".
-Defaults to `top`.
+The rule prevents inline styles from being created. This option defines what the error message
+should say: "(...) styles at the top (...)" or "(...) styles at the bottom (...)". Defaults to
+`top`.
 
 ### cssImportSource
 
-When auto-fixing the contents of the `css` attribute, this rule will wrap CSS styles in a `css(...)` function call or `` css`...`  `` template expression, and it will add an import declaration for the `css` function. `cssImportSource` is a string that determines what package `css` should be imported from.
+When auto-fixing the contents of the `css` attribute, this rule will wrap CSS styles in a `css(...)`
+function call or ``css`...` `` template expression, and it will add an import declaration for the
+`css` function. `cssImportSource` is a string that determines what package `css` should be imported
+from.
 
 This is `@compiled/react` by default.
 
 ### xcssImportSource
 
-When auto-fixing the contents of the `xcss` attribute, this rule will wrap XCSS styles in a `xcss(...)` function call, and it will add an import declaration for the `xcss` function. `xcssImportSource` is a string that determines what package `xcss` should be imported from.
+When auto-fixing the contents of the `xcss` attribute, this rule will wrap XCSS styles in a
+`xcss(...)` function call, and it will add an import declaration for the `xcss` function.
+`xcssImportSource` is a string that determines what package `xcss` should be imported from.
 
 This is `@atlaskit/primitives` by default.
 
 ### excludeReactComponents
 
-Whether to exclude `css` attributes of React components from being affected by this ESLint rule. We assume that an element is a React component if its name starts with a capital letter, e.g. `<Button />`.
+Whether to exclude `css` attributes of React components from being affected by this ESLint rule. We
+assume that an element is a React component if its name starts with a capital letter, e.g.
+`<Button />`.
 
 This is `false` by default.
 
 ### autoFix
 
-When set to `true`, this rule will turn on the autofixer. Set this to `false` if you do not want the autofixers to run.
+When set to `true`, this rule will turn on the autofixer. Set this to `false` if you do not want the
+autofixers to run.
 
 This is `true` by default.

package/constellation/ensure-design-token-usage/usage.mdx

@@ -1,12 +1,14 @@
 # ensure-design-token-usage
 
-Using design tokens results in a harmonious experience for end users whilst providing theming and consistency.
-All experiences must use color tokens otherwise when switching between themes, unexpected incidents can occur where not all of the UI is themed.
-Space, and shape tokens are strongly recommended to further align our experiences and make future changes easier.
+Using design tokens results in a harmonious experience for end users whilst providing theming and
+consistency. All experiences must use color tokens otherwise when switching between themes,
+unexpected incidents can occur where not all of the UI is themed. Space, and shape tokens are
+strongly recommended to further align our experiences and make future changes easier.
 
 ## Examples
 
-Using anything other than design tokens such as hardcoded values or legacy theme colors will be considered violations.
+Using anything other than design tokens such as hardcoded values or legacy theme colors will be
+considered violations.
 
 ### Incorrect
 
@@ -57,15 +59,18 @@ This rule comes with options to aid in migrating to design tokens.
 
 ### domains
 
-An array specifiying which token domains to lint against (`color`, `spacing`, `shape`). Defaults to [`'color'`] if not provided.
+An array specifiying which token domains to lint against (`color`, `spacing`, `shape`). Defaults to
+[`'color'`] if not provided.
 
 ### applyImport
 
-When `true`, the rule when automatically add imports to the `@atlaskit/tokens` package where tokens are auto-fixed. Defaults to `true` if not provided.
+When `true`, the rule when automatically add imports to the `@atlaskit/tokens` package where tokens
+are auto-fixed. Defaults to `true` if not provided.
 
 ### shouldEnforceFallbacks
 
-When `true` the rule will add in stub fallbacks when choosing a suggestion in your IDE. Defaults to `false` if not provided.
+When `true` the rule will add in stub fallbacks when choosing a suggestion in your IDE. Defaults to
+`false` if not provided.
 
 ### exceptions
 

package/constellation/ensure-design-token-usage-preview/usage.mdx

@@ -1,5 +1,6 @@
 # ensure-design-token-usage/preview
 
-This rule is a clone of `ensure-design-token-usage` and is intended to allow you to set some domains to `warn` before they are set to `error` in the main rule.
+This rule is a clone of `ensure-design-token-usage` and is intended to allow you to set some domains
+to `warn` before they are set to `error` in the main rule.
 
 See `ensure-design-token-usage` for full usage documentation.

package/constellation/icon-label/usage.mdx

@@ -1,11 +1,13 @@
 # icon-label
 
-Icon labels are used to describe what the icon is so the visually impaired can be described what the UI element is.
-There are cases where icons should have labels as well as cases where they shouldn't be labelled.
+Icon labels are used to describe what the icon is so the visually impaired can be described what the
+UI element is. There are cases where icons should have labels as well as cases where they shouldn't
+be labelled.
 
 ## Examples
 
-This rule will find violations for when an icon label is or isn't needed when composed with other Design System components.
+This rule will find violations for when an icon label is or isn't needed when composed with other
+Design System components.
 
 ### Incorrect
 

package/constellation/index/usage.mdx

@@ -2,7 +2,8 @@
 order: 0
 ---
 
-This plugin contains rules that should be used when working with the [Atlassian Design System](https://atlassian.design).
+This plugin contains rules that should be used when working with the
+[Atlassian Design System](https://atlassian.design).
 
 ## Rules
 
@@ -24,7 +25,8 @@ This plugin contains rules that should be used when working with the [Atlassian
 | <a href="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).                                                                                                                                                                                                      | Yes         |         |             |
 | <a href="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.                                                                                                                                                              | Yes         |         |             |
 | <a href="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.                                                                                                                                                        | Yes         |         |             |
-| <a href="no-html-button-element/usage">no-html-button-element</a>                                           | Prevent direct usage of HTML button elements and enforce usage of Button and Pressable.                                                                                                                                                                                                                             |             |         |             |
+| <a href="no-html-anchor/usage">no-html-anchor</a>                                                           | Discourage direct usage of HTML anchor elements in favor of Atlassian Design System link components.                                                                                                                                                                                                                |             |         |             |
+| <a href="no-html-button/usage">no-html-button</a>                                                           | Discourage direct usage of HTML button elements in favor of Atlassian Design System button components.                                                                                                                                                                                                              |             |         |             |
 | <a href="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         |         |             |
 | <a href="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     |             |
 | <a href="no-margin/usage">no-margin</a>                                                                     | Disallow using the margin CSS property.                                                                                                                                                                                                                                                                             |             |         |             |

package/constellation/no-banned-imports/usage.mdx

@@ -1,6 +1,8 @@
 # no-banned-imports
 
-Using private or experimental packages is dangerous as they are not supported across major versions meaning you will not be able to migrate easily causing friction for yourself and the Atlassian Design System team.
+Using private or experimental packages is dangerous as they are not supported across major versions
+meaning you will not be able to migrate easily causing friction for yourself and the Atlassian
+Design System team.
 
 ## Examples
 

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

@@ -1,10 +1,14 @@
 # no-css-tagged-template-expression
 
-Disallows any `css` tagged template expressions that originate from a CSS-in-JS library, including `@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
+Disallows any `css` tagged template expressions that originate from a CSS-in-JS library, including
+`@atlaskit/css`, `@compiled/react`, Emotion, and `styled-components`.
 
-Tagged template expressions cannot be type safe and are difficult to parse correctly. Will auto fix ` css`` ` to the preferred `css({})` call expression syntax.
+Tagged template expressions cannot be type safe and are difficult to parse correctly. Will auto fix
+` css`` ` to the preferred `css({})` call expression syntax.
 
-Thank you to the [Compiled team for their rule](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin/src/rules/no-css-tagged-template-expression) from which this was ported.
+Thank you to the
+[Compiled team for their rule](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin/src/rules/no-css-tagged-template-expression)
+from which this was ported.
 
 ## Examples
 
@@ -14,12 +18,12 @@ Thank you to the [Compiled team for their rule](https://github.com/atlassian-lab
 import { css } from '@emotion/react';
 
 css`
-  color: blue;
+    color: blue;
 `;
 
 const styles = css`
-  color: blue;
-  font-weight: 500;
+    color: blue;
+    font-weight: 500;
 `;
 ```
 
@@ -31,8 +35,8 @@ import { css } from '@emotion/react';
 css({ color: 'blue' });
 
 const styles = css({
-  color: 'blue',
-  fontWeight: 500,
+    color: 'blue',
+    fontWeight: 500,
 });
 ```
 
@@ -42,15 +46,16 @@ const styles = css({
 
 By default, this rule will check `css` 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'] }]
@@ -63,4 +68,4 @@ export const styles = css``;
 
 ## Limitations
 
-- Comments are not auto-fixable. You will need to manually convert usages containing functions.
+-   Comments are not auto-fixable. You will need to manually convert usages containing functions.

package/constellation/no-deprecated-apis/usage.mdx

@@ -1,10 +1,12 @@
 # no-deprecated-apis
 
-Props across the Atlassian Design System can be deprecated when they are deemed no-longer fit for purporse or dangerous and risk effective use at scale.
+Props across the Atlassian Design System can be deprecated when they are deemed no-longer fit for
+purporse or dangerous and risk effective use at scale.
 
 ## Examples
 
-Anything that can be used as props from Atlassian Design System components can be violations when marked as deprecated.
+Anything that can be used as props from Atlassian Design System components can be violations when
+marked as deprecated.
 
 ### Incorrect
 
@@ -18,26 +20,28 @@ Anything that can be used as props from Atlassian Design System components can b
 
 ## Options
 
-The rule can take one option: `deprecatedConfig`,
-if not provided the rule will use an internal config.
-If provided the rule will use the passed in config instead.
+The rule can take one option: `deprecatedConfig`, if not provided the rule will use an internal
+config. If provided the rule will use the passed in config instead.
 
 ### deprecatedConfig
 
 The following fields can be defined in the config:
 
-- `deprecatedProp`, which is the deprecated props. Each prop has the following fields:
-  - `moduleSpecifier`, which is the module specifier of the package in which the prop was deprecated. For example: `@atlaskit/button`.
-  - `namedSpecifier` **(optional)**, which is an array of named specifiers of the package in which the prop was deprecated. For example: `Button`.
-  - `actionableVersion` **(optional)**, which is the version of the package in which the prop can be actioned on. For example: `1.0.0`.
+-   `deprecatedProp`, which is the deprecated props. Each prop has the following fields:
+    -   `moduleSpecifier`, which is the module specifier of the package in which the prop was
+        deprecated. For example: `@atlaskit/button`.
+    -   `namedSpecifier` **(optional)**, which is an array of named specifiers of the package in
+        which the prop was deprecated. For example: `Button`.
+    -   `actionableVersion` **(optional)**, which is the version of the package in which the prop
+        can be actioned on. For example: `1.0.0`.
 
 ```json
 {
-  "cssFn": [
-    {
-      "moduleSpecifier": "@atlaskit/menu"
-    }
-  ]
+    "cssFn": [
+        {
+            "moduleSpecifier": "@atlaskit/menu"
+        }
+    ]
 }
 ```
 
@@ -45,24 +49,26 @@ The following fields can be defined in the config:
 import { configs } from '@atlaskit/eslint-plugin-design-system';
 
 module.exports = {
-  rules: {
-    '@atlaskit/design-system/no-deprecated-api': [
-      'error',
-      {
-        deprecatedConfig: {
-          cssFn: [
+    rules: {
+        '@atlaskit/design-system/no-deprecated-api': [
+            'error',
             {
-              moduleSpecifier: '@atlaskit/menu',
+                deprecatedConfig: {
+                    cssFn: [
+                        {
+                            moduleSpecifier: '@atlaskit/menu',
+                        },
+                    ],
+                },
             },
-          ],
-        },
-      },
-    ],
-  },
+        ],
+    },
 };
 ```
 
-The plugin also provides a `filterActionableDeprecations` util function that accepts the `deprecated APIs config` and your root `package.json` as params and will filter the default deprecated APIs config based on the package versions installed.
+The plugin also provides a `filterActionableDeprecations` util function that accepts the
+`deprecated APIs config` and your root `package.json` as params and will filter the default
+deprecated APIs config based on the package versions installed.
 
 ```js
 import { configs, filterActionableDeprecations } from '@atlaskit/eslint-plugin-design-system';

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

@@ -1,7 +1,7 @@
 # no-deprecated-design-token-usage
 
-Using deprecated design tokens is dangerous as they will eventually be deleted after the sunset period.
-This rule helps you move to non-deprecated design tokens.
+Using deprecated design tokens is dangerous as they will eventually be deleted after the sunset
+period. This rule helps you move to non-deprecated design tokens.
 
 ## Examples
 
@@ -20,8 +20,11 @@ css({ color: token('i.am.a.token') });
 
 ## Options
 
-It's recommended to set this rule to "warn" to allow for new and old tokens to exist side-by-side for the duration of the deprecation period and avoid big-bang migrations.
+It's recommended to set this rule to "warn" to allow for new and old tokens to exist side-by-side
+for the duration of the deprecation period and avoid big-bang migrations.
 
-Once the deprecation period is over for a design token it will be moved into `deleted` state at which point the counterpart of this rule `no-unsafe-design-token-usage` will mark violations as errors.
+Once the deprecation period is over for a design token it will be moved into `deleted` state at
+which point the counterpart of this rule `no-unsafe-design-token-usage` will mark violations as
+errors.
 
 Running `eslint --fix` will automatically apply replacement tokens if present.

package/constellation/no-deprecated-imports/usage.mdx

@@ -1,6 +1,7 @@
 # no-deprecated-imports
 
-Packages across the Atlassian Design System can be deprecated when they are deemed no-longer fit for purporse or dangerous and risk effective use at scale.
+Packages across the Atlassian Design System can be deprecated when they are deemed no-longer fit for
+purporse or dangerous and risk effective use at scale.
 
 ## Examples
 
@@ -17,27 +18,30 @@ import GlobalNav from '@atlaskit/global-navigation';
 
 ## Options
 
-The rule can take one option: `deprecatedConfig`,
-if not provided the rule will use an internal config.
-If provided the rule will use the passed in config instead.
+The rule can take one option: `deprecatedConfig`, if not provided the rule will use an internal
+config. If provided the rule will use the passed in config instead.
 
 ### deprecatedConfig
 
 The following fields can be defined in the config:
 
-- `packagePath`, which is the name of the package. For example: `@atlaskit/navigation-next` and `@atlaskit/navigation`.
-  With the package path as the key, you can either provide the values as:
-  - `message` **(optional)**, the message to display when the deprecated packages path is used. For example: `multi-select is deprecated. Please use '@atlaskit/select' instead.`
-    Or as:
-  - `imports`, which is an array of named imports to be deprecated. Each named import has the following fields:
-    - `importName`, which is the name of the import to be deprecated. For example: `assistive` and `visuallyHidden`.
-    - `message` **(optional)**, which is the message to display when the deprecated import is used. For example: `The assistive mixin is deprecated. Please use `@atlaskit/visually-hidden` instead.`.
+-   `packagePath`, which is the name of the package. For example: `@atlaskit/navigation-next` and
+    `@atlaskit/navigation`. With the package path as the key, you can either provide the values as:
+    -   `message` **(optional)**, the message to display when the deprecated packages path is used.
+        For example: `multi-select is deprecated. Please use '@atlaskit/select' instead.` Or as:
+    -   `imports`, which is an array of named imports to be deprecated. Each named import has the
+        following fields:
+        -   `importName`, which is the name of the import to be deprecated. For example: `assistive`
+            and `visuallyHidden`.
+        -   `message` **(optional)**, which is the message to display when the deprecated import is
+            used. For example:
+            `The assistive mixin is deprecated. Please use `@atlaskit/visually-hidden` instead.`.
 
 ```json
 {
-  "@atlaskit/navigation-next": {
-    "message": "navigation-next is deprecated. Please use '@atlaskit/atlassian-navigation' instead."
-  }
+    "@atlaskit/navigation-next": {
+        "message": "navigation-next is deprecated. Please use '@atlaskit/atlassian-navigation' instead."
+    }
 }
 ```
 
@@ -45,18 +49,18 @@ The following fields can be defined in the config:
 import packageJson from './package.json';
 
 module.exports = {
-  rules: {
-    '@atlaskit/design-system/no-deprecated-imports': [
-      'error',
-      {
-        deprecatedConfig: {
-          '@atlaskit/navigation-next': {
-            message:
-              "navigation-next is deprecated. Please use '@atlaskit/atlassian-navigation' instead.",
-          },
-        },
-      },
-    ],
-  },
+    rules: {
+        '@atlaskit/design-system/no-deprecated-imports': [
+            'error',
+            {
+                deprecatedConfig: {
+                    '@atlaskit/navigation-next': {
+                        message:
+                            "navigation-next is deprecated. Please use '@atlaskit/atlassian-navigation' instead.",
+                    },
+                },
+            },
+        ],
+    },
 };
 ```