@atlaskit/eslint-plugin-design-system 8.27.0 → 8.28.0

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

@@ -0,0 +1,76 @@
+# no-keyframes-tagged-template-expression
+
+Disallows any `keyframes` tagged template expressions that originate from `@emotion/react`, `@emotion/core`, `compiled/react` or `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.
+
+Thank you to the [Compiled team for their rule](https://github.com/atlassian-labs/compiled/tree/master/packages/eslint-plugin/src/rules/no-keyframes-tagged-template-expression) from which this was ported.
+
+---
+
+The `--fix` option on the command line automatically fixes problems reported by this rule.
+
+## Examples
+
+### Incorrect
+
+```js
+import { keyframes } from '@compiled/react';
+
+keyframes`to { opacity: 0 }`;
+
+const fadeOut = keyframes`
+  from {
+    opacity: 1;
+  }
+  to {
+    opacity: 0;
+  }
+`;
+```
+
+### Correct
+
+```js
+import { keyframes } from '@compiled/react';
+
+keyframes({ to: { opacity: 0 } });
+
+const fadeOut = keyframes({
+  from: {
+    opacity: 1,
+  },
+  to: {
+    opacity: 0,
+  },
+});
+```
+
+## Options
+
+### importSources
+
+By default, this rule will check `keyframes` usages from:
+
+- `@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).
+
+```tsx
+// [{ importSources: ['other-lib'] }]
+
+import { keyframes } from 'other-lib';
+
+// Invalid!
+export const animation = keyframes``;
+```
+
+## Limitations
+
+- Comments are not fixable

package/constellation/no-margin/usage.mdx

@@ -0,0 +1,20 @@
+# no-margin
+
+Using margins to define spacing results in components that can't be readily reused in other contexts breaking the composition model.
+Instead defining spacing in parents with flex and grid using the `gap` property will result in more resilient experiences.
+
+## Examples
+
+This rule will mark all margin use as violations.
+
+### Incorrect
+
+```tsx
+css({ margin: '10px' });
+```
+
+### Correct
+
+```tsx
+css({ gap: token('spacing.100') });
+```

package/constellation/no-nested-styles/usage.mdx

@@ -0,0 +1,47 @@
+# no-nested-styles
+
+Disallows using nested styles. Nested styles can change unexpectedly when child markup changes and result in duplicates when extracting to CSS.
+
+## Examples
+
+This rule checks for nested styles inside `css` objects.
+This rule has no options.
+
+### Incorrect
+
+```js
+css({
+  div: {
+    color: 'red',
+  },
+});
+```
+
+```js
+css({
+  '@media (min-width: 480px)': {
+    color: 'red',
+  },
+});
+```
+
+### Correct
+
+```js
+css({
+  color: 'red',
+  ':hover': {
+    color: 'black',
+  },
+});
+```
+
+```js
+import { media } from '@atlaskit/primitives';
+
+css({
+  [media.above.xs]: {
+    color: 'red',
+  },
+});
+```

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

@@ -0,0 +1,53 @@
+# 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).
+
+## Examples
+
+This rule checks for physical property usage inside of `css` function calls.
+
+### Incorrect
+
+```js
+css({
+  left: 0,
+  right: 0,
+  top: 0,
+  bottom: 0,
+});
+```
+
+```js
+css({
+  marginLeft: 0,
+});
+```
+
+```js
+css({
+  textAlign: 'left',
+});
+```
+
+### Correct
+
+```js
+css({
+  inset: 0,
+});
+```
+
+```js
+css({
+  marginInlineStart: 0,
+});
+```
+
+```js
+css({
+  textAlign: 'start',
+});
+```

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

