@atlaskit/eslint-plugin-ui-styling-standard 0.11.5 → 0.12.0
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.
- package/CHANGELOG.md +17 -0
- package/README.md +11 -7
- package/constellation/atlaskit-theme/usage.mdx +113 -0
- package/constellation/convert-props-syntax/usage.mdx +32 -22
- package/constellation/enforce-style-prop/usage.mdx +21 -18
- package/constellation/index/overview.mdx +92 -76
- package/constellation/local-cx-xcss/usage.mdx +10 -6
- package/constellation/no-array-arguments/usage.mdx +10 -9
- package/constellation/no-classname-prop/usage.mdx +7 -4
- package/constellation/no-container-queries/usage.mdx +17 -15
- package/constellation/no-dynamic-styles/usage.mdx +26 -29
- package/constellation/no-exported-styles/usage.mdx +23 -18
- package/constellation/no-important-styles/usage.mdx +5 -3
- package/constellation/no-imported-style-values/usage.mdx +30 -22
- package/constellation/no-nested-selectors/usage.mdx +22 -20
- package/constellation/no-unsafe-values/usage.mdx +45 -51
- package/constellation/use-compiled/usage.mdx +51 -0
- package/dist/cjs/index.codegen.js +1 -1
- package/dist/cjs/presets/all.codegen.js +3 -1
- package/dist/cjs/presets/recommended.codegen.js +3 -1
- package/dist/cjs/rules/atlaskit-theme/index.js +95 -0
- package/dist/cjs/rules/index.codegen.js +6 -2
- package/dist/cjs/rules/use-compiled/index.js +257 -0
- package/dist/cjs/rules/use-compiled/is-safe.js +130 -0
- package/dist/cjs/rules/use-compiled/utils.js +26 -0
- package/dist/es2019/index.codegen.js +1 -1
- package/dist/es2019/presets/all.codegen.js +3 -1
- package/dist/es2019/presets/recommended.codegen.js +3 -1
- package/dist/es2019/rules/atlaskit-theme/index.js +85 -0
- package/dist/es2019/rules/index.codegen.js +6 -2
- package/dist/es2019/rules/use-compiled/index.js +182 -0
- package/dist/es2019/rules/use-compiled/is-safe.js +118 -0
- package/dist/es2019/rules/use-compiled/utils.js +15 -0
- package/dist/esm/index.codegen.js +1 -1
- package/dist/esm/presets/all.codegen.js +3 -1
- package/dist/esm/presets/recommended.codegen.js +3 -1
- package/dist/esm/rules/atlaskit-theme/index.js +89 -0
- package/dist/esm/rules/index.codegen.js +6 -2
- package/dist/esm/rules/use-compiled/index.js +250 -0
- package/dist/esm/rules/use-compiled/is-safe.js +121 -0
- package/dist/esm/rules/use-compiled/utils.js +17 -0
- package/dist/types/index.codegen.d.ts +4 -0
- package/dist/types/presets/all.codegen.d.ts +3 -1
- package/dist/types/presets/recommended.codegen.d.ts +3 -1
- package/dist/types/rules/atlaskit-theme/index.d.ts +3 -0
- package/dist/types/rules/index.codegen.d.ts +2 -0
- package/dist/types/rules/use-compiled/index.d.ts +3 -0
- package/dist/types/rules/use-compiled/is-safe.d.ts +10 -0
- package/dist/types/rules/use-compiled/utils.d.ts +6 -0
- package/dist/types-ts4.5/index.codegen.d.ts +4 -0
- package/dist/types-ts4.5/presets/all.codegen.d.ts +3 -1
- package/dist/types-ts4.5/presets/recommended.codegen.d.ts +3 -1
- package/dist/types-ts4.5/rules/atlaskit-theme/index.d.ts +3 -0
- package/dist/types-ts4.5/rules/index.codegen.d.ts +2 -0
- package/dist/types-ts4.5/rules/use-compiled/index.d.ts +3 -0
- package/dist/types-ts4.5/rules/use-compiled/is-safe.d.ts +10 -0
- package/dist/types-ts4.5/rules/use-compiled/utils.d.ts +6 -0
- package/package.json +3 -2
- package/src/index.codegen.tsx +3 -3
- package/src/presets/all.codegen.tsx +67 -69
- package/src/presets/recommended.codegen.tsx +67 -69
- package/src/rules/atlaskit-theme/README.md +109 -0
- package/src/rules/atlaskit-theme/__tests__/test.ts +122 -0
- package/src/rules/atlaskit-theme/index.ts +136 -0
- package/src/rules/index.codegen.tsx +17 -13
- package/src/rules/use-compiled/README.md +49 -0
- package/src/rules/use-compiled/__tests__/can-auto-fix.test.tsx +73 -0
- package/src/rules/use-compiled/__tests__/css.test.tsx +126 -0
- package/src/rules/use-compiled/__tests__/imports.test.tsx +139 -0
- package/src/rules/use-compiled/__tests__/keyframes.test.tsx +140 -0
- package/src/rules/use-compiled/__tests__/pragma.test.tsx +108 -0
- package/src/rules/use-compiled/__tests__/styled.test.tsx +114 -0
- package/src/rules/use-compiled/__tests__/use-compiled.test.tsx +15 -0
- package/src/rules/use-compiled/index.tsx +275 -0
- package/src/rules/use-compiled/is-safe.tsx +163 -0
- package/src/rules/use-compiled/utils.tsx +37 -0
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,22 @@
|
|
|
1
1
|
# @atlaskit/eslint-plugin-ui-styling-standard
|
|
2
2
|
|
|
3
|
+
## 0.12.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- [#96162](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/96162)
|
|
8
|
+
[`d68864c620d0`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/d68864c620d0) -
|
|
9
|
+
Add `use-compiled` rule to enforce usage of `@compiled/react` instead of other CSS-in-JS
|
|
10
|
+
libraries
|
|
11
|
+
|
|
12
|
+
## 0.11.6
|
|
13
|
+
|
|
14
|
+
### Patch Changes
|
|
15
|
+
|
|
16
|
+
- [#97707](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/97707)
|
|
17
|
+
[`764c0805b3c1`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/764c0805b3c1) -
|
|
18
|
+
Moved compiled/atlaskit-theme eslint rule to UI styling standard
|
|
19
|
+
|
|
3
20
|
## 0.11.5
|
|
4
21
|
|
|
5
22
|
### Patch Changes
|
package/README.md
CHANGED
|
@@ -1,13 +1,15 @@
|
|
|
1
1
|
# UI Styling Standard ESLint Plugin
|
|
2
2
|
|
|
3
|
-
The UI Styling Standard is a set of principles to guide styling UI code across Atlassian's frontend
|
|
3
|
+
The UI Styling Standard is a set of principles to guide styling UI code across Atlassian's frontend
|
|
4
|
+
codebases and ecosystem.
|
|
4
5
|
|
|
5
|
-
These are the current ESLint rules that enforce and help comply with the UI Styling Standard today,
|
|
6
|
+
These are the current ESLint rules that enforce and help comply with the UI Styling Standard today,
|
|
7
|
+
but more are planned to support the standard over time.
|
|
6
8
|
|
|
7
9
|
## Installation
|
|
8
10
|
|
|
9
|
-
You must use the recommended config to follow the styling standards at Atlassian,
|
|
10
|
-
|
|
11
|
+
You must use the recommended config to follow the styling standards at Atlassian, which will ensure
|
|
12
|
+
compatability and performance with the design system.
|
|
11
13
|
|
|
12
14
|
```diff
|
|
13
15
|
module.exports = {
|
|
@@ -17,9 +19,9 @@ module.exports = {
|
|
|
17
19
|
};
|
|
18
20
|
```
|
|
19
21
|
|
|
20
|
-
We don't recommended maintaining your own configuration.
|
|
21
|
-
|
|
22
|
-
|
|
22
|
+
We don't recommended maintaining your own configuration. If you do not use our config you will need
|
|
23
|
+
to specify individual rules and configuration. Add the plugin to your `.eslintrc.js` file and enable
|
|
24
|
+
individual rules as you're ready to adopt.
|
|
23
25
|
|
|
24
26
|
```diff
|
|
25
27
|
module.exports = {
|
|
@@ -40,6 +42,7 @@ module.exports = {
|
|
|
40
42
|
|
|
41
43
|
| Rule | Description | Recommended | Fixable | Suggestions |
|
|
42
44
|
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------- | ----------- |
|
|
45
|
+
| <a href="./src/rules/atlaskit-theme/README.md">atlaskit-theme</a> | Ban certain usages of `@atlaskit/theme` that `@compiled/react` does not understand | Yes | | |
|
|
43
46
|
| <a href="./src/rules/convert-props-syntax/README.md">convert-props-syntax</a> | Convert props syntax that is unsupported by styled-components@<4 or @emotion/styled to props syntax that is supported. This is useful when used in conjunction with `no-styled-tagged-template-expression`, as output from the latter may use props syntax unsupported by those libraries. | Yes | Yes | |
|
|
44
47
|
| <a href="./src/rules/enforce-style-prop/README.md">enforce-style-prop</a> | Disallows usage of static styles in the `style` attribute in components | Yes | | |
|
|
45
48
|
| <a href="./src/rules/local-cx-xcss/README.md">local-cx-xcss</a> | Ensures the cx() function, which is part of the XCSS API, is only used within the xcss prop. This aids tracking what styles are applied to a jsx element. | Yes | | |
|
|
@@ -52,6 +55,7 @@ module.exports = {
|
|
|
52
55
|
| <a href="./src/rules/no-imported-style-values/README.md">no-imported-style-values</a> | Disallows imports of style values | Yes | | |
|
|
53
56
|
| <a href="./src/rules/no-nested-selectors/README.md">no-nested-selectors</a> | Prevents usage of nested selectors within css styling | Yes | | |
|
|
54
57
|
| <a href="./src/rules/no-unsafe-values/README.md">no-unsafe-values</a> | Disallows styles that are difficult/impossible to statically anaylze. | Yes | | |
|
|
58
|
+
| <a href="./src/rules/use-compiled/README.md">use-compiled</a> | Ensures usage of `@compiled/react` instead of other CSS-in-JS libraries | Yes | Yes | |
|
|
55
59
|
| <a href="https://atlassian.design/components/eslint-plugin-ui-styling-standard/consistent-css-prop-usage/usage">@atlaskit/design-system/consistent-css-prop-usage</a> | Ensures consistency with `css` and `xcss` prop usages | Yes | Yes | |
|
|
56
60
|
| <a href="https://atlassian.design/components/eslint-plugin-ui-styling-standard/no-css-tagged-template-expression/usage">@atlaskit/design-system/no-css-tagged-template-expression</a> | Disallows any `css` tagged template expressions that originate from Emotion, Styled Components or Compiled | Yes | Yes | |
|
|
57
61
|
| <a href="https://atlassian.design/components/eslint-plugin-ui-styling-standard/no-keyframes-tagged-template-expression/usage">@atlaskit/design-system/no-keyframes-tagged-template-expression</a> | Disallows any `keyframe` tagged template expressions that originate from Emotion, Styled Components or Compiled | Yes | Yes | |
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# atlaskit-theme
|
|
2
|
+
|
|
3
|
+
This rule bans certain usages of `@atlaskit/theme` that `@compiled/react` is unable to compile. This
|
|
4
|
+
includes `typography`, `elevation` and `skeletonShimmer`.
|
|
5
|
+
|
|
6
|
+
## Examples
|
|
7
|
+
|
|
8
|
+
### Typography
|
|
9
|
+
|
|
10
|
+
Use `<Heading>` instead of `typography`.
|
|
11
|
+
|
|
12
|
+
👎 Example of **incorrect** code for this rule:
|
|
13
|
+
|
|
14
|
+
```tsx
|
|
15
|
+
import { styled } from '@compiled/react';
|
|
16
|
+
import { typography } from '@atlaskit/theme';
|
|
17
|
+
|
|
18
|
+
export const HeadingComponent = styled.h2`
|
|
19
|
+
${typography.h200()};
|
|
20
|
+
`;
|
|
21
|
+
```
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
import { styled } from '@compiled/react';
|
|
25
|
+
import { typography } from '@atlaskit/theme';
|
|
26
|
+
|
|
27
|
+
export const HeadingComponent = styled.h2(typography.h200());
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
👍 Example of **correct** code for this rule:
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
import { styled } from '@compiled/react';
|
|
34
|
+
|
|
35
|
+
const HeadingComponent = styled.h2({
|
|
36
|
+
fontSize: '20px',
|
|
37
|
+
});
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
```tsx
|
|
41
|
+
import Heading from '@atlaskit/heading';
|
|
42
|
+
import { token } from '@atlaskit/tokens';
|
|
43
|
+
import { styled } from '@compiled/react';
|
|
44
|
+
|
|
45
|
+
const TitleComponent = styled.span({
|
|
46
|
+
marginTop: token('space.150', '12px'),
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
export const Title = (props) => (
|
|
50
|
+
<Heading level="h200" as="h3">
|
|
51
|
+
<TitleComponent {...props} />
|
|
52
|
+
</Heading>
|
|
53
|
+
);
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Elevation
|
|
57
|
+
|
|
58
|
+
We don’t support this mixin, please use tokens instead.
|
|
59
|
+
|
|
60
|
+
👎 Example of **incorrect** code for this rule:
|
|
61
|
+
|
|
62
|
+
```tsx
|
|
63
|
+
import { styled } from '@compiled/react';
|
|
64
|
+
import { elevation } from '@atlaskit/theme';
|
|
65
|
+
|
|
66
|
+
export const ElevationComponent = styled.div`
|
|
67
|
+
${elevation.e100()};
|
|
68
|
+
`;
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
👍 Example of **correct** code for this rule:
|
|
72
|
+
|
|
73
|
+
```tsx
|
|
74
|
+
import { styled } from '@compiled/react';
|
|
75
|
+
import { token } from '@atlaskit/tokens';
|
|
76
|
+
|
|
77
|
+
export const TestComponent = styled.div({
|
|
78
|
+
boxShadow: token(
|
|
79
|
+
'elevation.shadow.raised',
|
|
80
|
+
'0 1px 1px rgba(9,30,66,0.25),0 0 1px 1px rgba(9,30,66,0.13)',
|
|
81
|
+
),
|
|
82
|
+
});
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
### Skeleton Shimmer
|
|
86
|
+
|
|
87
|
+
You can preview our `@atlaskit/skeleton` (docs available to internal Atlassians only:
|
|
88
|
+
[link](https://staging.atlassian.design/components/skeleton/examples)).
|
|
89
|
+
|
|
90
|
+
Otherwise, please use an SVG skeleton or your own `@compiled/react` variant yourself.
|
|
91
|
+
|
|
92
|
+
👎 Example of **incorrect** code for this rule:
|
|
93
|
+
|
|
94
|
+
```tsx
|
|
95
|
+
import { styled } from '@compiled/react';
|
|
96
|
+
import { skeletonShimmer } from '@atlaskit/theme/constants';
|
|
97
|
+
|
|
98
|
+
export const SkeletonShimmerComponent = styled.div`
|
|
99
|
+
${skeletonShimmer};
|
|
100
|
+
`;
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
👍 Example of **correct** code for this rule:
|
|
104
|
+
|
|
105
|
+
```tsx
|
|
106
|
+
export const SkeletonShimmerComponent = () => {
|
|
107
|
+
return (
|
|
108
|
+
<Wrapper>
|
|
109
|
+
<object data="./skeleton.svg" type="image/svg+xml"></object>
|
|
110
|
+
</Wrapper>
|
|
111
|
+
);
|
|
112
|
+
};
|
|
113
|
+
```
|
|
@@ -1,36 +1,44 @@
|
|
|
1
1
|
# convert-props-syntax
|
|
2
2
|
|
|
3
|
-
Convert props syntax that are unsupported by `styled-components@<4` and `@emotion/styled` to a props
|
|
3
|
+
Convert props syntax that are unsupported by `styled-components@<4` and `@emotion/styled` to a props
|
|
4
|
+
syntax that is supported. This is useful when used in conjunction with
|
|
5
|
+
`no-styled-tagged-template-expression`, as output from the latter may use props syntax that results
|
|
6
|
+
in a type error.
|
|
4
7
|
|
|
5
8
|
These libraries do not support having an arrow function inside a CSS value:
|
|
6
9
|
|
|
7
10
|
```js
|
|
8
11
|
styled.div({
|
|
9
|
-
|
|
10
|
-
|
|
12
|
+
color: ({ myColor }) => myColor,
|
|
13
|
+
backgroundColor: (props) => props.someColor,
|
|
11
14
|
});
|
|
12
15
|
```
|
|
13
16
|
|
|
14
|
-
However, refactoring the arrow function so that it is the argument to `styled.div` will fix the
|
|
17
|
+
However, refactoring the arrow function so that it is the argument to `styled.div` will fix the
|
|
18
|
+
issue:
|
|
15
19
|
|
|
16
20
|
```js
|
|
17
21
|
styled.div((props) => ({
|
|
18
|
-
|
|
19
|
-
|
|
22
|
+
color: props.myColor,
|
|
23
|
+
backgroundColor: props.someColor,
|
|
20
24
|
}));
|
|
21
25
|
```
|
|
22
26
|
|
|
23
|
-
This ESLint rule will only run on usages of the `styled` API when imported from libraries that are
|
|
27
|
+
This ESLint rule will only run on usages of the `styled` API when imported from libraries that are
|
|
28
|
+
known to have this problem.
|
|
24
29
|
|
|
25
30
|
## About the autofixer
|
|
26
31
|
|
|
27
|
-
This rule has an autofixer that will automatically perform the above arrow function refactoring for
|
|
32
|
+
This rule has an autofixer that will automatically perform the above arrow function refactoring for
|
|
33
|
+
the majority of cases, including for nested selectors and any props used in template literal values.
|
|
28
34
|
|
|
29
|
-
However, there are a few situations where the autofixer will not be run. For these, you will need to
|
|
35
|
+
However, there are a few situations where the autofixer will not be run. For these, you will need to
|
|
36
|
+
manually fix the output, or migrate the code to `@compiled/react`.
|
|
30
37
|
|
|
31
38
|
### Type annotations
|
|
32
39
|
|
|
33
|
-
Type annotations in the arrow function are not supported; you will need to remediate the lint error
|
|
40
|
+
Type annotations in the arrow function are not supported; you will need to remediate the lint error
|
|
41
|
+
manually. For example:
|
|
34
42
|
|
|
35
43
|
```js
|
|
36
44
|
type Props = {
|
|
@@ -60,12 +68,13 @@ styled.div((props: Props) => ({
|
|
|
60
68
|
|
|
61
69
|
### Special syntax in the arrow function parameter(s)
|
|
62
70
|
|
|
63
|
-
Rest elements, default values, and so on in the parameter of an arrow function will need to be
|
|
71
|
+
Rest elements, default values, and so on in the parameter of an arrow function will need to be
|
|
72
|
+
remediated manually. For example:
|
|
64
73
|
|
|
65
74
|
```js
|
|
66
75
|
styled.div({
|
|
67
|
-
|
|
68
|
-
|
|
76
|
+
color: ({ myColor = '#fff' }) => myColor,
|
|
77
|
+
backgroundColor: ({ myColor = '#aaa' }) => myColor,
|
|
69
78
|
});
|
|
70
79
|
```
|
|
71
80
|
|
|
@@ -73,8 +82,8 @@ could potentially be remediated with
|
|
|
73
82
|
|
|
74
83
|
```js
|
|
75
84
|
styled.div((props) => ({
|
|
76
|
-
|
|
77
|
-
|
|
85
|
+
color: myColor ?? '#fff',
|
|
86
|
+
backgroundColor: myColor ?? '#aaa',
|
|
78
87
|
}));
|
|
79
88
|
```
|
|
80
89
|
|
|
@@ -86,12 +95,12 @@ styled.div((props) => ({
|
|
|
86
95
|
import styled from 'styled-components';
|
|
87
96
|
|
|
88
97
|
styled.div({
|
|
89
|
-
|
|
90
|
-
|
|
98
|
+
color: ({ myColor }) => myColor,
|
|
99
|
+
backgroundColor: (props) => props.someColor,
|
|
91
100
|
});
|
|
92
101
|
|
|
93
102
|
styled.div({
|
|
94
|
-
|
|
103
|
+
color: `url(/tmp/${({ coolProp }) => coolProp}.png)`,
|
|
95
104
|
});
|
|
96
105
|
```
|
|
97
106
|
|
|
@@ -101,15 +110,16 @@ styled.div({
|
|
|
101
110
|
import styled from '@emotion/styled';
|
|
102
111
|
|
|
103
112
|
styled.div((props) => ({
|
|
104
|
-
|
|
105
|
-
|
|
113
|
+
color: props.myColor,
|
|
114
|
+
backgroundColor: props.someColor,
|
|
106
115
|
}));
|
|
107
116
|
|
|
108
117
|
styled.div((props) => ({
|
|
109
|
-
|
|
118
|
+
color: url(`/tmp/${coolProp}.png`),
|
|
110
119
|
}));
|
|
111
120
|
```
|
|
112
121
|
|
|
113
122
|
## When not to use it
|
|
114
123
|
|
|
115
|
-
You do not need this rule if you are not using a codebase that has a violating library as it will
|
|
124
|
+
You do not need this rule if you are not using a codebase that has a violating library as it will
|
|
125
|
+
never do anything.
|
|
@@ -2,7 +2,10 @@
|
|
|
2
2
|
|
|
3
3
|
This rule enforces passing dynamic CSS values to the `style` prop in JSX components.
|
|
4
4
|
|
|
5
|
-
We only want `props.style` to be used for dynamic values that cannot be easily determined at build
|
|
5
|
+
We only want `props.style` to be used for dynamic values that cannot be easily determined at build
|
|
6
|
+
time, e.g. `<div style={{ width: props.width }}>`. No statics values such as numbers, strings or any
|
|
7
|
+
other statically analysable values should be passed to the `style` attribute. Instead, static CSS
|
|
8
|
+
values should be passed into the `css` prop in JSX components.
|
|
6
9
|
|
|
7
10
|
## Examples
|
|
8
11
|
|
|
@@ -10,14 +13,14 @@ We only want `props.style` to be used for dynamic values that cannot be easily d
|
|
|
10
13
|
|
|
11
14
|
```tsx
|
|
12
15
|
function Component() {
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
16
|
+
return (
|
|
17
|
+
<div
|
|
18
|
+
style={{
|
|
19
|
+
margin: 0,
|
|
20
|
+
color: 'red',
|
|
21
|
+
}}
|
|
22
|
+
/>
|
|
23
|
+
);
|
|
21
24
|
}
|
|
22
25
|
```
|
|
23
26
|
|
|
@@ -25,14 +28,14 @@ function Component() {
|
|
|
25
28
|
|
|
26
29
|
```tsx
|
|
27
30
|
function Component(props) {
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
31
|
+
return (
|
|
32
|
+
<div
|
|
33
|
+
style={{
|
|
34
|
+
width: props.width,
|
|
35
|
+
'--my-nested-width': props.width,
|
|
36
|
+
}}
|
|
37
|
+
css={css({ margin: 0, color: 'red' })}
|
|
38
|
+
/>
|
|
39
|
+
);
|
|
37
40
|
}
|
|
38
41
|
```
|
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
The UI Styling Standard is a set of principles to guide styling UI code
|
|
2
|
-
|
|
1
|
+
The UI Styling Standard is a set of principles to guide styling UI code across Atlassian's frontend
|
|
2
|
+
codebases and ecosystem.
|
|
3
3
|
|
|
4
4
|
These are the current ESLint rules that enforce and help comply with the UI Styling Standard today,
|
|
5
5
|
but more are planned to support the standard over time.
|
|
@@ -11,6 +11,7 @@ but more are planned to support the standard over time.
|
|
|
11
11
|
|
|
12
12
|
| Rule | Description | Recommended | Fixable | Suggestions |
|
|
13
13
|
| --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------- | ------- | ----------- |
|
|
14
|
+
| <a href="atlaskit-theme/usage">atlaskit-theme</a> | Ban certain usages of `@atlaskit/theme` that `@compiled/react` does not understand | Yes | | |
|
|
14
15
|
| <a href="convert-props-syntax/usage">convert-props-syntax</a> | Convert props syntax that is unsupported by styled-components@<4 or @emotion/styled to props syntax that is supported. This is useful when used in conjunction with `no-styled-tagged-template-expression`, as output from the latter may use props syntax unsupported by those libraries. | Yes | Yes | |
|
|
15
16
|
| <a href="enforce-style-prop/usage">enforce-style-prop</a> | Disallows usage of static styles in the `style` attribute in components | Yes | | |
|
|
16
17
|
| <a href="local-cx-xcss/usage">local-cx-xcss</a> | Ensures the cx() function, which is part of the XCSS API, is only used within the xcss prop. This aids tracking what styles are applied to a jsx element. | Yes | | |
|
|
@@ -23,6 +24,7 @@ but more are planned to support the standard over time.
|
|
|
23
24
|
| <a href="no-imported-style-values/usage">no-imported-style-values</a> | Disallows imports of style values | Yes | | |
|
|
24
25
|
| <a href="no-nested-selectors/usage">no-nested-selectors</a> | Prevents usage of nested selectors within css styling | Yes | | |
|
|
25
26
|
| <a href="no-unsafe-values/usage">no-unsafe-values</a> | Disallows styles that are difficult/impossible to statically anaylze. | Yes | | |
|
|
27
|
+
| <a href="use-compiled/usage">use-compiled</a> | Ensures usage of `@compiled/react` instead of other CSS-in-JS libraries | Yes | Yes | |
|
|
26
28
|
| <a href="consistent-css-prop-usage/usage">@atlaskit/design-system/consistent-css-prop-usage</a> | Ensures consistency with `css` and `xcss` prop usages | Yes | Yes | |
|
|
27
29
|
| <a href="no-css-tagged-template-expression/usage">@atlaskit/design-system/no-css-tagged-template-expression</a> | Disallows any `css` tagged template expressions that originate from Emotion, Styled Components or Compiled | Yes | Yes | |
|
|
28
30
|
| <a href="no-keyframes-tagged-template-expression/usage">@atlaskit/design-system/no-keyframes-tagged-template-expression</a> | Disallows any `keyframe` tagged template expressions that originate from Emotion, Styled Components or Compiled | Yes | Yes | |
|
|
@@ -38,39 +40,46 @@ but more are planned to support the standard over time.
|
|
|
38
40
|
|
|
39
41
|
## Purpose of the UI Styling Standard
|
|
40
42
|
|
|
41
|
-
For Atlassians, refer to the
|
|
43
|
+
For Atlassians, refer to the
|
|
44
|
+
[internal UI Styling Standard policy](https://go.atlassian.com/ui-styling-standard-policy).
|
|
42
45
|
|
|
43
46
|
To enforce scoped encapsulation, type safety, and deterministic behavior in styling code that is
|
|
44
47
|
present in other programming languages. This is a stepping stone to large performance improvements,
|
|
45
|
-
reduced visual regressions, and enables testing and maintainability at scale.
|
|
46
|
-
|
|
47
|
-
|
|
48
|
+
reduced visual regressions, and enables testing and maintainability at scale. This approach improves
|
|
49
|
+
readability and developer productivity via automation with tooling, testing, code migrations, and
|
|
50
|
+
future advancements like generative AI.
|
|
48
51
|
|
|
49
52
|
### Desired outcomes:
|
|
50
53
|
|
|
51
|
-
-
|
|
52
|
-
-
|
|
53
|
-
|
|
54
|
-
-
|
|
55
|
-
|
|
56
|
-
-
|
|
54
|
+
- We can make large visual changes and migrations safely and in a fraction of the time.
|
|
55
|
+
- To have the vast majority of styling code be deterministic, immutable, and bound to its scope,
|
|
56
|
+
reducing unknown visual and UX regressions.
|
|
57
|
+
- To enable teams to write tooling quicker that's better and more performant to lint, test, and
|
|
58
|
+
migrate UI code to improve current and future developer productivity and satisfaction.
|
|
59
|
+
- To enable large performance improvements for customers and developers with a zero-runtime
|
|
60
|
+
styling solution.
|
|
61
|
+
- To reduce the amount of overall custom styling code written while supporting customization
|
|
62
|
+
without without the need for hacks and technical debt.
|
|
63
|
+
- We aim to see a reduction of the “average styles per component”, reducing the effort to build
|
|
64
|
+
and maintain UIs.
|
|
57
65
|
|
|
58
66
|
## Basic principles
|
|
59
67
|
|
|
60
|
-
We want the styling ecosystem (CSS, CSS-in-JS, and parts of JSX) at Atlassian and the wider
|
|
61
|
-
we support to be as mature as the other code we write, such as TypeScript/JavaScript,
|
|
68
|
+
We want the styling ecosystem (CSS, CSS-in-JS, and parts of JSX) at Atlassian and the wider
|
|
69
|
+
ecosystem we support to be as mature as the other code we write, such as TypeScript/JavaScript,
|
|
70
|
+
Java, Go, etc.
|
|
62
71
|
|
|
63
72
|
### Like other languages, styling code must be:
|
|
64
73
|
|
|
65
|
-
-
|
|
66
|
-
-
|
|
67
|
-
-
|
|
68
|
-
-
|
|
69
|
-
-
|
|
70
|
-
-
|
|
74
|
+
- type-safe
|
|
75
|
+
- static and locally analyzable
|
|
76
|
+
- reusable and composable
|
|
77
|
+
- restricted to an encapsulated scope
|
|
78
|
+
- deterministic—with styling known in isolation
|
|
79
|
+
- discoverable and readable without deep knowledge of the CSS spec
|
|
71
80
|
|
|
72
|
-
As the W3C CSS spec and wider industry grows, having our styling code meet these principles will
|
|
73
|
-
can programatically evolve that a better future state.
|
|
81
|
+
As the W3C CSS spec and wider industry grows, having our styling code meet these principles will
|
|
82
|
+
mean we can programatically evolve that a better future state.
|
|
74
83
|
|
|
75
84
|
## Examples
|
|
76
85
|
|
|
@@ -142,86 +151,93 @@ export const Component = ({
|
|
|
142
151
|
|
|
143
152
|
### Correct code
|
|
144
153
|
|
|
145
|
-
Every element should be clear in isolation how it's styled, using locally and statically available
|
|
154
|
+
Every element should be clear in isolation how it's styled, using locally and statically available
|
|
155
|
+
context so both humans and tooling can read this component in a performant and deterministic manner.
|
|
146
156
|
|
|
147
157
|
1. Use `@compiled/…` wherever possible!
|
|
148
158
|
2. Instead of dynamic styles:
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
159
|
+
1. Use static `css()` calls everywhere.
|
|
160
|
+
2. Compose styles together, turning styles on or off.
|
|
161
|
+
3. When absoluteuly necessary, use `props.style` for dynamic styles.
|
|
152
162
|
3. Instead of nested selectors or global styles:
|
|
153
|
-
|
|
154
|
-
|
|
163
|
+
1. Style components directly.
|
|
164
|
+
2. Treat everything as local scope, parents shouldn't interact with children wherever feasible.
|
|
155
165
|
4. Instead of passing raw styles around:
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
161
|
-
|
|
166
|
+
1. Write composable and reusable components which distribute styles with clear context.
|
|
167
|
+
2. Co-locate styles in the same file for human readability and far better tooling feasibility
|
|
168
|
+
and performance.
|
|
169
|
+
5. Instead of `styled.…`, use `const styles = css({ … });` (hoisted and static) and
|
|
170
|
+
`<div css={styles} />`.
|
|
171
|
+
1. There will be a safe way to make bounded customizations on components through the use of
|
|
172
|
+
`<Component xcss={css({ … })}>` in the future.
|
|
173
|
+
6. Instead of `...props`, be explicit with the `aria-` or `data-` props you support, or have more
|
|
174
|
+
complex spread handling. This is because `className`, `style`, and other things can be applied
|
|
175
|
+
without any knowledge, resulting in regressions in the future.
|
|
176
|
+
7. Instead of `!important`, `&& { … }`, or other specificity hacks, ensure your styles are correctly
|
|
177
|
+
scoped to the component.
|
|
162
178
|
|
|
163
179
|
```tsx
|
|
164
180
|
import { css } from '@compiled/react';
|
|
165
181
|
import { token } from '@atlaskit/tokens';
|
|
166
182
|
|
|
167
183
|
const wrapperStyles = css({
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
184
|
+
padding: token('space.200'), // eg. from mixin
|
|
185
|
+
font: token('font.body'), // eg. from mixin
|
|
186
|
+
color: token('color.text'),
|
|
171
187
|
});
|
|
172
188
|
const disabledWrapperStyles = css({
|
|
173
|
-
|
|
189
|
+
color: token('color.text.disabled'),
|
|
174
190
|
});
|
|
175
191
|
const innerWrapperStyles = css({
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
192
|
+
// eg. colocated `innerWrapperStyles` (alternatively could create a reusable `<InnerWrapper>`)
|
|
193
|
+
display: 'flex',
|
|
194
|
+
gap: token('space.100'),
|
|
195
|
+
flexDirection: 'column',
|
|
180
196
|
});
|
|
181
197
|
const buttonStyles = css({
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
198
|
+
appearance: 'none', // eg. from global styles
|
|
199
|
+
padding: `${token('space.100')} ${token('space.200')}`, // eg. from global styles
|
|
200
|
+
color: token('color.link'),
|
|
185
201
|
});
|
|
186
202
|
const disabledButtonStyles = css({
|
|
187
|
-
|
|
188
|
-
|
|
189
|
-
|
|
203
|
+
cursor: 'not-allowed', // eg. from disabledStyles
|
|
204
|
+
color: token('color.text.disabled'),
|
|
205
|
+
opacity: '70%',
|
|
190
206
|
});
|
|
191
207
|
const buttonAppearanceStyles = cssMap({
|
|
192
|
-
|
|
193
|
-
|
|
208
|
+
primary: { background: token('color.background.brand.subtlest') },
|
|
209
|
+
secondary: { background: token('color.background.success') },
|
|
194
210
|
});
|
|
195
211
|
|
|
196
212
|
export const Component = ({
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
200
|
-
|
|
213
|
+
disabled = false,
|
|
214
|
+
width = 100,
|
|
215
|
+
appearance = 'primary',
|
|
216
|
+
'aria-label': ariaLabel,
|
|
201
217
|
}: {
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
|
|
218
|
+
disabled?: boolean;
|
|
219
|
+
width?: number;
|
|
220
|
+
appearance?: 'primary' | 'secondary';
|
|
221
|
+
'aria-label'?: string;
|
|
206
222
|
}) => (
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
|
|
217
|
-
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
223
|
+
<div
|
|
224
|
+
css={[wrapperStyles, props.disabled && disabledWrapperStyles]}
|
|
225
|
+
style={{ width: `${props.width}px` }}
|
|
226
|
+
aria-label={ariaLabel}
|
|
227
|
+
>
|
|
228
|
+
<div css={innerWrapperStyles}>
|
|
229
|
+
{/* Typically, this `<button>` should be an Atlassian Design System `<Button>` */}
|
|
230
|
+
<button
|
|
231
|
+
disabled={props.disabled}
|
|
232
|
+
css={[
|
|
233
|
+
buttonStyles,
|
|
234
|
+
buttonAppearances[props.appearance],
|
|
235
|
+
props.disabled && disabledButtonStyles,
|
|
236
|
+
]}
|
|
237
|
+
>
|
|
238
|
+
Click me
|
|
239
|
+
</button>
|
|
240
|
+
</div>
|
|
224
241
|
</div>
|
|
225
|
-
</div>
|
|
226
242
|
);
|
|
227
243
|
```
|