@atlaskit/primitives 1.6.0 → 1.6.2
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 +96 -83
- package/constellation/bleed/code.mdx +1 -1
- package/constellation/box/code.mdx +1 -1
- package/constellation/box/examples.mdx +5 -1
- package/constellation/box/usage.mdx +3 -0
- package/constellation/flex/code.mdx +1 -1
- package/constellation/flex/examples.mdx +5 -3
- package/constellation/grid/code.mdx +1 -1
- package/constellation/grid/examples.mdx +4 -3
- package/constellation/inline/code.mdx +1 -1
- package/constellation/inline/examples.mdx +27 -10
- package/constellation/inline/usage.mdx +2 -0
- package/constellation/overview/index.mdx +8 -1
- package/constellation/responsive/01-show/code.mdx +1 -1
- package/constellation/responsive/01-show/examples.mdx +8 -3
- package/constellation/responsive/02-hide/code.mdx +1 -1
- package/constellation/responsive/02-hide/examples.mdx +8 -2
- package/constellation/responsive/03-breakpoints/examples.mdx +1 -1
- package/constellation/responsive/examples.mdx +9 -6
- package/constellation/stack/code.mdx +1 -1
- package/constellation/stack/examples.mdx +10 -4
- package/constellation/stack/usage.mdx +3 -0
- package/constellation/xcss/examples.mdx +0 -1
- package/constellation/xcss/migration.mdx +4 -6
- package/constellation/xcss/usage.mdx +20 -16
- package/dist/cjs/xcss/style-maps.partial.js +4 -3
- package/dist/es2019/xcss/style-maps.partial.js +4 -3
- package/dist/esm/xcss/style-maps.partial.js +4 -3
- package/dist/types/xcss/style-maps.partial.d.ts +3 -2
- package/dist/types-ts4.5/xcss/style-maps.partial.d.ts +3 -2
- package/package.json +3 -14
- package/report.api.md +1 -0
- package/scripts/__tests__/__snapshots__/codegen.test.tsx.snap +1 -0
- package/scripts/typography-codegen-template.tsx +1 -1
- package/tmp/api-report-tmp.d.ts +1 -0
- package/constellation/heading/code.mdx +0 -19
- package/constellation/heading/examples.mdx +0 -28
- package/constellation/heading/usage.mdx +0 -21
- package/dist/cjs/components/heading-context.js +0 -44
- package/dist/cjs/components/heading.js +0 -95
- package/dist/es2019/components/heading-context.js +0 -35
- package/dist/es2019/components/heading.js +0 -87
- package/dist/esm/components/heading-context.js +0 -34
- package/dist/esm/components/heading.js +0 -87
- package/dist/types/components/heading-context.d.ts +0 -31
- package/dist/types/components/heading.d.ts +0 -45
- package/dist/types-ts4.5/components/heading-context.d.ts +0 -31
- package/dist/types-ts4.5/components/heading.d.ts +0 -45
- package/extract-react-types/heading-props.tsx +0 -3
- package/heading/package.json +0 -15
- package/heading-context/package.json +0 -15
|
@@ -12,7 +12,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
12
12
|
directoryName="primitives"
|
|
13
13
|
/>
|
|
14
14
|
|
|
15
|
-
import ERTBox from '!!extract-react-types-loader!../../extract-react-types/box-props'
|
|
15
|
+
import ERTBox from '!!extract-react-types-loader!../../extract-react-types/box-props';
|
|
16
16
|
|
|
17
17
|
## Props
|
|
18
18
|
|
|
@@ -37,7 +37,10 @@ The nomenclature used by these props follows [logical properties](https://develo
|
|
|
37
37
|
|
|
38
38
|
`Box` accepts a wide variety of background colors, referenced as semantic design tokens. For the full list of color tokens or to learn more, visit our [Token documentation](/tokens/design-tokens/).
|
|
39
39
|
|
|
40
|
-
<Example
|
|
40
|
+
<Example
|
|
41
|
+
Component={BoxBackgroundColor}
|
|
42
|
+
packageName="@atlaskit/primitives/box"
|
|
43
|
+
/>
|
|
41
44
|
|
|
42
45
|
## xcss
|
|
43
46
|
|
|
@@ -49,4 +52,5 @@ For more information on xcss, see the dedicated [xcss documentation](/components
|
|
|
49
52
|
## Practical use case
|
|
50
53
|
|
|
51
54
|
`Box` is designed to be used in conjunction with `Inline` and `Stack` to create layouts. This example demonstrates how primitives can be used to create familiar components and patterns.
|
|
55
|
+
|
|
52
56
|
<Example Component={PracticalUseCase} packageName="@atlaskit/primitives/box" />
|
|
@@ -8,6 +8,7 @@ A `Box` is a generic container with convenient and managed access to design toke
|
|
|
8
8
|
Use a `Box` to compose layouts and add styling to child elements through visual props, including spacing and color through design tokens.
|
|
9
9
|
|
|
10
10
|
## `Box` styling
|
|
11
|
+
|
|
11
12
|
Display behavior is set by using the available props or using `xcss`. Makers can make design decisions for `Box` by setting:
|
|
12
13
|
|
|
13
14
|
- `padding`
|
|
@@ -20,10 +21,12 @@ Display behavior is set by using the available props or using `xcss`. Makers can
|
|
|
20
21
|
- `backgroundColor`
|
|
21
22
|
|
|
22
23
|
## Using `Box`
|
|
24
|
+
|
|
23
25
|
To identify usages of `Box` in a given design, look for where a UI element will receive some visual styles applied to a container. `Box` can be used on a range of sizes of elements, from buttons to section wrappers.
|
|
24
26
|
`Box`, being generic in nature, can be "over-used", so it’s important to consider situations where more specific and expressive primitives could be used, for example: `Inline` and `Stack` to manage horizontal and vertical layouts, respectively.
|
|
25
27
|
|
|
26
28
|
## Related
|
|
29
|
+
|
|
27
30
|
- [Learn more about the Inline primitive](/components/primitives/inline/usage)
|
|
28
31
|
- [Learn more about the Stack primitive](/components/primitives/stack/usage)
|
|
29
32
|
- [Learn more about the Grid primitive](/components/primitives/grid/examples)
|
|
@@ -12,7 +12,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
12
12
|
directoryName="primitives"
|
|
13
13
|
/>
|
|
14
14
|
|
|
15
|
-
import ERTFlex from '!!extract-react-types-loader!../../extract-react-types/flex-props'
|
|
15
|
+
import ERTFlex from '!!extract-react-types-loader!../../extract-react-types/flex-props';
|
|
16
16
|
|
|
17
17
|
## Props
|
|
18
18
|
|
|
@@ -17,12 +17,14 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
17
17
|
directoryName="primitives"
|
|
18
18
|
/>
|
|
19
19
|
|
|
20
|
-
|
|
21
20
|
## Basic
|
|
22
21
|
|
|
23
22
|
The `Flex` component is a basic mapping to the CSS Flexbox API. It can be used as a less richly-configured `Inline` or `Stack`. Like Stack and Inline, `Flex` exclusively supports token-backed `gap` properties to ensure layouts using `Flex` match the Atlassian Design System spacing scale.
|
|
24
23
|
|
|
25
|
-
<Example
|
|
24
|
+
<Example
|
|
25
|
+
Component={FlexJustifyContent}
|
|
26
|
+
packageName="@atlaskit/primitives/flex"
|
|
27
|
+
/>
|
|
26
28
|
|
|
27
29
|
## Align items and justify content
|
|
28
30
|
|
|
@@ -32,7 +34,7 @@ The `Flex` component is a basic mapping to the CSS Flexbox API. It can be used a
|
|
|
32
34
|
|
|
33
35
|
## Wrap
|
|
34
36
|
|
|
35
|
-
Flex-prefixed properties in CSS do not have this prefix in the component API.
|
|
37
|
+
Flex-prefixed properties in CSS do not have this prefix in the component API.
|
|
36
38
|
For example, `flex-wrap` is instead applied as the `wrap` property.
|
|
37
39
|
|
|
38
40
|
<Example Component={FlexWrap} packageName="@atlaskit/primitives/flex" />
|
|
@@ -12,7 +12,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
12
12
|
directoryName="primitives"
|
|
13
13
|
/>
|
|
14
14
|
|
|
15
|
-
import ERTGrid from '!!extract-react-types-loader!../../extract-react-types/grid-props'
|
|
15
|
+
import ERTGrid from '!!extract-react-types-loader!../../extract-react-types/grid-props';
|
|
16
16
|
|
|
17
17
|
## Props
|
|
18
18
|
|
|
@@ -28,8 +28,8 @@ It can be used as an alternative to [Flex](/components/primitives/flex), [Inline
|
|
|
28
28
|
|
|
29
29
|
## Gap properties
|
|
30
30
|
|
|
31
|
-
|
|
32
31
|
Gap properties `rowGap`, `columnGap` and `gap` only allow token-backed values. This is to aid ergonomics and keep the whitespace of the grid harmonious with the spacing system.
|
|
32
|
+
|
|
33
33
|
<Example Component={GridGap} packageName="@atlaskit/primitives/grid" />
|
|
34
34
|
|
|
35
35
|
## Template syntax
|
|
@@ -62,5 +62,6 @@ Grid-prefixed properties in CSS do not have this prefix in the component API. `g
|
|
|
62
62
|
<Example Component={GridAutoFlow} packageName="@atlaskit/primitives/grid" />
|
|
63
63
|
|
|
64
64
|
You may also be looking for:
|
|
65
|
-
|
|
66
|
-
|
|
65
|
+
|
|
66
|
+
- [responsive layout grid](/components/grid)
|
|
67
|
+
- [legacy page grid](/components/page/grid)
|
|
@@ -12,7 +12,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
12
12
|
directoryName="primitives"
|
|
13
13
|
/>
|
|
14
14
|
|
|
15
|
-
import ERTInline from '!!extract-react-types-loader!../../extract-react-types/inline-props'
|
|
15
|
+
import ERTInline from '!!extract-react-types-loader!../../extract-react-types/inline-props';
|
|
16
16
|
|
|
17
17
|
## Props
|
|
18
18
|
|
|
@@ -24,7 +24,6 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
24
24
|
directoryName="primitives"
|
|
25
25
|
/>
|
|
26
26
|
|
|
27
|
-
|
|
28
27
|
## Basic
|
|
29
28
|
|
|
30
29
|
Inline should be used to efficiently lay-out a group of elements horizontally.
|
|
@@ -37,13 +36,19 @@ Use the given props to configure display behaviour using designs tokens, as show
|
|
|
37
36
|
|
|
38
37
|
Spacing between items can be controlled with the `space` prop:
|
|
39
38
|
|
|
40
|
-
<Example
|
|
39
|
+
<Example
|
|
40
|
+
Component={InlineSpaceBasic}
|
|
41
|
+
packageName="@atlaskit/primitives/inline"
|
|
42
|
+
/>
|
|
41
43
|
|
|
42
44
|
When content is set to wrap, the `space` prop applies equal spacing between rows.
|
|
43
45
|
|
|
44
46
|
For a different space value between rows use the `rowSpace` prop.
|
|
45
47
|
|
|
46
|
-
<Example
|
|
48
|
+
<Example
|
|
49
|
+
Component={InlineSpaceWrap}
|
|
50
|
+
packageName="@atlaskit/primitives/inline"
|
|
51
|
+
/>
|
|
47
52
|
|
|
48
53
|
## Alignment
|
|
49
54
|
|
|
@@ -51,11 +56,17 @@ To control the alignment of items you can use the `alignBlock` and `alignInline`
|
|
|
51
56
|
|
|
52
57
|
### Block alignment
|
|
53
58
|
|
|
54
|
-
<Example
|
|
59
|
+
<Example
|
|
60
|
+
Component={InlineAlignBlock}
|
|
61
|
+
packageName="@atlaskit/primitives/inline"
|
|
62
|
+
/>
|
|
55
63
|
|
|
56
64
|
### Inline alignment
|
|
57
65
|
|
|
58
|
-
<Example
|
|
66
|
+
<Example
|
|
67
|
+
Component={InlineAlignInline}
|
|
68
|
+
packageName="@atlaskit/primitives/inline"
|
|
69
|
+
/>
|
|
59
70
|
|
|
60
71
|
## Spread
|
|
61
72
|
|
|
@@ -73,15 +84,18 @@ When the number of items goes beyond the available space `shouldWrap` can be use
|
|
|
73
84
|
|
|
74
85
|
For logically related elements it's possible to specify a `separator` character value.
|
|
75
86
|
|
|
76
|
-
<Example
|
|
87
|
+
<Example
|
|
88
|
+
Component={InlineSeparator}
|
|
89
|
+
packageName="@atlaskit/primitives/inline"
|
|
90
|
+
/>
|
|
77
91
|
|
|
78
92
|
## Width control
|
|
79
93
|
|
|
80
|
-
By default an `Inline` will have its width influenced by the context where it appears.
|
|
94
|
+
By default an `Inline` will have its width influenced by the context where it appears.
|
|
81
95
|
To control the width, the `grow` prop can be used with the values:
|
|
82
96
|
|
|
83
|
-
|
|
84
|
-
|
|
97
|
+
- `hug` (default) to use space only as required by its children, or
|
|
98
|
+
- `fill` to take all space provided by the parent element.
|
|
85
99
|
|
|
86
100
|
<Example Component={InlineGrow} packageName="@atlaskit/primitives/inline" />
|
|
87
101
|
|
|
@@ -95,4 +109,7 @@ It's possible to control the rendered HTML element with the `as` prop.
|
|
|
95
109
|
|
|
96
110
|
An example of how an `Inline` might be used in product, using Atlassian Design System components.
|
|
97
111
|
|
|
98
|
-
<Example
|
|
112
|
+
<Example
|
|
113
|
+
Component={InlinePracticalUseCase}
|
|
114
|
+
packageName="@atlaskit/primitives/inline"
|
|
115
|
+
/>
|
|
@@ -19,6 +19,7 @@ In its simplest form, `Inline` operates like a flexbox row, however adds the bui
|
|
|
19
19
|
`Inline` also has a flex-direction: row; this is the default for flexbox, so it is not explicitly applied.
|
|
20
20
|
|
|
21
21
|
## Use `Inline`
|
|
22
|
+
|
|
22
23
|
The purpose of an Inline is primarily as a container element controlling how child components are displayed and positioned horizontally. Inline should be used any time you wish to layout elements or components horizontally.
|
|
23
24
|
|
|
24
25
|
The various Inline props can then be used to customize the spacing and styling on any child elements. These include:
|
|
@@ -33,6 +34,7 @@ The various Inline props can then be used to customize the spacing and styling o
|
|
|
33
34
|
- `separator`
|
|
34
35
|
|
|
35
36
|
## Related
|
|
37
|
+
|
|
36
38
|
- [Learn more about the Primitives](/components/primitives/overview)
|
|
37
39
|
- [Learn more about the Box primitive](/components/primitives/box/usage)
|
|
38
40
|
- [Learn more about the Stack primitive](/components/primitives/stack/usage)
|
|
@@ -32,11 +32,13 @@ Each primitive is designed to have a single responsibility, and it should be imm
|
|
|
32
32
|
However, they are also flexible enough that they should be able to be used together to compose complex designs not otherwise implemented directly in the Design Systems.
|
|
33
33
|
|
|
34
34
|
Currently, three core primitive components are available - Box, Inline and Stack. A large amount of layout problems can be reduced to laying out content:
|
|
35
|
+
|
|
35
36
|
- in a container (see [box](/components/primitives/box))
|
|
36
37
|
- horizontally (see [inline](/components/primitives/inline))
|
|
37
38
|
- vertically (see [stack](/components/primitives/stack))
|
|
38
39
|
|
|
39
40
|
Additional layouts not well-expressed by these core primitives can also be composed using:
|
|
41
|
+
|
|
40
42
|
- CSS Flexbox (see [flex](/components/primitives/flex))
|
|
41
43
|
- CSS Grid (see [grid](/components/primitives/grid))
|
|
42
44
|
- Bleed (see [bleed](/components/primitives/bleed))
|
|
@@ -44,6 +46,7 @@ Additional layouts not well-expressed by these core primitives can also be compo
|
|
|
44
46
|
## Installation
|
|
45
47
|
|
|
46
48
|
To install primitive components, add @atlaskit/primitives as a dependency on your project:
|
|
49
|
+
|
|
47
50
|
```bash
|
|
48
51
|
$ yarn add @atlaskit/primitives
|
|
49
52
|
```
|
|
@@ -63,7 +66,11 @@ in a layout and grouping them together under a `Box`.
|
|
|
63
66
|
The behavior within and around these boxes can then be broken down into their horizontal `Inline` and vertical `Stack` components.
|
|
64
67
|
|
|
65
68
|
<SectionMessage>
|
|
66
|
-
The ESLint rule
|
|
69
|
+
The ESLint rule{' '}
|
|
70
|
+
<a href="/components/eslint-plugin-design-system/usage#use-primitives">
|
|
71
|
+
use-primitives
|
|
72
|
+
</a>{' '}
|
|
73
|
+
offers suggestions for possible primitives to apply in a layout.
|
|
67
74
|
</SectionMessage>
|
|
68
75
|
|
|
69
76
|
<Image src={inlineUsageExample} />
|
|
@@ -12,7 +12,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
12
12
|
directoryName="primitives"
|
|
13
13
|
/>
|
|
14
14
|
|
|
15
|
-
import ShowProps from '!!extract-react-types-loader!../../../extract-react-types/show-props'
|
|
15
|
+
import ShowProps from '!!extract-react-types-loader!../../../extract-react-types/show-props';
|
|
16
16
|
|
|
17
17
|
## Props
|
|
18
18
|
|
|
@@ -15,17 +15,22 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
15
15
|
directoryName="primitives"
|
|
16
16
|
/>
|
|
17
17
|
|
|
18
|
-
|
|
19
18
|
### Show
|
|
20
19
|
|
|
21
20
|
Using `Show` allows you to show the children using CSS `display: …` when the viewport size is above a specified breakpoint. By default, unless the breakpoint is met, contents are hidden.
|
|
22
21
|
|
|
23
22
|
Children that are not shown are still rendered into the DOM, so there so there is typically little performance savings — primarily that they are not painted.
|
|
24
23
|
|
|
25
|
-
<Example
|
|
24
|
+
<Example
|
|
25
|
+
Component={ShowExample}
|
|
26
|
+
packageName="@atlaskit/primitives/responsive"
|
|
27
|
+
/>
|
|
26
28
|
|
|
27
29
|
### Mixing Show and Hide
|
|
28
30
|
|
|
29
31
|
Prefer using consistent `above` or `below` for readability and consistency.
|
|
30
32
|
|
|
31
|
-
<Example
|
|
33
|
+
<Example
|
|
34
|
+
Component={ShowHideExample}
|
|
35
|
+
packageName="@atlaskit/primitives/responsive"
|
|
36
|
+
/>
|
|
@@ -12,7 +12,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
12
12
|
directoryName="primitives"
|
|
13
13
|
/>
|
|
14
14
|
|
|
15
|
-
import HideProps from '!!extract-react-types-loader!../../../extract-react-types/hide-props'
|
|
15
|
+
import HideProps from '!!extract-react-types-loader!../../../extract-react-types/hide-props';
|
|
16
16
|
|
|
17
17
|
## Props
|
|
18
18
|
|
|
@@ -21,10 +21,16 @@ Using Hide allows you to Hide the children using CSS `display: none` when the vi
|
|
|
21
21
|
|
|
22
22
|
Children that are hidden are still rendered into the DOM, so there so there is typically little performance savings — primarily that they are not painted.
|
|
23
23
|
|
|
24
|
-
<Example
|
|
24
|
+
<Example
|
|
25
|
+
Component={HideExample}
|
|
26
|
+
packageName="@atlaskit/primitives/responsive"
|
|
27
|
+
/>
|
|
25
28
|
|
|
26
29
|
### Mixing Show and Hide
|
|
27
30
|
|
|
28
31
|
Prefer using consistent `above` or `below` for readability and consistency.
|
|
29
32
|
|
|
30
|
-
<Example
|
|
33
|
+
<Example
|
|
34
|
+
Component={ShowHideExample}
|
|
35
|
+
packageName="@atlaskit/primitives/responsive"
|
|
36
|
+
/>
|
|
@@ -10,7 +10,6 @@ import ShowExample from '../../examples/constellation/responsive/show';
|
|
|
10
10
|
import HideExample from '../../examples/constellation/responsive/hide';
|
|
11
11
|
import ShowHideExample from '../../examples/constellation/responsive/show-hide';
|
|
12
12
|
|
|
13
|
-
|
|
14
13
|
import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
15
14
|
|
|
16
15
|
<CodeDocsHeader
|
|
@@ -25,16 +24,20 @@ Utilize our media queries exposed in `css`, `styled`, or `xcss` as computed keys
|
|
|
25
24
|
|
|
26
25
|
### Using with `xcss`
|
|
27
26
|
|
|
28
|
-
Please use `xcss` whenever possible to ensure consistency and safety with style overrides.
|
|
27
|
+
Please use `xcss` whenever possible to ensure consistency and safety with style overrides. Read more at [xcss](/components/primitives/xcss)
|
|
29
28
|
|
|
30
|
-
<Example
|
|
29
|
+
<Example
|
|
30
|
+
Component={XCSSExample}
|
|
31
|
+
packageName="@atlaskit/primitives/responsive"
|
|
32
|
+
/>
|
|
31
33
|
|
|
32
34
|
### Using with `css`
|
|
33
|
-
<Example Component={CSSExample} packageName="@atlaskit/primitives/responsive" />
|
|
34
35
|
|
|
36
|
+
<Example Component={CSSExample} packageName="@atlaskit/primitives/responsive" />
|
|
35
37
|
|
|
36
38
|
## Responsive primitives
|
|
37
39
|
|
|
38
40
|
Consider these shortcuts to writing your own custom media queries. Composing with our primitives will be far quicker and consistent to implement, but may result in excess DOM nodes.
|
|
39
|
-
|
|
40
|
-
|
|
41
|
+
|
|
42
|
+
- [Show](/components/primitives/responsive/show)
|
|
43
|
+
- [Hide](/components/primitives/responsive/hide)
|
|
@@ -12,7 +12,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
|
|
|
12
12
|
directoryName="primitives"
|
|
13
13
|
/>
|
|
14
14
|
|
|
15
|
-
import ERTStack from '!!extract-react-types-loader!../../extract-react-types/stack-props'
|
|
15
|
+
import ERTStack from '!!extract-react-types-loader!../../extract-react-types/stack-props';
|
|
16
16
|
|
|
17
17
|
## Props
|
|
18
18
|
|
|
@@ -44,7 +44,10 @@ To control the alignment of items you can use the `alignBlock` and `alignInline`
|
|
|
44
44
|
|
|
45
45
|
### Inline alignment
|
|
46
46
|
|
|
47
|
-
<Example
|
|
47
|
+
<Example
|
|
48
|
+
Component={StackAlignInline}
|
|
49
|
+
packageName="@atlaskit/primitives/stack"
|
|
50
|
+
/>
|
|
48
51
|
|
|
49
52
|
## Spread
|
|
50
53
|
|
|
@@ -58,8 +61,8 @@ By default a `Stack` will have its width influenced by the context where it appe
|
|
|
58
61
|
|
|
59
62
|
To control that the `grow` prop can be used with the values:
|
|
60
63
|
|
|
61
|
-
|
|
62
|
-
|
|
64
|
+
- `hug` (default) to use space only as required by its children, or
|
|
65
|
+
- `fill` to take all space provided by the parent element.
|
|
63
66
|
|
|
64
67
|
<Example Component={StackGrow} packageName="@atlaskit/primitives/stack" />
|
|
65
68
|
|
|
@@ -71,4 +74,7 @@ It's possible to control the rendered HTML element with the `as` prop.
|
|
|
71
74
|
|
|
72
75
|
## Practical use case
|
|
73
76
|
|
|
74
|
-
<Example
|
|
77
|
+
<Example
|
|
78
|
+
Component={PracticalUseCase}
|
|
79
|
+
packageName="@atlaskit/primitives/stack"
|
|
80
|
+
/>
|
|
@@ -17,9 +17,11 @@ In its simplest form, `Stack` operates like a flexbox column, however adds the b
|
|
|
17
17
|
```
|
|
18
18
|
|
|
19
19
|
## Use `Stack`
|
|
20
|
+
|
|
20
21
|
The purpose of a `Stack` is primarily as a container element controlling how content is displayed and aligned vertically. `Stack` should be used any time you wish to layout elements or components vertically.
|
|
21
22
|
|
|
22
23
|
The various `Stack` props can then be used to customize the spacing and styling on any child elements. These include:
|
|
24
|
+
|
|
23
25
|
- `alignBlock`
|
|
24
26
|
- `alignInline`
|
|
25
27
|
- `spread`
|
|
@@ -27,6 +29,7 @@ The various `Stack` props can then be used to customize the spacing and styling
|
|
|
27
29
|
- `space`
|
|
28
30
|
|
|
29
31
|
## Related
|
|
32
|
+
|
|
30
33
|
- [Learn more about the Primitives](/components/primitives/overview)
|
|
31
34
|
- [Learn more about the Box primitive](/components/primitives/box/usage)
|
|
32
35
|
- [Learn more about the Inline primitive](/components/primitives/inline/usage)
|
|
@@ -29,7 +29,6 @@ To enable interactivity, use familiar selectors like `:hover` and `:focus-visibl
|
|
|
29
29
|
|
|
30
30
|
<Example Component={xcssInteractive} packageName="@atlaskit/primitives/xcss" />
|
|
31
31
|
|
|
32
|
-
|
|
33
32
|
## Responsiveness
|
|
34
33
|
|
|
35
34
|
`xcss` also accepts a subset of media queries at [predefined breakpoints](/components/primitives/responsive/breakpoints/examples).
|
|
@@ -35,7 +35,6 @@ JSXAttributes, be aware if you're not seeing your styles appear.
|
|
|
35
35
|
+ <Box xcss={someStyles} />
|
|
36
36
|
```
|
|
37
37
|
|
|
38
|
-
|
|
39
38
|
#### Changing the way you express styles
|
|
40
39
|
|
|
41
40
|
Why are nested selectors a problem? A key philosophy of `xcss` is encouraging more deterministic style application. Restricting nested styles eliminates side-effects and encourages component encapsulation. Consider the below example:
|
|
@@ -44,7 +43,7 @@ Why are nested selectors a problem? A key philosophy of `xcss` is encouraging mo
|
|
|
44
43
|
const myComponentStyles = css({
|
|
45
44
|
'> *': {
|
|
46
45
|
color: 'color.text.danger',
|
|
47
|
-
}
|
|
46
|
+
},
|
|
48
47
|
});
|
|
49
48
|
|
|
50
49
|
const MyComponent = () => (
|
|
@@ -130,9 +129,8 @@ const myComponentStyles = xcss({
|
|
|
130
129
|
const MyComponent = () => <Box xcss={myComponentStyles} />
|
|
131
130
|
```
|
|
132
131
|
|
|
133
|
-
|
|
134
132
|
## Get help
|
|
135
133
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
134
|
+
- Atlassians can reach out in [Slack](slack://channel?team=TFCUTJ0G5&id=CFJ9DU39U) for help with `xcss` migration.
|
|
135
|
+
- Other developers who need help with tokens or the `xcss` utility can post in the [public developer community](https://community.developer.atlassian.com/).
|
|
136
|
+
- For general help with the Atlassian Design System, [contact us](/resources/contact-us).
|
|
@@ -3,9 +3,10 @@ title: xcss
|
|
|
3
3
|
description: xcss is a safer, tokens-first approach to CSS-in-JS.
|
|
4
4
|
order: 0
|
|
5
5
|
---
|
|
6
|
+
|
|
6
7
|
import { MediaQueriesTable } from '@af/design-system-docs-ui';
|
|
7
8
|
|
|
8
|
-

|
|
9
10
|
|
|
10
11
|
`xcss` is an Atlassian Design System styling API that natively integrates with Atlassian's [design tokens](/tokens) and [primitives](/components/primitives).
|
|
11
12
|
|
|
@@ -13,14 +14,14 @@ The `xcss` utility behaves similarly to the `css` utility in libraries like `sty
|
|
|
13
14
|
|
|
14
15
|
Familiar features:
|
|
15
16
|
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
17
|
+
- `xcss` generates a `className` that is applied to the components
|
|
18
|
+
- `xcss` provides key-value pairs of CSS properties in an object format
|
|
19
|
+
- `xcss` supports style precedence and conditional styles
|
|
19
20
|
|
|
20
21
|
Key differences:
|
|
21
22
|
|
|
22
|
-
|
|
23
|
-
|
|
23
|
+
- `xcss` has type-safety that ensures token name usage for all CSS properties represented by design tokens.
|
|
24
|
+
- `xcss` restricts nested selectors completely from usage
|
|
24
25
|
|
|
25
26
|
## Usage
|
|
26
27
|
|
|
@@ -46,9 +47,10 @@ const someStyles = xcss({
|
|
|
46
47
|
});
|
|
47
48
|
|
|
48
49
|
const MyBox = () => {
|
|
49
|
-
return <Box xcss={someStyles}
|
|
50
|
-
}
|
|
50
|
+
return <Box xcss={someStyles} />;
|
|
51
|
+
};
|
|
51
52
|
```
|
|
53
|
+
|
|
52
54
|
The `xcss` prop and the `xcss` function are direct complements and are designed to be used together.
|
|
53
55
|
|
|
54
56
|
It is important to note that styles generated from `xcss` cannot be applied directly to the `className` property or `css` as they are with other CSS-in-JS libraries.
|
|
@@ -68,12 +70,13 @@ import { xcss } from '@atlaskit/primitives';
|
|
|
68
70
|
|
|
69
71
|
const someStyles = xcss({
|
|
70
72
|
padding: 'space.200', // <--- works
|
|
71
|
-
color: 'space.200',
|
|
72
|
-
borderRadius: 'border.radius.100' // <--- also valid
|
|
73
|
+
color: 'space.200', // <--- invalid and will error
|
|
74
|
+
borderRadius: 'border.radius.100', // <--- also valid
|
|
73
75
|
});
|
|
74
76
|
```
|
|
75
77
|
|
|
76
78
|
### Restricted nesting
|
|
79
|
+
|
|
77
80
|
`xcss` is flexible enough to implement any design, but it does restrict the application of styles in one key way.
|
|
78
81
|
Selectors cannot be nested or target elements beyond the element on which styles are applied.
|
|
79
82
|
This restriction is intended to encourage better component encapsulation, reduce side-effects and make the codebase more resilient to change.
|
|
@@ -83,16 +86,16 @@ import { xcss } from '@atlaskit/primitives';
|
|
|
83
86
|
|
|
84
87
|
const someStyles = xcss({
|
|
85
88
|
':hover': {
|
|
86
|
-
transform: 'scale(1)' // this is okay
|
|
89
|
+
transform: 'scale(1)', // this is okay
|
|
87
90
|
},
|
|
88
91
|
// This is not okay as this selector affects any nested div in
|
|
89
92
|
// the component tree.
|
|
90
93
|
'div:hover': {
|
|
91
|
-
transform: 'scale(1)'
|
|
94
|
+
transform: 'scale(1)',
|
|
92
95
|
},
|
|
93
96
|
// Neither is this
|
|
94
97
|
'> * > div:hover': {
|
|
95
|
-
transform: 'scale(1)'
|
|
98
|
+
transform: 'scale(1)',
|
|
96
99
|
},
|
|
97
100
|
});
|
|
98
101
|
```
|
|
@@ -101,6 +104,7 @@ These unsafe selectors will throw a type error if applied.
|
|
|
101
104
|
For richer examples of how to use `xcss` please see the [primitives `xcss` documentation](/components/primitives/xcss/examples).
|
|
102
105
|
|
|
103
106
|
### Media Queries
|
|
107
|
+
|
|
104
108
|
xcss can create responsive layouts at predefined breakpoints that are consistent with the Atlassian Design System. To enable responsive behavior, xcss exposes the following pre-defined breakpoints:
|
|
105
109
|
|
|
106
110
|
<MediaQueriesTable />
|
|
@@ -142,6 +146,6 @@ const someStyles = xcss({
|
|
|
142
146
|
|
|
143
147
|
## Get help
|
|
144
148
|
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
149
|
+
- Atlassians can reach out in [Slack](slack://channel?team=TFCUTJ0G5&id=CFJ9DU39U) for help with `xcss` migration.
|
|
150
|
+
- Other developers who need help with tokens or the `xcss` utility can post in the [public developer community](https://community.developer.atlassian.com/).
|
|
151
|
+
- For general help with the Atlassian Design System, [contact us](/resources/contact-us).
|
|
@@ -73,11 +73,11 @@ exports.negativeSpaceMap = negativeSpaceMap;
|
|
|
73
73
|
|
|
74
74
|
/**
|
|
75
75
|
* THIS SECTION WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
|
|
76
|
-
* @codegen <<SignedSource::
|
|
76
|
+
* @codegen <<SignedSource::2d67e9258c01e48d564a26a1e4400b94>>
|
|
77
77
|
* @codegenId colors
|
|
78
78
|
* @codegenCommand yarn workspace @atlaskit/primitives codegen-styles
|
|
79
79
|
* @codegenParams ["border", "background", "shadow", "text", "fill", "surface"]
|
|
80
|
-
* @codegenDependency ../../../tokens/src/artifacts/tokens-raw/atlassian-light.tsx <<SignedSource::
|
|
80
|
+
* @codegenDependency ../../../tokens/src/artifacts/tokens-raw/atlassian-light.tsx <<SignedSource::f6a616f7ea03ec40c148fc83050d073b>>
|
|
81
81
|
*/
|
|
82
82
|
var borderColorMap = {
|
|
83
83
|
'color.border': "var(--ds-border, #091e4221)",
|
|
@@ -346,7 +346,8 @@ var textColorMap = {
|
|
|
346
346
|
'color.text.subtlest': "var(--ds-text-subtlest, #7A869A)",
|
|
347
347
|
'color.text.subtle': "var(--ds-text-subtle, #42526E)",
|
|
348
348
|
'color.link': "var(--ds-link, #0052CC)",
|
|
349
|
-
'color.link.pressed': "var(--ds-link-pressed, #0747A6)"
|
|
349
|
+
'color.link.pressed': "var(--ds-link-pressed, #0747A6)",
|
|
350
|
+
'color.link.visited': "var(--ds-link-visited, #403294)"
|
|
350
351
|
};
|
|
351
352
|
exports.textColorMap = textColorMap;
|
|
352
353
|
var fillMap = {
|
|
@@ -61,11 +61,11 @@ export const negativeSpaceMap = {
|
|
|
61
61
|
*/
|
|
62
62
|
/**
|
|
63
63
|
* THIS SECTION WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
|
|
64
|
-
* @codegen <<SignedSource::
|
|
64
|
+
* @codegen <<SignedSource::2d67e9258c01e48d564a26a1e4400b94>>
|
|
65
65
|
* @codegenId colors
|
|
66
66
|
* @codegenCommand yarn workspace @atlaskit/primitives codegen-styles
|
|
67
67
|
* @codegenParams ["border", "background", "shadow", "text", "fill", "surface"]
|
|
68
|
-
* @codegenDependency ../../../tokens/src/artifacts/tokens-raw/atlassian-light.tsx <<SignedSource::
|
|
68
|
+
* @codegenDependency ../../../tokens/src/artifacts/tokens-raw/atlassian-light.tsx <<SignedSource::f6a616f7ea03ec40c148fc83050d073b>>
|
|
69
69
|
*/
|
|
70
70
|
export const borderColorMap = {
|
|
71
71
|
'color.border': "var(--ds-border, #091e4221)",
|
|
@@ -331,7 +331,8 @@ export const textColorMap = {
|
|
|
331
331
|
'color.text.subtlest': "var(--ds-text-subtlest, #7A869A)",
|
|
332
332
|
'color.text.subtle': "var(--ds-text-subtle, #42526E)",
|
|
333
333
|
'color.link': "var(--ds-link, #0052CC)",
|
|
334
|
-
'color.link.pressed': "var(--ds-link-pressed, #0747A6)"
|
|
334
|
+
'color.link.pressed': "var(--ds-link-pressed, #0747A6)",
|
|
335
|
+
'color.link.visited': "var(--ds-link-visited, #403294)"
|
|
335
336
|
};
|
|
336
337
|
export const fillMap = {
|
|
337
338
|
'color.icon': "var(--ds-icon, #505F79)",
|
|
@@ -62,11 +62,11 @@ export var negativeSpaceMap = {
|
|
|
62
62
|
*/
|
|
63
63
|
/**
|
|
64
64
|
* THIS SECTION WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
|
|
65
|
-
* @codegen <<SignedSource::
|
|
65
|
+
* @codegen <<SignedSource::2d67e9258c01e48d564a26a1e4400b94>>
|
|
66
66
|
* @codegenId colors
|
|
67
67
|
* @codegenCommand yarn workspace @atlaskit/primitives codegen-styles
|
|
68
68
|
* @codegenParams ["border", "background", "shadow", "text", "fill", "surface"]
|
|
69
|
-
* @codegenDependency ../../../tokens/src/artifacts/tokens-raw/atlassian-light.tsx <<SignedSource::
|
|
69
|
+
* @codegenDependency ../../../tokens/src/artifacts/tokens-raw/atlassian-light.tsx <<SignedSource::f6a616f7ea03ec40c148fc83050d073b>>
|
|
70
70
|
*/
|
|
71
71
|
export var borderColorMap = {
|
|
72
72
|
'color.border': "var(--ds-border, #091e4221)",
|
|
@@ -332,7 +332,8 @@ export var textColorMap = {
|
|
|
332
332
|
'color.text.subtlest': "var(--ds-text-subtlest, #7A869A)",
|
|
333
333
|
'color.text.subtle': "var(--ds-text-subtle, #42526E)",
|
|
334
334
|
'color.link': "var(--ds-link, #0052CC)",
|
|
335
|
-
'color.link.pressed': "var(--ds-link-pressed, #0747A6)"
|
|
335
|
+
'color.link.pressed': "var(--ds-link-pressed, #0747A6)",
|
|
336
|
+
'color.link.visited': "var(--ds-link-visited, #403294)"
|
|
336
337
|
};
|
|
337
338
|
export var fillMap = {
|
|
338
339
|
'color.icon': "var(--ds-icon, #505F79)",
|