Apply component documentation content improvements (#2674)

Co-authored-by: Josh Wooding <[email protected]> Co-authored-by: sion-docs <[email protected]> Co-authored-by: Zhihao Cui <[email protected]>
jpmorganchase · Dec 15, 2023 · ba332f5 · ba332f5 · vercel · Dec 15, 2023
1 parent b9831e3
commit ba332f5
Show file tree

Hide file tree

Showing 155 changed files with 1,180 additions and 1,187 deletions.
diff --git a/site/docs/components/accordion/accessibility.mdx b/site/docs/components/accordion/accessibility.mdx
@@ -12,17 +12,17 @@ data:
 <KeyboardControls>
 <KeyboardControl keyOrCombos="Tab">
 
-- If focus is above the Accordion group, Tab moves focus to the first Accordion item in the group. Then each next Accordion item is a tab stop.
+- If focus is above the accordion group, Tab moves focus to the first accordion item in the group. Then, each press moves to the next accordion item.
 
 </KeyboardControl>
 <KeyboardControl keyOrCombos="Shift + Tab">
 
-If focus is below the Accordion Group, Shift + Tab moves focus to the last Accordion item in the group. Then each Shift + Tab moves focus to the previous Accordion item in the group.
+- If focus is below the accordion group, this action moves focus to the last accordion item in the group. Then, each press moves focus to the previous accordion item in the group.
 
 </KeyboardControl>
 <KeyboardControl keyOrCombos="Enter / Space">
 
-- Accordions are collapsed by default. Enter or Space expands, or collapses, Accordions.
+- Accordions are in the collapsed state by default. This action expands, or collapses, accordions.
 
 </KeyboardControl>
 </KeyboardControls>
diff --git a/site/docs/components/accordion/examples.mdx b/site/docs/components/accordion/examples.mdx
@@ -12,35 +12,35 @@ data:
 
 ### Default
 
-Accordion is a single element by default that can be expanded or collapsed to show or hide content within a panel.
+By default, `Accordion` is a single element the user can expand or collapse to show or hide content within a panel.
 
 </LivePreview>
 <LivePreview componentName="accordion" exampleName="AccordionGroup" >
 
-### Accordion Groups
+### Accordion groups
 
-You can place Accordions in an Accordion Group which allows multiple accordions to be open at the same time.
+You can place accordions in an accordion group, which allows multiple accordions to be open at the same time.
 
 </LivePreview>
 <LivePreview componentName="accordion" exampleName="Disabled" >
 
 ### Disabled
 
-Use the `disabled` prop to disable an Accordion. A disabled Accordion cannot be expanded, collapsed or focused.
+Use the `disabled` prop to disable an accordion. The user can't expand, collapse or focus a disabled accordion.
 
 </LivePreview>
 <LivePreview componentName="accordion" exampleName="Status" >
 
 ### Status
 
-You can set a status of either "error", "warning" or "success" for an Accordion. This should be used to indicate the status of the content within the Accordion.
+You can set a status of "error", "warning" or "success" for an accordion to indicate the type of content it contains.
 
 </LivePreview>
 <LivePreview componentName="accordion" exampleName="InlineBadge" >
 
-### Inline Badge
+### Inline badge
 
-You can use an inline [Badge](../badge) to indicate a change, or number of changes, to the content within the Accordion.
+You can use an inline [badge](../badge) to indicate a change, or several changes, to the content within the accordion.
 
 </LivePreview>
 </LivePreviewControls>
diff --git a/site/docs/components/accordion/index.mdx b/site/docs/components/accordion/index.mdx
@@ -1,16 +1,16 @@
 ---
 title: Accordion
 data:
-  description: Accordion displays a panel which can be expanded or collapsed to allow the user to show or hide content and control the complexity of a given view.
+  description: "`Accordion` displays a panel that the user can expand or collapse to show or hide content and control the complexity of a given view."
   sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/accordion/Accordion.tsx"
   package:
     name: "@salt-ds/core"
     initialVersion: "1.0.0"
-  alsoKnownAs: ["Collapsible Panel", "Concertina", "Expansion Panel"]
+  alsoKnownAs: ["Collapsible panel", "Concertina", "Expansion panel"]
   relatedComponents:
     [
       { name: "Icon", relationship: "contains" },
-      { name: "Status Indicator", relationship: "contains" },
+      { name: "Status indicator", relationship: "contains" },
     ]
   stickerSheet: ""
 layout: DetailComponent

diff --git a/site/docs/components/accordion/usage.mdx b/site/docs/components/accordion/usage.mdx
@@ -7,21 +7,23 @@ data:
   $ref: ./#/data
 ---
 
-### When to use Accordion
+### Using the component
+
+#### When to use
 
 - To organize related content within expandable groups/categories/sections.
 
-- To reduce scrolling or overall page length when it is not critical that content is displayed in full.
+- To reduce scrolling or overall page length when displaying content in full isn't critical.
 
-- When content cannot be displayed all at once due to restricted screen real estate.
+- When you can't display all the content at once due to restricted screen space.
 
-### When not to use Accordion
+#### When not to use
 
-- This component is not intended for use with grids to replace grouped rows.
+- To replace grouped rows with grids.
 
 ### Import
 
-To import Accordion and Accordion Group from the core Salt package, use:
+To import `Accordion` and related components from the core Salt package, use:
 
 ```js
 import {
@@ -34,18 +36,18 @@ import {
 
 ### Props
 
-#### Accordion
+#### `Accordion`
 
 <PropsTable componentName="Accordion" />
 
-#### Accordion Group
+#### `AccordionGroup`
 
 <PropsTable componentName="AccordionGroup" />
 
-#### Accordion Header
+#### `AccordionHeader`
 
 <PropsTable componentName="AccordionHeader" />
 
-#### Accordion Panel
+#### `AccordionPanel`
 
 <PropsTable componentName="AccordionPanel" />
diff --git a/site/docs/components/ag-grid-theme/examples.mdx b/site/docs/components/ag-grid-theme/examples.mdx
@@ -13,7 +13,20 @@ data:
 
 ### Default
 
-Applies the default look when applying Salt theme
+Applies the default look when applying the Salt theme.
+
+</LivePreview>
+
+<LivePreview componentName="ag-grid-theme" exampleName="Variants" >
+
+### Variants
+
+There are three variants of the Salt AG Grid theme: primary (default), secondary and zebra. To use one of the non-default variants, add an additional class name to the container element above `<AgGridReact/>`.
+
+The class names are:
+
+- `ag-theme-salt-variant-secondary`
+- `ag-theme-salt-variant-zebra`
 
 </LivePreview>
 
@@ -105,7 +118,7 @@ Users can reveal a child grid when a row in the master grid is expanded.
 </LivePreview>
 <LivePreview componentName="ag-grid-theme" exampleName="NoDataOverlay" >
 
-### No data overlay
+### "No data" overlay
 
 This overlay tells the user that there is no information to display.
 
@@ -119,7 +132,7 @@ Users can move between pages using the controls in the lower right.
 </LivePreview>
 <LivePreview componentName="ag-grid-theme" exampleName="ParentChildRows" >
 
-### Parent child rows
+### Parent-child rows
 
 These rows group items under headers and sub-headers.
 
@@ -151,18 +164,6 @@ Row groups display in the above panel.
 
 The section below the table displays a status bar.
 
-</LivePreview>
-<LivePreview componentName="ag-grid-theme" exampleName="Variants" >
-
-### Variants
-
-There are three variants of the Salt AG Grid theme: primary (default), secondary and zebra. To use one of the non-default variants, add an additional class name to the container element above `<AgGridReact/>`.
-
-The class names are:
-
-- `ag-theme-salt-variant-secondary`
-- `ag-theme-salt-variant-zebra`
-
 </LivePreview>
 <LivePreview componentName="ag-grid-theme" exampleName="WrappedHeader" >
 

diff --git a/site/docs/components/ag-grid-theme/index.mdx b/site/docs/components/ag-grid-theme/index.mdx
@@ -1,7 +1,7 @@
 ---
-title: AG Grid Theme
+title: AG Grid theme
 data:
-  description: AG Grid Theme is a package that adds Salt theme styles to AG Grid. The package contains CSS files only, and works with AG Grid versions 25 - 28.
+  description: "AG Grid theme is a package that adds Salt theme styles to AG Grid. The package contains CSS files only, and works with AG Grid versions 25-28."
   sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/ag-grid-theme"
   package:
     name: "@salt-ds/ag-grid-theme"

diff --git a/site/docs/components/ag-grid-theme/usage.mdx b/site/docs/components/ag-grid-theme/usage.mdx
@@ -9,13 +9,13 @@ data:
   $ref: ./#/data
 ---
 
-### Using AG Grid Theme
+### Using the package
 
-#### When to use AG Grid Theme
+#### When to use
 
 When you want to use the Salt theme with AG Grid.
 
-#### When not to use AG Grid Theme
+#### When not to use
 
 When you want to use a component that is not related to AG Grid. Instead, use Grid.
 

diff --git a/site/docs/components/avatar/accessibility.mdx b/site/docs/components/avatar/accessibility.mdx
@@ -9,6 +9,6 @@ data:
 
 ### Best practices
 
-Decorative Avatars (Avatars that repeat the information already expressed by the accompanying text) should be hidden from the screen reader to avoid repetition. If you are adding an Avatar for decorative purposes, use `aria-hidden` to hide its label from the screen reader.
+You should exclude decorative avatars (avatars that repeat the information already expressed by the accompanying text) from screen reader access to avoid repetition. If you're adding an avatar for decorative purposes, use `aria-hidden` to exclude its label from the screen reader.
 
-If an alternative icon is used inside an Avatar, the icon's `aria-label` should be descriptive in relation to the Avatar context, not the icon context. For example, when using `<BuildingSolidIcon/>` to represent a company `aria-label` should read "Company profile" rather than the Icon's default label "building solid".
+If you're using an alternative icon inside an avatar, the icon's `aria-label` should be descriptive in relation to the avatar context, not the icon context. For example, when using `<BuildingSolidIcon/>` to represent a company, `aria-label` should read "Company profile" rather than the icon's default label "building solid."
diff --git a/site/docs/components/avatar/examples.mdx b/site/docs/components/avatar/examples.mdx
@@ -12,34 +12,34 @@ data:
 
 ### Image
 
-You can pass an image using the `src` property to be used as the Avatar image.
+You can pass an image as the avatar image using the `src` prop.
 
-A custom image or SVG can also be passed as the child of the component. Note that for images passed as children, you will also need to handle the fallback logic.
+You can also pass a custom image or SVG as the child of the component. Note that for images passed as children, you'll also need to handle the fallback logic.
 
 </LivePreview>
 <LivePreview componentName="avatar" exampleName="Initials" >
 
 ### Initials
 
-If a photo is not available, the Avatar will fall back to initials or an icon:
+If a photo is not available, the avatar will fall back to initials or an icon:
 
-- Initials can be used when a photo is unavailable, but profile information is.
+- You can use initials when a photo is unavailable, but profile information is.
 
-- Icon can be used when neither a photo nor profile information are available.
+- Use an icon when neither a photo nor profile information is available.
 
 </LivePreview>
 <LivePreview componentName="avatar" exampleName="Sizes" >
 
 ### Sizes
 
-The Avatar size can be increased by modifying the size property. Each Avatar variant has a default size across all four densities, equal to the [Size Foundation](/salt/foundations/size) `size-base`; 20px (HD), 28px (MD), 36px (LD), and 44px (TD). The size property acts as a multiplier of the base size.
+You can use the `size` prop to modify the avatar size. Each avatar variant has a default size across all four densities, equal to the [size foundation](/salt/foundations/size) `size-base`: 20px (HD), 28px (MD), 36px (LD), and 44px (TD). The size property acts as a multiplier of the base size.
 
 </LivePreview>
 <LivePreview componentName="avatar" exampleName="CustomFallbackIcon" >
 
-### Custom Fallback Icon
+### Custom fallback icon
 
-Avatar renders with an icon defined by `UserSolidIcon` but an alternative icon can be passed as `fallbackIcon`.
+`Avatar` renders with an icon defined by `UserSolidIcon`, but you can pass an alternative icon as `fallbackIcon`.
 
 </LivePreview>
 </LivePreviewControls>
diff --git a/site/docs/components/avatar/index.mdx b/site/docs/components/avatar/index.mdx
@@ -1,7 +1,7 @@
 ---
 title: Avatar
 data:
-  description: The Avatar component is a graphical element which can be used to represent a person, group, entity, or communication channel.
+  description: "`Avatar` is a graphical element which you can use to represent a person, group, entity or communication channel."
   sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/avatar/Avatar.tsx"
   package:
     name: "@salt-ds/core"

diff --git a/site/docs/components/avatar/usage.mdx b/site/docs/components/avatar/usage.mdx
@@ -7,17 +7,19 @@ data:
   $ref: ./#/data
 ---
 
-### When to use Avatar
+### Using the component
 
-Use Avatar to visually represent a person, group, entity or communication channel. The same image, initials, or placeholder image should appear for a given object instance throughout the experience.
+#### When to use
 
-### When not to use Avatar
+To visually represent a person, group, entity or communication channel. The same image, initials, or placeholder image should appear for a given object instance throughout the experience.
 
-Do not use when a large, full-size image is required.
+#### When not to use
+
+When a large, full-size image is necessary.
 
 ### Import
 
-To import Avatar from the core Salt package, use:
+To import `Avatar` from the core Salt package, use:
 
 ```
 import { Avatar } from "@salt-ds/core";

diff --git a/site/docs/components/badge/accessibility.mdx b/site/docs/components/badge/accessibility.mdx
@@ -7,4 +7,6 @@ data:
   $ref: ./#/data
 ---
 
-We recommend only using the accent color for Badge. Align to the minimum contrast guidance outlined in [WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) for any color overrides.
+### Best practices
+
+We recommend only using the accent color for `Badge`. Align to the minimum contrast guidance outlined in [WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) for any color overrides.
diff --git a/site/docs/components/badge/examples.mdx b/site/docs/components/badge/examples.mdx
@@ -9,44 +9,40 @@ data:
 
 <LivePreviewControls>
   <LivePreview componentName="badge" exampleName="Default">
-    ### Default (top-right)
+  ### Default (top-right)
 
-    Badge is positioned in the top-right corner when attached to a child component such as an icon.
+By default, `Badge` is in the top-right corner when attached to a child component such as an icon. Badges visually anchor to the attached component. As the number of alphanumeric characters increases, the badge width expands, but stays in the same place.
 
+#### Best practices
 
-    #### Guidance
-
-    - Badge is visually anchored to the attached component. As the number of alphanumeric characters increases, the Badge width expands, but stays in the same place.
-    - Use badge in the top-right corner if you want to provide a summary of the overall state of the content the badge is anchored to. For example, you may want to provide a quick overview of how many new or unread items there are, using numeric values.
+Use a badge in the top-right corner to summarize the overall state of the content the badge is anchored to. For example, you may want to provide a quick overview of the number of new or unread items, using numeric values.
 
   </LivePreview>
   <LivePreview componentName="badge" exampleName="InlineBadge">
 
-    ### Inline Badge
+### Inline badge
 
-    To place a badge inline, instead of in the top-right corner of an element simply do not pass `children` to Badge.
+To place a badge inline instead of in the top-right corner of an element, don't pass `children` to the badge.
 
-    #### Guidance
+#### Best practices
 
-    Using Badge inline with text makes clear which part of the content the badge relates to and allows specific details to be highlighted within the content to draw the user’s attention. For example, you may use Badge within Tab, inline to the text.
+Using a badge inline with text clarifies which part of the content the badge relates to and allows specific details to be highlighted within the content to draw the user’s attention. For example, you may use a badge within `TabNext`, inline with the text.
 
   </LivePreview>
   <LivePreview componentName="badge" exampleName="BadgeWithMaximumDigits">
 
-    ### Badge with maximum digits
-
-    Specify the maximum number to be displayed with the `max` property. If `value` exceeds `max`, the value will be clamped and a (`+`) suffix will be appended.
+### Badge with maximum digits
 
-    #### Guidance
+Specify the maximum displayed number with the `max` prop. If `value` exceeds `max`, it will clamp the value and append a (`+`) suffix.
 
-    - In the case that no max value is passed to the component, the value will be limited to 3 digits by default and therefore display 999+ for any values over 999.
+When you don't pass a max value to the component, the value will have a limitation of three digits by default, displaying 999+ for any values over 999.
 
   </LivePreview>
   <LivePreview componentName="badge" exampleName="BadgeWithString">
 
-    ### Badge with string
+  ### Badge with string
 
-    The `value` property can accept both a `number` and a `string`.
+The `value` property can accept both a `number` and a `string`.
 
   </LivePreview>
 </LivePreviewControls>
diff --git a/site/docs/components/badge/index.mdx b/site/docs/components/badge/index.mdx
@@ -1,7 +1,7 @@
 ---
 title: Badge
 data:
-  description: Badge is a numeric or alpha character annotation that represents a number of items.  It appears either on the top-right of an element, or inline.
+  description: "`Badge` is a numeric or alpha character annotation.  It appears either in the top-right corner of an element, or inline."
   sourceCodeUrl: "https://github.com/jpmorganchase/salt-ds/blob/main/packages/core/src/badge/Badge.tsx"
   package:
     name: "@salt-ds/core"