# Design System ESLint Plugin

This plugin contains rules that should be used when working with the
[Atlassian Design System](https://atlassian.design).

## Installation

```sh
yarn add @atlaskit/eslint-plugin-design-system -D
```

## Configuration

Use the recommended config to get reasonable defaults recommended by the Atlassian Design System:

```diff
module.exports = {
  extends: [
+    'plugin:@atlaskit/design-system/recommended',
  ],
};
```

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 `eslint.config.cjs` file.

```diff
module.exports = {
  plugins: [
+    '@atlaskit/design-system',
  ],
};
```

Enable the rules that you would like to use.

```diff
module.exports = {
  rules: [
+    '@atlaskit/design-system/no-deprecated-apis': 'error',
  ],
};
```

## Rules

<!-- START_RULE_TABLE_CODEGEN -->
<!-- @codegenCommand yarn workspace @atlaskit/eslint-plugin-design-system codegen -->

| Rule                                                                                                                          | Description                                                                                                                                                                                                                                                                                                         | Recommended | Fixable | Suggestions |
| ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------- | ----------- |
| <a href="./src/rules/consistent-css-prop-usage/README.md">consistent-css-prop-usage</a>                                       | Ensures consistency with `css` and `xcss` prop usages                                                                                                                                                                                                                                                               | Yes         | Yes     |             |
| <a href="./src/rules/enforce-inline-styles-in-select/README.md">enforce-inline-styles-in-select</a>                           | Disallow unsupported CSS selectors in styles prop for @atlaskit/select and require inline styles only                                                                                                                                                                                                               |             |         |             |
| <a href="./src/rules/ensure-avatar-tag-avatar-props/README.md">ensure-avatar-tag-avatar-props</a>                             | Ensures AvatarTag avatar prop does not include controlled props (size, borderColor, appearance) which are managed internally.                                                                                                                                                                                       | Yes         |         |             |
| <a href="./src/rules/ensure-design-token-usage/README.md">ensure-design-token-usage</a>                                       | Enforces usage of design tokens rather than hard-coded values.                                                                                                                                                                                                                                                      | Yes         | Yes     | Yes         |
| <a href="./src/rules/ensure-design-token-usage-preview/README.md">ensure-design-token-usage/preview</a>                       | Enforces usage of pre-release design tokens rather than hard-coded values.                                                                                                                                                                                                                                          |             | Yes     | Yes         |
| <a href="./src/rules/ensure-icon-color/README.md">ensure-icon-color</a>                                                       | Enforces that upcoming icon components have a color prop set, to enable a migration of the default value.                                                                                                                                                                                                           |             |         |             |
| <a href="./src/rules/ensure-proper-xcss-usage/README.md">ensure-proper-xcss-usage</a>                                         | Enforces proper xcss usage: migrate from xcss() to cssMap() and use cssMap objects with specific keys.                                                                                                                                                                                                              |             |         |             |
| <a href="./src/rules/expand-motion-shorthand/README.md">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     |             |
| <a href="./src/rules/icon-label/README.md">icon-label</a>                                                                     | Enforces accessible usage of icon labels when composed with Atlassian Design System components.                                                                                                                                                                                                                     | Yes         | Yes     |             |
| <a href="./src/rules/lozenge-badge-tag-labelling-system-migration/README.md">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     |             |
| <a href="./src/rules/no-banned-imports/README.md">no-banned-imports</a>                                                       | Disallow importing banned modules.                                                                                                                                                                                                                                                                                  | Yes         |         |             |
| <a href="./src/rules/no-css-map-scoped/README.md">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         |         |             |
| <a href="./src/rules/no-css-tagged-template-expression/README.md">no-css-tagged-template-expression</a>                       | Disallows any `css` tagged template expressions that originate from Emotion, Styled Components or Compiled                                                                                                                                                                                                          |             | Yes     |             |
| <a href="./src/rules/no-dark-theme-vr-tests/README.md">no-dark-theme-vr-tests</a>                                             | Disallow using dark colorScheme in VR tests.                                                                                                                                                                                                                                                                        |             | Yes     |             |
| <a href="./src/rules/no-deprecated-apis/README.md">no-deprecated-apis</a>                                                     | Disallow using deprecated APIs.                                                                                                                                                                                                                                                                                     | Yes         |         |             |
| <a href="./src/rules/no-deprecated-design-token-usage/README.md">no-deprecated-design-token-usage</a>                         | Disallow using deprecated design tokens.                                                                                                                                                                                                                                                                            | Yes         | Yes     |             |
| <a href="./src/rules/no-deprecated-imports/README.md">no-deprecated-imports</a>                                               | Disallow importing deprecated modules.                                                                                                                                                                                                                                                                              | Yes         | Yes     | Yes         |
| <a href="./src/rules/no-direct-use-of-web-platform-drag-and-drop/README.md">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         |         |             |
| <a href="./src/rules/no-emotion-primitives/README.md">no-emotion-primitives</a>                                               | Ensures usage of Compiled Primitives import instead of Emotion entrypoint.                                                                                                                                                                                                                                          |             | Yes     |             |
| <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).                                                                                                                                                                                                      |             |         |             |
| <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.                                                                                                                                                              |             |         |             |
| <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.                                                                                                                                                        |             |         |             |
| <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.                                                                                                                                                                                                                | Yes         |         | Yes         |
| <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.                                                                                                                                                                                                              | Yes         |         |             |
| <a href="./src/rules/no-html-checkbox/README.md">no-html-checkbox</a>                                                         | Discourage direct usage of HTML checkbox elements in favor of the Atlassian Design System checkbox component.                                                                                                                                                                                                       | Yes         |         | Yes         |
| <a href="./src/rules/no-html-code/README.md">no-html-code</a>                                                                 | Discourage direct usage of HTML code elements in favor of the Atlassian Design System code component.                                                                                                                                                                                                               | Yes         |         | Yes         |
| <a href="./src/rules/no-html-heading/README.md">no-html-heading</a>                                                           | Discourage direct usage of HTML heading elements in favor of Atlassian Design System heading components.                                                                                                                                                                                                            | Yes         |         | Yes         |
| <a href="./src/rules/no-html-image/README.md">no-html-image</a>                                                               | Discourage direct usage of HTML image elements in favor of the Atlassian Design System image component.                                                                                                                                                                                                             | Yes         |         | Yes         |
| <a href="./src/rules/no-html-radio/README.md">no-html-radio</a>                                                               | Discourage direct usage of HTML radio elements in favor of the Atlassian Design System radio component.                                                                                                                                                                                                             | Yes         |         | Yes         |
| <a href="./src/rules/no-html-range/README.md">no-html-range</a>                                                               | Discourage direct usage of HTML range elements in favor of the Atlassian Design System range component.                                                                                                                                                                                                             | Yes         |         | Yes         |
| <a href="./src/rules/no-html-select/README.md">no-html-select</a>                                                             | Discourage direct usage of HTML select elements in favor of the Atlassian Design System select component.                                                                                                                                                                                                           | Yes         |         | Yes         |
| <a href="./src/rules/no-html-text-input/README.md">no-html-text-input</a>                                                     | Discourage direct usage of HTML text input elements in favor of the Atlassian Design System textfield component.                                                                                                                                                                                                    | Yes         |         | Yes         |
| <a href="./src/rules/no-html-textarea/README.md">no-html-textarea</a>                                                         | Discourage direct usage of HTML textarea elements in favor of the Atlassian Design System textarea component.                                                                                                                                                                                                       | Yes         |         | Yes         |
| <a href="./src/rules/no-icon-spacing-prop/README.md">no-icon-spacing-prop</a>                                                 | Disallows usage of the deprecated spacing prop on new icons. Use Flex with cssMap for spacing instead.                                                                                                                                                                                                              | Yes         |         | Yes         |
| <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.                                                                                                                                                                                                                                                                             |             |         |             |
| <a href="./src/rules/no-modal-label/README.md">no-modal-label</a>                                                             | Disallows usage of the `label` prop on Atlassian Design System modal dialog and modal entry-point triggers.                                                                                                                                                                                                         | Yes         |         |             |
| <a href="./src/rules/no-nested-styles/README.md">no-nested-styles</a>                                                         | Disallows use of nested styles in `css` functions.                                                                                                                                                                                                                                                                  | Yes         |         |             |
| <a href="./src/rules/no-physical-properties/README.md">no-physical-properties</a>                                             | Disallow physical properties and values in `css` and `cssMap` function calls.                                                                                                                                                                                                                                       |             | Yes     |             |
| <a href="./src/rules/no-placeholder/README.md">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         |         |             |
| <a href="./src/rules/no-readonly-or-disabled-inputs/README.md">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         |         |             |
| <a href="./src/rules/no-separator-with-list-elements/README.md">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         |         |             |
| <a href="./src/rules/no-styled-tagged-template-expression/README.md">no-styled-tagged-template-expression</a>                 | Disallows any `styled` tagged template expressions that originate from Emotion, Styled Components or Compiled                                                                                                                                                                                                       |             | Yes     |             |
| <a href="./src/rules/no-to-match-snapshot/README.md">no-to-match-snapshot</a>                                                 | Disallow using toMatchSnapshot() and toMatchInlineSnapshot() in unit tests. Snapshot assertions should be replaced with explicit assertions.                                                                                                                                                                        |             |         |             |
| <a href="./src/rules/no-unsafe-design-token-usage/README.md">no-unsafe-design-token-usage</a>                                 | Enforces design token usage is statically and locally analyzable.                                                                                                                                                                                                                                                   | Yes         | Yes     |             |
| <a href="./src/rules/no-unsafe-inline-snapshot/README.md">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.                                                                                                                                     |             |         |             |
| <a href="./src/rules/no-unsafe-style-overrides/README.md">no-unsafe-style-overrides</a>                                       | Discourage usage of unsafe style overrides used against the Atlassian Design System.                                                                                                                                                                                                                                | Yes         |         |             |
| <a href="./src/rules/no-unsupported-drag-and-drop-libraries/README.md">no-unsupported-drag-and-drop-libraries</a>             | Disallow importing unsupported drag and drop modules.                                                                                                                                                                                                                                                               | Yes         |         |             |
| <a href="./src/rules/no-unused-css-map/README.md">no-unused-css-map</a>                                                       | Detects unused styles in cssMap objects to help keep code clean.                                                                                                                                                                                                                                                    | Yes         |         |             |
| <a href="./src/rules/prefer-primitives/README.md">prefer-primitives</a>                                                       | Increase awareness of primitive components via code hints. Strictly used for education purposes and discoverability.                                                                                                                                                                                                |             |         |             |
| <a href="./src/rules/use-button-group-label/README.md">use-button-group-label</a>                                             | Ensures button groups are described to assistive technology by a direct label or by another element.                                                                                                                                                                                                                | Yes         |         | Yes         |
| <a href="./src/rules/use-character-counter-field/README.md">use-character-counter-field</a>                                   | Suggests using CharacterCounterField or CharacterCounter when Textfield or Textarea components have maxLength or minLength props.                                                                                                                                                                                   | Yes         |         |             |
| <a href="./src/rules/use-correct-field/README.md">use-correct-field</a>                                                       | Ensure makers use appropriate field component for their respective form elements.                                                                                                                                                                                                                                   | Yes         | Yes     | Yes         |
| <a href="./src/rules/use-cx-function-in-xcss/README.md">use-cx-function-in-xcss</a>                                           | Enforces cx function use to combine styles in xcss.                                                                                                                                                                                                                                                                 | Yes         | Yes     | Yes         |
| <a href="./src/rules/use-datetime-picker-calendar-button/README.md">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         |
| <a href="./src/rules/use-drawer-label/README.md">use-drawer-label</a>                                                         | Encourages to provide accessible name for Atlassian Design System Drawer component.                                                                                                                                                                                                                                 | Yes         |         | Yes         |
| <a href="./src/rules/use-field-message-wrapper/README.md">use-field-message-wrapper</a>                                       | Encourage use of message wrapper component when using form message components.                                                                                                                                                                                                                                      | Yes         |         | Yes         |
| <a href="./src/rules/use-heading/README.md">use-heading</a>                                                                   | Encourage the usage of heading components.                                                                                                                                                                                                                                                                          | Yes         | Yes     | Yes         |
| <a href="./src/rules/use-heading-level-in-section-message/README.md">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     |             |
| <a href="./src/rules/use-heading-level-in-spotlight-card/README.md">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     |             |
| <a href="./src/rules/use-href-in-link-item/README.md">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         |
| <a href="./src/rules/use-latest-xcss-syntax/README.md">use-latest-xcss-syntax</a>                                             | Enforces usage of space design tokens rather than hard-coded values in xcss.                                                                                                                                                                                                                                        | Yes         | Yes     |             |
| <a href="./src/rules/use-latest-xcss-syntax-typography/README.md">use-latest-xcss-syntax-typography</a>                       | Prohibits use of unsafe styling properties in xcss. Please use Text/Heading primitives instead.                                                                                                                                                                                                                     | Yes         | Yes     |             |
| <a href="./src/rules/use-menu-section-title/README.md">use-menu-section-title</a>                                             | Encourages makers to provide accessible title for Atlassian Design System Menu Section component.                                                                                                                                                                                                                   | Yes         |         | Yes         |
| <a href="./src/rules/use-modal-dialog-close-button/README.md">use-modal-dialog-close-button</a>                               | Encourages makers to use close button in Atlassian Design System's modal dialog component.                                                                                                                                                                                                                          | Yes         | Yes     | Yes         |
| <a href="./src/rules/use-modal-title/README.md">use-modal-title</a>                                                           | Encourages makers to include `ModalTitle` within `ModalHeader` when using Atlassian Design System modal dialog.                                                                                                                                                                                                     | Yes         |         |             |
| <a href="./src/rules/use-onboarding-spotlight-label/README.md">use-onboarding-spotlight-label</a>                             | Ensures onboarding spotlight dialogs are described to assistive technology by a direct label or by another element.                                                                                                                                                                                                 | Yes         |         | Yes         |
| <a href="./src/rules/use-popup-label/README.md">use-popup-label</a>                                                           | Encourages to provide accessible name for Atlassian Design System Popup component.                                                                                                                                                                                                                                  | Yes         |         | Yes         |
| <a href="./src/rules/use-pressable-motion/README.md">use-pressable-motion</a>                                                 | Suggests semantic motion tokens when Pressable or native buttons change interactive colours through local static styles.                                                                                                                                                                                            |             |         | Yes         |
| <a href="./src/rules/use-primitives-text/README.md">use-primitives-text</a>                                                   | Encourage the usage of text components.                                                                                                                                                                                                                                                                             | Yes         | Yes     | Yes         |
| <a href="./src/rules/use-should-render-to-parent/README.md">use-should-render-to-parent</a>                                   | Encourages makers to use the `shouldRenderToParent` where possible in Atlassian Design System `Popup` and `DropdownMenu` components.                                                                                                                                                                                | Yes         |         | Yes         |
| <a href="./src/rules/use-simple-field/README.md">use-simple-field</a>                                                         | Encourage use of simple field for better developer experience and accessibility.                                                                                                                                                                                                                                    | Yes         |         | Yes         |
| <a href="./src/rules/use-simple-form/README.md">use-simple-form</a>                                                           | Encourage use of simple form for better developer experience and accessibility.                                                                                                                                                                                                                                     | Yes         |         | Yes         |
| <a href="./src/rules/use-spotlight-package/README.md">use-spotlight-package</a>                                               | Discourage the use of @atlaskit/onboarding in favor of @atlaskit/spotlight.                                                                                                                                                                                                                                         |             | Yes     | Yes         |
| <a href="./src/rules/use-tag-group-label/README.md">use-tag-group-label</a>                                                   | Ensures tag groups are described to assistive technology by a direct label or by another element.                                                                                                                                                                                                                   | Yes         |         | Yes         |
| <a href="./src/rules/use-textfield-autocomplete/README.md">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     |             |
| <a href="./src/rules/use-tokens-motion/README.md">use-tokens-motion</a>                                                       | Enforces usage of motion design tokens rather than hard-coded duration and easing values.                                                                                                                                                                                                                           |             |         | Yes         |
| <a href="./src/rules/use-tokens-shape/README.md">use-tokens-shape</a>                                                         | Enforces usage of shape design tokens rather than hard-coded values.                                                                                                                                                                                                                                                |             | Yes     | Yes         |
| <a href="./src/rules/use-tokens-space/README.md">use-tokens-space</a>                                                         | Enforces usage of space design tokens rather than hard-coded values.                                                                                                                                                                                                                                                |             | Yes     | Yes         |
| <a href="./src/rules/use-tokens-typography/README.md">use-tokens-typography</a>                                               | Enforces usage of design tokens for typography properties rather than hard-coded values.                                                                                                                                                                                                                            | Yes         | Yes     | Yes         |
| <a href="./src/rules/use-visually-hidden/README.md">use-visually-hidden</a>                                                   | Enforce usage of the visually hidden component.                                                                                                                                                                                                                                                                     | Yes         | Yes     |             |

<!-- END_RULE_TABLE_CODEGEN -->