docs: add flush accordion content (#3168)

* update usage docs with flush modifier

* update usage images

* update: usage

* update: style

* fix break

* update mdx

* update mdx

* update image

* update style tab

* refine style images

* adjust style images in tab comp.

* update style structure

* update style image

* update color  image

src/pages/components/accordion/style.mdx

@@ -32,13 +32,25 @@ tabs: ['Usage', 'Style', 'Code', 'Accessibility']
 <Row>
 <Column colLg={12}>
 
-![accordion interactive states](images/accordion-style-2.png)
+<Tabs>
+
+<Tab label="Default">
+
+![default accordion alignment interactive states](images/accordion-style-2.png)
+
+</Tab>
+
+<Tab label="Flush">
+
+![flush accordion alignment interactive states](images/accordion-style-3.png)
+
+</Tab>
+
+</Tabs>
 
 </Column>
 </Row>
 
-<Caption>Examples of enabled, hover, focus, and disabled states</Caption>
-
 ## Typography
 
 All accordion titles are set in sentence case. See the accordion
@@ -54,27 +66,80 @@ All accordion titles are set in sentence case. See the accordion
 There is no max-height for an open panel but an accordion may
 [scroll](/components/accordion/usage#scrolling-content) if constrained by
 vertical space. The width of an accordion varies based on the content, layout,
-and page design. The icon used in the header is a `chevron`.
+and page design. The icon used in the header is a `chevron`. The accordion has
+an indented default alignment but can also be set to have a flush alignment.
+
+### Default alignment
 
 | Element | Property       | px/rem   | Spacing token |
 | ------- | -------------- | -------- | ------------- |
 | Header  | height         | 40 / 2.5 | –             |
 | Item    | border-top     | 1        | –             |
-| Icon    | size           | 16 / 1   | –             |
-|         | padding-right  | 16 / 1   | `$spacing-05` |
 | Title   | margin-left    | 16 / 1   | `$spacing-05` |
-| Panel   | padding-right  | 25%      | –             |
-|         | padding-top    | 8 / 0.5  | `$spacing-03` |
+| Panel   | padding-top    | 8 / 0.5  | `$spacing-03` |
+|         | padding-bottom | 24 / 1.5 | `$spacing-06` |
+|         | padding-right  | 25%      | –             |
 |         | padding-left   | 16 / 1   | `$spacing-05` |
+| Icon    | size           | 16 / 1   | –             |
+|         | padding-right  | 16 / 1   | `$spacing-05` |
+
+<div className="image--fixed">
+
+![Structure measurements for default accordion alignment](images/accordion-style-4.png)
+
+</div>
+
+<Caption>
+  Structure measurements for default accordion alignment. | px / rem
+</Caption>
+
+<br />
+
+<div className="image--fixed">
+
+![Spacing measurements for default accordion alignment](images/accordion-style-5.png)
+
+</div>
+
+<Caption>
+  Spacing measurements for default accordion alignment. | px / rem
+</Caption>
+
+### Flush alignment
+
+| Element | Property       | px/rem   | Spacing token |
+| ------- | -------------- | -------- | ------------- |
+| Header  | height         | 40 / 2.5 | –             |
+| Item    | border-top     | 1        | –             |
+| Title   | margin-left    | 0        | –             |
+| Panel   | padding-top    | 8 / 0.5  | `$spacing-03` |
 |         | padding-bottom | 24 / 1.5 | `$spacing-06` |
+|         | padding-right  | 25%      | –             |
+|         | padding-left   | 0        | –             |
+| Icon    | size           | 16 / 1   | –             |
+|         | padding-right  | 0        | –             |
+
+<div className="image--fixed">
+
+![Structure measurements for flush accordion alignment](images/accordion-style-6.png)
+
+</div>
+
+<Caption>
+  Structure measurements for flush accordion alignment. | px / rem
+</Caption>
+
+<br />
 
 <div className="image--fixed">
 
-![Structure and spacing measurements for accordion](images/accordion-style-3.png)
+![Spacing measurements for flush accordion alignment](images/accordion-style-7.png)
 
 </div>
 
-<Caption>Structure and spacing measurements for accordion | px / rem</Caption>
+<Caption>
+  Spacing measurements for flush accordion alignment. | px / rem
+</Caption>
 
 ### Margin right
 

src/pages/components/accordion/usage.mdx

@@ -20,6 +20,7 @@ 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>
@@ -38,7 +39,7 @@ 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.
 
-### When to use:
+### When to use
 
 - To organize related information.
 - To shorten pages and reduce scrolling when content is not crucial to read in
@@ -54,8 +55,7 @@ extra click; instead use a full scrolling page with normal headers.
       id: 'accordion',
       label: 'Accordion',
     },
-  ]}
->
+  ]}>
   <ComponentVariant
     id="accordion"
     knobs={{
@@ -70,8 +70,7 @@ extra click; instead use a full scrolling page with normal headers.
       Vue: 'http://vue.carbondesignsystem.com/?path=/story/components-cvaccordion--default',
       'Web Components':
         'https://web-components.carbondesignsystem.com/?path=/story/components-accordion--default',
-    }}
-  >
+    }}>
     {`
   <Accordion>
     <AccordionItem title="Title 1"><p>The accordion component delivers large amounts of content in a small space through progressive disclosure. The user gets key details about the underlying content and can choose to expand that content within the constraints of the accordion. Accordions work especially well on mobile interfaces or whenever vertical space is at a premium.</p></AccordionItem>
@@ -147,8 +146,12 @@ such as a side panel or tile.
 
 #### Grid placement
 
-When placing an accordion on the 2x Grid the indented title aligns to the grid
-columns and the top and bottom borders hang in the gutter.
+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.
 
 <Row>
 <Column colLg={8}>
@@ -246,6 +249,35 @@ 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
@@ -257,7 +289,7 @@ very short content might do better in a structured list.
 - [Progress indicator](/components/progress-indicator/usage)
 - [Structured list](/components/structured-list/usage)
 - [Tabs](/components/tabs/usage)
-- Tree view
+- [Tree view](/components/tree-view/usage)
 
 ## References