@atlaskit/primitives 1.10.1 → 1.11.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @atlaskit/primitives
 
+## 1.11.0
+
+### Minor Changes
+
+- [#43366](https://bitbucket.org/atlassian/atlassian-frontend/pull-requests/43366) [`f1d3719ea48`](https://bitbucket.org/atlassian/atlassian-frontend/commits/f1d3719ea48) - Tokenised values are now accepted in all border-radius, border-width, border-color, and opacity CSS properties in XCSS.
+
 ## 1.10.1
 
 ### Patch Changes

package/constellation/box/examples.mdx

@@ -8,6 +8,7 @@ import BoxBasic from '../../examples/constellation/box/basic';
 import BoxPadding from '../../examples/constellation/box/padding';
 import BoxBackgroundColor from '../../examples/constellation/box/background-color';
 import BoxXcss from '../../examples/constellation/box/xcss';
+import BoxConditional from '../../examples/constellation/box/conditional-styles';
 import BoxPracticalUseCase from '../../examples/constellation/box/practical-use-case';
 
 import { CodeDocsHeader } from '@af/design-system-docs-ui';
@@ -20,38 +21,45 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 ## Basic
 
-Box is a general-purpose container that allows for controlled use of design tokens. Use the given props to configure display behaviour and styling that aligns with the Atlassian Design System.
-[To learn more about styling primitive components visit our `xcss` documentation.](/components/primitives/xcss/usage)
+Box is a general-purpose container that allows for controlled use of design tokens. Use the given props to configure display behavior and styling that aligns with the Atlassian Design System.
+Use [XCSS](/components/primitives/xcss/usage) to style primitive components safely with tokens.
 
 <Example Component={BoxBasic} packageName="@atlaskit/primitives/box" />
 
 ## Padding
 
-Padding props can be used to access spacing design tokens and control internal layout. The following example demonstrates how each prop works with space tokens.
+Use padding props to access spacing design tokens and control internal layout. The following example demonstrates how each prop works with space tokens.
 
 <Example Component={BoxPadding} packageName="@atlaskit/primitives/box" />
 
-The nomenclature used by these props follows [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties). This naming is used to support different [writing modes](https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode) in our products.
+The nomenclature used by these props follows [logical properties](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Logical_Properties). This naming is used to support different [writing modes](https://developer.mozilla.org/en-US/docs/Web/CSS/writing-mode) in Atlassian products.
 
 ## Background color
 
-`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/).
+Box accepts a wide variety of background colors, referenced as semantic design tokens. For the full list of color tokens, visit the [token list](/components/tokens/all-tokens).
 
 <Example
   Component={BoxBackgroundColor}
   packageName="@atlaskit/primitives/box"
 />
 
-## xcss
+## XCSS
 
 Box exposes an `xcss` prop. This prop accepts `xcss` function calls that contain a subset of permitted styles. When used with `Box`, `xcss` accepts most CSS properties, and when a token exists, the rule accepts that token as a value.
-For more information on xcss, see the dedicated [xcss documentation](/components/primitives/xcss).
+
+For more information on XCSS, see the dedicated [XCSS documentation](/components/primitives/xcss).
 
 <Example Component={BoxXcss} packageName="@atlaskit/primitives/box" />
 
+## Conditional styles
+
+To achieve conditional styles, it is usually simpler to apply conditional behavior at the `xcss` object level, rather than applying conditional behavior to individual properties.
+
+<Example Component={BoxConditional} packageName="@atlaskit/primitives/box" />
+
 ## Practical use case
 
-`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.
+Box is designed to be used in conjunction with the inline and stack components to create layouts. This example demonstrates how these can be used to create familiar components and patterns.
 
 <Example
   Component={BoxPracticalUseCase}

package/constellation/box/usage.mdx

@@ -4,12 +4,19 @@ description: A box is a generic container that provides managed access to design
 order: 2
 ---
 
-A `Box` is a generic container with convenient and managed access to design tokens, and built-in guidance for the best practices of the Atlassian Design System.
+A box is a generic container that provides convenient and managed access to design tokens, and built-in guidance for the best practices of the Atlassian Design System. Use box in conjunction with other layout components such as [inline](/components/primitives/inline/usage) and [stack](/components/primitives/stack/usage) to easily create customized layouts.
+
 Use a box to compose layouts and add styling to child elements through visual props, including spacing and color through design tokens.
 
+## Using box
+
+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.
+
+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, use [inline](/components/primitives/inline/usage) and [stack](/components/primitives/stack/usage) to manage horizontal and vertical layouts, respectively.
+
 ## Styling
 
-Display behavior is set by using the available props or using `xcss`. Makers can make design decisions for box by setting:
+Display behavior is set by using the available props or using [XCSS](/components/primitives/xcss/usage). Makers can make design decisions for box by setting:
 
 - `padding`
 - `paddingInline`
@@ -20,15 +27,8 @@ Display behavior is set by using the available props or using `xcss`. Makers can
 - `paddingBlockEnd`
 - `backgroundColor`
 
-## Using box
-
-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.
-`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.
-
 ## Related
 
-- [Learn more about the Inline primitive](/components/primitives/inline/usage)
-- [Learn more about the Stack primitive](/components/primitives/stack/usage)
-- [Learn more about the Grid primitive](/components/primitives/grid/examples)
-- [Learn more about the Bleed primitive](/components/primitives/bleed/examples)
-- [Learn more about the Flex primitive](/components/primitives/flex/examples)
+- [Manage horizontal layout using an inline component](/components/primitives/inline/usage)
+- [Manage vertical layout using a stack component](/components/primitives/stack/usage)
+- [Use design tokens in code with XCSS](/components/primitives/XCSS/usage)

package/constellation/inline/examples.mdx

@@ -26,7 +26,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 ## Basic
 
-Inline should be used to layout a group of elements horizontally.
+Use an inline component to configure the layout of a group of elements horizontally.
 
 Use the given props to configure display behavior using design tokens, as shown in the more complex examples below.
 
@@ -34,7 +34,7 @@ Use the given props to configure display behavior using design tokens, as shown
 
 ## Space
 
-Spacing between items can be controlled with the `space` prop:
+Control the spacing between items with the `space` prop.
 
 <Example
   Component={InlineSpaceBasic}
@@ -50,6 +50,16 @@ For a different space value between rows use the `rowSpace` prop.
   packageName="@atlaskit/primitives/inline"
 />
 
+## Reverse content
+
+`flex-direction: `row-reverse` is a pattern that has [accessibility concerns](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction#accessibility_concerns) so inline doesn't support it.
+
+If reversing content is required, we generally recommend to use JavaScript to reverse the JSX content thereby preserving the tabbing order.
+
+In situations where tabbing order changes based on different breakpoints, then we have [show](/components/primitives/responsive/hide/examples) and [hide](/components/primitives/responsive/hide/examples) components that enable switching between different orderings of content.
+
+For non-tabbable content that needs to be reversed, `flex-direction: row-reverse` is supported in XCSS. However, please be aware that we may lint against this in the future.
+
 ## Alignment
 
 To control the alignment of items you can use the `alignBlock` and `alignInline` props which control alignment in the vertical and horizontal axis respectively.
@@ -76,7 +86,7 @@ Elements can be set to stay together, spaced at the given value (default behavio
 
 ## Wrap
 
-When the number of items goes beyond the available space `shouldWrap` can be used to create new rows of content.
+When the number of items goes beyond the available space, use `shouldWrap` to create new rows of content.
 
 <Example Component={InlineWrap} packageName="@atlaskit/primitives/inline" />
 
@@ -92,7 +102,7 @@ For logically related elements it's possible to specify a `separator` character
 ## Width control
 
 By default an `Inline` will have its width influenced by the context where it appears.
-To control the width, the `grow` prop can be used with the values:
+To control the width, use the `grow` prop with the values:
 
 - `hug` (default) to use space only as required by its children, or
 - `fill` to take all space provided by the parent element.
@@ -107,7 +117,7 @@ It's possible to control the rendered HTML element with the `as` prop.
 
 ## Practical use case
 
-An example of how an `Inline` might be used in product, using Atlassian Design System components.
+An example of how an inline component might be used in product, using Atlassian Design System components.
 
 <Example
   Component={InlinePracticalUseCase}

package/constellation/inline/usage.mdx

@@ -4,11 +4,11 @@ description: An inline manages the horizontal layout of direct children using fl
 order: 2
 ---
 
-Primitive components act as building blocks for composing a user experience. Use the inline primitive to lay out UI elements horizontally using built-in design guidance from the Atlassian Design System.
+Use the inline component in conjunction with other layout components such as [box](/components/primitives/box/usage) and [stack](/components/primitives/stack/usage) to easily create customized layouts, with built-in guidance from the Atlassian Design System.
 
-Inline primitives work as you might expect, aligning content horizontally across a page or layout, as a container that decides the horizontal layout of its children. Inline components also decide the specifics of how the children are displayed, for example, where they are aligned or how much space is between child elements. Inline should be used purely for visual alignment, and should have no opinions about the functionality of its children.
+Inline components act as container to decide the horizontal layout of its children. They decide the specifics of how the children are displayed, for example, where they are aligned or how much space is between child elements. An inline component should be used purely for visual alignment, and should have no opinions about the functionality of its children.
 
-In its simplest form, `Inline` operates like a flexbox row, however adds the built in design token support and guidance.
+In its simplest form, an inline component operates like a flexbox row, however adds the built in design token support and guidance.
 
 ```jsx
 <Inline space="space.100" alignInline="center" alignBlock="start">
@@ -18,11 +18,11 @@ In its simplest form, `Inline` operates like a flexbox row, however adds the bui
 
 Inline also has a `flex-direction: row;`. This is the default for flexbox, so it is not explicitly applied.
 
-## Use inline
+## Using inline
 
-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.
+The purpose of an inline is primarily as a container element controlling how child components are displayed and positioned horizontally. An inline should be used any time you wish to layout elements or components horizontally.
 
-The inline props can then be used to customize the spacing and styling on any child elements. These include:
+Use the inline props to customize the spacing and styling on any child elements. These include:
 
 - `alignBlock`
 - `alignInline`
@@ -35,9 +35,6 @@ The inline props can then be used to customize the spacing and styling on any ch
 
 ## Related
 
-- [Primitives](/components/primitives/overview)
-- [Box](/components/primitives/box/usage)
-- [Stack](/components/primitives/stack/usage)
-- [Grid](/components/primitives/grid/examples)
-- [Bleed](/components/primitives/bleed/examples)
-- [Flex](/components/primitives/flex/examples)
+- [Use box for a generic container with access to design tokens](/components/primitives/box/usage)
+- [Manage vertical layout using a stack component](/components/primitives/stack/usage)
+- [Use design tokens in code with XCSS](/components/primitives/XCSS/usage)

package/constellation/stack/examples.mdx

@@ -23,20 +23,31 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 ## Basic
 
-Stack should be used to efficiently lay-out a group of elements vertically.
+Use a stack component to efficiently lay-out a group of elements vertically.
+
 Use the given props to configure display behavior using designs tokens, as shown in the more complex examples below.
 
 <Example Component={StackBasic} packageName="@atlaskit/primitives/stack" />
 
 ## Space
 
-Spacing between items can be controlled with the `space` prop.
+Control spacing between items with the `space` prop.
 
 <Example Component={StackSpaceBasic} packageName="@atlaskit/primitives/stack" />
 
+## Reverse content
+
+`flex-direction: `column-reverse` is a pattern that has [accessibility concerns](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction#accessibility_concerns) so stack doesn't support it.
+
+If reversing content is required, we generally recommend to use JavaScript to reverse the JSX content thereby preserving the tabbing order.
+
+In situations where tabbing order changes based on different breakpoints, then we have [show](/components/primitives/responsive/show/examples) and [hide](/components/primitives/responsive/hide/examples) components that enable switching between different orderings of content.
+
+For non-tabbable content that needs to be reversed, `flex-direction: column-reverse` is supported in XCSS. However, please be aware that we may lint against this in the future.
+
 ## Alignment
 
-To control the alignment of items you can use the `alignBlock` and `alignInline` props which control alignment in the vertical and horizontal axis respectively.
+Control the alignment of items using the `alignBlock` and `alignInline` props which control alignment in the vertical and horizontal axis respectively.
 
 ### Block alignment
 
@@ -51,15 +62,13 @@ To control the alignment of items you can use the `alignBlock` and `alignInline`
 
 ## Spread
 
-Elements can be set to stay together, spaced at the given value (default behavior) or spread equally in the space available.
+Use the `spread` prop to set elements to stay together, spaced at the given value (default behavior) or spread equally in the space available.
 
 <Example Component={StackSpread} packageName="@atlaskit/primitives/stack" />
 
 ## Width control
 
-By default a `Stack` will have its width influenced by the context where it appears. To control the width the `grow` prop can be used with the values:
-
-To control that the `grow` prop can be used with the values:
+By default a `Stack` will have its width influenced by the context where it appears. To control the width use the `grow` prop with the values:
 
 - `hug` (default) to use space only as required by its children, or
 - `fill` to take all space provided by the parent element.
@@ -74,6 +83,8 @@ It's possible to control the rendered HTML element with the `as` prop.
 
 ## Practical use case
 
+An example of how a stack component might be used in product, using Atlassian Design System components.
+
 <Example
   Component={StackPracticalUseCase}
   packageName="@atlaskit/primitives/stack"

package/constellation/stack/usage.mdx

@@ -4,9 +4,9 @@ description: A stack manages the vertical layout of direct children using flexbo
 order: 2
 ---
 
-Primitive components are building blocks for composing a user experience. A `Stack` primitive lays out UI elements vertically, and makes use of the built-in design guidance from the Atlassian Design System.
+Use the stack component in conjunction with other layout components such as [box](/components/primitives/box/usage) and [inline](/components/primitives/inline/usage) to easily create customized layouts, with built-in guidance from the Atlassian Design System.
 
-Stacks work by aligning content vertically on a page or layout, as a container that decides the vertical layout of its children. Stack components also decide the specifics of how the children are displayed, for example, where they are aligned or how much space is between child elements. Stack is purely for visual alignment, and should have no opinions about the functionality of its children.
+A stack component aligns content vertically on a page or layout, acting as a container that decides the vertical layout of its children. Stack components also decide the specifics of how the children are displayed, for example, where they are aligned or how much space is between child elements. Stack is purely for visual alignment, and should have no opinions about the functionality of its children.
 
 In its simplest form, `Stack` works like a flexbox column, with built-in design token support and guidance.
 
@@ -16,9 +16,9 @@ In its simplest form, `Stack` works like a flexbox column, with built-in design
 </Stack>
 ```
 
-## Usage
+## Using stack
 
-A `Stack` is primarily a container element controlling how content is displayed and aligned vertically. Use stack any time you wish to lay out elements or components vertically.
+A stack is primarily a container element controlling how content is displayed and aligned vertically. Use stack any time you wish to lay out elements or components vertically.
 
 These props customize the spacing and styling of any child elements:
 
@@ -30,9 +30,6 @@ These props customize the spacing and styling of any child elements:
 
 ## Related
 
-- [Primitives](/components/primitives/overview)
-- [Box](/components/primitives/box/usage)
-- [Inline](/components/primitives/inline/usage)
-- [Grid](/components/primitives/grid/examples)
-- [Bleed](/components/primitives/bleed/examples)
-- [Flex](/components/primitives/flex/examples)
+- [Use box for a generic container with access to design tokens](/components/primitives/box/usage)
+- [Manage horizontal layout using an inline component](/components/primitives/inline/usage)
+- [Use design tokens in code with XCSS](/components/primitives/XCSS/usage)

package/constellation/xcss/examples.mdx

@@ -1,6 +1,6 @@
 ---
 title: XCSS
-description: xcss is a safer, tokens-first approach to CSS-in-JS.
+description: XCSS is a safer, tokens-first approach to CSS-in-JS.
 order: 1
 ---
 
@@ -19,7 +19,7 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 ## Basic
 
-`xcss` can pull together different types of interactions and UI in a safer, more composable way.
+XCSS can pull together different types of interactions and UI in a safer, more composable way.
 
 <Example Component={xcssBasic} packageName="@atlaskit/primitives/xcss" />
 
@@ -31,7 +31,7 @@ To enable interactivity, use familiar selectors like `:hover` and `:focus-visibl
 
 ## Responsiveness
 
-`xcss` also accepts a subset of media queries at [predefined breakpoints](/components/primitives/responsive/breakpoints/examples).
+XCSS also accepts a subset of media queries at [predefined breakpoints](/components/primitives/responsive/breakpoints/examples).
 
 <Example Component={xcssResponsive} packageName="@atlaskit/primitives/xcss" />
 

package/constellation/xcss/migration.mdx

@@ -1,6 +1,6 @@
 ---
 title: Migrating your app to XCSS
-description: xcss is a safer, tokens-first approach to CSS-in-JS.
+description: XCSS is a safer, tokens-first approach to CSS-in-JS.
 order: 2
 ---
 
@@ -8,9 +8,9 @@ order: 2
 
 ### Changes for developers
 
-There are two key changes to be mindful of when migrating to `xcss`.
+There are two key changes to be mindful of when migrating to XCSS.
 The first is updating callsites to remove any nested styles and
-tokenised values.
+tokenized values.
 
 ```diff
 - import { css } from '@emotion/react';
@@ -21,13 +21,12 @@ tokenised values.
   // token based properties will no longer need to be wrapped
 - padding: token('space.100'),
 + padding: 'space.100'
-  // no change is required for non-tokenised values
+  // no change is required for non-tokenized values
   transform: 'scale(2)'
 });
 ```
 
-The second change is that for the `xcss` function to be applied correctly it must be applied on a
-component with an `xcss` JSXAttribute. This won't work with the `css` or `className`
+The second change is that for the `xcss` function to be applied correctly it must be applied on a component with an `xcss` JSXAttribute. This won't work with the `css` or `className`
 JSXAttributes, be aware if you're not seeing your styles appear.
 
 ```diff
@@ -35,9 +34,9 @@ JSXAttributes, be aware if you're not seeing your styles appear.
 + <Box xcss={someStyles} />
 ```
 
-#### Changing the way you express styles
+### Changing the way you express styles
 
-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:
+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:
 
 ```tsx
 const myComponentStyles = css({
@@ -77,13 +76,13 @@ const MyComponent = () => (
 
 There will likely be cases where nesting is the only option. While not desirable, nesting can be used minimally, and when the potential impact is considered.
 
-### FAQ
+## FAQ
 
-Migration to `xcss` is simple for the majority of cases. Here are some common strategies for migrations.
+Migration to XCSS is simple for the majority of cases. Here are some common strategies for migrations.
 
-#### Non-tokenised values
+### Non-tokenized values
 
-Before migrating to tokens, there are two options. Migrate to tokens first and then on a second pass migrate to `xcss` or make the jump directly to use both tokens and `xcss`.
+Before migrating to tokens, there are two options. Migrate to tokens first and then on a second pass migrate to XCSS or make the jump directly to use both tokens and XCSS.
 
 ```tsx
 const someStyles = css({
@@ -101,10 +100,10 @@ const someStyles = xcss({
 });
 ```
 
-#### Moving from the `styled` API
+### Moving from the `styled` API
 
 If currently using the `styled` API there are a few steps to migrate.
-The safest approach is to use object styles, migrate to tokens (optionally) and then migrate to `xcss`.
+The safest approach is to use object styles, migrate to tokens (optionally) and then migrate to XCSS.
 
 ```tsx
 const MyComponent = styled.div`
@@ -128,9 +127,3 @@ const myComponentStyles = xcss({
 
 const MyComponent = () => <Box xcss={myComponentStyles} />
 ```
-
-## Get help
-
-- Atlassians can reach out in [Slack](slack://channel?team=TFCUTJ0G5&id=CFJ9DU39U) for help with `xcss` migration.
-- Other developers who need help with tokens or the `xcss` utility can post in the [public developer community](https://community.developer.atlassian.com/).
-- For general help with the Atlassian Design System, [contact us](/resources/contact-us).

package/constellation/xcss/usage.mdx

@@ -6,20 +6,20 @@ order: 0
 
 import { MediaQueriesTable } from '@af/design-system-docs-ui';
 
-`xcss` is an Atlassian Design System styling API that natively integrates with Atlassian's [design tokens](/tokens) and [primitives](/components/primitives).
+XCSS is an Atlassian Design System styling API that natively integrates with Atlassian's [design tokens](/tokens) and [primitives](/components/primitives).
 
-The `xcss` utility behaves similarly to the `css` utility in libraries like `styled-components`, `@compiled` or `@emotion`. If you've used these libraries, `xcss` will feel familiar, with a few additional features and constraints.
+The XCSS utility behaves similarly to the `css` utility in libraries like `styled-components`, `@compiled` or `@emotion`. If you've used these libraries, XCSS will feel familiar, with a few additional features and constraints.
 
 Familiar features:
 
-- `xcss` generates a `className` that is applied to the components
-- `xcss` provides key-value pairs of CSS properties in an object format
-- `xcss` supports style precedence and conditional styles
+- XCSS generates a `className` that is applied to the components
+- XCSS provides key-value pairs of CSS properties in an object format
+- XCSS supports style precedence and conditional styles
 
 Key differences:
 
-- `xcss` has type-safety that ensures token name usage for all CSS properties represented by design tokens.
-- `xcss` restricts nested selectors completely from usage
+- XCSS has type-safety that ensures token name usage for all CSS properties represented by design tokens.
+- XCSS restricts nested selectors completely from usage
 
 ## Usage
 
@@ -55,7 +55,7 @@ It is important to note that styles generated from `xcss` cannot be applied dire
 
 ### Type safety
 
-`xcss` uses strongly-typed values generated from design token definitions, making it simpler to apply the right token to the right CSS property.
+XCSS uses strongly-typed values generated from design token definitions, making it simpler to apply the right token to the right CSS property.
 This is intended to be more ergonomic and intuitive, but also prevent the misapplication of tokens to the wrong properties.
 
 Any [valid token name](/components/tokens/all-tokens) is available to be applied against its
@@ -75,7 +75,7 @@ const someStyles = xcss({
 
 ### Restricted nesting
 
-`xcss` is flexible enough to implement any design, but it does restrict the application of styles in one key way.
+XCSS is flexible enough to implement any design, but it does restrict the application of styles in one key way.
 Selectors cannot be nested or target elements beyond the element on which styles are applied.
 This restriction is intended to encourage better component encapsulation, reduce side-effects and make the codebase more resilient to change.
 
@@ -99,19 +99,20 @@ const someStyles = xcss({
 ```
 
 These unsafe selectors will throw a type error if applied.
-For richer examples of how to use `xcss` please see the [primitives `xcss` documentation](/components/primitives/xcss/examples).
+Find richer examples of how to use XCSS in the [XCSS examples](/components/primitives/xcss/examples).
 
 ### Media Queries
 
-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:
+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:
 
 <MediaQueriesTable />
 
-Media queries can be applied through keys that can be imported from `@atlaskit/primitives/responsive`.
-For in depth examples on how to enable responsive behavior, please see our [primitive responsiveness documentation](/components/primitives/xcss/examples#responsiveness).
+Media queries can be applied through keys imported from `@atlaskit/primitives/responsive`.
+Find more in depth examples on how to enable responsive behavior in the [responsive documentation](/components/primitives/xcss/examples#responsiveness).
 
-The objects defined at each breakpoint behave in much the same way as a normal xcss object, and can apply responsiveness to any CSS.
+The objects defined at each breakpoint behave in much the same way as a normal XCSS object, and can apply responsiveness to any CSS.
 The only limitation is that a media query can't contain another media query. This is to prevent arbitrary nesting.
+
 Additionally, pseudo-selectors can't contain media queries. To use media queries and pseudos, the media query must contain the pseudo.
 
 ```
@@ -142,8 +143,8 @@ const someStyles = xcss({
 });
 ```
 
-## Get help
+## Related
 
-- Atlassians can reach out in [Slack](slack://channel?team=TFCUTJ0G5&id=CFJ9DU39U) for help with `xcss` migration.
-- Other developers who need help with tokens or the `xcss` utility can post in the [public developer community](https://community.developer.atlassian.com/).
-- For general help with the Atlassian Design System, [contact us](/resources/contact-us).
+- [Use box for a generic container with access to design tokens](/components/primitives/box/usage)
+- [Manage horizontal layout using an inline component](/components/primitives/inline/usage)
+- [Manage vertical layout using a stack component](/components/primitives/stack/usage)

package/dist/cjs/xcss/style-maps.partial.js

@@ -4,7 +4,7 @@ var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefau
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.uiTextStylesMap = exports.uiTextMap = exports.textColorStylesMap = exports.textColorMap = exports.surfaceColorStylesMap = exports.surfaceColorMap = exports.spaceStylesMap = exports.spaceMap = exports.shadowMap = exports.paddingStylesMap = exports.negativeSpaceMap = exports.lineHeightStylesMap = exports.lineHeightMap = exports.layerMap = exports.isSurfaceColorToken = exports.inverseColorMap = exports.fontWeightStylesMap = exports.fontWeightMap = exports.fontSizeStylesMap = exports.fontSizeMap = exports.fontFamilyStylesMap = exports.fontFamilyMap = exports.fillMap = exports.dimensionMap = exports.borderWidthMap = exports.borderRadiusMap = exports.borderColorMap = exports.bodyTextStylesMap = exports.bodyTextMap = exports.backgroundColorStylesMap = exports.backgroundColorMap = void 0;
+exports.uiTextStylesMap = exports.uiTextMap = exports.textColorStylesMap = exports.textColorMap = exports.surfaceColorStylesMap = exports.surfaceColorMap = exports.spaceStylesMap = exports.spaceMap = exports.shadowMap = exports.paddingStylesMap = exports.opacityMap = exports.negativeSpaceMap = exports.lineHeightStylesMap = exports.lineHeightMap = exports.layerMap = exports.isSurfaceColorToken = exports.inverseColorMap = exports.fontWeightStylesMap = exports.fontWeightMap = exports.fontSizeStylesMap = exports.fontSizeMap = exports.fontFamilyStylesMap = exports.fontFamilyMap = exports.fillMap = exports.dimensionMap = exports.borderWidthMap = exports.borderRadiusMap = exports.borderColorMap = exports.bodyTextStylesMap = exports.bodyTextMap = exports.backgroundColorStylesMap = exports.backgroundColorMap = void 0;
 var _defineProperty2 = _interopRequireDefault(require("@babel/runtime/helpers/defineProperty"));
 var _react = require("@emotion/react");
 var _tokens = require("@atlaskit/tokens");
@@ -111,10 +111,45 @@ var inverseColorMap = exports.inverseColorMap = {
 
 /**
  * THIS SECTION WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
- * @codegen <<SignedSource::4f49a5a763f3c327f1d7ce5f2d030194>>
+ * @codegen <<SignedSource::8c10abde8168de6260b5aa120dd948bc>>
+ * @codegenId elevation
+ * @codegenCommand yarn workspace @atlaskit/primitives codegen-styles
+ * @codegenParams ["opacity", "shadow", "surface"]
+ * @codegenDependency ../../../tokens/src/artifacts/tokens-raw/atlassian-light.tsx <<SignedSource::f1021f8d47ab63374e371ce18db72a1c>>
+ */
+var opacityMap = exports.opacityMap = {
+  'opacity.disabled': "var(--ds-opacity-disabled, 0.4)",
+  'opacity.loading': "var(--ds-opacity-loading, 0.2)"
+};
+var shadowMap = exports.shadowMap = {
+  'elevation.shadow.overflow': "var(--ds-shadow-overflow, 0px 0px 8px #091e423f, 0px 0px 1px #091e424f)",
+  'elevation.shadow.overflow.perimeter': "var(--ds-shadow-overflow-perimeter, #091e421f)",
+  'elevation.shadow.overflow.spread': "var(--ds-shadow-overflow-spread, #091e4229)",
+  'elevation.shadow.overlay': "var(--ds-shadow-overlay, 0px 8px 12px #091e423f, 0px 0px 1px #091e424f)",
+  'elevation.shadow.raised': "var(--ds-shadow-raised, 0px 1px 1px #091e423f, 0px 0px 1px #091e4221)"
+};
+var surfaceColorMap = exports.surfaceColorMap = {
+  'elevation.surface': "var(--ds-surface, #FFFFFF)",
+  'elevation.surface.hovered': "var(--ds-surface-hovered, #FAFBFC)",
+  'elevation.surface.pressed': "var(--ds-surface-pressed, #F4F5F7)",
+  'elevation.surface.overlay': "var(--ds-surface-overlay, #FFFFFF)",
+  'elevation.surface.overlay.hovered': "var(--ds-surface-overlay-hovered, #FAFBFC)",
+  'elevation.surface.overlay.pressed': "var(--ds-surface-overlay-pressed, #F4F5F7)",
+  'elevation.surface.raised': "var(--ds-surface-raised, #FFFFFF)",
+  'elevation.surface.raised.hovered': "var(--ds-surface-raised-hovered, #FAFBFC)",
+  'elevation.surface.raised.pressed': "var(--ds-surface-raised-pressed, #F4F5F7)",
+  'elevation.surface.sunken': "var(--ds-surface-sunken, #F4F5F7)"
+};
+/**
+ * @codegenEnd
+ */
+
+/**
+ * THIS SECTION WAS CREATED VIA CODEGEN DO NOT MODIFY {@see http://go/af-codegen}
+ * @codegen <<SignedSource::0f7982208166d5dae0e25517d29aeaef>>
  * @codegenId colors
  * @codegenCommand yarn workspace @atlaskit/primitives codegen-styles
- * @codegenParams ["border", "background", "shadow", "text", "fill", "surface"]
+ * @codegenParams ["border", "background", "text", "fill"]
  * @codegenDependency ../../../tokens/src/artifacts/tokens-raw/atlassian-light.tsx <<SignedSource::f1021f8d47ab63374e371ce18db72a1c>>
  */
 var borderColorMap = exports.borderColorMap = {
@@ -339,13 +374,6 @@ var backgroundColorMap = exports.backgroundColorMap = {
   'elevation.surface.sunken': "var(--ds-surface-sunken, #F4F5F7)",
   'utility.elevation.surface.current': "var(--ds-elevation-surface-current, #FFFFFF)"
 };
-var shadowMap = exports.shadowMap = {
-  'elevation.shadow.overflow': "var(--ds-shadow-overflow, 0px 0px 8px #091e423f, 0px 0px 1px #091e424f)",
-  'elevation.shadow.overflow.perimeter': "var(--ds-shadow-overflow-perimeter, #091e421f)",
-  'elevation.shadow.overflow.spread': "var(--ds-shadow-overflow-spread, #091e4229)",
-  'elevation.shadow.overlay': "var(--ds-shadow-overlay, 0px 8px 12px #091e423f, 0px 0px 1px #091e424f)",
-  'elevation.shadow.raised': "var(--ds-shadow-raised, 0px 1px 1px #091e423f, 0px 0px 1px #091e4221)"
-};
 var textColorMap = exports.textColorMap = {
   'color.text': "var(--ds-text, #172B4D)",
   'color.text.accent.lime': "var(--ds-text-accent-lime, #4C6B1F)",
@@ -408,18 +436,6 @@ var fillMap = exports.fillMap = {
   'color.icon.information': "var(--ds-icon-information, #0747A6)",
   'color.icon.subtle': "var(--ds-icon-subtle, #6B778C)"
 };
-var surfaceColorMap = exports.surfaceColorMap = {
-  'elevation.surface': "var(--ds-surface, #FFFFFF)",
-  'elevation.surface.hovered': "var(--ds-surface-hovered, #FAFBFC)",
-  'elevation.surface.pressed': "var(--ds-surface-pressed, #F4F5F7)",
-  'elevation.surface.overlay': "var(--ds-surface-overlay, #FFFFFF)",
-  'elevation.surface.overlay.hovered': "var(--ds-surface-overlay-hovered, #FAFBFC)",
-  'elevation.surface.overlay.pressed': "var(--ds-surface-overlay-pressed, #F4F5F7)",
-  'elevation.surface.raised': "var(--ds-surface-raised, #FFFFFF)",
-  'elevation.surface.raised.hovered': "var(--ds-surface-raised-hovered, #FAFBFC)",
-  'elevation.surface.raised.pressed': "var(--ds-surface-raised-pressed, #F4F5F7)",
-  'elevation.surface.sunken': "var(--ds-surface-sunken, #F4F5F7)"
-};
 /**
  * @codegenEnd
  */