@atlaskit/primitives 7.0.0 → 7.0.2

package/constellation/pressable/usage.mdx

@@ -9,81 +9,101 @@ import pressablePrimaryDont from './images/pressable-01b-dont.png';
 
 ## Usage
 
-Pressable is a button with consistent focus styles and analytics built in. Pressable works with design tokens to make it easy to compose Atlassian-styled clickable elements that aren't possible using existing [buttons](/components/button/examples), [menus](/components/menu/examples), or other existing design system components.
+Use pressable to make custom-styled buttons and other pressable elements. Pressable works similarly
+to an HTML `<button>`, but with Atlassian focus styles, analytics events, and styling APIs built in.
+
+For example, you could use pressable to make a colored square button that opens a color picker, or a
+basic card that shows more details when selected.
 
 ![Pressable anatomy](./images/pressable-anatomy.png)
 
-1. **Pressable area:** For accessibility this should be a minimum of 24 by 24 pixels, unless exempt from [Target Size (Minimum) (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).
+1. **Pressable area:** For accessibility this should be a minimum of 24 by 24 pixels, unless exempt
+   from
+   [Target Size (Minimum) (Level AA)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html).
 2. **Focus ring**: This is included in pressable and appears on keyboard focus.
-3. **Accessible label:** Pressable should always include a clear label for accessibility. Use this to communicate the action that occurs when the button is pressed.
+3. **Accessible label:** Pressable should always include a clear label for accessibility. Use this
+   to communicate the action that occurs when the button is pressed.
+
+### Use existing buttons and other components whenever possible
 
-### Use pressable when there aren't existing components that work for your experience
+Only use pressable when existing components such as [buttons](/components/button/examples) or
+[menus](/components/menu/examples) can't be customized to fit your case.
 
-Only use pressable when existing components such as [the button component](/components/button/examples), menus, or other existing design system components can't be customized to fit your case. Using existing components with safe customizations will prevent inconsistency as Atlassian UI evolves.
+Using [existing components](/components) with safe customizations is usually faster and keeps
+Atlassian UI more visually consistent as things change.
 
 <DoDont
-  type="do"
-  image={{
-    url: pressablePrimaryDo,
-    alt: "A set of custom buttons built with pressable that aren't possible using existing design system components",
-  }}
+	type="do"
+	image={{
+		url: pressablePrimaryDo,
+		alt: 'A set of custom buttons built with pressable that are not possible using existing design system components',
+	}}
 >
-  Use pressable to create buttons when there isn't an existing design system
-  component to achieve your use case.
+	Use pressable to create buttons when there isn't an existing design system component to achieve
+	your use case.
 </DoDont>
 
 <DoDont
-  type="dont"
-  image={{
-    url: pressablePrimaryDont,
-    alt: 'A custom button build with Pressable that looks similar to Button, an existing design system component',
-  }}
+	type="dont"
+	image={{
+		url: pressablePrimaryDont,
+		alt: 'A custom button build with Pressable that looks similar to Button, an existing design system component',
+	}}
 >
-  Don't use pressable in place of an element that already has a design system
-  representation, such as{' '}
-  <a href="/components/button/examples">the button component</a>. This can cause
-  visual and behavioral inconsistencies in Atlassian products.
+	Don't use pressable to redesign elements that already exists in the Atlassian design system, such
+	as <a href="/components/button/examples">buttons</a>. This can cause visual and behavioral
+	inconsistency in products.
 </DoDont>
 
 ## Accessibility
 
 ### Use clear labels for assistive technology
 
-Pressable should always announce what action will happen once pressed.
+Pressable elements should always announce what action will happen once pressed, especially for
+elements with no visible label, such as icon buttons.
 
 ![Pressable labels](./images/pressable-labels.png)
 
-#### When no visible label is present
+Use [the visually hidden component](/components/visually-hidden/examples) to provide an accessible
+label. This will render hidden text inside the button, which is preferable over the `aria-label`
+attribute because not all screen readers translate this between languages.
 
-- Ensure an accessible label is still available by using [the visually hidden component](/components/visually-hidden/examples) which will render hidden text inside the button. This is preferable over the `aria-label` attribute because not all screen readers translate this between languages.
-- Use [a tooltip](/components/tooltip/examples) to provide sighted users with the same information.
+Also consider [a tooltip](/components/tooltip/examples) to provide sighted users with the same
+information.
 
 ### Focus ring behavior
 
-Pressable creates buttons that are available in focus order, and provides a visual ring to clarify what is in focus. Adding additional focus styles is unnecessary.
+Pressable buttons are available in focus order, and include a visual ring to clarify what is in
+focus by default. Adding additional focus styles is unnecessary.
 
 ### Avoid disabling buttons
 
-Disabled buttons can cause accessibility problems. Avoid disabling buttons and [follow our disabled and tooltip button guidance](/components/button/usage#avoid-disabling-buttons).
+Disabled buttons can cause accessibility problems. Avoid disabling buttons and
+[follow our disabled button and tooltip guidance](/components/button/usage#avoid-disabling-buttons).
 
 ## Best practices
 
 ### Make it clear what can be pressed
 
-Custom buttons should be obviously interactable. Make sure they are clearly identifiable through styles, surrounding context, labels, or other cues.
+Custom buttons should look interactive. Make sure clickable elements are clearly identifiable
+through styles, surrounding context, labels, and other cues.
 
-### Don't use pressable for navigation
+### Use pressable for on-page actions, not navigation
 
-Pressable is meant for on-page actions such as opening modals, or submitting forms. If you're making something that navigates to a new page, use a component that renders a semantically correct HTML `<a>` element such as:
+Pressable is meant for on-page actions such as opening modals or submitting forms. If you're making
+something that navigates to a new page, use a component that renders a semantically correct HTML
+`<a>` element such as:
 
 - The [link](/components/primitives/link/examples) component (coming soon) for standard text links.
-- The [anchor](/components/primitives/anchor/examples) primitive (coming soon) to create custom links.
+- The [anchor](/components/primitives/anchor/examples) primitive (coming soon) to create custom
+  links.
 
 ## Content guidelines
 
 ### Use sentence case capitalization
 
-Use sentence case capitalization, only capitalizing the first letter of the label and any proper nouns. Other forms of capitalization should be only applied through styling with `text-transform`.
+Use sentence case capitalization, only capitalizing the first letter of the label and any proper
+nouns. Other forms of capitalization should be only applied through styling with `text-transform`.
 
 ### Make it clear what pressing the button does
 
@@ -93,10 +113,13 @@ For example, _Change issue color to yellow_ instead of _yellow_.
 
 ### Follow other label and UI content guidance
 
-Follow label and content guidelines for [buttons](/components/button/usage#content-guidelines). Review our [general UI text guidance](/foundations/accessibility/#meaningful-text) for specific question.
+Follow label and content guidelines for [buttons](/components/button/usage#content-guidelines).
+Review the [general UI text guidance](/foundations/accessibility/#meaningful-text) for specific
+questions.
 
 ## Related
 
-- [Counterpart anchor primitive for links](/components/primitives/button/usage)
-- Prefer to use existing components such as [buttons](/components/button/examples) or [menus](/components/menu/examples) for most actions in Atlassian products
-- Pressable is built on the same API as [box](/components/primitives/box/usage)
+- Use existing components such as [buttons](/components/button/examples) or
+  [menus](/components/menu/examples) for most actions in Atlassian products.
+- Use the [anchor primitive for custom links](/components/primitives/button/usage).
+- Pressable is built on the same API as [box](/components/primitives/box/usage).

package/constellation/responsive/01-show/code.mdx

@@ -7,9 +7,9 @@ order: 2
 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 ShowProps from '!!extract-react-types-loader!../../../extract-react-types/show-props';

package/constellation/responsive/01-show/examples.mdx

@@ -10,27 +10,23 @@ import ShowHideExample from '../../../examples/constellation/responsive/show-hid
 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"
 />
 
 ### Show
 
-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.
+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.
 
-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.
+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.
 
-<Example
-  Component={ShowExample}
-  packageName="@atlaskit/primitives/responsive"
-/>
+<Example Component={ShowExample} packageName="@atlaskit/primitives/responsive" />
 
 ### Mixing Show and Hide
 
 Prefer using consistent `above` or `below` for readability and consistency.
 
-<Example
-  Component={ShowHideExample}
-  packageName="@atlaskit/primitives/responsive"
-/>
+<Example Component={ShowHideExample} packageName="@atlaskit/primitives/responsive" />

package/constellation/responsive/02-hide/code.mdx

@@ -7,9 +7,9 @@ order: 2
 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 HideProps from '!!extract-react-types-loader!../../../extract-react-types/hide-props';

package/constellation/responsive/02-hide/examples.mdx

@@ -10,27 +10,23 @@ import ShowHideExample from '../../../examples/constellation/responsive/show-hid
 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"
 />
 
 ### Hide
 
-Using Hide allows you to Hide the children using CSS `display: none` when the viewport size is above a specified breakpoint. By default, unless the breakpoint is met, contents are hidden.
+Using Hide allows you to Hide the children using CSS `display: none` when the viewport size is above
+a specified breakpoint. By default, unless the breakpoint is met, contents are hidden.
 
-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.
+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.
 
-<Example
-  Component={HideExample}
-  packageName="@atlaskit/primitives/responsive"
-/>
+<Example Component={HideExample} packageName="@atlaskit/primitives/responsive" />
 
 ### Mixing Show and Hide
 
 Prefer using consistent `above` or `below` for readability and consistency.
 
-<Example
-  Component={ShowHideExample}
-  packageName="@atlaskit/primitives/responsive"
-/>
+<Example Component={ShowHideExample} packageName="@atlaskit/primitives/responsive" />

package/constellation/responsive/03-breakpoints/examples.mdx

@@ -9,9 +9,9 @@ import { MediaQueriesTable } from '@af/design-system-docs-ui';
 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"
 />
 
 ### Media Queries

package/constellation/responsive/examples.mdx

@@ -13,23 +13,22 @@ import ShowHideExample from '../../examples/constellation/responsive/show-hide';
 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"
 />
 
 ## Responsive `css` or `xcss`
 
-Utilize our media queries exposed in `css`, `styled`, or `xcss` as computed keys to build responsive UIs. Learn more about these media query exports in [usage](/components/primitives/responsive/usage).
+Utilize our media queries exposed in `css`, `styled`, or `xcss` as computed keys to build responsive
+UIs. Learn more about these media query exports in [usage](/components/primitives/responsive/usage).
 
 ### Using with `xcss`
 
-Please use `xcss` whenever possible to ensure consistency and safety with style overrides. Read more at [xcss](/components/primitives/xcss)
+Please use `xcss` whenever possible to ensure consistency and safety with style overrides. Read more
+at [xcss](/components/primitives/xcss)
 
-<Example
-  Component={XCSSExample}
-  packageName="@atlaskit/primitives/responsive"
-/>
+<Example Component={XCSSExample} packageName="@atlaskit/primitives/responsive" />
 
 ### Using with `css`
 
@@ -37,7 +36,8 @@ Please use `xcss` whenever possible to ensure consistency and safety with style
 
 ## Responsive primitives
 
-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.
+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.
 
 - [Show](/components/primitives/responsive/show)
 - [Hide](/components/primitives/responsive/hide)

package/constellation/responsive/usage.mdx

@@ -6,26 +6,32 @@ order: 2
 
 ## Media query helpers
 
-The media query helper object `media.above[breakpoint]` maps to our [breakpoints](/components/primitives/responsive/breakpoints/examples) as a media query for use in CSS-in-JS. `media.above[breakpoint]` targets all viewports **above** (larger than) the min-width of a given breakpoint
+The media query helper object `media.above[breakpoint]` maps to our
+[breakpoints](/components/primitives/responsive/breakpoints/examples) as a media query for use in
+CSS-in-JS. `media.above[breakpoint]` targets all viewports **above** (larger than) the min-width of
+a given breakpoint
 
-These responsive helpers are designed be used in conjunction with [xcss](/components/primitives/xcss). It is recommended that both are used when available as this uses our media queries to allow for safe, responsive styling.
+These responsive helpers are designed be used in conjunction with
+[xcss](/components/primitives/xcss). It is recommended that both are used when available as this
+uses our media queries to allow for safe, responsive styling.
 
 ### Basic example
 
-Compose your default styles alongside media overrides in [xcss](/components/primitives/xcss) or `css`.
+Compose your default styles alongside media overrides in [xcss](/components/primitives/xcss) or
+`css`.
 
 #### xcss
 
 ```tsx
 const customStyles = xcss({
-  display: 'none', // hide by default
-  padding: 'space.100',
-  [media.above.md]: { display: 'revert' }, // show above md
-  [media.above.lg]: { padding: 'space.150' }, // increase padding above md
+	display: 'none', // hide by default
+	padding: 'space.100',
+	[media.above.md]: { display: 'revert' }, // show above md
+	[media.above.lg]: { padding: 'space.150' }, // increase padding above md
 });
 
 export const Component = ({ children }: { children: ReactNode }) => (
-  <Box xcss={customStyles}>{children}</Box>
+	<Box xcss={customStyles}>{children}</Box>
 );
 ```
 
@@ -33,15 +39,17 @@ export const Component = ({ children }: { children: ReactNode }) => (
 
 ```tsx
 const customStyles = css({
-  marginBlock: token('space.0'),
-  [media.above.xs]: { marginBlock: token('space.025') },
-  [media.above.sm]: { marginBlock: token('space.050') },
-  [media.above.md]: { marginBlock: token('space.075') },
-  [media.above.lg]: { marginBlock: token('space.100') },
-  [media.above.xl]: { marginBlock: token('space.150') },
+	marginBlock: token('space.0'),
+	[media.above.xs]: { marginBlock: token('space.025') },
+	[media.above.sm]: { marginBlock: token('space.050') },
+	[media.above.md]: { marginBlock: token('space.075') },
+	[media.above.lg]: { marginBlock: token('space.100') },
+	[media.above.xl]: { marginBlock: token('space.150') },
 });
 ```
 
 ### Using media.above
 
-It is important to note that the `media.above.xxs` will **always** match, it is explicitly `'@media all'`. This is only included for easy programmatic usage, but it has a negative performance impact.
+It is important to note that the `media.above.xxs` will **always** match, it is explicitly
+`'@media all'`. This is only included for easy programmatic usage, but it has a negative performance
+impact.

package/constellation/stack/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/stack/examples.mdx

@@ -16,16 +16,17 @@ import StackAs from '../../examples/constellation/stack/as';
 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
 
 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.
+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" />
 
@@ -37,17 +38,25 @@ Control spacing between items with the `space` prop.
 
 ## 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.
+`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.
+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.
+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.
+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
 
-Control the alignment of items using 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
 
@@ -55,20 +64,19 @@ Control the alignment of items using the `alignBlock` and `alignInline` props wh
 
 ### Inline alignment
 
-<Example
-  Component={StackAlignInline}
-  packageName="@atlaskit/primitives/stack"
-/>
+<Example Component={StackAlignInline} packageName="@atlaskit/primitives/stack" />
 
 ## Spread
 
-Use the `spread` prop to set elements 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 use the `grow` prop 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.
@@ -83,9 +91,7 @@ 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.
+An example of how a stack component might be used in product, using Atlassian Design System
+components.
 
-<Example
-  Component={StackPracticalUseCase}
-  packageName="@atlaskit/primitives/stack"
-/>
+<Example Component={StackPracticalUseCase} packageName="@atlaskit/primitives/stack" />

package/constellation/stack/usage.mdx

@@ -4,21 +4,29 @@ description: A stack manages the vertical layout of direct children using flexbo
 order: 2
 ---
 
-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.
+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.
 
-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.
+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.
+In its simplest form, `Stack` works like a flexbox column, with built-in design token support and
+guidance.
 
 ```jsx
 <Stack space="space.100" alignInline="center" alignBlock="start">
-  ...
+	...
 </Stack>
 ```
 
 ## 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:
 

package/constellation/text/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/text/examples.mdx

@@ -15,34 +15,44 @@ import TextTruncation from '../../examples/constellation/text/text-truncation';
 
 ## Basic
 
-Use a Text component for main content. Text typically appears after headings or subheadings as detailed descriptions and messages, but also as standalone text in components.
+Use a Text component for main content. Text typically appears after headings or subheadings as
+detailed descriptions and messages, but also as standalone text in components.
 
 The `size` prop expresses the visual appearance of the text element:
-- `'large'` is for long-form content. Use this size for a comfortable reading experience such as in blogs.
-- `'medium'` is the default size in components or where space is limited, for detailed or descriptive content such as primary descriptions in flags.
-- `'small'` should be used sparingly and is for secondary level content such as fine print or semantic messaging.
+
+- `'large'` is for long-form content. Use this size for a comfortable reading experience such as in
+  blogs.
+- `'medium'` is the default size in components or where space is limited, for detailed or
+  descriptive content such as primary descriptions in flags.
+- `'small'` should be used sparingly and is for secondary level content such as fine print or
+  semantic messaging.
 
 <Example Component={TextBasic} packageName="@atlaskit/primitives" />
 
 ## Color
 
-Text uses the `color.text` token which automatically switches colors to be legible across both light and dark modes.
+Text uses the `color.text` token which automatically switches colors to be legible across both light
+and dark modes.
 
-Text will automatically apply the correct inverse color token if placed within a [box component](/components/primitives/box) with a bold background color.
+Text will automatically apply the correct inverse color token if placed within a
+[box component](/components/primitives/box) with a bold background color.
 
 <Example Component={TextColorInverse} packageName="@atlaskit/primitives" />
 
-The `color` prop can be used with any text color token. If Text is nested inside another Text component, color will automatically inherit from its parent.
+The `color` prop can be used with any text color token. If Text is nested inside another Text
+component, color will automatically inherit from its parent.
 
 <Example Component={TextColorInherit} packageName="@atlaskit/primitives" />
 
 ## Font weight
 
-Font weight defaults to regular (400) and can be set using the `weight` prop.
-More information about the available weights can be found on the [typography foundations page](/foundations/typography-beta/#body-font-weight).
+Font weight defaults to regular (400) and can be set using the `weight` prop. More information about
+the available weights can be found on the
+[typography foundations page](/foundations/typography-beta/#body-font-weight).
 
-Note: Text supports the semibold weight, however due to differences between font stacks across different operating systems, semibold text may render as bold.
-We recommend using regular, medium, and bold for the best results.
+Note: Text supports the semibold weight, however due to differences between font stacks across
+different operating systems, semibold text may render as bold. We recommend using regular, medium,
+and bold for the best results.
 
 <Example Component={TextWeight} packageName="@atlaskit/primitives" />
 
@@ -54,15 +64,18 @@ Text can be aligned using the `align` prop.
 
 ## Rendered HTML element
 
-Text renders a HTML `<span>` element by default. Use the `as` prop to change the rendered HTML element.
+Text renders a HTML `<span>` element by default. Use the `as` prop to change the rendered HTML
+element.
 
 <Example Component={TextAsElement} packageName="@atlaskit/primitives" />
 
 ## Arrangement with other text styles
 
-Text does not apply any vertical margin or spacing. To control space between text and other content, use a [stack component](/components/primitives/stack).
+Text does not apply any vertical margin or spacing. To control space between text and other content,
+use a [stack component](/components/primitives/stack).
 
-The available values for paragraph spacing are outlined in the [Typography foundations](/foundations/typography-beta/#body) page.
+The available values for paragraph spacing are outlined in the
+[Typography foundations](/foundations/typography-beta/#body) page.
 
 <Example Component={TextSpacing} packageName="@atlaskit/primitives" />
 
@@ -70,6 +83,7 @@ The available values for paragraph spacing are outlined in the [Typography found
 
 Truncation in product experiences [should be avoided](/content/language-and-grammar/#truncation).
 
-However if truncation cannot be avoided, for example when displaying user-generated content, use the `maxLines` prop to indicate how text should be truncated.
+However if truncation cannot be avoided, for example when displaying user-generated content, use the
+`maxLines` prop to indicate how text should be truncated.
 
 <Example Component={TextTruncation} packageName="@atlaskit/primitives" />