[doc update] Structured list

src/pages/components/structured-list/usage.mdx

@@ -15,12 +15,46 @@ definitions.
 
 <AnchorLinks>
 
+<AnchorLink>Overview</AnchorLink>
+<AnchorLink>Live demo</AnchorLink>
+<AnchorLink>Formatting</AnchorLink>
 <AnchorLink>Content</AnchorLink>
-<AnchorLink>Interactions</AnchorLink>
+<AnchorLink>Related</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
+## Overview
+
+Structured list displays a simple list with a considerable amount of items of
+read-only values. It helps organize and present grouped information into logical
+and scannable patterns. The content within a list can be stacked to create
+hierarchy within the data.
+
+#### When to use
+
+- To browse information or select certain information within the group in the
+  simplest form
+- To view description and detailed information, present features, or compare
+  pricing plans
+
+#### When not to use
+
+Nesting items is not recommended, as structured lists are used to present simple
+data. If you have more than 25 items or additional content that needs to be
+shown, consider using a
+[data table](https://www.carbondesignsystem.com/components/data-table/usage/),
+which supports nesting items and presents a larger set of content.
+
+### Variants
+
+| Variant      | Purpose                                                                       |
+| ------------ | ----------------------------------------------------------------------------- |
+| _Default_    | Allows the user to quickly browse and view information within a group of data |
+| _Selectable_ | Allows the user to mark or select a desired option within a group of data     |
+
+## Live demo
+
 import { CheckmarkFilled16 } from '@carbon/icons-react';
 
 <ComponentDemo
@@ -34,19 +68,21 @@ import { CheckmarkFilled16 } from '@carbon/icons-react';
       label: 'Selectable structured list',
     },
   ]}
-  scope={{ CheckmarkFilled16 }}>
+  scope={{ CheckmarkFilled16 }}
+>
   <ComponentVariant
     id="default-structured-list"
     links={{
       React:
         'https://react.carbondesignsystem.com/?path=/story/components-structuredlist--simple',
       Angular:
         'https://angular.carbondesignsystem.com/?path=/story/components-structured-list--basic',
-      Vue:
-        'http://vue.carbondesignsystem.com/?path=/story/components-cvstructuredlist--default',
+      Vue: 'http://vue.carbondesignsystem.com/?path=/story/components-cvstructuredlist--default',
       Vanilla: 'https://the-carbon-components.netlify.com/?nav=structured-list',
-      "Web Components": 'https://web-components.carbondesignsystem.com/?path=/story/components-structured-list--default',
-    }}>{`
+      'Web Components':
+        'https://web-components.carbondesignsystem.com/?path=/story/components-structured-list--default',
+    }}
+  >{`
     <StructuredListWrapper ariaLabel="Structured list">
       <StructuredListHead>
         <StructuredListRow
@@ -97,11 +133,12 @@ import { CheckmarkFilled16 } from '@carbon/icons-react';
         'https://react.carbondesignsystem.com/?path=/story/components-structuredlist--selection',
       Angular:
         'https://angular.carbondesignsystem.com/?path=/story/components-structured-list--with-selection',
-      Vue:
-        'http://vue.carbondesignsystem.com/?path=/story/components-cvstructuredlist--selectable-with-events',
+      Vue: 'http://vue.carbondesignsystem.com/?path=/story/components-cvstructuredlist--selectable-with-events',
       Vanilla: 'https://the-carbon-components.netlify.com/?nav=structured-list',
-      "Web Components": 'https://web-components.carbondesignsystem.com/?path=/story/components-structured-list--default',
-    }}>{`
+      'Web Components':
+        'https://web-components.carbondesignsystem.com/?path=/story/components-structured-list--default',
+    }}
+  >{`
     <StructuredListWrapper selection ariaLabel="Structured list">
       <StructuredListHead>
         <StructuredListRow
@@ -199,20 +236,44 @@ import { CheckmarkFilled16 } from '@carbon/icons-react';
   `}</ComponentVariant>
 </ComponentDemo>
 
+## Formatting
+
+### Anatomy
+
+Structured list is composed of two sections—column header and data row.
+
+<Row>
+<Column colLg={8}>
+
+![data table anatomy](images/structured-list-usage-1.png)
+
+</Column>
+</Row>
+
+1. **Column header**: Shows titles for the row header description.
+2. **Data row**: Shows different types of data. Rows can be selectable and
+   modified to show alternating zebra stripe background colors
+
+### Sizing
+
+Row height varies based on content and can expand to fit multiple lines. In a
+single list, all rows do not have to be the same height. Column widths can
+either be equally proportional or proportioned based on content.
+
 ## Content
 
-- Row height varies based on content and can expand to fit multiple lines.
-- In a single list, all rows do not have to be the same height.
-- Column widths can either be equally proportional or proportioned based on
-  content.
-- If a list extends past 25 items, consider using a
-  [data table](/components/data-table/usage) to present this larger set of
-  content.
-- A maximum of one paragraph of text is recommended per row.
-- Nesting items is not recommended, as structured lists are used to present
-  simple data. If you have additional content that needs to be shown, consider
-  using a [data table](/components/data-table/usage), which supports nesting
-  items.
+- A maximum of three paragraphs of text is recommended per row.
+- A structured list’s title and row information should use sentence-case
+  capitalization.
+
+#### Column header titles
+
+- Column header titles should be short and clear, sticking to one or two words
+  that describe the data in that column.
+- In cases where a column header title is too long, wrap the text to two lines
+  and then truncate the rest of the text. The full text should be shown in a
+  tooltip on hover.
+- Column header titles should use sentence-case capitalization.
 
 <Row>
 <Column colLg={8}>
@@ -224,10 +285,7 @@ import { CheckmarkFilled16 } from '@carbon/icons-react';
 
 ## Interactions
 
-Structured lists can be single-select if a user is choosing between a set of
-options.
-
-#### Guidelines:
+#### Selectable structured list
 
 - Only one item can be selected from the list.
 - By default, one option should be selected.
@@ -236,6 +294,14 @@ options.
 - When the user selects an item from the list, the selected row will appear with
   the `checkmark--filled` icon.
 
+## Related
+
+These following components are additional ways to organize a group of data.
+
+- [Accordion](https://www.carbondesignsystem.com/components/accordion/usage/)
+- [Data table](https://www.carbondesignsystem.com/components/data-table/usage/)
+- [List](https://www.carbondesignsystem.com/components/list/usage/)
+
 ## Feedback
 
 Help us improve this component by providing feedback, asking questions, and