@@ -0,0 +1,90 @@
+# no-styled-tagged-template-expression
+
+Disallows any `styled` tagged template expressions that originate from `@emotion/react`, `@emotion/core`, `compiled/react` or `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.
+
+---
+
+The `--fix` option on the command line automatically fixes problems reported by this rule.
+
+## Examples
+
+### Incorrect
+
+```js
+import { styled } from '@compiled/react';
+
+const InlinedStyles = styled.div`
+  color: blue;
+`;
+
+const MultilineStyles = styled.div`
+  color: blue;
+  font-weight: 500;
+`;
+
+const ComposedStyles = styled(InlinedStyles)`
+  font-weight: 500;
+`;
+
+const DynamicStyles = styled.div`
+  color: ${(props) => props.color};
+  ${(props) => (props.disabled ? 'opacity: 0.8' : 'opacity: 1')}
+`;
+```
+
+### Correct
+
+```js
+import { styled } from '@compiled/react';
+
+const InlinedStyles = styled.div({
+  color: 'blue',
+});
+
+const MultilineStyles = styled.div({
+  color: 'blue',
+  fontWeight: 500,
+});
+
+const ComposedStyles = styled(InlinedStyles)({
+  fontWeight: 500,
+});
+
+const DynamicStyles = styled.div(
+  {
+    color: (props) => props.color,
+  },
+  (props) => (props.disabled ? 'opacity: 0.8' : 'opacity: 1'),
+);
+```
+
+## Options
+
+### importSources
+
+By default, this rule will check `styled` usages from:
+
+- `@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).
+
+```tsx
+// [{ importSources: ['other-lib'] }]
+
+import { styled } from 'other-lib';
+
+// Invalid!
+export const Component = styled.div``;
+```
+
+## Limitations
+
+- Comments are not fixable

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

@@ -0,0 +1,49 @@
+# 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.
+
+## Examples
+
+This rule will mark design token usage that is not statically and locally analyzable,
+as well as design tokens that are considered deleted.
+
+## Incorrect
+
+```js
+const textColor = 'red';
+
+css({ color: textColor });
+             ^^^^^^^^^ must be a string literal
+```
+
+```js
+css({ boxShadow: '0px 1px 1px var(--ds-accent-subtleBlue)' });
+                              ^^^^^^^^^^^^^^^^^^^^^^^^^^ must use the token() function
+```
+
+## Correct
+
+```js
+import { token } from '@atlaskit/tokens';
+
+css({ boxShadow: token('elevation.shadow.card') });
+
+css`
+  color: ${(token('color.text.highemphasis'), N20)};
+`;
+```
+
+## Options
+
+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
+
+### shouldEnforceFallbacks (deprecated)
+
+When `true` the rule will mark token function usage as violations when fallbacks aren't defined.
+When `false` the rule will mark token function usage as violations when fallbacks are defined.

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

@@ -0,0 +1,49 @@
+# 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.
+
+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
+
+### Incorrect
+
+```tsx
+import Button from '@atlaskit/button';
+
+<Button css={{ fontWeight: 500 }}>foo</Button>;
+        ^^^
+```
+
+```tsx
+import { LinkItem } from '@atlaskit/menu';
+
+<LinkItem cssFn={() => ({ '> div > div': { padding: 2 } })} />;
+          ^^^^^
+```
+
+```tsx
+import { ButtonItem } from '@atlaskit/side-navigation';
+
+<ButtonItem className="text-neutral-400" />;
+            ^^^^^^^^^
+```
+
+### Correct
+
+```tsx
+<Button>
+  <strong>foo</strong>
+</Button>
+```
+
+```tsx
+const styles = css({ padding: 'var(--ds-space-100)' });
+
+<Box as="a" xcss={styles}>
+  <Stack>
+    <Inline />
+    <Inline />
+  </Stack>
+</Box>;
+```

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

@@ -0,0 +1,17 @@
+# 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/
+
+## 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`.
+
+### Incorrect
+
+```ts
+import { DraggableLocation } from 'react-beautiful-dnd';
+                                   ^^^^^^^^^^^^^^^^^^^
+
+import { useDrag } from 'react-dnd'
+                         ^^^^^^^^^
+```

package/constellation/prefer-primitives/usage.mdx

@@ -0,0 +1,31 @@
+# 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.
+
+## Examples
+
+This rule marks code as violations when it may be able to be replaced with a primitive component.
+
+### Incorrect
+
+```js
+<div />
+^^^^^^^
+
+<Component>
+  <div css={someStyles}></div>
+  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+</Component>
+```
+
+### Correct
+
+```js
+<Box />
+```
+
+```js
+<Component>
+  <Box xcss={someStyles}></Box>
+</Component>
+```

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

