@atlaskit/eslint-plugin-ui-styling-standard 0.16.3 → 0.16.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/CHANGELOG.md +8 -0
  2. package/constellation/atlaskit-theme/usage.mdx +74 -55
  3. package/constellation/convert-props-syntax/usage.mdx +29 -24
  4. package/constellation/enforce-style-prop/usage.mdx +32 -26
  5. package/constellation/local-cx-xcss/usage.mdx +27 -15
  6. package/constellation/no-array-arguments/usage.mdx +12 -9
  7. package/constellation/no-classname-prop/usage.mdx +13 -5
  8. package/constellation/no-container-queries/usage.mdx +65 -16
  9. package/constellation/no-dynamic-styles/usage.mdx +16 -11
  10. package/constellation/no-exported-styles/usage.mdx +25 -30
  11. package/constellation/no-global-styles/usage.mdx +4 -3
  12. package/constellation/no-important-styles/usage.mdx +5 -3
  13. package/constellation/no-imported-style-values/usage.mdx +30 -27
  14. package/constellation/no-nested-selectors/usage.mdx +51 -18
  15. package/constellation/no-styled/usage.mdx +17 -14
  16. package/constellation/no-unsafe-selectors/usage.mdx +184 -58
  17. package/constellation/no-unsafe-values/usage.mdx +150 -48
  18. package/constellation/use-compiled/usage.mdx +8 -8
  19. package/package.json +1 -1
  20. package/src/rules/atlaskit-theme/README.md +74 -55
  21. package/src/rules/convert-props-syntax/README.md +29 -24
  22. package/src/rules/enforce-style-prop/README.md +32 -26
  23. package/src/rules/local-cx-xcss/README.md +27 -15
  24. package/src/rules/no-array-arguments/README.md +12 -9
  25. package/src/rules/no-classname-prop/README.md +13 -5
  26. package/src/rules/no-container-queries/README.md +65 -16
  27. package/src/rules/no-dynamic-styles/README.md +16 -11
  28. package/src/rules/no-exported-styles/README.md +25 -30
  29. package/src/rules/no-global-styles/README.md +4 -3
  30. package/src/rules/no-important-styles/README.md +5 -3
  31. package/src/rules/no-imported-style-values/README.md +30 -27
  32. package/src/rules/no-nested-selectors/README.md +51 -18
  33. package/src/rules/no-styled/README.md +17 -14
  34. package/src/rules/no-unsafe-selectors/README.md +184 -58
  35. package/src/rules/no-unsafe-values/README.md +150 -48
  36. package/src/rules/use-compiled/README.md +8 -8
@@ -1,23 +1,23 @@
1
1
  # use-compiled
2
2
 
3
- Ensures usage of `@compiled/react` over other CSS-in-JS libraries like Emotion or styled-components.
3
+ Blocks CSS-in-JS libraries other than `@compiled/react`, including Emotion and styled-components.
4
4
 
5
5
  **WARNING** It may be unsafe to mix usages of `@compiled/react` with other CSS-in-JS libraries on
6
6
  the same component. When converting to `@compiled/react` verify ALL changes. For this reason, the
7
- auto-fixer has been disabled by default, but it may be useful to enable to empower a migration.
7
+ autofixer has been disabled by default, but it may be useful to enable to empower a migration.
8
8
 
9
9
  ## Examples
10
10
 
11
11
  ### Incorrect
12
12
 
13
- ```js
13
+ ```tsx
14
14
  /** @jsx jsx */
15
15
  import { css } from '@emotion/core';
16
16
  import { jsx } from '@emotion/react';
17
17
  import styled from '@emotion/styled';
18
18
  ```
19
19
 
20
- ```js
20
+ ```tsx
21
21
  import styled, { css } from 'styled-components';
22
22
  ```
23
23
 
@@ -26,7 +26,7 @@ import styled, { css } from 'styled-components';
26
26
  We expect usage of `xcss` with `@atlaskit/primitives` when working with Primitives, and `css` with
27
27
  `@compiled/react` when working with custom or native code.
28
28
 
29
- ```js
29
+ ```tsx
30
30
  /** @jsx jsx */
31
31
  import { jsx, css, styled } from '@compiled/react';
