Feat/docs content section (carbon-design-system#1692)

* update copy for content section page

* add new images - update mdx image paths - update json

* Update content-section.mdx

* Update components.json

* fix(content-section): remove extra Row component

* update image path anatomy and content guideline table

* Update src/pages/components/content-section.mdx

Co-authored-by: Rich Kummer <[email protected]>

* Update src/pages/components/content-section.mdx

Co-authored-by: Rich Kummer <[email protected]>

* Update src/pages/components/content-section.mdx

Co-authored-by: Rich Kummer <[email protected]>

* Update src/pages/components/content-section.mdx

Co-authored-by: Rich Kummer <[email protected]>

* Update general copy

* delete v1 images

* replace images and add gallery images

* fix links for images

* add gallery

* add Related components section

* Updated images for gallery

* add description for child widths

* Update src/pages/components/content-section.mdx

Co-authored-by: Rich Kummer <[email protected]>

* Update content-section.mdx

---------

Co-authored-by: Anna Wen <[email protected]>
Co-authored-by: Rich Kummer <[email protected]>
Co-authored-by: Kenny Lam <[email protected]>

src/pages/components/content-block.mdx

@@ -52,7 +52,8 @@ Content block is often paired with the content section or the vertical table of
 ![Content block with a section heading at the desktop breakpoint. The section heading is highlighted.](../../images/component/content-block/content-block-usage-01.png)
 
 <Caption>
-  Content block paired with a content section, the content section heading is highlighted.
+  Content block paired with a content section, the content section heading is
+  highlighted.
 </Caption>
 
 </Column>
@@ -62,7 +63,8 @@ Content block is often paired with the content section or the vertical table of
 ![Content block with a table of contents - vertical  at the desktop breakpoint. The table of contents - vertical is highlighted.](../../images/component/content-block/content-block-usage-02.png)
 
 <Caption>
-  Content block paired with a table of contents vertical, the table of contents is highlighted.
+  Content block paired with a table of contents vertical, the table of contents
+  is highlighted.
 </Caption>
 
 </Column>
@@ -121,19 +123,15 @@ At smaller breakpoints the content block will respond to the 2x grid.
 
 ![Image of the content block at tablet breakpoint](../../images/component/content-block/content-block-behavior-01.png)
 
-<Caption>
-  Example of content block medium breakpoint
-</Caption>
+<Caption>Example of content block medium breakpoint</Caption>
 
 </Column>
 
 <Column colMd={8} colLg={4}>
 
 ![Image of the content section at mobile breakpoint](../../images/component/content-block/content-block-behavior-02.png)
 
-<Caption>
-  Example of content block at mobile breakpoint
-</Caption>
+<Caption>Example of content block at mobile breakpoint</Caption>
 
 </Column>
 

src/pages/components/content-section.mdx

@@ -17,13 +17,14 @@ import ResourceLinks from 'components/ResourceLinks';
 <AnchorLink>Gallery</AnchorLink>
 <AnchorLink>Resources</AnchorLink>
 <AnchorLink>Content guidance</AnchorLink>
+<AnchorLink>Related components</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
 ## Overview
 
-The content section acts as the heading level two on all pages after the lead space component. The content section is used to divide the main categories or sections of the page to help guide the user through the content or narrative.
+The content section acts as the heading level two on pages after the lead space component and spans the full 16 column grid. The content section is used to divide the main categories or sections of the page to help guide the user through the content or narrative. 
 
 ![Image of the content section](../../images/component/content-section/content-section-overview.png)
 
@@ -33,114 +34,55 @@ The content section acts as the heading level two on all pages after the lead sp
 
 ![Anatomy image of the content section](../../images/component/content-section/content-section-anatomy.png)
 
-1. **Content section heading:** An optional, customizable heading for the Content section.
-2. **Content block heading:** An optional, customizable heading for the Content section.
-3. **Sub heading:** An opptional, customizable sub heading for the Content section.
-4. **Copy:** An optional short description.
-5. **Child container:** Insert additional components to enhance the narrative, such as content group, content item or card group.
-6. **CTA:** Use this as a general call to action, typically used to encompass the entire content section.
-7. **Border:** An optional bottom border.
+1. **Content section heading:** A customizable heading for the Content section.
+2. **Child container:** Insert additional components to enhance the narrative, such as content block, content group, content item or card group, etc.
+3. **Border:** An optional bottom border.
 
 ## Modifiers
 
-### Headings
-
-The content section has two types of optional headings – **content section** and **content block** – that can be turned on and off to fit the layout needs.
-
-![Image of the content section](../../images/component/content-section/content-section-modifier-heading-01.png)
-
-<Caption>Example of the content section.</Caption>
-
-#### Content section heading
-
-Turn off the content section heading to utilize the vertical [table of contents](../components/table-of-contents) component for long form reading experiences that allow the user to quickly navigate through the content.
-
-<Row>
-
-<Column colMd={4} colLg={6}>
-
-![Example highlighting content section heading](../../images/component/content-section/content-section-modifier-heading-02.png)
-
-<Caption>
-  Example of the content section component, where the content section heading is
-  highlighted.
-</Caption>
-
-</Column>
-
-<Column colMd={4} colLg={6}>
-
-![Example highlighting table of contents](../../images/component/content-section/content-section-modifier-heading-03.png)
-
-<Caption>
-  Example of replacing the content section heading with the vertical table of
-  contents.
-</Caption>
-
-</Column>
-
-</Row>
+### Children
 
-#### Content block heading
+The content section can accept many different types of child components, which allows designers and authors maximum flexibility when creating page layouts. The most common layouts on IBM.com are 8 column and 12 column components.
 
-Turn off the content block heading for concise layout samples, this layout works well with the horizontal table of contents component.
+There is no limit to how many child components the content section can accept - consider the story you are trying to tell, the overall hierarchy of the page and how many content sections should be used to break up the content. View the [gallery](#gallery) to see examples of content section with various child components.
 
-<Row>
+#### 8 column child
 
-<Column colMd={4} colLg={6}>
+In this example the content section is paired with a group of [content item pictograms](../components/content-item) that span the center 8 columns of the grid.
 
-![Example highlighting content block heading](../../images/component/content-section/content-section-modifier-heading-04.png)
+![Image of a content section with an 8 column child component](../../images/component/content-section/content-section-modifier-children-01.png)
 
 <Caption>
-  Example of the content section component, where the content block heading is
-  highlighted.
+  Example of the content section with a child component that spans 8 columns.
 </Caption>
 
-</Column>
+#### 12 column child
 
-<Column colMd={4} colLg={6}>
+In this example the content section is paired with a [card group](../components/card-group) that spans 12 columns of the grid.
 
-![Example highlighting the removal of the content block heading](../../images/component/content-section/content-section-modifier-heading-05.png)
+![Image of a content section with an 12 column child component](../../images/component/content-section/content-section-modifier-children-02.png)
 
 <Caption>
-  Example of turning off the content section's content block heading, and all
-  remaining content shifts upward to top align with the content section heading.
+  Example of the content section with a child component that spans 12 columns.
 </Caption>
 
-</Column>
-
-</Row>
-
-### Children
-
-The content section can accept many different types of child components, which allows designers and authors maximum flexibility when creating page layouts. The most common layouts on IBM.com are 8 column and 12 column components.
+#### Mixing children widths
 
-#### 8 column child
+The content section can support mixing of various children and how many columns of the grid the children can span. Most of the Carbon for IBM.com components have been carefully designed with line length, and column usage in mind, and therefore should fit within the columns without alteration.
 
-_Add description text here_
+In this example the content section has two children:
+- A content block that spans 8 columns of the grid
+- A group of content items that span 12 columns of the grid
 
-![Image of a content section with an 8 column child component](../../images/component/content-section/content-section-modifier-children-02.png)
+![Image of a content section with an 12 column child component](../../images/component/content-section/content-section-modifier-children-03.png)
 
 <Caption>
-  Example of the content section with a child component that spans 8 columns.
+  Example of the content section with a child component that spans 8 columns, followed by another child that spans 12 columns.
 </Caption>
 
-#### 12 column child
-
-_Add description text here_
-
-![Image of a content section with an 12 column child component](../../images/component/content-section/content-section-modifier-children-01.png)
-
-<Caption>
-  Example of the content section with a child component that spans 12 columns.
-</Caption>
-
-There is no limit to how many child components the content section can accept - consider the story you are trying to tell, the overall hierarchy of the page and how many content sections should be used to break up the content. View the [gallery](#gallery) to see examples of content section with various child components.
-
 ## Behaviors
 
-The content section elements are persistent throughout the experience. It is fully responsive and changes how
-elements are displayed based on the browser size, at tablet and mobile breakpoints the content section heading stacks on top of the content block heading.
+The content section elements are persistent throughout the experience. It is fully responsive and changes how elements are displayed based on the browser size, at tablet and mobile breakpoints the content section heading stacks on top of the child container.
 
 <Row>
 
@@ -166,20 +108,47 @@ elements are displayed based on the browser size, at tablet and mobile breakpoin
 
 The content section is the main building block for establishing sections throughout pages of the IBM.com platform. Here are some examples of various layouts you can create by utilizing the extreme flexibility the content section provides by utilizing the varying heading options and adding custom children.
 
+<ImageGallery>
+<ImageGalleryImage alt="Content section with tabs extended" title="Content section with tabs extended and content item row" col={8}>
+
+![Content section with tabs extended](../../images/component/content-section/content-section-gallery-01.png)
+
+</ImageGalleryImage>
+<ImageGalleryImage alt="Content section with content block and a group of content item pictograms" title="Content section with content block and a group of content item pictograms" col={4}>
+
+![Content section with content block and a group of content item pictograms](../../images/component/content-section/content-section-gallery-02.png)
+
+</ImageGalleryImage>
+<ImageGalleryImage alt="Content section with three children" title="Content section with three children: content block, image, and quote" col={4}>
+
+![Content section with three children](../../images/component/content-section/content-section-gallery-03.png)
+
+</ImageGalleryImage>
+<ImageGalleryImage alt="Content section with card group" title="Content section with card group" col={8}>
+
+![Content section with card group](../../images/component/content-section/content-section-gallery-04.png)
+
+</ImageGalleryImage>
+</ImageGallery>
+
 <ResourceLinks name="Content section" type="layout" />
 
 ## Content guidance
 
 | Element                                                    | Content type | Required | Instances | Character limit <br/>(English / translated) | Notes                                                                                        |
 | ---------------------------------------------------------- | ------------ | -------- | --------- | ------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Content section heading                                    | Text         | No       | 1         | 25 / 35                                     |                                                                                              |
-| Content block heading                                      | Text         | No       | 1         | 40 / 55                                     |                                                                                              |
-| Sub heading                                                | Text         | No       | 1         | 120 / 150                                   |                                                                                              |
-| Copy                                                       | Text         | No       | 1         | 1600 / 2400                                 |                                                                                              |
-| Child container                                            | Component    | No       | 1+        | –                                           | An optional container area that child components and other content types can be passed into. |
-| [CTA](https://www.ibm.com/standards/carbon/components/cta) | Component    | No       | 1         | 25 / 35                                     |                                                                                              |
+| Content section heading                                    | Text         | Yes      | 1         | 25 / 35                                     |                                                                                              |
+| Child container                                            | Component    | Yes      | 1+        | –                                           | An optional container area that child components and other content types can be passed into. |
 | Border                                                     | Component    | No       | 1         | –                                           |                                                                                              |
 
 For more information, see the [character count standards](https://www.ibm.com/standards/carbon/guidelines/content#character-count-standards).
 
+## Related components
+
+| Component name                                   | Description                                                                        |
+| ------------------------------------------------ | ---------------------------------------------------------------------------------- |
+| [Content block](../components/content-block)     | Content block is one of the main content components used to structure pages.       |
+| [Content group](../components/content-group)     | Content group is one of the main content components used to display content items. |
+| [Content item](../components/content-item)       | Content item is the lowest level hierarchically of the content components.        |
+
 <ComponentFooter name="Content section" type="layout" />