docs: update single variant usage template (#4030)

* single variant usage doc update * update missing sentence * review updates * fix typos --------- Co-authored-by: Taylor Jones <[email protected]>
carbon-design-system · May 1, 2024 · f4e0b4e · f4e0b4e
1 parent b361cb2
commit f4e0b4e
Show file tree

Hide file tree

Showing 3 changed files with 425 additions and 121 deletions.
diff --git a/src/pages/components/accordion/usage.mdx b/src/pages/components/accordion/usage.mdx
@@ -22,7 +22,6 @@ associated sections of content.
 <AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Content</AnchorLink>
 <AnchorLink>Behaviors</AnchorLink>
-<AnchorLink>Modifiers</AnchorLink>
 <AnchorLink>Related</AnchorLink>
 <AnchorLink>References</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
@@ -47,14 +46,12 @@ associated sections of content.
 ## Overview
 
 The accordion component delivers large amounts of content in a small space
-through progressive disclosure. The header title give the user a high level
+through progressive disclosure. The header title gives the user a high level
 overview of the content allowing the user to decide which sections to read.
 
 Accordions can make information processing and discovering more effective.
 However, it does hide content from users and it's important to account for a
-user not noticing or reading all of the included content. If a user is likely to
-read all of the content then don't use an accordion as it adds the burden of an
-extra click; instead use a full scrolling page with normal headers.
+user not noticing or reading all of the included content.
 
 ### When to use
 
@@ -64,6 +61,14 @@ extra click; instead use a full scrolling page with normal headers.
 - When space is at a premium and long content cannot be displayed all at once,
   like on a mobile interface or in a side panel.
 
+### When not to use
+
+- When organizing large amounts of information that can be nested, consider
+  using [tree view](/components/tree-view/usage) instead.
+- If a user is likely to read all of the content, then don't use an accordion as
+  it adds the burden of an extra click; instead use a full scrolling page with
+  normal headers.
+
 ## Formatting
 
 ### Anatomy
@@ -83,6 +88,35 @@ extra click; instead use a full scrolling page with normal headers.
 
 ### Alignment
 
+#### Flush alignment
+
+Use flush alignment when designing within smaller spaces on a page such as side
+panels or sidebars to achieve better text alignment with other content. Flush
+alignment is also used to help avoid converging rule lines between components
+that are close to each other on a page.
+
+<Row>
+<Column colLg={8}>
+
+![accordion flush alignment](images/accordion-flush.png)
+
+</Column>
+</Row>
+
+Flush alignment places the row title and chevron icons with 0px padding, keeping
+them flush to the rule dividers. For hover and focus interactive states, the
+left and right padding receives an additional 16px padding.
+
+<Row>
+<Column colLg={8}>
+
+![accordion flush alignment spec](images/accordion-flush-spec.png)
+
+</Column>
+</Row>
+
+#### Icon alignment
+
 By default the chevron icon is placed on the `end` side of the header. This
 allows for the title on the `start` side to align with other type elements in
 the layout, which is the preferred alignment scenario.
@@ -136,9 +170,9 @@ such as a side panel or tile.
 When placing an accordion on the 2x Grid with its default alignment, the
 indented title and content align to the grid columns, and the top and bottom
 borders hang into the gutter. However, the accordion can be modified to have a
-[flush alignment](https://carbondesignsystem.com/components/accordion/usage#modifiers)
-where the titles and content are instead flush aligned with the top and bottom
-borders having 0px padding.
+[flush alignment](/components/accordion/usage#alignment) where the titles and
+content are instead flush aligned with the top and bottom borders having 0px
+padding.
 
 <Row>
 <Column colLg={8}>
@@ -171,6 +205,11 @@ When the accordion content is longer than the viewport the whole accordion
 should vertically scroll. Content should not scroll inside of an individual
 panel. Content should never scroll horizontally in an accordion.
 
+### Further guidance
+
+For further content guidance, see Carbon's
+[content guidelines](<[https://www.carbondesignsystem.com/guidelines/content/general](https://www.carbondesignsystem.com/guidelines/content/general)>).
+
 ## Behaviors
 
 ### States
@@ -236,47 +275,24 @@ Users can trigger a state change by pressing `Enter` or `Space` while the header
 area has focus. For additional keyboard interactions, see the
 [accessibility tab](/components/accordion/accessibility#keyboard-interactions).
 
-## Modifiers
-
-#### Flush alignment
-
-Use flush alignment when designing within smaller spaces on a page such as side
-panels or sidebars to achieve better text alignment with other content. Flush
-alignment is also used to help avoid converging rule lines between components
-that are close to each other on a page.
-
-<Row>
-<Column colLg={8}>
-
-![accordion flush alignment](images/accordion-flush.png)
-
-</Column>
-</Row>
-
-Flush alignment places the row title and chevron icons with 0px padding, keeping
-them flush to the rule dividers. For hover and focus interactive states, the
-left and right padding receives an additional 16px padding.
-
-<Row>
-<Column colLg={8}>
-
-![accordion flush alignment spec](images/accordion-flush-spec.png)
-
-</Column>
-</Row>
-
 ## Related
 
 The following components are additional ways to organize content. Consider the
 type and length of content you are working with when choosing a content
 container. Longer form content may benefit from tabs or a content switcher while
 very short content might do better in a structured list.
 
-- [Content switcher](/components/content-switcher/usage)
-- [Progress indicator](/components/progress-indicator/usage)
-- [Structured list](/components/structured-list/usage)
-- [Tabs](/components/tabs/usage)
-- [Tree view](/components/tree-view/usage)
+- [Content switchers](/components/content-switcher/usage) allow users to toggle
+  between two or more content sections within the same space on the screen.
+- [Progress indicators](/components/progress-indicator/usage) guide users
+  through any linear, multistep task by showing the user their completed,
+  current, and future steps.
+- [Structured lists](/components/structured-list/usage) group content that is
+  similar or related, such as terms and definitions.
+- [Tabs](/components/tabs/usage) organize related content by allowing the user
+  to navigate between groups of information that appear within the same context.
+- [Tree view](/components/tree-view/usage) is a hierarchical structure that
+  provides nested levels of navigation.
 
 ## References
 

diff --git a/src/pages/components/content-switcher/usage.mdx b/src/pages/components/content-switcher/usage.mdx
@@ -22,7 +22,7 @@ within the same space on the screen.
 <AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Content</AnchorLink>
 <AnchorLink>Behaviors</AnchorLink>
-<AnchorLink>Modifier</AnchorLink>
+<AnchorLink>Modifiers</AnchorLink>
 <AnchorLink>Related</AnchorLink>
 <AnchorLink>References</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
@@ -366,7 +366,7 @@ The content tab is clickable anywhere within the container.
 
 <Caption>Text and icon content switchers with their clickable areas</Caption>
 
-## Modifier
+## Modifiers
 
 ### Content switcher with icons