32
32
 
@@ -34,7 +34,7 @@ const styles = css({ color: 'var(--ds-color-text)' });
34
34
  export default () => <div css={styles}>…</div>;
35
35
  ```
36
36
 
37
- ```js
37
+ ```tsx
38
38
  import { xcss, Box } from '@atlaskit/primitives';
39
39
 
40
40
  const styles = xcss({ color: 'color.text' });
@@ -45,10 +45,10 @@ export default () => <Box xcss={styles}>…</Box>;
45
45
 
46
46
  ### `canAutoFix: boolean`
47
47
 
48
- Determines whether or not the auto-fixer is enabled.
48
+ Determines whether or not the autofixer is enabled.
49
49
 
50
50
  Defaults to `false` due to safety concerns when mixing Compiled and other CSS-in-JS libraries on the
51
51
  same component.
52
52
 
53
- Even when enabled, the auto-fixer will only convert usages that are deemed safe. Currently this is
53
+ Even when enabled, the autofixer will only convert usages that are deemed safe. Currently this is
54
54
  limited to purely static styles where all keys and values are simple literals.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atlaskit/eslint-plugin-ui-styling-standard",
3
- "version": "0.16.3",
3
+ "version": "0.16.4",
4
4
  "author": "Atlassian Pty Ltd",
5
5
  "description": "The eslint plugin to enforce and educate on Atlassian's UI Styling Standard",
6
6
  "license": "Apache-2.0",
@@ -1,111 +1,130 @@
1
- This rule bans certain usages of `@atlaskit/theme` that `@compiled/react` is unable to compile. This
2
- includes `typography`, `elevation` and `skeletonShimmer`.
1
+ Blocks legacy `@atlaskit/theme` mixins that `@compiled/react` cannot compile. This includes the
2
+ `typography`, `elevation` and `skeletonShimmer` mixins.
3
3
 
4
4
  ## Examples
5
5
 
6
6
  ### Typography
7
7
 
8
- Use `<Heading>` instead of `typography`.
8
+ Don't use `typography` mixins.
9
9
 
10
- 👎 Example of **incorrect** code for this rule:
10
+ Use [typography tokens](https://atlassian.design/foundations/typography-beta/applying-typography) or
11
+ the [Heading](https://atlassian.design/components/heading) and
12
+ [Text](https://atlassian.design/components/primitives/text) components.
11
13
 
12
- ```tsx
13
- import { styled } from '@compiled/react';
14
- import { typography } from '@atlaskit/theme';
15
-
16
- export const HeadingComponent = styled.h2`
17
- ${typography.h200()};
18
- `;
19
- ```
14
+ #### Incorrect
20
15
 
21
16
  ```tsx
22
- import { styled } from '@compiled/react';
17
+ import { css } from '@compiled/react';
23
18
  import { typography } from '@atlaskit/theme';
24
19
 
25
- export const HeadingComponent = styled.h2(typography.h200());
20
+ const titleStyles = css(typography.h700());
26
21
  ```
27
22
 
28
- 👍 Example of **correct** code for this rule:
23
+ #### Correct
29
24
 
30
25
  ```tsx
31
- import { styled } from '@compiled/react';
26
+ import { css } from '@compiled/react';
27
+ import { token } from '@atlaskit/tokens';
32
28
 
