@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.
Files changed (51) hide show
  1. package/CHANGELOG.md +96 -83
  2. package/constellation/bleed/code.mdx +1 -1
  3. package/constellation/box/code.mdx +1 -1
  4. package/constellation/box/examples.mdx +5 -1
  5. package/constellation/box/usage.mdx +3 -0
  6. package/constellation/flex/code.mdx +1 -1
  7. package/constellation/flex/examples.mdx +5 -3
  8. package/constellation/grid/code.mdx +1 -1
  9. package/constellation/grid/examples.mdx +4 -3
  10. package/constellation/inline/code.mdx +1 -1
  11. package/constellation/inline/examples.mdx +27 -10
  12. package/constellation/inline/usage.mdx +2 -0
  13. package/constellation/overview/index.mdx +8 -1
  14. package/constellation/responsive/01-show/code.mdx +1 -1
  15. package/constellation/responsive/01-show/examples.mdx +8 -3
  16. package/constellation/responsive/02-hide/code.mdx +1 -1
  17. package/constellation/responsive/02-hide/examples.mdx +8 -2
  18. package/constellation/responsive/03-breakpoints/examples.mdx +1 -1
  19. package/constellation/responsive/examples.mdx +9 -6
  20. package/constellation/stack/code.mdx +1 -1
  21. package/constellation/stack/examples.mdx +10 -4
  22. package/constellation/stack/usage.mdx +3 -0
  23. package/constellation/xcss/examples.mdx +0 -1
  24. package/constellation/xcss/migration.mdx +4 -6
  25. package/constellation/xcss/usage.mdx +20 -16
  26. package/dist/cjs/xcss/style-maps.partial.js +4 -3
  27. package/dist/es2019/xcss/style-maps.partial.js +4 -3
  28. package/dist/esm/xcss/style-maps.partial.js +4 -3
  29. package/dist/types/xcss/style-maps.partial.d.ts +3 -2
  30. package/dist/types-ts4.5/xcss/style-maps.partial.d.ts +3 -2
  31. package/package.json +3 -14
  32. package/report.api.md +1 -0
  33. package/scripts/__tests__/__snapshots__/codegen.test.tsx.snap +1 -0
  34. package/scripts/typography-codegen-template.tsx +1 -1
  35. package/tmp/api-report-tmp.d.ts +1 -0
  36. package/constellation/heading/code.mdx +0 -19
  37. package/constellation/heading/examples.mdx +0 -28
  38. package/constellation/heading/usage.mdx +0 -21
  39. package/dist/cjs/components/heading-context.js +0 -44
  40. package/dist/cjs/components/heading.js +0 -95
  41. package/dist/es2019/components/heading-context.js +0 -35
  42. package/dist/es2019/components/heading.js +0 -87
  43. package/dist/esm/components/heading-context.js +0 -34
  44. package/dist/esm/components/heading.js +0 -87
  45. package/dist/types/components/heading-context.d.ts +0 -31
  46. package/dist/types/components/heading.d.ts +0 -45
  47. package/dist/types-ts4.5/components/heading-context.d.ts +0 -31
  48. package/dist/types-ts4.5/components/heading.d.ts +0 -45
  49. package/extract-react-types/heading-props.tsx +0 -3
  50. package/heading/package.json +0 -15
  51. 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 Component={BoxBackgroundColor} packageName="@atlaskit/primitives/box" />
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 Component={FlexJustifyContent} packageName="@atlaskit/primitives/flex" />
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
- * [responsive layout grid](/components/grid)
66
- * [legacy page grid](/components/page/grid)
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 Component={InlineSpaceBasic} packageName="@atlaskit/primitives/inline" />
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 Component={InlineSpaceWrap} packageName="@atlaskit/primitives/inline" />
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 Component={InlineAlignBlock} packageName="@atlaskit/primitives/inline" />
59
+ <Example
60
+ Component={InlineAlignBlock}
61
+ packageName="@atlaskit/primitives/inline"
62
+ />
55
63
 
56
64
  ### Inline alignment
57
65
 
58
- <Example Component={InlineAlignInline} packageName="@atlaskit/primitives/inline" />
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 Component={InlineSeparator} packageName="@atlaskit/primitives/inline" />
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
- * `hug` (default) to use space only as required by its children, or
84
- * `fill` to take all space provided by the parent element.
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 Component={InlinePracticalUseCase} packageName="@atlaskit/primitives/inline" />
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 <a href="/components/eslint-plugin-design-system/usage#use-primitives">use-primitives</a> offers suggestions for possible primitives to apply in a layout.
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 Component={ShowExample} packageName="@atlaskit/primitives/responsive" />
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 Component={ShowHideExample} packageName="@atlaskit/primitives/responsive" />
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 Component={HideExample} packageName="@atlaskit/primitives/responsive" />
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 Component={ShowHideExample} packageName="@atlaskit/primitives/responsive" />
33
+ <Example
34
+ Component={ShowHideExample}
35
+ packageName="@atlaskit/primitives/responsive"
36
+ />
@@ -15,7 +15,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
15
15
  />
16
16
 
17
17
  ### Media Queries
18
- Media queries can be applied through the `media` object.
19
18
 
19
+ Media queries can be applied through the `media` object.
20
20
 
21
21
  <MediaQueriesTable />
@@ -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. Read more at [xcss](/components/primitives/xcss)
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 Component={XCSSExample} packageName="@atlaskit/primitives/responsive" />
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
- * [Show](/components/primitives/responsive/show)
40
- * [Hide](/components/primitives/responsive/hide)
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 Component={StackAlignInline} packageName="@atlaskit/primitives/stack" />
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
- * `hug` (default) to use space only as required by its children, or
62
- * `fill` to take all space provided by the parent element.
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 Component={PracticalUseCase} packageName="@atlaskit/primitives/stack" />
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
- * Atlassians can reach out in [Slack](slack://channel?team=TFCUTJ0G5&id=CFJ9DU39U) for help with `xcss` migration.
137
- * Other developers who need help with tokens or the `xcss` utility can post in the [public developer community](https://community.developer.atlassian.com/).
138
- * For general help with the Atlassian Design System, [contact us](/resources/contact-us).
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
- ![xcss Logo](logo.png "xcss Logo")
9
+ ![xcss Logo](logo.png 'xcss Logo')
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
- * `xcss` generates a `className` that is applied to the components
17
- * `xcss` provides key-value pairs of CSS properties in an object format
18
- * `xcss` supports style precedence and conditional styles
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
- * `xcss` has type-safety that ensures token name usage for all CSS properties represented by design tokens.
23
- * `xcss` restricts nested selectors completely from usage
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', // <--- invalid and will error
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
- * Atlassians can reach out in [Slack](slack://channel?team=TFCUTJ0G5&id=CFJ9DU39U) for help with `xcss` migration.
146
- * Other developers who need help with tokens or the `xcss` utility can post in the [public developer community](https://community.developer.atlassian.com/).
147
- * For general help with the Atlassian Design System, [contact us](/resources/contact-us).
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::3db44f53b728773bb3ba1473d4567724>>
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::815ddd719715ae06521cad06e1921e40>>
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::3db44f53b728773bb3ba1473d4567724>>
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::815ddd719715ae06521cad06e1921e40>>
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::3db44f53b728773bb3ba1473d4567724>>
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::815ddd719715ae06521cad06e1921e40>>
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)",