@atlaskit/primitives 6.5.0 → 7.0.1

package/.eslintrc.js

@@ -1,3 +1,3 @@
 module.exports = {
-  ignorePatterns: ['./scripts/codegen-file-templates/*'],
+	ignorePatterns: ['./scripts/codegen-file-templates/*'],
 };

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @atlaskit/primitives
 
+## 7.0.1
+
+### Patch Changes
+
+- [#110191](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/110191)
+  [`c3dc02298f8aa`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/c3dc02298f8aa) -
+  [ux] Change heading xsmall lineheight from 16 to 20 for minor third theme.
+- Updated dependencies
+
+## 7.0.0
+
+### Major Changes
+
+- [#108387](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/108387)
+  [`0f3b7b4c63c6d`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/0f3b7b4c63c6d) -
+  `xcss`: Restrict valid chained pseudo-selectors a limited subset:
+
+  - `:visited:active`
+  - `:active:visited`
+  - `:hover::before`
+  - `:hover::after`
+  - `:focus-visible::before`
+  - `:focus-visible::after`
+
+  Previously, any combination of two pseudo-selectors was allowed. This decision was made to improve
+  performance for TypeScript compilation and IDE type hinting.
+
 ## 6.5.0
 
 ### Minor Changes
@@ -80,7 +107,7 @@
 
 - [#93706](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/pull-requests/93706)
   [`2e4fdfa436da`](https://stash.atlassian.com/projects/CONFCLOUD/repos/confluence-frontend/commits/2e4fdfa436da) -
-  Add support for React 18.
+  Add support for React 18 in non-strict mode.
 
 ## 5.6.1
 

package/LICENSE.md

@@ -1,13 +1,11 @@
 Copyright 2022 Atlassian Pty Ltd
 
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in
+compliance with the License. You may obtain a copy of the License at
 
     http://www.apache.org/licenses/LICENSE-2.0
 
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
+Unless required by applicable law or agreed to in writing, software distributed under the License is
+distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+implied. See the License for the specific language governing permissions and limitations under the
+License.

package/constellation/anchor/code.mdx

@@ -7,9 +7,9 @@ order: 1
 import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 <CodeDocsHeader
-  name="@atlaskit/primitives"
-  repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
-  directoryName="primitives"
+	name="@atlaskit/primitives"
+	repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
+	directoryName="primitives"
 />
 
 import ERTAnchor from '!!extract-react-types-loader!../../extract-react-types/anchor-props';

package/constellation/anchor/examples.mdx

@@ -17,26 +17,31 @@ import { CodeDocsHeader } from '@af/design-system-docs-ui';
 import SectionMessage from '@atlaskit/section-message';
 
 <CodeDocsHeader
-  name="@atlaskit/primitives"
-  repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
-  directoryName="primitives"
+	name="@atlaskit/primitives"
+	repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
+	directoryName="primitives"
 />
 
-Anchor is a primitive used for building custom links with Atlassian Design System styling, routing support, and built-in event tracking. Ultimately it renders an anchor `<a>` element.
+Anchor is a primitive for building custom links with Atlassian Design System styling, routing
+support, and built-in event tracking. It renders an anchor `<a>` element.
 
-Only use anchor when existing components such as [link](/components/link/examples) or [link button](/components/button/link-button/examples) are unsuitable and unable to be customized to fit your needs.
+Only use anchor when existing components such as [link](/components/link/examples) or
+[link button](/components/button/link-button/examples) can't be customized to fit your needs.
 
 ## Default
 
-Anchor is unstyled besides a default underline. If you are using the [CSS reset](/components/css-reset/examples), it will also inherit some global styles.
+Anchor is unstyled besides a default underline and consistent Atlassian Design System `:focus`
+styles.
+
+If you are using the [CSS reset](/components/css-reset/examples), anchor will also inherit some
+global styles.
 
 <Example Component={AnchorDefault} packageName="@atlaskit/primitives/anchor" />
 
 ## Basic styling with XCSS
 
-Anchor can be styled using XCSS. It includes consistent Atlassian Design System `:focus` styles, so it's unnecessary to add your own.
-
-For more information on XCSS, see the [XCSS documentation](/components/primitives/xcss).
+Anchor can be styled further using the design system styling API,
+[XCSS](/components/primitives/xcss).
 
 <Example Component={AnchorBasic} packageName="@atlaskit/primitives/anchor" />
 
@@ -48,20 +53,24 @@ Use a combination of XCSS and other primitives for more complex designs.
 
 ## HTML attributes
 
-Anchor passes through all valid HTML attributes to the underlying `<a>` element.
+Anchor can pass all valid
+[anchor HTML attributes](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#attributes),
+such as `rel` or `download`, to the underlying `<a>` element.
 
-<Example
-  Component={AnchorHtmlAttributes}
-  packageName="@atlaskit/primitives/anchor"
-/>
+<Example Component={AnchorHtmlAttributes} packageName="@atlaskit/primitives/anchor" />
 
 ## Router links
 
-Routing libraries often supply their own link components enhanced with routing support. This can be configured in the [AppProvider context](/components/app-provider/examples#router-links), and anchor will automatically use it.
+Routing libraries often supply link components enhanced with routing support. You can configure this
+in the [AppProvider context](/components/app-provider/examples#router-links), and anchor will
+automatically use it.
 
-This example shows a configuration for [React Resource Router](https://github.com/atlassian-labs/react-resource-router), however any routing library can be used.
+This example shows a configuration for
+[React Resource Router](https://github.com/atlassian-labs/react-resource-router), however any
+routing library can be used.
 
-Using this method, anchor accepts `href` as a string for standard usage. For advanced usage, an object can be passed.
+Using this method, anchor accepts `href` as a string for standard usage. For advanced usage, an
+object can be passed.
 
 Anchor will only render a router link if:
 
@@ -70,34 +79,19 @@ Anchor will only render a router link if:
 - it's not a non-HTTP-based link (e.g. emails, phone numbers, hash links etc.).
 
 <Example
-  Component={AnchorRouterLinkConfiguration}
-  packageName="@atlaskit/primitives/anchor"
-  appearance="source-only"
+	Component={AnchorRouterLinkConfiguration}
+	packageName="@atlaskit/primitives/anchor"
+	appearance="source-only"
 />
 
-<Snippet
-  name="primitives-event-tracking-header"
-  variables={{ componentName: 'anchor' }}
-/>
+<Snippet name="primitives-event-tracking-header" variables={{ componentName: 'anchor' }} />
 
-<Example
-  Component={AnchorAnalytics}
-  packageName="@atlaskit/primitives/anchor"
-/>
+<Example Component={AnchorAnalytics} packageName="@atlaskit/primitives/anchor" />
 
 <Snippet name="primitives-event-tracking-gasv3" />
 
-<Example
-  Component={AnchorAnalyticsGASv3}
-  packageName="@atlaskit/primitives/anchor"
-/>
+<Example Component={AnchorAnalyticsGASv3} packageName="@atlaskit/primitives/anchor" />
 
-<Snippet
-  name="primitives-event-tracking-ufo"
-  variables={{ componentName: 'anchor' }}
-/>
+<Snippet name="primitives-event-tracking-ufo" variables={{ componentName: 'anchor' }} />
 
-<Example
-  Component={AnchorPressTracing}
-  packageName="@atlaskit/primitives/anchor"
-/>
+<Example Component={AnchorPressTracing} packageName="@atlaskit/primitives/anchor" />

package/constellation/anchor/usage.mdx

@@ -6,44 +6,77 @@ order: 2
 
 ## Usage
 
-Anchors help users navigate to another page or sections of a page. They can also download files or provide contact information such as phone numbers or email addresses.
+Use an anchor to make elements that work like hyperlinks. Anchors can navigate to any linkable
+location such as a web page, a location on a page, a file download, or a `mailto` email address.
 
-Anchor has consistent focus styles and analytics built in. It works with design tokens to make it easy to compose Atlassian-styled links that aren't possible using the [link component](/components/link/examples), [link buttons](/components/button/link-button/examples), or other existing design system components.
+Anchor is based on the HTML `<a>` tag, but with Atlassian focus styles and analytics events built
+in. You can customize the anchor's appearance further using our styling APIs.
 
-## Use anchor when there aren't existing components that work for your experience
+For example, an anchor could be used to make
+[a link card](/components/primitives/anchor/examples#advanced-styling) with a larger clickable area
+than a typical [link](/components/link/examples).
 
-Existing components such as the [link component](/components/link/examples) (for text-based links) should be used whenever possible for links to maintain visual consistency. Only use anchor when building custom links beyond the capabilities of the the link component.
+### Use links, link buttons, or other existing components where possible
 
-Do not use anchor to perform actions rather than navigation. Use the equivalent [pressable primitive](/components/primitives/pressable/examples) to build a custom button instead.
+Anchor is meant for custom elements and styles that aren't possible using other components. For
+standard links or buttons that navigate users to a new location, use
+[link](/components/link/examples) or [link button](/components/button/link-button/examples).
 
-## Accessibility
+Using [existing components](/components) wherever possible makes Atlassian's UI more visually
+consistent, and these components are faster to use for most basic use cases.
 
-### Underline links unless other context already indicates it is a link
+## Accessibility
 
-Anchor has an underline by default but it can be disabled in some circumstances. Underlines help differentiate links from regular text and addresses a WCAG-A recommendation. Using color alone isn't accessible, especially if links are surrounded by other text.
+### Show what's clickable using underlines or other affordances
 
-Only remove underlines if the context surrounding the link makes it clear that it is interactive, such as in navigation. Anhor may also be used to create linkable areas such as a card, in which case the underline may be omitted.
+Anchors have an underline by default. This helps differentiate links from regular text, which is an
+accessibility requirement. Using color alone to differentiate links isn't accessible, especially if
+links are surrounded by other text.
 
-Also, don't underline text that isn't a link. This makes the text look clickable because it looks a link.
+Only remove underlines if the context surrounding the link makes it clear that it's interactive,
+such as in navigation or a card layout.
 
-For more information see ['Understanding Use of Color (Level A)'](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html) and ['Failure of Success Criterion 1.4.1 due to creating links that are not visually evident without color vision'](https://www.w3.org/WAI/WCAG22/Techniques/failures/F73).
+Also, don't underline text that isn't a link. This makes the text look clickable because it looks a
+link.
 
 <!-- TODO: Add do/dont images once designed (if necessary?) -->
 
 <DoDont type="do">
-  Use underlined links in body copy. Only omit an underline if the context makes
-  it clear the link is selectable.
+	Use underlined links in body copy. Only omit an underline if the context makes it clear the link
+	is selectable.
 </DoDont>
 
 <DoDont type="dont">Use underlined links in navigation.</DoDont>
 
+For more information see
+['Understanding Use of Color (Level A)'](https://www.w3.org/WAI/WCAG22/Understanding/use-of-color.html)
+and
+['Failure of Success Criterion 1.4.1 due to creating links that are not visually evident without color vision'](https://www.w3.org/WAI/WCAG22/Techniques/failures/F73).
+
+### Use anchor for links and navigation, not on-page actions
+
+Anchors are for navigation and URL changes, while buttons are for on-page actions such as form
+submissions or opening modals. These elements are treated differently by assistive technologies, so
+avoid using one in place of the other.
+
+Don't use anchor to make custom actions rather than navigation elements. To build a custom action or
+button, use the [pressable primitive](/components/primitives/pressable/examples) instead.
+
+More on
+[when to use links vs buttons](/components/button/usage#use-buttons-for-actions-and-links-for-navigation).
+
 ### Use descriptive link text that clarifies the purpose of the link
 
-Don't link vague words or phrases like “here” or “learn more.” Make sure the linked text clearly describes the purpose of the link.
+Don't link vague words or phrases like “here” or “learn more.” Make sure the linked text clearly
+describes the purpose of the link for assistive technologies.
 
+See [link content guidelines](/components/primitives/anchor/usage#content-guidelines) for details
+and examples.
+
+<!-- TODO: Crosslink updated link content guidance. Should be info in language and grammar and link component. (snippet time?) -->
 <!-- TODO: Add some Do/Don't images as examples -->
 
-<DoDont type="do">Clearly describe the purpose of the link.</DoDont>
+<DoDont type="do">Link text that describes the purpose of the link.</DoDont>
 
 <DoDont type="dont">Link vague words or phrases.</DoDont>
 
@@ -56,45 +89,51 @@ It might make sense for a link to open in a new window if:
 - There's a risk of someone losing their current place or task
 - The link takes the person out of the current product or to an external website
 
-For more information see ['G200: Opening new windows and tabs from a link only when necessary'](https://www.w3.org/TR/WCAG20-TECHS/G200.html).
+For more information see
+['G200: Opening new windows and tabs from a link only when necessary'](https://www.w3.org/TR/WCAG20-TECHS/G200.html).
 
 ### Keep links large enough to interact with
 
-Make link text size at least 12px. Smaller text is harder to read and interact with. If anchor is not used for text-based links, ensure the clickable area is at least 24 by 24 pixels for accessibility unless exempt from [Target Size (Minimum) (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).
-
-## Best practices
-
-### Don't confuse links and buttons
-
-Anchors are for navigation and URL changes, while buttons are for on-page actions such as form submissions or opening modals. These elements are treated differently by assistive technologies, so avoid using one in place of the other.
-
-More details on [when to use links and buttons](/components/button/usage#use-buttons-for-actions-and-links-for-navigation).
+Make link text size at least 12px. Smaller text is harder to read and interact with. If anchor is
+not used for text-based links, ensure the clickable area is at least 24 by 24 pixels for
+accessibility unless exempt from
+[Target Size (Minimum) (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).
 
 ## Content guidelines
 
 ### Use clear and unique link text
 
-Try not to repeat the same link text over and over on a page. Make sure link text is clear about where the link will go.
+Try not to repeat the same link text over and over on a page. Make sure link text is clear about
+where the link will go.
 
 ### Specify download links, including file type and size
 
-Always specify if a link triggers a download, and make the linked text clear about what exactly will be downloaded. Include file type and size as well.
+Always specify if a link triggers a download, and make the linked text clear about what exactly will
+be downloaded. Include file type and size as well.
+
+<!-- TODO: add example of this -->
 
 ### Don't include unnecessary links
 
 Using too many links can overwhelm other, more important information on a page.
 
-Anchors take people to a new page or location. Be mindful of whether or not the linked resource is helpful or distracting to the current task.
+Anchors take people to a new page or location. Be mindful of whether or not the linked resource is
+helpful or distracting to the current task.
 
 ### Links in sentences or body copy
 
-Only link the words that are necessary to clarify where the link goes. Don't link the entire sentence. (Linking smaller phrases can be better for internationalization when sentence structures change across languages.)
+Only link the words that are necessary to clarify where the link goes. Don't link the entire
+sentence. (Linking smaller phrases can be better for internationalization when sentence structures
+change across languages.)
 
-Only include the verb in the linked text if it better describes the purpose the link or differentiates it from other links and actions on the page.
+Only include the verb in the linked text if it better describes the purpose the link or
+differentiates it from other links and actions on the page.
 
 For example:
 
-> Update [Jira settings](/components/button/usage#use-buttons-for-actions-and-links-for-navigation) to turn off notifications. To upgrade, [sign up for Jira](/components/button/usage#use-buttons-for-actions-and-links-for-navigation).
+> Update [Jira settings](/components/button/usage#use-buttons-for-actions-and-links-for-navigation)
+> to turn off notifications. To upgrade,
+> [sign up for Jira](/components/button/usage#use-buttons-for-actions-and-links-for-navigation).
 
 If only Jira was linked, it wouldn't be clear that this was a sign up page.
 
@@ -102,10 +141,12 @@ If only Jira was linked, it wouldn't be clear that this was a sign up page.
 
 For standalone links, link the whole phrase. Don't add punctuation.
 
-These type of links typically follow general button or other label content rules (sentence case capitalization, no punctuation, etc.)
+These type of links typically follow general button or other label content rules (sentence case
+capitalization, no punctuation, etc.)
 
 ## Related
 
-- [Counterpart pressable primitive for buttons](/components/primitives/button/usage)
-- Prefer to use existing components such as the [link component](/components/link/examples) or [link buttons](/components/button/link-button/examples)
-- Anchor is built on the same API as [box](/components/primitives/box/usage)
+- Use existing components such as [link](/components/link/examples) or
+  [link button](/components/button/link-button/examples) wherever possible.
+- Use [pressable primitive for custom buttons](/components/primitives/button/usage).
+- Anchor is built on the same API as [box](/components/primitives/box/usage).

package/constellation/bleed/code.mdx

@@ -11,9 +11,9 @@ props:
 import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 <CodeDocsHeader
-  name="@atlaskit/primitives"
-  repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
-  directoryName="primitives"
+	name="@atlaskit/primitives"
+	repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
+	directoryName="primitives"
 />
 
 ## Props

package/constellation/bleed/examples.mdx

@@ -12,37 +12,41 @@ import BleedAll from '../../examples/constellation/bleed/all';
 import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 <CodeDocsHeader
-  name="@atlaskit/primitives"
-  repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
-  directoryName="primitives"
+	name="@atlaskit/primitives"
+	repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
+	directoryName="primitives"
 />
 
 ## Using Bleed
 
-Bleed is a component that allows its children to break the boundaries of its container. This is useful for content
-that wants to negate the padding or whitespace applied by its parent in a controlled manner. For example in the below grid layout, the middle
-item bleeds across the inline and block axes to overlap the gap set by the grid.
+Bleed is a component that allows its children to break the boundaries of its container. This is
+useful for content that wants to negate the padding or whitespace applied by its parent in a
+controlled manner. For example in the below grid layout, the middle item bleeds across the inline
+and block axes to overlap the gap set by the grid.
 
 <Example Component={BleedAll} packageName="@atlaskit/primitives/bleed" />
 
 ## Bleed and no bleed
 
-Bleed might be utilised to create a stacking effect with a group of avatars. Here each avatar is laid out with the `Inline` parent
-container. Without a bleed, each avatar would sit directly adjacent to its sibling. With `Bleed` we can negate the whitespace and force
-each avatar to overlap its direct sibling and create our desired stack.
+Bleed might be utilised to create a stacking effect with a group of avatars. Here each avatar is
+laid out with the `Inline` parent container. Without a bleed, each avatar would sit directly
+adjacent to its sibling. With `Bleed` we can negate the whitespace and force each avatar to overlap
+its direct sibling and create our desired stack.
 
 <Example Component={BleedDefault} packageName="@atlaskit/primitives/bleed" />
 
 ## Block whitespace
 
-Bleed can be controlled on the block axis (vertical) with the `block` property. The values of this property are tied to our spacing scale.
-Note, in the context of a flex container bleed will collapse the whitespace around its child element.
+Bleed can be controlled on the block axis (vertical) with the `block` property. The values of this
+property are tied to our spacing scale. Note, in the context of a flex container bleed will collapse
+the whitespace around its child element.
 
 <Example Component={BleedBlock} packageName="@atlaskit/primitives/bleed" />
 
 ## Inline whitespace
 
-Bleed can also be controlled on the inline axis (horizontal) with the `inline` property. The values of this property are tied to our spacing scale.
-Note, in the context of a flex container bleed will collapse the whitespace around its child element.
+Bleed can also be controlled on the inline axis (horizontal) with the `inline` property. The values
+of this property are tied to our spacing scale. Note, in the context of a flex container bleed will
+collapse the whitespace around its child element.
 
 <Example Component={BleedInline} packageName="@atlaskit/primitives/bleed" />

package/constellation/box/code.mdx

@@ -11,9 +11,9 @@ props:
 import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 <CodeDocsHeader
-  name="@atlaskit/primitives"
-  repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
-  directoryName="primitives"
+	name="@atlaskit/primitives"
+	repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
+	directoryName="primitives"
 />
 
 ## Props

package/constellation/box/examples.mdx

@@ -14,38 +14,44 @@ import BoxPracticalUseCase from '../../examples/constellation/box/practical-use-
 import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 <CodeDocsHeader
-  name="@atlaskit/primitives"
-  repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
-  directoryName="primitives"
+	name="@atlaskit/primitives"
+	repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
+	directoryName="primitives"
 />
 
 ## Basic
 
-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.
+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
 
-Use padding props 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 Atlassian 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, visit the [token list](/components/tokens/all-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"
-/>
+<Example Component={BoxBackgroundColor} packageName="@atlaskit/primitives/box" />
 
 ## 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.
+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).
 
@@ -53,7 +59,8 @@ For more information on XCSS, see the dedicated [XCSS documentation](/components
 
 ## Conditional styles
 
-To achieve conditional styles, we suggest composing conditional styles via the `props.xcss` API rather than applying conditional behaviour to individual props.
+To achieve conditional styles, we suggest composing conditional styles via the `props.xcss` API
+rather than applying conditional behaviour to individual props.
 
 <Example Component={BoxConditional} packageName="@atlaskit/primitives/box" />
 
@@ -61,9 +68,8 @@ To achieve conditional styles, we suggest composing conditional styles via the `
 
 Box is designed to be composed with inline, stack, and other components to create layouts.
 
-Atlassian uses dozens of distinct card-like components across products. Therefore, rather than providing a strict component, the Atlassian Design System empowers and supports you to build your own card components in ways that are consistent and will scale over time.
+Atlassian uses dozens of distinct card-like components across products. Therefore, rather than
+providing a strict component, the Atlassian Design System empowers and supports you to build your
+own card components in ways that are consistent and will scale over time.
 
-<Example
-  Component={BoxPracticalUseCase}
-  packageName="@atlaskit/primitives/box"
-/>
+<Example Component={BoxPracticalUseCase} packageName="@atlaskit/primitives/box" />

package/constellation/box/usage.mdx

@@ -4,19 +4,29 @@ description: A box is a generic container that provides managed access to design
 order: 2
 ---
 
-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.
+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.
+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.
+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.
+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](/components/primitives/xcss/usage). 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`

package/constellation/flex/code.mdx

@@ -11,9 +11,9 @@ props:
 import { CodeDocsHeader } from '@af/design-system-docs-ui';
 
 <CodeDocsHeader
-  name="@atlaskit/primitives"
-  repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
-  directoryName="primitives"
+	name="@atlaskit/primitives"
+	repository="https://bitbucket.org/atlassian/atlassian-frontend-mirror"
+	directoryName="primitives"
 />
 
 ## Props