33
- const HeadingComponent = styled.h2({
34
- fontSize: '20px',
29
+ const titleStyles = css({
30
+ font: token('font.heading.large'),
31
+ });
32
+
33
+ const paragraphStyles = css({
34
+ font: token('font.body.large'),
35
35
  });
36
36
  ```
37
37
 
38
38
  ```tsx
39
+ import { css } from '@compiled/react';
39
40
  import Heading from '@atlaskit/heading';
41
+ import { Stack, Text } from '@atlaskit/primitives';
40
42
  import { token } from '@atlaskit/tokens';
41
- import { styled } from '@compiled/react';
42
43
 
43
- const TitleComponent = styled.span({
44
- marginTop: token('space.150', '12px'),
45
- });
46
-
47
- export const Title = (props) => (
48
- <Heading level="h200" as="h3">
49
- <TitleComponent {...props} />
50
- </Heading>
44
+ const Component = () => (
45
+ <Stack>
46
+ <Heading size="large">Title</Heading>
47
+ <Text size="large">Lorem ipsum</Text>
48
+ </Stack>
51
49
  );
52
50
  ```
53
51
 
54
52
  ### Elevation
55
53
 
56
- We don’t support this mixin, please use tokens instead.
54
+ Don't use `elevation` mixins.
55
+
56
+ Use [elevation tokens](https://atlassian.design/foundations/elevation) instead.
57
57
 
58
- 👎 Example of **incorrect** code for this rule:
58
+ #### Incorrect
59
59
 
60
60
  ```tsx
61
- import { styled } from '@compiled/react';
61
+ import { css } from '@compiled/react';
62
62
  import { elevation } from '@atlaskit/theme';
63
63
 
64
- export const ElevationComponent = styled.div`
65
- ${elevation.e100()};
66
- `;
64
+ const cardStyles = css(elevation.e100());
67
65
  ```
68
66
 
69
- 👍 Example of **correct** code for this rule:
67
+ #### Correct
70
68
 
71
69
  ```tsx
72
70
  import { styled } from '@compiled/react';
73
71
  import { token } from '@atlaskit/tokens';
74
72
 
75
- export const TestComponent = styled.div({
76
- boxShadow: token(
77
- 'elevation.shadow.raised',
78
- '0 1px 1px rgba(9,30,66,0.25),0 0 1px 1px rgba(9,30,66,0.13)',
79
- ),
73
+ const cardStyles = css({
74
+ backgroundColor: token('elevation.surface.raised'),
75
+ boxShadow: token('elevation.shadow.raised'),
80
76
  });
81
77
  ```
82
78
 
83
79
  ### Skeleton Shimmer
84
80
 
85
- You can preview our `@atlaskit/skeleton` (docs available to internal Atlassians only:
86
- [link](https://staging.atlassian.design/components/skeleton/examples)).
81
+ Don't use the `skeletonShimmer` mixin.
87
82
 
88
- Otherwise, please use an SVG skeleton or your own `@compiled/react` variant yourself.
83
+ Preview our [Skeleton](https://staging.atlassian.design/components/skeleton/examples) component
84
+ (internal Atlassians only).
89
85
 
90
- 👎 Example of **incorrect** code for this rule:
86
+ Otherwise:
87
+
88
+ - Use the `color.skeleton` and `color.skeleton.subtle` tokens to make your own component.
89
+ - Use `@atlassian/jira-skeletons` when working on Jira (internal Atlassians only).
90
+
91
+ #### Incorrect
91
92
 
92
93
  ```tsx
93
- import { styled } from '@compiled/react';
94
+ import { css } from '@compiled/react';
94
95
  import { skeletonShimmer } from '@atlaskit/theme/constants';
95
96
 
96
- export const SkeletonShimmerComponent = styled.div`
97
- ${skeletonShimmer};
98
- `;
97
+ const skeletonStyles = css(skeletonShimmer());
99
98
  ```
100
99
 
101
- 👍 Example of **correct** code for this rule:
100
+ #### Correct
101
+
102
+ ```tsx
103
+ import Skeleton from '@atlaskit/skeleton';
104
+
105
+ <Skeleton width="200px" height="16px" isShimmering />;
106
+ ```
102
107
 
103
108
  ```tsx
104
- export const SkeletonShimmerComponent = () => {
105
- return (
106
- <Wrapper>
107
- <object data="./skeleton.svg" type="image/svg+xml"></object>
108
- </Wrapper>
109
- );
110
- };
109
+ import { css, keyframes } from '@compiled/react';
110
+
111
+ const shimmer = keyframes({
112
+ from: { backgroundColor: token('color.skeleton') },
113
+ to: { backgroundColor: token('color.skeleton.subtle') },
114
+ });
115
+
116
+ const skeletonStyles = css({
117
+ backgroundColor: token('color.skeleton'),
118
+ animationName: shimmer,
119
+ animationDuration: '1.5s',
120
+ animationIterationCount: 'infinite',
121
+ animationTimingFunction: 'linear',
122
+ animationDirection: 'alternate',
123
+ });
124
+ ```
125
+
126
+ ```tsx
127
+ import { ListSkeleton } from '@atlassian/jira-skeletons';
128
+
129
+ <ListSkeleton numOfRows={3} />;
111
130
  ```
@@ -1,11 +1,16 @@
1
- Convert props syntax that are unsupported by `styled-components@<4` and `@emotion/styled` to a props
2
- syntax that is supported. This is useful when used in conjunction with
3
- `no-styled-tagged-template-expression`, as output from the latter may use props syntax that results
4
- in a type error.
1
+ Blocks dynamic styling syntax that is unsupported by `styled-components@<4` and `@emotion/styled`,
2
+ and provides an autofix for converting to a supported syntax.
5
3
 
6
- These libraries do not support having an arrow function inside a CSS value:
4
+ Use this rule alongside `no-styled-tagged-template-expression`, which can output the unsupported
5
+ dynamic styling syntax.
7
6
 
8
- ```js
7
+ This rule applies only to `styled` usages from `styled-components` and `@emotion/styled`.
8
+
9
+ ## Autofix
10
+
11
+ The autofix will find style object values that are arrow functions,
12
+
13
+ ```tsx
9
14
  styled.div({
10
15
  color: ({ myColor }) => myColor,
11
16
  backgroundColor: (props) => props.someColor,
@@ -15,7 +20,7 @@ styled.div({
15
20
  However, refactoring the arrow function so that it is the argument to `styled.div` will fix the
16
21
  issue:
17
22
 
18
- ```js
23
+ ```tsx
19
24
  styled.div((props) => ({
20
25
  color: props.myColor,
21
26
  backgroundColor: props.someColor,
@@ -38,47 +43,47 @@ manually fix the output, or migrate the code to `@compiled/react`.
38
43
  Type annotations in the arrow function are not supported; you will need to remediate the lint error
39
44
  manually. For example:
40
45
 
41
- ```js
46
+ ```tsx
42
47
  type Props = {
43
- myColor: string,
44
- someColor: string,
48
+ myColor: string;
49
+ someColor: string;
45
50
  };
46
51
 
47
52
  styled.div({
48
- color: ({ myColor }: Props) => myColor,
49
- backgroundColor: (props: Props) => props.someColor,
53
+ color: ({ myColor }: Props) => myColor,
54
+ backgroundColor: (props: Props) => props.someColor,
50
55
  });
51
56
  ```
52
57
 
53
- will need to be manually refactored to
58
+ could be refactored as
54
59
 
55
- ```js
60
+ ```tsx
56
61
  type Props = {
57
- myColor: string,
58
- someColor: string,
62
+ myColor: string;
63
+ someColor: string;
59
64
  };
60
65
 
61
66
  styled.div((props: Props) => ({
62
- color: props.myColor,
63
- backgroundColor: props.someColor,
67
+ color: props.myColor,
68
+ backgroundColor: props.someColor,
64
69
  }));
65
70
  ```
66
71
 
67
- ### Special syntax in the arrow function parameter(s)
72
+ ### Special syntax in function parameters
68
73
 
69
74
  Rest elements, default values, and so on in the parameter of an arrow function will need to be
70
75
  remediated manually. For example:
71
76
 
72
- ```js
77
+ ```tsx
73
78
  styled.div({
74
79
  color: ({ myColor = '#fff' }) => myColor,
75
80
  backgroundColor: ({ myColor = '#aaa' }) => myColor,
76
81
  });
77
82
  ```
78
83
 
79
- could potentially be remediated with
84
+ could be refactored as
80
85
 
81
- ```js
86
+ ```tsx
82
87
  styled.div((props) => ({
83
88
  color: myColor ?? '#fff',
84
89
  backgroundColor: myColor ?? '#aaa',
@@ -89,7 +94,7 @@ styled.div((props) => ({
89
94
 
90
95
  ### Incorrect
91
96
 
92
- ```js
97
+ ```tsx
93
98
  import styled from 'styled-components';
94
99
 
95
100
  styled.div({
@@ -104,7 +109,7 @@ styled.div({
104
109
 
105
110
  ### Correct
106
111
 
107
- ```js
112
+ ```tsx
108
113
  import styled from '@emotion/styled';
109
114
 
110
115
  styled.div((props) => ({
@@ -1,39 +1,45 @@
1
- This rule enforces passing dynamic CSS values to the `style` prop in JSX components.
1
+ Blocks providing static values through the `style` prop, which should only be used to provide
2
+ dynamic values (values unknown at build time).
2
3
 
3
- We only want `props.style` to be used for dynamic values that cannot be easily determined at build
4
- time, e.g. `<div style={{ width: props.width }}>`. No statics values such as numbers, strings or any
5
- other statically analysable values should be passed to the `style` attribute. Instead, static CSS
6
- values should be passed into the `css` prop in JSX components.
4
+ Use the `css` prop for providing static values instead.
7
5
 
8
6
  ## Examples
9
7
 
10
8
  ### Incorrect
11
9
 
12
10
  ```tsx
13
- function Component() {
14
- return (
15
- <div
16
- style={{
17
- margin: 0,
18
- color: 'red',
19
- }}
20
- />
21
- );
22
- }
11
+ import { token } from '@atlaskit/tokens';
12
+
13
+ const Component = () => (
14
+ <div
15
+ style={{
16
+ margin: 0,
17
+ color: token('color.text.danger'),
18
+ }}
19
+ />
20
+ );
23
21
  ```
24
22
 
25
23
  ### Correct
26
24
 
25
+ Although `token` is a function call, it is statically resolvable by Compiled and should not be used
26
+ in the `style` prop.
27
+
27
28
  ```tsx
28
- function Component(props) {
29
- return (
30
- <div
31
- style={{
32
- width: props.width,
33
- '--my-nested-width': props.width,
34
- }}
35
- css={css({ margin: 0, color: 'red' })}
36
- />
37
- );
38
- }
29
+ import { css } from '@compiled/react';
30
+ import { token } from '@atlaskit/tokens';
31
+
32
+ type Props = { width: string };
33
+
34
+ const baseStyles = css({ margin: 0, color: token('color.text.danger') });
35
+
36
+ const Component = ({ width }: Props) => (
37
+ <div
38
+ css={baseStyles}
39
+ style={{
40
+ width: props.width,
41
+ '--my-nested-width': props.width,
42
+ }}
43
+ />
44
+ );
39
45
  ```
@@ -1,23 +1,35 @@
1
- This rule ensures the `cx()` function is only used within the `xcss` prop. This aids tracking what
2
- styles are applied to a jsx element.
1
+ Blocks the `cx()` function from being used outside of the `xcss` prop. This aids tracking which
2
+ styles are applied.
3
3
 
4
- The `cx` function is checked only if it is imported from `@compiled/react` or `@atlaskit/css`.
4
+ Use the `cx()` function when passing multiple styles to the `xcss` prop. This provides more robust
5
+ type checking than the conventional array syntax:
5
6
 
6
- Passing arguments to the `cx()` function is how you compose styles (combine more than one set of
7
- styles together) with XCSS. This is a workaround for the more conventional array syntax (e.g.
8
- [in Emotion](https://emotion.sh/docs/composition)) `<div xcss={[style1, style2]} />` not giving
9
- robust enough type checking.
7
+ ```tsx
8
+ import { cssMap, cx } from '@compiled/react';
9
+ import { token } from '@atlaskit/tokens';
10
+ import { Component } from 'some-package';
11
+
12
+ const styles = cssMap({
13
+ text: { color: token('color.text') },
14
+ primary: { color: token('color.text.brand') },
15
+ });
16
+
17
+ <Component xcss={cx(isPrimary && styles.text, !isPrimary && styles.primary)} />;
18
+ ```
19
+
20
+ The `cx()` function is only checked when imported from `@compiled/react` or `@atlaskit/css`.
10
21
 
11
22
  ## Examples
12
23
 
13
24
  ### Incorrect
14
25
 
15
- ```js
16
- import { cx, cssMap } from '@compiled/react';
26
+ ```tsx
27
+ import { cssMap, cx } from '@compiled/react';
28
+ import { token } from '@atlaskit/tokens';
17
29
 
18
30
  const styles = cssMap({
19
- text: { color: 'red' },
20
- bg: { background: 'blue' },
31
+ text: { color: token('color.text') },
32
+ bg: { background: token('color.background.neutral') },
21
33
  });
22
34
 
23
35
  const joinedStyles = cx(styles.text, styles.bg);
@@ -27,12 +39,12 @@ const joinedStyles = cx(styles.text, styles.bg);
27
39
 
28
40
  ### Correct
29
41
 
30
- ```js
31
- import { cx, cssMap } from '@compiled/react';
42
+ ```tsx
43
+ import { cssMap, cx } from '@compiled/react';
32
44
 
33
45
  const styles = cssMap({
34
- text: { color: 'red' },
35
- bg: { background: 'blue' },
46
+ text: { color: token('color.text') },
47
+ bg: { background: token('color.background.neutral') },
36
48
  });
37
49
 
38
50
  <Button xcss={cx(styles.text, styles.bg)} />;
@@ -1,36 +1,40 @@
1
- This rule prevents usage of array arguments to style declaration functions.
1
+ Blocks passing array arguments to style declaration functions.
2
2
 
3
3
  ## Examples
4
4
 
5
5
  ### Incorrect
6
6
 
7
- ```js
7
+ ```tsx
8
8
  import { css } from '@compiled/react';
9
+
9
10
  const styles = css([{ width: 100 }, { height: 100 }]);
10
11
  ```
11
12
 
12
- ```js
13
+ ```tsx
13
14
  import { styled } from '@compiled/react';
15
+
14
16
  const styles = css([{ width: 100 }, ...items]);
15
17
  ```
16
18
 
17
19
  ### Correct
18
20
 
19
- ```js
21
+ ```tsx
20
22
  import { css } from '@compiled/react';
23
+
21
24
  const styles = css({ width: 100 }, { height: 100 });
22
25
  ```
23
26
 
24
- ```js
27
+ ```tsx
25
28
  import { css } from '@compiled/react';
29
+
26
30
  const styles = css({ width: 100 }, ...items);
27
31
  ```
28
32
 
29
33
  ## Options
30
34
 
31
- ### importSources
35
+ ### `importSources: string[]`
32
36
 
33
- By default, this rule will check `css` usages from:
37
+ By default, this rule will check styles using:
34
38
 
35
39
  - `@atlaskit/css`
36
40
  - `@atlaskit/primitives`
@@ -40,5 +44,4 @@ By default, this rule will check `css` usages from:
40
44
  - `@emotion/styled`
41
45
  - `styled-components`
42
46
 
43
- To change this list of libraries, you can define a custom set of `importSources`, which accepts an
44
- array of package names (strings).
47
+ Override this list with the `importSources` option, which accepts an array of package names.
@@ -1,8 +1,7 @@
1
- This rule prevents usage of the `className` prop in JSX.
1
+ Blocks the `className` prop, which encourages unsafe global styles and cannot be statically
2
+ resolved.
2
3
 
3
- Avoid `className` because it invites the use of unsafe global styles and is impossible to determine
4
- via local tooling. Use props for configuration and typical CSS-in-JS for styling or `xcss` for
5
- bounded overrides.
4
+ Use the `css` prop for styling, with props for configuration and `xcss` for bounded overrides.
6
5
 
7
6
  ## Examples
8
7
 
@@ -20,14 +19,23 @@ bounded overrides.
20
19
 
21
20
  ```tsx
22
21
  import { css } from '@compiled/react';
22
+ import { token } from '@atlaskit/tokens';
23
23
 
24
- <div css={css({ padding: '10px' })} />;
24
+ const myStyles = css({ padding: token('space.100') });
25
+
26
+ <div css={myStyles} />;
25
27
  ```
26
28
 
27
29
  ```tsx
28
30
  <MyComponent isDisabled={isDisabled} />
29
31
  ```
30
32
 
33
+ ```tsx
34
+ import { Checkbox } from '@atlaskit/checkbox';
35
+
36
+ <Checkbox xcss={{ alignItems: 'center' }} />;
37
+ ```
38
+
31
39
  ## FAQ
32
40
 
33
41
  ### What if I'm using `className` to target elements with JavaScript?