@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,25 @@
1
1
  # no-unsafe-selectors
2
2
 
3
- Disallows unsafe selectors in CSS-in-JS style objects.
3
+ Blocks unsafe CSS selectors.
4
4
 
5
- This enables static analysis and prevents regressions and incidents when migrating between styling
6
- APIs.
7
-
8
- Use this rule alongside
5
+ Use alongside
9
6
  [no-nested-selectors](https://atlassian.design/components/eslint-plugin-ui-styling-standard/no-nested-selectors/usage)
10
- as the rules are complementary.
7
+ which blocks nested CSS selectors.
8
+
9
+ Blocking unsafe selectors enables static analysis and also prevents regressions and incidents when
10
+ migrating styles at scale.
11
11
 
12
12
  ## Examples
13
13
 
14
- ### Incorrect
14
+ ### Keyframes
15
+
16
+ #### Incorrect
15
17
 
16
- **No @keyframes at-rules**
18
+ Don't use `@keyframes` at-rules in styles.
17
19
 
18
- Use the `keyframes` CSS-in-JS API instead.
20
+ ```tsx
21
+ import { css } from '@compiled/react';
19
22
 
20
- ```ts
21
23
  css({
22
24
  '@keyframes fadeIn': {
23
25
  from: {
@@ -27,41 +29,102 @@ css({
27
29
  opacity: 1,
28
30
  },
29
31
  },
32
+ animation: '1s ease-in fadeIn',
30
33
  });
31
34
  ```
32
35
 
33
- **No legacy pseudo-element syntax**
36
+ #### Correct
37
+
38
+ Use the `keyframes` API.
39
+
40
+ ```tsx
41
+ import { css, keyframes } from '@compiled/react';
42
+
43
+ const fadeIn = keyframes({
44
+ from: {
45
+ opacity: 0,
46
+ },
47
+ to: {
48
+ opacity: 1,
49
+ },
50
+ });
51
+
52
+ css({
53
+ animation: `1s ease-in ${fadeIn}`,
54
+ });
55
+ ```
56
+
57
+ ### Legacy pseudo-element syntax
58
+
59
+ #### Incorrect
60
+
61
+ Don't use the legacy single colon syntax for pseudo-elements.
34
62
 
35
- Use the `::` double colon syntax for pseudo-elements.
63
+ This issue is autofixable.
36
64
 
37
- _Auto-fixer is available for this violation._
65
+ ```tsx
66
+ import { css } from '@compiled/react';
38
67
 
39
- ```ts
40
68
  css({
41
- ':after': {
69
+ '&:after': {
42
70
  content: '""',
43
- width: 100,
44
- height: 100,
45
- backgroundColor: 'red',
46
71
  },
47
72
  });
48
73
  ```
49
74
 
50
- **No increased specificity selectors**
75
+ #### Correct
51
76
 
52
- Use styles that do not require increased specificity.
77
+ Use the double colon syntax for pseudo-elements.
78
+
79
+ ```tsx
80
+ import { css } from '@compiled/react';
81
+
82
+ css({
83
+ '&::after': {
84
+ content: '""',
85
+ },
86
+ });
87
+ ```
88
+
89
+ ### Increased specificity selectors
90
+
91
+ #### Incorrect
92
+
93
+ Don't use the nesting selector to increase specificity of styles.
94
+
95
+ ```tsx
96
+ import { css } from '@compiled/react';
97
+ import { token } from '@atlaskit/tokens';
53
98
 
54
- ```ts
55
99
  css({
56
100
  '&&': {
57
- color: 'red',
101
+ color: token('color.text'),
58
102
  },
59
103
  });
60
104
  ```
61
105
 
62
- **No restricted at-rules**
106
+ #### Correct
107
+
108
+ Use styles that do not require increased specificity.
109
+
110
+ ```tsx
111
+ import { css } from '@compiled/react';
112
+ import { token } from '@atlaskit/tokens';
113
+
114
+ css({
115
+ color: token('color.text'),
116
+ });
117
+ ```
118
+
119
+ ### At-rules
120
+
121
+ #### Incorrect
122
+
123
+ Don't use at-rules in styles (see **Correct** below for exceptions).
124
+
125
+ ```tsx
126
+ import { css } from '@compiled/react';
63
127
 
64
- ```ts
65
128
  css({
66
129
  '@scope (.article-body) to (figure)': {
67
130
  img: {
@@ -71,34 +134,89 @@ css({
71
134
  });
72
135
  ```
73
136
 
74
- **No restricted pseudos**
137
+ #### Correct
138
+
139
+ Use only allowed at-rules:
140
+
141
+ - `@media` (through our
142
+ [breakpoints](https://atlassian.design/components/primitives/responsive/breakpoints/examples))
143
+ - `@property`
144
+ - `@supports`
145
+
146
+ ```tsx
147
+ import { css } from '@compiled/react';
148
+ import { media } from '@atlaskit/primitives/responsive';
149
+
150
+ css({
151
+ [media.above.sm]: {
152
+ display: 'block',
153
+ },
154
+ });
155
+ ```
156
+
157
+ ### Restricted pseudo-selectors
158
+
159
+ #### Incorrect
160
+
161
+ Don't use pseudo-classes which take arguments or implicitly rely on external context.
162
+
163
+ ```tsx
164
+ import { css } from '@compiled/react';
165
+ import { token } from '@atlaskit/tokens';
75
166
 
76
- ```ts
77
167
  css({
168
+ '&:hover': {
169
+ backgroundColor: token('color.background.neutral.hovered'),
170
+ },
171
+ '&:not(:hover)': {
172
+ backgroundColor: token('color.background.neutral'),
173
+ }
78
174
  '&:first-child': {
79
- width: 100,
175
+ fontWeight: token('font.weight.bold'),
80
176
  },
81
177
  });
82
178
  ```
83
179
 
84
- **No ambiguous pseudos**
180
+ #### Correct
85
181
 
86
- A pseudo-selector without a leading selector is ambiguous and is interpreted differently between
87
- contexts.
182
+ ```tsx
183
+ import { css } from '@compiled/react';
184
+ import { token } from '@atlaskit/tokens';
88
185
 
89
- Most CSS-in-JS libraries will implicitly add the nesting selector `&` before ambiguous
90
- pseudo-selectors. This is often the desired behavior.
186
+ type Props = { isFirstChild: boolean };
91
187
 
92
- The CSS nesting specification, CSS pre-processors, newer versions of `styled-components` (version
93
- 6+) and potentially future versions of `@emotion/*` will treat ambiguous pseudo-selectors as
94
- descendant selectors.
188
+ const baseStyles = css({
189
+ backgroundColor: token('color.background.neutral'),
190
+ '&:hover': {
191
+ backgroundColor: token('color.background.neutral.hovered'),
192
+ },
193
+ });
194
+
195
+ const firstChildStyles = css({
196
+ fontWeight: token('font.weight.bold'),
197
+ });
198
+
199
+ const Component = ({ isFirstChild }: Props) => (
200
+ <div css={[baseStyles, isFirstChild && firstChildStyles]} />
201
+ );
202
+ ```
203
+
204
+ ### Ambiguous pseudo-selectors
205
+
206
+ #### Incorrect
207
+
208
+ Don't use pseudo-selectors without a leading selector, as they are ambiguous and interpreted
209
+ differently between contexts.
210
+
211
+ For example some contexts will treat `:hover` as `&:hover` while others will treat it as `& :hover`
212
+ (which targets descendants).
95
213
 
96
- Use explicit selectors. Do not rely on implicit behavior for pseudo-selectors.
214
+ This issue is autofixable. By default a nesting selector `&` is added unless the
215
+ `shouldAlwaysInsertNestingSelectorForAmbiguousPseudos` option is disabled.
97
216
 
98
- _Auto-fixer is available for this violation. By default a nesting selector `&` is added unless the
99
- `shouldAlwaysInsertNestingSelectorForAmbiguousPseudos` option is disabled._
217
+ ```tsx
218
+ import { css } from '@compiled/react';
100
219
 
101
- ```ts
102
220
  css({
103
221
  /**
104
222
  * This pseudo-class has no leading selector and is ambiguous.
@@ -121,13 +239,24 @@ css({
121
239
  });
122
240
  ```
123
241
 
124
- **No grouped at-rules**
242
+ #### Correct
125
243
 
126
- Do not group at-rules with the `cssMap` API.
244
+ Use explicit selectors. Do not rely on implicit or undefined behavior for pseudo-selectors.
127
245
 
128
- Write flattened at-rules instead.
246
+ ```tsx
247
+
248
+ ```
249
+
250
+ ### Grouped at-rules
251
+
252
+ #### Incorrect
129
253
 
130
- ```ts
254
+ Don't group at-rules with the `cssMap` API.
255
+
256
+ ````tsx
257
+ import { cssMap } from '@compiled/react';
258
+
259
+ ```tsx
131
260
  cssMap({
132
261
  success: {
133
262
  '@media': {
@@ -136,15 +265,13 @@ cssMap({
136
265
  },
137
266
  },
138
267
  });
139
- ```
268
+ ````
140
269
 
141
- **No selectors object**
270
+ #### Correct
142
271
 
143
- Do not use a selectors object with the `cssMap` API.
144
-
145
- Refactor your styles so it is not required.
272
+ Write flattened at-rules instead.
146
273
 
147
- ```ts
274
+ ```tsx
148
275
  cssMap({
149
276
  success: {
150
277
  selectors: {
@@ -158,7 +285,7 @@ cssMap({
158
285
 
159
286
  ### Correct
160
287
 
161
- ```ts
288
+ ```tsx
162
289
  const fadeIn = keyframes({
163
290
  from: {
164
291
  opacity: 0,
@@ -173,7 +300,7 @@ css({
173
300
  });
174
301
  ```
175
302
 
176
- ```ts
303
+ ```tsx
177
304
  css({
178
305
  '::after': {
179
306
  content: '""',
@@ -184,7 +311,7 @@ css({
184
311
  });
185
312
  ```
186
313
 
187
- ```ts
314
+ ```tsx
188
315
  css({
189
316
  '&:first-of-type': {
190
317
  width: 100,
@@ -192,13 +319,13 @@ css({
192
319
  });
193
320
  ```
194
321
 
195
- ```ts
322
+ ```tsx
196
323
  css({
197
324
  '&:hover': {},
198
325
  });
199
326
  ```
200
327
 
201
- ```ts
328
+ ```tsx
202
329
  cssMap({
203
330
  success: {
204
331
  '@media (min-width: 900px)': {},
@@ -207,7 +334,7 @@ cssMap({
207
334
  });
208
335
  ```
209
336
 
210
- ```ts
337
+ ```tsx
211
338
  cssMap({
212
339
  success: {
213
340
  backgroundColor: 'white',
@@ -222,7 +349,7 @@ cssMap({
222
349
 
223
350
  ### `importSources: string[]`
224
351
 
225
- By default, this rule will check `css` usages from:
352
+ By default, this rule will check styles using:
226
353
 
227
354
  - `@atlaskit/css`
228
355
  - `@atlaskit/primitives`
@@ -232,8 +359,7 @@ By default, this rule will check `css` usages from:
232
359
  - `@emotion/styled`
233
360
  - `styled-components`
234
361
 
235
- To change this list of libraries, you can define a custom set of `importSources`, which accepts an
236
- array of package names (strings). This will override the built-in allow-list.
362
+ Override this list with the `importSources` option, which accepts an array of package names.
237
363
 
238
364
  ### `shouldAlwaysInsertNestingSelectorForAmbiguousPseudos: boolean`
239
365
 
@@ -1,14 +1,14 @@
1
1
  # no-unsafe-values
2
2
 
3
- This rule prevents the usage of styles that are difficult/impossible to statically analyze.
3
+ Blocks styles that are difficult or impossible to statically analyze.
4
4
 
5
5
  ## Examples
6
6
 
7
- ### Incorrect
7
+ ### Function calls
8
8
 
9
- **Function calls**
9
+ #### Incorrect
10
10
 
11
- Function calls are not allowed as arguments or as values, unless they are specified in
11
+ Function calls are blocked as arguments or as values, unless they are specified in
12
12
  `allowedFunctionCalls` (or in the default list).
13
13
 
14
14
  ```tsx
@@ -33,48 +33,121 @@ const styles = css({
33
33
  });
34
34
  ```
35
35
 
36
- **Dynamic keys**
36
+ #### Correct
37
37
 
38
- Dynamic keys are not allowed, unless they are specified in `allowedDynamicKeys` (or in the default
38
+ Use inline literals for static values.
39
+
40
+ ```tsx
41
+ import { css } from '@compiled/react';
42
+
43
+ const styles = css({ width: 100 });
44
+ ```
45
+
46
+ Use the `style` prop for dynamic values.
47
+
48
+ ```tsx
49
+ const Component = ({ width }) => <div style={{ width }} />;
50
+ ```
51
+
52
+ Some functions such as `tokens()` are allowed.
53
+
54
+ ```tsx
55
+ import { css } from '@compiled/react';
56
+ import { token } from '@atlaskit/tokens';
57
+
58
+ const styles = css({ padding: token('space.100') });
59
+ ```
60
+
61
+ ### Dynamic keys
62
+
63
+ #### Incorrect
64
+
65
+ Dynamic keys are blocked, unless they are specified in `allowedDynamicKeys` (or in the default
39
66
  list).
40
67
 
41
68
  ```tsx
42
69
  import { css } from '@compiled/react';
43
- import { SELECTOR } from 'my-package';
70
+
71
+ const HOVER_SELECTOR = '&:hover';
72
+ const MARGIN = 'margin';
44
73
 
45
74
  const styles = css({
46
- [SELECTOR]: {
47
- color: 'red',
75
+ [HOVER_SELECTOR]: {
76
+ [MARGIN]: 0,
48
77
  },
49
- [`${SELECTOR} > p`]: {
78
+ [`${HOVER_SELECTOR} > p`]: {
50
79
  width: 100,
51
80
  },
52
81
  });
53
82
  ```
54
83
 
55
- **Variables**
84
+ #### Correct
56
85
 
57
- Variables are not allowed as values, unless they:
86
+ Use literal values for pseudo-states and property names.
58
87
 
59
- - Have a simple, static value
60
- - Are defined in the same file
88
+ Don't use nested selectors, apply styles directly instead.
61
89
 
62
90
  ```tsx
63
91
  import { css } from '@compiled/react';
64
- import { SELECTOR } from 'my-package';
65
92
 
66
- function myFunction() {
67
- return '5px';
68
- }
93
+ const styles = css({
94
+ '&:hover': {
95
+ margin: 0,
96
+ },
97
+ });
98
+
99
+ const paragraphStyles = css({
100
+ width: 100,
101
+ });
102
+ ```
103
+
104
+ ### Variables
105
+
106
+ #### Incorrect
107
+
108
+ Variables are only allowed as values if they:
109
+
110
+ - have a simple, static value
111
+ - are defined in the same file
112
+
113
+ ```tsx
114
+ import { css } from '@compiled/react';
115
+ import { HEIGHT } from '../shared';
116
+
117
+ const styles = css({
118
+ height: HEIGHT,
119
+ });
120
+ ```
121
+
122
+ #### Correct
123
+
124
+ Use inlined values.
125
+
126
+ ```tsx
127
+ import { css } from '@compiled/react';
128
+
129
+ const styles = css({
130
+ height: '32px',
131
+ });
132
+ ```
133
+
134
+ Alternatively, define variables in the same file.
135
+
136
+ ```tsx
137
+ import { css } from '@compiled/react';
138
+
139
+ const HEIGHT = '32px';
69
140
 
70
141
  const styles = css({
71
- height: myFunction,
142
+ height: HEIGHT,
72
143
  });
73
144
  ```
74
145
 
75
- **Object access**
146
+ ### Object access
76
147
 
77
- Accessing object members is not allowed in values.
148
+ #### Incorrect
149
+
150
+ Don't access object members in values.
78
151
 
79
152
  ```tsx
80
153
  import { css } from '@compiled/react';
@@ -89,59 +162,89 @@ const styles = css({
89
162
  });
90
163
  ```
91
164
 
92
- **Spread elements**
165
+ #### Correct
93
166
 
94
- Spread elements are not allowed.
167
+ Use inlined values.
95
168
 
96
169
  ```tsx
97
170
  import { css } from '@compiled/react';
171
+ import { token } from '@atlaskit/tokens';
172
+
173
+ const styles = css({
174
+ color: token('color.text'),
175
+ });
176
+ ```
177
+
178
+ ### Spread elements
179
+
180
+ #### Incorrect
98
181
 
99
- const buttonStyles = {
100
- color: 'blue',
182
+ Don't use the spread operator in styles.
183
+
184
+ ```tsx
185
+ import { css } from '@compiled/react';
186
+ import { token } from '@atlaskit/tokens';
187
+
188
+ const subtleTextStyles = {
189
+ color: token('color.text.subtle'),
101
190
  };
102
191
 
103
192
  const styles = css({
104
- ...buttonStyles,
193
+ ...subtleTextStyles,
194
+ margin: 0,
105
195
  });
106
196
  ```
107
197
 
108
- **Array values**
198
+ #### Correct
109
199
 
110
- Array values are not allowed. This syntax is not supported by most styling libraries.
200
+ Use the `css` prop to compose styles.
111
201
 
112
202
  ```tsx
113
203
  import { css } from '@compiled/react';
204
+ import { token } from '@atlaskit/tokens';
205
+
206
+ const subtleTextStyles = {
207
+ color: token('color.text.subtle'),
208
+ };
114
209
 
115
210
  const styles = css({
116
- '::before': [{ fontWeight: 'bold' }, { color: 'red' }],
211
+ margin: 0,
117
212
  });
213
+
214
+ const Component = () => <div css={[subtleTextStyles, styles]} />;
118
215
  ```
119
216
 
120
- ### Correct
217
+ ### Array values
121
218
 
122
- Things to note about the following example:
219
+ #### Incorrect
123
220
 
124
- - The `warningStyles` are conditionally applied using the `css` prop
125
- - The dynamic `width` is applied using the `style` prop
126
- - The `token()` calls are allowed because they are statically analyzable (and in the default
127
- allow-list)
221
+ Don't use array values. This syntax is not supported by Compiled, or most other CSS-in-JS libraries.
128
222
 
129
223
  ```tsx
130
224
  import { css } from '@compiled/react';
131
225
  import { token } from '@atlaskit/tokens';
132
226
 
133
- const baseStyles = css({
134
- height: 100,
135
- });
227
+ const boldMixin = { fontWeight: token('font.weight.bold') };
136
228
 
137
- const warningStyles = css({
138
- color: token('color.text.warning'),
139
- backgroundColor: token('color.background.warning'),
229
+ const styles = css({
230
+ '&::before': [boldMixin, { color: token('color.text.danger') }],
140
231
  });
232
+ ```
141
233
 
142
- const Component = ({ isWarning, width }: { isWarning: boolean; width: number }) => {
143
- return <div style={{ width }} css={[baseStyles, isWarning && warningStyles]} />;
144
- };
234
+ #### Correct
235
+
236
+ Use a single object with inlined styles.
237
+
238
+ ```tsx
239
+ import { css } from '@compiled/react';
240
+ import { token } from '@atlaskit/tokens';
241
+
242
+ const styles = css({
243
+ '&::before': {
244
+ fontWeight: token('font.weight.bold'),
245
+ color: token('color.text.danger'),
246
+ },
247
+ });
145
248
  ```
146
249
 
147
250
  ## Options
@@ -200,9 +303,9 @@ Default imports are not currently supported.
200
303
  // ...
201
304
  ```
202
305
 
203
- ### `importSources : string[]`
306
+ ### `importSources: string[]`
204
307
 
205
- By default, this rule will check `css` usages from:
308
+ By default, this rule will check styles using:
206
309
 
207
310
  - `@atlaskit/css`
208
311
  - `@atlaskit/primitives`
@@ -212,5 +315,4 @@ By default, this rule will check `css` usages from:
212
315
  - `@emotion/styled`
213
316
  - `styled-components`
214
317
 
215
- To change this list of libraries, you can define a custom set of `importSources`, which accepts an
216
- array of package names (strings). This will override the built-in allow-list.
318
+ Override this list with the `importSources` option, which accepts an array of package names.