docs(structured list) feature flag usage, style, code tab update (#4258)

* update usage.mdx

* add tag

* add tag

* update style.mdx

* update tag code

* update code.mdx

* remove tag

* feat: add tags and latest gatsby theme

* chore: format

* update usage.mdx

* update style.mdx

* update code.mdx

* update fixes

* format

* update

* Fixed a few links & packcage

* link shortened

* link shortened-2

* Update src/pages/components/structured-list/style.mdx

Co-authored-by: Anna Gonzales <[email protected]>

* update images and content from review

* update typo

* update heading and image

* fix image

---------

Co-authored-by: Alison Joseph <[email protected]>
Co-authored-by: kritvi-bhatia17 <[email protected]>
Co-authored-by: Anna Gonzales <[email protected]>
Co-authored-by: kodiakhq[bot] <49736102+kodiakhq[bot]@users.noreply.github.com>

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

@@ -7,6 +7,7 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 ---
 
 import { CheckmarkFilled } from '@carbon/icons-react';
+import { Tag } from '@carbon/react';
 
 <PageDescription>
 
@@ -25,6 +26,7 @@ code usage documentation, see the Storybooks for each framework below.
     >
 
 <MdxIcon name="react" />
+<Tag type="blue">Feature flag</Tag>
 
   </ResourceCard>
 </Column>
@@ -60,6 +62,18 @@ code usage documentation, see the Storybooks for each framework below.
 </Column>
 </Row>
 
+### Feature flags
+
+A [feature flag](/components/overview/feature-flags/) has been added to the
+selectable variant of structured list to improve accessibility and changes its
+visual appearance, not its functionality. For more code-specific feature flag
+information, refer to the
+[@carbon/react](https://react.carbondesignsystem.com/?path=/docs/experimental-feature-flags-structuredlist--overview)
+framework.
+
+The `enable-v12-structured-list-visible-icons` flag enables icons within
+structured list to always be visible, even when not selected.
+
 ## Live demo
 
 <StorybookDemo

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

@@ -6,42 +6,86 @@ description:
 tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 ---
 
+<PageDescription>
+
+The following page documents visual specifications such as color, typography,
+structure, and size.
+
+</PageDescription>
+
+<AnchorLinks>
+
+<AnchorLink>Color</AnchorLink>
+<AnchorLink>Typography</AnchorLink>
+<AnchorLink>Structure</AnchorLink>
+<AnchorLink>Size</AnchorLink>
+<AnchorLink>Feedback</AnchorLink>
+
+</AnchorLinks>
+
 ## Color
 
-By default, structured lists have a transparent background layer. Optionally,
-you can apply a colored background layer to a structured list. Structured lists
-with a colored background layer are only available in the hang alignment.
-
-| Element              | Property         | Color token         |
-| -------------------- | ---------------- | ------------------- |
-| Header text          | text-color       | `$text-primary`     |
-| Header row divider   | border-bottom    | `$border-subtle` \* |
-| Header (transparent) | background-color | transparent         |
-| Header (background)  | background-color | `$layer` \*         |
-| Row text             | text-color       | `$text-secondary`   |
-| Row divider          | border-bottom    | `$border-subtle` \* |
-| Row (transparent)    | background-color | transparent         |
-| Row (background)     | background-color | `$layer` \*         |
-| Icon                 | icon-color       | `$icon-primary`     |
+Structured lists have a transparent background layer. Optionally, you can apply
+a background color to a structured list. Structured lists with a background
+color are only available in the hang alignment.
+
+### Default color
+
+| Element      | Property         | Color token         |
+| ------------ | ---------------- | ------------------- |
+| Header       | background-color | transparent         |
+| Header: text | text color       | `$text-primary`     |
+| Row          | background-color | transparent         |
+| Row: text    | text color       | `$text-secondary`   |
+| Divider      | border-bottom    | `$border-subtle` \* |
 
 <Caption>
-  * Denotes a contextual color token that will change values based on the layer
+  \* Denotes a contextual color token that will change values based on the layer
+  it is placed on.
+</Caption>
+
+<Row>
+<Column colLg={12}>
+
+![Default structured list color](images/structured-list-style-color-default-transparent.png)
+
+<Caption>Default structured list color</Caption>
+
+</Column>
+</Row>
+
+### Selectable color
+
+Selectable structured list has an available
+[feature flag](/components/overview/feature-flags/).
+
+| Element      | Property         | Color token         |
+| ------------ | ---------------- | ------------------- |
+| Header       | background-color | transparent         |
+| Header: text | text color       | `$text-primary`     |
+| Row          | background-color | transparent         |
+| Row: text    | text color       | `$text-secondary`   |
+| Divider      | border-bottom    | `$border-subtle` \* |
+| Icon         | svg              | `$icon-primary`     |
+
+<Caption>
+  \* Denotes a contextual color token that will change values based on the layer
   it is placed on.
 </Caption>
 
 <Row>
 <Column colLg={12}>
 <Tabs>
 
-<Tab label="Transparent">
+<Tab label="Flag enabled">
 
-![Color of the interactive structured list](images/structured-list-style-1.png)
+![Selectable structured list color with the feature flag enabled](images/structured-list-style-color-selectable-flag-enabled.png)
 
 </Tab>
 
-<Tab label="Background">
+<Tab label="Flag disabled">
 
-![Color of the interactive structured list](images/structured-list-style-2.png)
+![Selectable structured list color with the feature flag disabled](images/structured-list-style-color-selectable-flag-disabled.png)
 
 </Tab>
 
@@ -50,51 +94,101 @@ with a colored background layer are only available in the hang alignment.
 </Column>
 </Row>
 
-### Interactive states
-
-The structured list interactive states are shown below with its default
-transparent background layer and its optional color background layer.
-
-| State               | Element           | Proptery         | Color token                |
-| ------------------- | ----------------- | ---------------- | -------------------------- |
-| Enabled (selected)  | Row               | background-color | `$layer-selected` \*       |
-|                     | Row text          | text-color       | `$text-primary`            |
-| Hover               | Row               | background-color | `$layer-hover` \*          |
-|                     | Row text          | text-color       | `$text-primary`            |
-| Hover (selected)    | Row               | background-color | `$layer-selected-hover` \* |
-|                     | Row text          | text-color       | `$text-primary`            |
-| Focus               | Row (transparent) | background-color | transparent                |
-|                     | Row (background)  | background-color | `$layer` \*                |
-|                     | Border            | border           | `$focus`                   |
-| Focus (selected)    | Row               | background-color | `$layer-selected` \*       |
-|                     | Row text          | text-color       | `$text-primary`            |
-|                     | Border            | border           | `$focus`                   |
-| Disabled            | Row (transparent) | background-color | transparent                |
-|                     | Row (background)  | background-color | `$layer` \*                |
-|                     | Row text          | text-color       | `$text-disabled`           |
-|                     | Icon              | inner fill       | `$icon-disabled`           |
-| Disabled (selected) | Row               | background-color | `$layer-selected` \*       |
-|                     | Row text          | text-color       | `$text-disabled`           |
-|                     | Icon              | inner fill       | `$icon-disabled`           |
+<Title>Selectable interactive state color</Title>{' '}
+
+| State               | Element   | Property         | Color token                |
+| ------------------- | --------- | ---------------- | -------------------------- |
+| Enabled (selected)  | Row       | background-color | `$layer-selected` \*       |
+|                     | Row: text | text color       | `$text-primary`            |
+| Hover               | Row       | background-color | `$layer-hover` \*          |
+|                     | Row: text | text color       | `$text-primary`            |
+| Hover (selected)    | Row       | background-color | `$layer-selected-hover` \* |
+|                     | Row: text | text color       | `$text-primary`            |
+| Focus               | Row       | border           | `$focus`                   |
+| Focus (selected)    | Row       | background-color | `$layer-selected` \*       |
+|                     | Row: text | text color       | `$text-primary`            |
+|                     | Border    | border           | `$focus`                   |
+| Disabled            |
+|                     | Row: text | text color       | `$text-disabled`           |
+|                     | Icon      | svg              | `$icon-disabled`           |
+| Disabled (selected) | Row       | background-color | `$layer-selected` \*       |
+|                     | Row: text | text color       | `$text-disabled`           |
+|                     | Icon      | svg              | `$icon-disabled`           |
 
 <Caption>
-  * Denotes a contextual color token that will change values based on the layer
+  \* Denotes a contextual color token that will change values based on the layer
   it is placed on.
 </Caption>
 
 <Row>
 <Column colLg={12}>
 <Tabs>
 
-<Tab label="Transparent">
+<Tab label="Flag enabled">
 
-![State of the interactive structured list](images/structured-list-style-3.png)
+![Selectable structured list interactive states with the feature flag enabled](images/structured-list-style-interactive-color-selectable-flag-enabled.png)
 
 </Tab>
 
-<Tab label="Background">
+<Tab label="Flag disabled">
 
-![State of the interactive structured list](images/structured-list-style-4.png)
+![Selectable structured list interactive states with the feature flag disabled](images/structured-list-style-interactive-color-selectable-flag-disabled.png)
+
+</Tab>
+
+</Tabs>
+
+</Column>
+</Row>
+
+### With background color
+
+| Element | Property         | Color token |
+| ------- | ---------------- | ----------- |
+| Header  | background-color | `$layer` \* |
+| Row     | background-color | `$layer` \* |
+
+<Caption>
+  \* Denotes a contextual color token that will change values based on the layer
+  it is placed on.
+</Caption>
+
+<Row>
+<Column colLg={12}>
+<Tabs>
+
+<Tab label="Flag enabled">
+
+![Selectable structured list color with the feature flag enabled](images/structured-list-style-color-selectable-background-flag-enabled.png)
+
+</Tab>
+
+<Tab label="Flag disabled">
+
+![Selectable structured list color with the feature flag disabled](images/structured-list-style-color-selectable-background-flag-disabled.png)
+
+</Tab>
+
+</Tabs>
+
+</Column>
+</Row>
+
+<Title>With background interactive state color</Title>
+
+<Row>
+<Column colLg={12}>
+<Tabs>
+
+<Tab label="Flag enabled">
+
+![Selectable structured list interactive states with the feature flag enabled](images/structured-list-style-interactive-color-selectable-background-flag-enabled.png)
+
+</Tab>
+
+<Tab label="Flag disabled">
+
+![Selectable structured list interactive states with the feature flag disabled](images/structured-list-style-interactive-color-selectable-background-flag-disabled.png)
 
 </Tab>
 
@@ -105,37 +199,35 @@ transparent background layer and its optional color background layer.
 
 ## Typography
 
-Structured list headings should be set in title case, while all other text is
-set in sentence case. All typography is left aligned.
+Structured list header and row text should use sentence-case capitalization. All
+typography is left aligned.
 
-| Element   | px / rem   | Font-weight    | Type token            |
-| --------- | ---------- | -------------- | --------------------- |
-| Heading   | 14 / 0.875 | SemiBold / 600 | `$heading-compact-01` |
-| List text | 14 / 0.875 | Regular / 400  | `$body-01`            |
+| Element     | Font-size (px/rem) | Font-weight    | Type token            |
+| ----------- | ------------------ | -------------- | --------------------- |
+| Header text | 14 / 0.875         | SemiBold / 600 | `$heading-compact-01` |
+| Row text    | 14 / 0.875         | Regular / 400  | `$body-01`            |
 
 ## Structure
 
-| Element         | Property                    | px / rem    | Spacing token |
-| --------------- | --------------------------- | ----------- | ------------- |
-| Structured list | min-width                   | 500 / 31.25 | –             |
-| Header          | padding-top                 | 16 / 1      | `$spacing-05` |
-|                 | padding-bottom              | 8 / 0.5     | `$spacing-03` |
-|                 | padding-right               | 16 / 1      | `$spacing-05` |
-|                 | padding-left (hang)         | 16 / 1      | `$spacing-05` |
-|                 | padding-left (flush)        | 0           | –             |
-| Row text        | padding-top                 | 16 / 1      | `$spacing-05` |
-|                 | padding-bottom              | 24 / 1.5    | `$spacing-06` |
-|                 | padding-right               | 16 / 1      | `$spacing-05` |
-|                 | padding-left (hang)         | 16 / 1      | `$spacing-05` |
-|                 | padding-left (flush)        | 0           | –             |
-| Icon            | height, width               | 16px        | –             |
-|                 | padding-left, padding-right | 16 / 1      | `$spacing-05` |
-
 ### Default structure
 
+| Element      | Property             | px / rem    | Spacing token |
+| ------------ | -------------------- | ----------- | ------------- |
+| Container    | min-width            | 500 / 31.25 | –             |
+| Header: text | padding-top          | 16 / 1      | `$spacing-05` |
+|              | padding-bottom       | 8 / 0.5     | `$spacing-03` |
+|              | padding-right        | 16 / 1      | `$spacing-05` |
+|              | padding-left (hang)  | 16 / 1      | `$spacing-05` |
+|              | padding-left (flush) | 0px         | –             |
+| Row: text    | padding-top          | 16 / 1      | `$spacing-05` |
+|              | padding-bottom       | 24 / 1.5    | `$spacing-06` |
+|              | padding-right        | 16 / 1      | `$spacing-05` |
+|              | padding-left (hang)  | 16 / 1      | `$spacing-05` |
+|              | padding-left (flush) | 0px         | –             |
+
 <div className="image--fixed">
 
-![Spacing and measurements for default structured list](images/structured-list-style-5.png)
+![Spacing and measurements for default structured list with hang and flush alignment | px / rem. ](images/structured-list-style-structure.png)
 
 </div>
 
@@ -146,30 +238,49 @@ set in sentence case. All typography is left aligned.
 
 ### Selectable structure
 
+| Element      | Property                    | px / rem    | Spacing token |
+| ------------ | --------------------------- | ----------- | ------------- |
+| Container    | min-width                   | 500 / 31.25 | –             |
+| Header: text | padding-top                 | 16 / 1      | `$spacing-05` |
+|              | padding-bottom              | 8 / 0.5     | `$spacing-03` |
+|              | padding-right               | 16 / 1      | `$spacing-05` |
+|              | padding-left, padding-right | 16 / 1      | `$spacing-05` |
+| Row: text    | padding-top                 | 16 / 1      | `$spacing-05` |
+|              | padding-bottom              | 24 / 1.5    | `$spacing-06` |
+|              | padding-left, padding-right | 16 / 1      | `$spacing-05` |
+| Icon         | height, width               | 16px        | –             |
+|              | padding-left, padding-right | 16 / 1      | `$spacing-05` |
+
 <div className="image--fixed">
 
-![Spacing and measurements for selectable structured list](images/structured-list-style-6.png)
+![Structure and spacing measurements for selectable structured list with a feature flag | px / rem.](images/structured-list-style-structure-selectable-flag-enabled.png)
 
 </div>
 
 <Caption>
-  Spacing and measurements for selectable structured list with hang alignment |
-  px / rem.
+  Structure and spacing measurements for selectable structured list with a
+  feature flag | px / rem.
 </Caption>
 
 ## Size
 
-There are two structured list sizes: default and condensed.
+There are two structured list height sizes: **default** and **condensed**.
 
-| Element  | Size      | px / rem  |
-| -------- | --------- | --------- |
-| Row item | Default   | 60 / 3.75 |
-|          | Condensed | 36 / 2.25 |
+| Element | Size      | Height (px/rem) |
+| ------- | --------- | --------------- |
+| Row     | Default   | 60 / 3.75       |
+|         | Condensed | 36 / 2.25       |
 
 <div className="image--fixed">
 
-![Sizes of structured list with selection](images/structured-list-style-7.png)
+![Structured list sizes | px / rem](images/structured-list-style-size.png)
 
 </div>
 
-<Caption>Default and condensed sizes for structured lists</Caption>
+<Caption> Structured list sizes | px / rem </Caption>
+
+## Feedback
+
+Help us improve this component by providing feedback, asking questions, and
+leaving any other comments on
+[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md).