@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,12 +1,12 @@
1
1
  # no-dynamic-styles
2
2
 
3
- This rule prevents the use of dynamic styles (function expressions) in style declarations.
3
+ Blocks dynamic styles (function expressions) in style declarations.
4
4
 
5
5
  This ensures that style declarations:
6
6
 
7
7
  - are statically analyzable
8
8
  - can be efficiently extracted into atomic CSS
9
- - are more readable, deterministic, and thus easier to maintain
9
+ - are more readable and deterministic, thus easier to maintain
10
10
 
11
11
  ## Examples
12
12
 
@@ -31,14 +31,20 @@ const Component = styled.div<{ width: number }>({
31
31
  ```tsx
32
32
  import styled from 'styled-components';
33
33
 
34
- const Container = styled.div<hasPadding>({
34
+ const Container = styled.div<{ hasPadding: boolean }>({
35
35
  padding: ({ hasPadding }) => (hasPadding ? token('space.100', '8px') : token('space.0', '0px')),
36
36
  });
37
37
  ```
38
38
 
39
39
  ### Correct
40
40
 
41
- **Flags**
41
+ Define all styles statically, and dynamically apply them using the `css` prop. Use the `style` prop
42
+ for values that are only known at runtime.
43
+
44
+ For further guidance, consult our
45
+ [migration guide](https://atlassian.design/components/eslint-plugin-ui-styling-standard/migration-guide).
46
+
47
+ #### Flags
42
48
 
43
49
  If you have a style that is on/off depending on a prop, use the `css` prop to conditionally apply
44
50
  it.
@@ -54,7 +60,7 @@ const Container = ({ hasPadding = false }: { hasPadding?: boolean }) => {
54
60
  };
55
61
  ```
56
62
 
57
- **Variants**
63
+ #### Variants
58
64
 
59
65
  If you have variants which are known ahead of time, use `cssMap` to define them and the `css` prop
60
66
  to conditionally apply it.
@@ -79,7 +85,7 @@ const Wrapper = ({ appearance = 'primary' }: { appearance?: 'primary' | 'error'
79
85
  );
80
86
  ```
81
87
 
82
- **Dynamic values**
88
+ #### Dynamic values
83
89
 
84
90
  If you have styles which are truly dynamic, use the `style` prop.
85
91
 
@@ -97,7 +103,7 @@ const Component = ({ width }: { width: number }) => {
97
103
  import { css } from '@compiled/react';
98
104
 
99
105
  const containerStyles = css({
100
- '::before': {
106
+ '&::before': {
101
107
  width: 'var(--ak-example-width)',
102
108
  },
103
109
  });
@@ -109,9 +115,9 @@ function Example({ width }: { width: number }) {
109
115
 
110
116
  ## Options
111
117
 
112
- ### importSources
118
+ ### `importSources: string[]`
113
119
 
114
- By default, this rule will check usages from:
120
+ By default, this rule will check styles using:
115
121
 
116
122
  - `@atlaskit/css`
117
123
  - `@atlaskit/primitives`
@@ -121,5 +127,4 @@ By default, this rule will check usages from:
121
127
  - `@emotion/styled`
122
128
  - `styled-components`
123
129
 
124
- To change this list of libraries, you can define a custom set of `importSources`, which accepts an
125
- array of package names (strings).
130
+ Override this list with the `importSources` option, which accepts an array of package names.
@@ -1,16 +1,20 @@
1
1
  # no-exported-styles
2
2
 
3
- This rule disallows exports of `css`, `cssMap`, `keyframes`, `styled`, `xcss` styles.
3
+ Blocks exports of `css`, `cssMap`, `keyframes`, `styled`, `xcss` styles, which are unsafe.
4
4
 
5
- Exporting style declarations from these libraries may result in unexpected errors when imported,
6
- because its value will be null at runtime. Additionally, co-locating style definitions with their
7
- usage is considered best practice in order to improve code readability and build performance.
5
+ Use alongside `no-imported-style-values` which blocks consumption of imported styles.
6
+
7
+ Compiled style declarations are null at runtime, so using imported styles will cause unexpected
8
+ errors.
9
+
10
+ Co-locate style definitions with their usage instead. This will also improve code readability,
11
+ maintainability and build performance.
8
12
 
9
13
  ## Examples
10
14
 
11
15
  ### Incorrect
12
16
 
13
- ```js
17
+ ```tsx
14
18
  import { css } from '@compiled/react';
15
19
 
16
20
  export const styles = css({});
@@ -18,7 +22,7 @@ export const styles = css({});
18
22
  export default css({});
19
23
  ```
20
24
 
21
- ```js
25
+ ```tsx
22
26
  import { keyframes } from '@compiled/react';
23
27
 
24
28
  export const animation = keyframes({});
@@ -26,21 +30,12 @@ export const animation = keyframes({});
26
30
  export default keyframes({});
27
31
  ```
28
32
 
29
- Avoid exporting any style-like objects or values for consumption as well as these will violate our
30
- `no-imported-style-values` rule which blocks consumption of imported styles.
31
-
32
- ```js
33
- export default {
34
- color: 'red',
35
- margin: '0px',
36
- };
37
- ```
38
-
39
- ```js
33
+ ```tsx
40
34
  import { css } from '@compiled/react';
35
+ import { token } from '@atlaskit/tokens';
41
36
 
42
- const color = css({
43
- /* */
37
+ const colorStyles = css({
38
+ color: token('color.text'),
44
39
  });
45
40
 
46
41
  const styles = {
@@ -56,29 +51,30 @@ export default styles.primary.text.color;
56
51
 
57
52
  ### Correct
58
53
 
59
- Co-locate your styles next to your components to improve code readability, linting, and build
60
- performance.
54
+ Co-locate styles with components to improve code readability, linting, and build performance.
61
55
 
62
- ```js
56
+ ```tsx
63
57
  import { css } from '@compiled/react';
64
58
 
65
59
  const styles = css({});
66
- export const Component = ({ children }) => <div css={styles}>{children}></div>;
60
+
61
+ export const Component = () => <div css={styles} />;
67
62
  ```
68
63
 
69
- ```js
70
- import { keyframes } from '@compiled/react';
64
+ ```tsx
65
+ import { css, keyframes } from '@compiled/react';
71
66
 
72
67
  const animation = keyframes({});
73
68
  const styles = css({ animate: `${animation} 1s ease-in` });
74
- export const Component = ({ children }) => <div css={styles}>{children}></div>;
69
+
70
+ export const Component = () => <div css={styles} />;
75
71
  ```
76
72
 
77
73
  ## Options
78
74
 
79
- ### importSources
75
+ ### `importSources: string[]`
80
76
 
81
- By default, this rule will check `css` usages from:
77
+ By default, this rule will check styles using:
82
78
 
83
79
  - `@atlaskit/css`
84
80
  - `@atlaskit/primitives`
@@ -88,5 +84,4 @@ By default, this rule will check `css` usages from:
88
84
  - `@emotion/styled`
89
85
  - `styled-components`
90
86
 
91
- To change this list of libraries, you can define a custom set of `importSources`, which accepts an
92
- array of package names (strings).
87
+ Override this list with the `importSources` option, which accepts an array of package names.
@@ -1,9 +1,10 @@
1
1
  # no-global-styles
2
2
 
3
- This rule prevents global styles through CSS-in-JS or CSS module imports.
3
+ Blocks global styles through CSS-in-JS and CSS module imports.
4
4
 
5
- Requiring local definition of styles helps to ensure that style dependencies are statically
6
- resolvable.
5
+ Use local styles so that style dependencies are statically resolvable.
6
+
7
+ The only global styling that should be used is `@atlaskit/css-reset`.
7
8
 
8
9
  ## Examples
9
10
 
@@ -1,6 +1,6 @@
1
1
  # no-important-styles
2
2
 
3
- This rule prevents the usage of the `!important` flag in style declarations.
3
+ Blocks the `!important` flag in style declarations.
4
4
 
5
5
  Properly composed styles will never need an `!important` flag. It is used to override specificity
6
6
  when working across different scopes, and the UI Styling Standard enforces styles with minimal
@@ -14,9 +14,10 @@ The use of `!important` is a code smell and greatly impacts readability and dete
14
14
 
15
15
  ```js
16
16
  import { css } from '@compiled/react';
17
+ import { token } from '@atlaskit/tokens';
17
18
 
18
19
  const styles = css({
19
- color: 'red!important',
20
+ color: `${token('color.text.danger')}!important`,
20
21
  });
21
22
  ```
22
23
 
@@ -24,8 +25,9 @@ const styles = css({
24
25
 
25
26
  ```js
26
27
  import { css } from '@compiled/react';
28
+ import { token } from '@atlaskit/tokens';
27
29
 
28
30
  const styles = css({
29
- color: 'red',
31
+ color: token('color.text.danger'),
30
32
  });
31
33
  ```
@@ -1,31 +1,33 @@
1
1
  # no-imported-style-values
2
2
 
3
- This rule disallows using imported style values in `css`, `cssMap`, `styled`, `keyframes` and `xcss`
4
- calls.
3
+ Blocks imported style values in `css`, `cssMap`, `styled`, `keyframes` and `xcss` calls.
5
4
 
6
- Importing style values may result in unexpected errors when used in these APIs, because its value
7
- will be null at runtime when using `@compiled/react`. Additionally, co-locating style definitions
8
- with their usage is considered best practice in order to improve code readability and build
9
- performance.
5
+ Use alongside `no-exported-styles` which blocks exporting styles.
6
+
7
+ Compiled style declarations are null at runtime, so using imported styles will cause unexpected
8
+ errors.
9
+
10
+ Co-locate style definitions with their usage instead. This will also improve code readability and
11
+ build performance.
10
12
 
11
13
  ## Examples
12
14
 
13
15
  ### Incorrect
14
16
 
15
- ```js
17
+ ```tsx
16
18
  import { css } from '@compiled/react';
17
- import { colors, getColor } from '@mui/theme';
19
+ import { colors, getColor } from '../shared';
18
20
 
19
21
  const styles = css({
20
- [colorKey]: getColor('red'),
21
- background: colors['red'],
22
+ color: getColor('red'),
23
+ backgroundColor: colors['red'],
22
24
  });
23
25
  ```
24
26
 
25
- ```js
27
+ ```tsx
26
28
  import { css } from '@compiled/react';
27
- import { buttonStyles, cssShared, HEIGHT, colorKey } from '../shared';
28
29
  import { ff } from '@atlaskit/ff';
30
+ import { buttonStyles, cssShared, HEIGHT, colorKey } from '../shared';
29
31
 
30
32
  const sharedObject = { padding: 0 };
31
33
 
@@ -39,47 +41,49 @@ const styles = css({
39
41
 
40
42
  Importing styles to use in style composition is not allowed.
41
43
 
42
- ```js
44
+ ```tsx
43
45
  import { css } from '@compiled/react';
46
+ import { token } from '@atlaskit/tokens';
44
47
  import { buttonStyles } from '../shared';
45
48
 
46
49
  const styles = css({
47
- color: 'red',
50
+ color: token('color.text'),
48
51
  });
49
52
 
50
- export default () => <div css={[styles, buttonStyles]} />;
53
+ const Component = () => <div css={[styles, buttonStyles]} />;
51
54
  ```
52
55
 
53
56
  Importing styles to pass to the style prop is also not allowed.
54
57
 
55
- ```js
58
+ ```tsx
56
59
  import { importedWidth } from '../shared';
57
60
 
58
- export default () => <div style={{ width: importedWidth }} />;
61
+ const Component = () => <div style={{ width: importedWidth }} />;
59
62
  ```
60
63
 
61
64
  ### Correct
62
65
 
63
- Co-locate your styles next to your components to improve code readability, linting, and build
64
- performance.
66
+ Co-locate styles with components to improve code readability, linting, and build performance.
65
67
 
66
- ```js
68
+ ```tsx
67
69
  import { css } from '@compiled/react';
68
70
  import { token } from '@atlaskit/tokens';
69
71
 
70
72
  const styles = css({
71
- color: 'red',
73
+ color: token('color.text'),
72
74
  padding: token('space.150'),
73
75
  });
74
- export const Component = ({ children }) => <div css={styles}>{children}></div>;
76
+
77
+ const Component = () => <div css={styles} />;
75
78
  ```
76
79
 
77
- ```js
80
+ ```tsx
78
81
  import { keyframes } from '@compiled/react';
79
82
 
80
83
  const animation = keyframes({});
81
84
  const styles = css({ animate: `${animation} 1s ease-in` });
82
- export const Component = ({ children }) => <div css={styles}>{children}></div>;
85
+
86
+ const Component = () => <div css={styles} />;
83
87
  ```
84
88
 
85
89
  ## Options
@@ -140,7 +144,7 @@ Default imports are not currently supported.
140
144
 
141
145
  ### `importSources: string[]`
142
146
 
143
- By default, this rule will check `css` usages from:
147
+ By default, this rule will check styles using:
144
148
 
145
149
  - `@atlaskit/css`
146
150
  - `@atlaskit/primitives`
@@ -150,5 +154,4 @@ By default, this rule will check `css` usages from:
150
154
  - `@emotion/styled`
151
155
  - `styled-components`
152
156
 
153
- To change this list of libraries, you can define a custom set of `importSources`, which accepts an
154
- array of package names (strings).
157
+ Override this list with the `importSources` option, which accepts an array of package names.
@@ -1,54 +1,88 @@
1
1
  # no-nested-selectors
2
2
 
3
- This rule prevents the usage of the nested selectors in style declarations. Avoid setting styles for
4
- any child elements or elements that require context from other elements.
3
+ Blocks nested selectors in style declarations.
4
+
5
+ Use styles which do not require context from other elements.
5
6
 
6
7
  ## Examples
7
8
 
8
9
  ### Incorrect
9
10
 
10
- ```js
11
+ ```tsx
11
12
  import { css } from '@compiled/react';
13
+ import { token } from '@atlaskit/tokens';
14
+
12
15
  const styles = css({
13
16
  h2: {
14
- fontSize: '1.5rem',
17
+ font: token('font.heading.large'),
15
18
  },
16
19
  });
20
+
21
+ const Component = () => (
22
+ <div css={styles}>
23
+ <h2>Heading</h2>
24
+ </div>
25
+ );
17
26
  ```
18
27
 
19
- ```js
28
+ ```tsx
20
29
  import { styled } from '@compiled/react';
21
- const Component = styled.div({
22
- '*': {
23
- padding: 0,
30
+ import { token } from '@atlaskit/tokens';
31
+
32
+ const Table = styled.table({
33
+ border: `1px solid ${token('color.border')}`,
34
+ td: {
35
+ padding: token('space.100'),
24
36
  },
25
37
  });
26
38
  ```
27
39
 
28
- ```js
40
+ ```tsx
29
41
  import { styled } from '@compiled/react';
42
+ import { token } from '@atlaskit/tokens';
43
+
30
44
  const Component = styled.div({
31
45
  '.myclass': {
32
- padding: 0,
46
+ padding: token('space.100'),
33
47
  },
34
48
  });
35
49
  ```
36
50
 
37
51
  ### Correct
38
52
 
39
- ```js
53
+ ```tsx
40
54
  import { css } from '@compiled/react';
41
- const styles = css({
42
- display: 'flex',
43
- flexDirection: 'column',
55
+ import { token } from '@atlaskit/tokens';
56
+
57
+ const headingStyles = css({
58
+ font: token('font.heading.large'),
59
+ });
60
+
61
+ const Component = () => (
62
+ <div>
63
+ <h2 css={headingStyles}>Heading</h2>
64
+ </div>
65
+ );
66
+ ```
67
+
68
+ ```tsx
69
+ import { css } from '@compiled/react';
70
+ import { token } from '@atlaskit/tokens';
71
+
72
+ const tableStyles = css({
73
+ border: `1px solid ${token('color.border')}`,
74
+ });
75
+
76
+ const tdStyles = css({
77
+ padding: token('space.100'),
44
78
  });
45
79
  ```
46
80
 
47
81
  ## Options
48
82
 
49
- ### importSources
83
+ ### `importSources: string[]`
50
84
 
51
- By default, this rule will check `css` usages from:
85
+ By default, this rule will check styles using:
52
86
 
53
87
  - `@atlaskit/css`
54
88
  - `@atlaskit/primitives`
@@ -58,5 +92,4 @@ By default, this rule will check `css` usages from:
58
92
  - `@emotion/styled`
59
93
  - `styled-components`
60
94
 
61
- To change this list of libraries, you can define a custom set of `importSources`, which accepts an
62
- array of package names (strings).
95
+ Override this list with the `importSources` option, which accepts an array of package names.
@@ -1,8 +1,15 @@
1
1
  # no-styled
2
2
 
3
- This rule prevents usage of `styled` imports'.
3
+ Blocks the `styled` API, which creates unnecessary indirection.
4
4
 
5
- Avoid usages of styled, eg. `styled.div`, `styled('div')`, `styled(Component)`, etc.
5
+ This indirection:
6
+
7
+ - obfuscates which tag is being rendered
8
+ - adds linting complexity
9
+ - promotes exported styles
10
+ - can complicate refactoring
11
+
12
+ Use the `css` API instead. It has better performance and clarity.
6
13
 
7
14
  ## Examples
8
15
 
@@ -51,8 +58,9 @@ export default styled.div.attrs((props) => ({ 'data-testid': props.testId }))`
51
58
 
52
59
  ```tsx
53
60
  import { css, jsx } from '@emotion/react';
61
+ import { token } from '@atlaskit/tokens';
54
62
 
55
- const styles = css({ color: 'red' });
63
+ const styles = css({ color: token('color.text.subtlest') });
56
64
 
57
65
  const Component = ({ children }) => {
58
66
  return <div css={styles}>{children}</div>;
@@ -60,7 +68,6 @@ const Component = ({ children }) => {
60
68
  ```
61
69
 
62
70
  ```tsx
63
- // Using Primitives
64
71
  import { Box, xcss } from '@atlaskit/primitives';
65
72
 
66
73
  const styles = xcss({
@@ -74,16 +81,12 @@ const Component = ({ children }) => {
74
81
 
75
82
  ## FAQ
76
83
 
77
- ### Why avoid using `styled` imports?
84
+ ### How will I extend like `styled(Button)`?
78
85
 
79
- Using `styled` imports impacts file readability, has TypeScript implications, adds linting
80
- complexity, promotes exported styles, and potential refactoring efforts. Using `css()` with the
81
- `<div css={…}>` syntax is more performant and clear.
86
+ Don't modify the styles of components you don't own, unless they provide an explicit bounded
87
+ interface for doing so — such as the `xcss` prop.
82
88
 
83
- ### How will I extend like `styled(Button)`?
89
+ Use props (excluding `className` which is prohibited) to modify component styles instead.
84
90
 
85
- Primarily, we would suggest you don't extend styles of a component you don't own unless they have an
86
- explicit bounded interface for you to customize against. The Atlassian Design System for example has
87
- removed `styled(Button)` interactivity in our latest variants because they are unsafe for us to
88
- evolve the system with. Instead, make use of reusable component patterns to pass props around which
89
- impact the styles of that component.
91
+ The Atlassian Design System, for example, no longer supports `styled(Button)` because it is unsafe
92
+ for us to evolve the system with.