Feat/docs content section

src/data/components.json

@@ -940,7 +940,7 @@
     "Content section": {
       "url": "/components/content-section",
       "designLink": "https://ibm.box.com/s/oqlsa6m0vfownbn1s2y682mnugsf6cuv",
-      "description": "Content section is a high-level content component that acts as the main content unit to build web page experiences for IBM.com. It encapsulates other content components (one or multiple Content blocks and/or Content groups) and brings them together, providing flexibility to create many different solutions for users.",
+      "description": "Content section is the main layout component used to to build web experiences on IBM.com. It encapsulates two types of headings and can accept many child components to enable maximum customization and flexibility.",
       "storybook": {
         "webcomponents": "https://www.ibm.com/standards/carbon/web-components/?path=/story/components-content-section--default",
         "react": "https://www.ibm.com/standards/carbon/react/?path=/story/components-content-section--default",

src/pages/components/content-section.mdx

@@ -1,9 +1,6 @@
 ---
 title: Content section
-description:
-  Content section is a high-level content component that acts as the main content unit to build web page experiences for
-  IBM.com. It encapsulates other content components (one or multiple Content blocks and/or Content groups) and brings
-  them together, providing flexibility to create many different solutions for users.
+description: Content section is the main layout component used to to build web experiences on IBM.com. It encapsulates two types of headings and can accept many child components to enable maximum customization and flexibility.
 ---
 
 import ComponentDescription from 'components/ComponentDescription';
@@ -14,146 +11,144 @@ import ResourceLinks from 'components/ResourceLinks';
 
 <AnchorLinks>
 
-<AnchorLink>Resources</AnchorLink>
 <AnchorLink>Overview</AnchorLink>
+<AnchorLink>Modifiers</AnchorLink>
 <AnchorLink>Behaviors</AnchorLink>
-<AnchorLink>Tips and techniques</AnchorLink>
+<AnchorLink>Gallery</AnchorLink>
+<AnchorLink>Resources</AnchorLink>
 <AnchorLink>Content guidance</AnchorLink>
 <AnchorLink>Related components</AnchorLink>
 <AnchorLink>Feedback</AnchorLink>
 
 </AnchorLinks>
 
-<ResourceLinks name="Content section" type="layout" />
-
 ## Overview
 
-The Content section component can be used and customized for different types of web page experiences, boosting
-productivity by not having to recreate it every time. Because it is naturally decoupled from the Dotcom shell, it can be
-used multiple times on a web page, acting as the main structural content unit.
+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. 
 
-<Row>
+![Image of the content section](../../images/component/content-section/content-section-overview.png)
 
-<Column colMd={8} colLg={4}>
+<Caption>Example of the content section.</Caption>
 
-![A visual example of the hierarchy of different content components](../../images/component/content-section/component--content-section--structure.gif)
+### Anatomy
 
-<Caption>
-  See how Content section, Content block, Content group and Content item act as
-  hierarchical content containers for each other.
-</Caption>
+![Anatomy image of the content section](../../images/component/content-section/content-section-anatomy.png)
 
-</Column>
+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.
 
-<Column colMd={8} colLg={8}>
+## Modifiers
 
-![A visual example of the Content section component](../../images/component/content-section/component--content-section--overview.png)
+### Children
 
-<Caption>Anatomy of the Content section component</Caption>
+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.
 
-1. **Heading:** A customizable heading for the Content section.
-2. **Description:** A short description.
-3. **CTA text link or CTA card link:** Use this as a general call to action at the Content section level.
-4. **Child container:** Use this to insert other high-level content units, like content blocks and content groups.
+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.
 
-</Column>
+#### 8 column child
 
-</Row>
+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.
 
-#### When to use
+![Image of a content section with an 8 column child component](../../images/component/content-section/content-section-modifier-children-01.png)
 
-Use Content section when you need to organize a web page experience into main content units. One of the advantages of
-Content section is that it can take a different color theme from the page theme. Use this option carefully to avoid an
-unwanted page banding experience. Page banding happens when contrasting full-width backgrounds are alternating on a
-page, interrupting the reading experience for the user.
+<Caption>
+  Example of the content section with a child component that spans 8 columns.
+</Caption>
 
-#### When not to use
+#### 12 column child
 
-Do not use a Content section to separate only content items, or other related basic content items (like paragraphs)
-inside a web page. Use a [Content group](https://www.ibm.com/standards/carbon/components/content-group) instead.
+In this example the content section is paired with a [card group](../components/card-group) that spans 12 columns of the grid.
 
-## Behaviors
+![Image of a content section with an 12 column child component](../../images/component/content-section/content-section-modifier-children-02.png)
 
-The Content section elements are persistent throughout the online experience. It is fully responsive and changes how
-elements are displayed based on the browser size.
+<Caption>
+  Example of the content section with a child component that spans 12 columns.
+</Caption>
 
-#### Desktop breakpoints
+#### Mixing children widths
 
-If the browser is wider than the max breakpoint of 1584px, the Content section and all other page content will center
-and extra margin will appear on either side of the page layout. The Content section heading, description and link CTA
-will take the first four (out of 16) columns of the grid, while the children container will take the other 12 columns.
+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.
 
-#### Mobile breakpoints
+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
 
-At medium and small breakpoints, the Content section will add a significant change: the child container will move above
-the CTA text link. See the image below.
+![Image of a content section with an 12 column child component](../../images/component/content-section/content-section-modifier-children-03.png)
 
-<Row>
+<Caption>
+  Example of the content section with a child component that spans 8 columns, followed by another child that spans 12 columns.
+</Caption>
 
-<Column colMd={8} colLg={12}>
+## Behaviors
 
-![A visual example of the Content section component at different breakpoints](../../images/component/content-section/component--content-section--behavior.png)
+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.
 
-</Column>
+<Row>
 
-</Row>
+<Column colMd={8} colLg={8}>
 
-<Caption>
-  Content section with a Content block simple, at desktop and mobile breakpoints
-</Caption>
+![Image of the content section at tablet breakpoint](../../images/component/content-section/content-section-behavior-01.png)
 
-### Examples
+<Caption>Example of content section at medium breakpoint</Caption>
 
-These examples showcase the adaptability of Content section, encapsulating a
-[Content block simple](https://www.ibm.com/standards/carbon/components/content-block-simple), or a
-[Content block cards](https://www.ibm.com/standards/carbon/components/content-block-cards), both ready-to-use
-components.
+</Column>
 
-<Row>
+<Column colMd={8} colLg={4}>
 
-<Column colMd={8} colLg={8}>
+![Image of the content section at mobile breakpoint](../../images/component/content-section/content-section-behavior-02.png)
 
-![A visual example of the content block component](../../images/component/content-section/component--content-section--showcase.gif)
+<Caption>Example of content section at mobile breakpoint</Caption>
 
 </Column>
 
 </Row>
 
-<Caption>
-  Showcasing the versatility and adaptability of the Content section component
-</Caption>
+## Gallery
+
+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}>
 
-## Tips and techniques
+![Content section with tabs extended](../../images/component/content-section/content-section-gallery-01.png)
 
-The Content section elements are persistent throughout the online experience. It is fully responsive and changes how
-elements are displayed based on the browser size.
+</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}>
 
-It's important to keep in mind that on medium and small breakpoints, the child container is positioned between the
-Content section description and the CTA text link.
+![Content section with content block and a group of content item pictograms](../../images/component/content-section/content-section-gallery-02.png)
 
-Each type of content unit (content section, content block, content group or content item, and their many options) will
-usually have a certain type of CTA as the last element in the component architecture.
+</ImageGalleryImage>
+<ImageGalleryImage alt="Content section with three children" title="Content section with three children: content block, image, and quote" col={4}>
 
-Try to avoid CTA stacking at the end of a Content section. If multiple CTAs are present, use different types. For
-example, a card link from a Content block and a CTA text link as the final element of the Content section.
+![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                                                                                        |
 | ---------------------------------------------------------- | ------------ | -------- | --------- | ------------------------------------------- | -------------------------------------------------------------------------------------------- |
-| Heading                                                    | Text         | No       | 1         | 25 / 35                                     |                                                                                              |
-| Copy                                                       | Text         | No       | 1         | 65 / 85                                     |                                                                                              |
-| 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                                     | Text style only. Jump link type is not allowed.                                              |
+| 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                                                                                                                                                       |
-| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| [Card section](https://www.ibm.com/standards/carbon/components/card-section)                                 | Card section is a Content section that includes a content section heading and in its child container, it contains a Card group component.                         |
-| [Card section carousel](https://www.ibm.com/standards/carbon/components/card-section-carousel)               | Card section carousel is a Content section that includes a content section heading and a carousel component for navigation throughout a group of CTA cards.       |
-| [Card section images](https://www.ibm.com/standards/carbon/components/card-section#card-section-with-images) | Card section images is a Content section that includes a content section heading, and a Card group component encapsulated in the Content section child container. |
+| 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" />