@@ -0,0 +1,58 @@
+# 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.
+
+## Examples
+
+This rule will indicate user with warning to strongly recommend usage of either `label` or `titleId` prop.
+
+### Incorrect
+
+```tsx
+<ButtonGroup>
+ ^^^^^^^^^^^ Missing either `label` or `titleId` prop.
+  <Button>Save</Button>
+  <Button>Edit</Button>
+  <Button>Delete</Button>
+</ButtonGroup>
+
+<ButtonGroup label="">
+             ^^^^^ `label` prop is missing accessible name value.
+  <Button>Save</Button>
+  <Button>Edit</Button>
+  <Button>Delete</Button>
+</ButtonGroup>
+
+<h2 id="button-group-title">ButtonGroup content title</hi>
+<ButtonGroup titleId="">
+             ^^^^^^^ `titleId` prop is missing reference value.
+  <Button>Save</Button>
+  <Button>Edit</Button>
+  <Button>Delete</Button>
+</ButtonGroup>
+
+<h2 id="button-group-title">ButtonGroup content title</h2>
+<ButtonGroup titleId="button-group-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.
+  <Button>Save</Button>
+  <Button>Edit</Button>
+  <Button>Delete</Button>
+</ButtonGroup>
+```
+
+### Correct
+
+```tsx
+<ButtonGroup label="ButtonGroup content title">
+  <Button>Save</Button>
+  <Button>Edit</Button>
+  <Button>Delete</Button>
+</ButtonGroup>
+
+<h2 id="button-group-title">ButtonGroup content title</h2>
+<ButtonGroup titleId="button-group-title">
+  <Button>Save</Button>
+  <Button>Edit</Button>
+  <Button>Delete</Button>
+</ButtonGroup>
+```

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

@@ -0,0 +1,53 @@
+# 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.
+
+## Examples
+
+This rule will indicate user with warning to strongly recommend usage of either `label` or `titleId` prop.
+
+### Incorrect
+
+```tsx
+<Drawer>
+ ^^^^^^ Missing either `label` or `titleId` prop.
+  Drawer content
+</Drawer>
+
+<Drawer label>
+        ^^^^^ `label` prop is missing value.
+  Drawer content
+</Drawer>
+
+<Drawer label="">
+        ^^^^^ `label` prop is missing accessible name value.
+  Drawer content
+</Drawer>
+
+<Drawer titleId>
+        ^^^^^^^ `titleId` prop is missing reference value.
+  <h1 id="drawer-title">Drawer content title</hi>
+</Drawer>
+
+<Drawer titleId="">
+        ^^^^^^^ `titleId` prop is missing reference value.
+  <h1 id="drawer-title">Drawer content title</hi>
+</Drawer>
+
+<Drawer titleId="drawer-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="drawer-title">Drawer content title</hi>
+</Drawer>
+```
+
+### Correct
+
+```tsx
+<Drawer label="Drawer content title">
+  Drawer content
+</Drawer>
+
+<Drawer titleId="drawer-title">
+  <h1 id="drawer-title">Drawer content title</hi>
+</Drawer>
+```

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

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

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

@@ -0,0 +1,18 @@
+# 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.
+
+## Examples
+
+### Incorrect
+
+```tsx
+<LinkItem>Button</LinkItem>
+ ^^^^^^^^
+```
+
+### Correct
+
+```tsx
+<LinkItem href="http://example.com">Link</LinkItem>
+```

package/constellation/use-primitives/usage.mdx

@@ -0,0 +1,77 @@
+# 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.
+
+## Examples
+
+This rule marks code as violations when it can be replaced 1:1 with a primitive component.
+
+### Incorrect
+
+```jsx
+const someStyles = css({
+  padding: '8px';
+})
+
+<div css={someStyles}>
+^^^^^^^^^^^^^^^^^^^^^^
+  // ...
+</div>
+```
+
+### Correct
+
+```jsx
+const someStyles = xcss({
+  padding: 'space.100';
+})
+
+<Box xcss={someStyles}>
+  // ...
+</Box>
+```
+
+Currently, the rule is extremely defensive, only reporting on `css` styles that contain:
+
+- 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
+
+- 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-visually-hidden/usage.mdx

@@ -0,0 +1,34 @@
+# 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.
+
+## Examples
+
+This rule marks code as violations when it can be replaced 1:1 with the visually hidden component.
+
+### Incorrect
+
+```js
+import { css } from '@emotion/core';
+import { visuallyHidden } from '@atlaskit/theme/constants';
+
+const visuallyHiddenStyles = css({
+  width: '1px',
+  height: '1px',
+  padding: '0',
+  position: 'absolute',
+  border: '0',
+  clip: 'rect(1px, 1px, 1px, 1px)',
+  overflow: 'hidden',
+  whiteSpace: 'nowrap',
+});
+
+const VisuallyHidden = styled.span`${visuallyHidden()}`;
+                                     ^^^^^^^^^^^^^^
+```
+
+### Correct
+
+```js
+import VisuallyHidden from '@atlaskit/visually-hidden';
+```