@patternfly/patternfly 5.0.0-alpha.49 → 5.0.0-alpha.50

package/docs/layouts/Flex/examples/Flex.md

@@ -6,24 +6,21 @@ cssPrefix: pf-v5-l-flex
 
 ## Introduction
 
-The flex layout is based on the CSS Flex properties where the layout determines how a flex item will grow or shrink to fit the space available in its container. The system relies on a default spacer value `--pf-v5-l-flex--spacer--base`, whose value is `--pf-v5-global--spacer--md` or `16px` that is applied to flex items. By default, `flex-wrap` is set to `wrap` and `align-items` is set to `baseline`.
+The flex layout is based on the CSS Flex properties where the layout determines how a flex item will grow or shrink to fit the space available in its container. By default, a flex layout uses the [spacing system](#spacing-system) to space children along the main axis and [gap spacing](#gap-spacing) to space any wrapping children along the cross axis, `flex-wrap` is set to `wrap`, and `align-items` is set to `baseline`. The flex layout is infinitely nestable and can be nested to group items within.
 
-### Default spacing
-
-*   Flex items (not last child): `margin-right: 16px`.
-*   Nested `.pf-v5-l-flex` containers (not last child): `margin-right: 16px`.
-*   `.pf-m-column` direct descendants (not last child): `margin-bottom: 16px`.
-*   `.pf-m-column` nested `.pf-v5-l-flex` containers (not last child): `margin-bottom: 16px`.
+### Spacing
 
-## Features
+The flex layout provides two ways of spacing its direct children.
 
-*   `.pf-v5-l-flex` is infinitely nestable and can be used to group items within.
-*   `.pf-m-spacer-{xs,sm,md,lg,xl,2xl,3xl}` can be applied to parent or direct children and changes the spacer value for only the element to which it is applied. Responsive spacers can be used by appending `{-on-[breakpoint]}` to `.pf-m-spacer-{size}`. Example: `.pf-m-spacer-lg-on-xl`.
-*   `.pf-m-space-items-{xs,sm,md,lg,xl,2xl,3xl}` can be applied to `.pf-v5-l-flex` only and changes the spacing of direct children only. Responsive spacers can be used by appending `{-on-[breakpoint]}` to `.pf-m-space-items-{size}`. Example: `.pf-m-space-items-lg-on-xl`.
+*   [Spacing system](#spacing-system)
+    *   The spacing system applies a margin between the flex layout's direct children to create space between items along the main axis only. The benefit of the spacing system is that it allows for variable spacing between direct children. Use the spacing system when individual flex items along the main axis require a different spacer than sibling items.
+*   [Gap spacing](#gap-spacing)
+    *   Gap spacing uses flex `gap` to space the flex layout's direct children, and can be applied to space rows (`row-gap`), columns (`column-gap`), or both (`gap`). The benefit of gap spacing is that item wrapping is improved and improved item spacing that works better with CSS flex's logical layout properties. E.g., spacing in RTL layouts that rely on logical properties is improved. Use the gap system when all direct children should use the same spacer for rows, columns, or both.
+    *   **Note** using `gap` along the main axis will override any other spacing applied using the spacing system.
 
 ### Breakpoints
 
-*   [Breakpoints](/developer-resources/global-css-variables#breakpoint-variables-and-class-suffixes) `-on-sm`, `-on-md`, `-on-lg`, `-on-xl`, and `-on-2xl` are provided.
+[Breakpoints](/developer-resources/global-css-variables#breakpoint-variables-and-class-suffixes) `-on-sm`, `-on-md`, `-on-lg`, `-on-xl`, and `-on-2xl` are provided.
 
 ### Usefulness
 
@@ -32,31 +29,30 @@ The flex layout is based on the CSS Flex properties where the layout determines
 
 ### Differences from utility class
 
-*   It contains multiple css declarations and does not use the !important tag.
+*   It contains multiple css declarations and does not use the `!important` tag.
 *   It does not require wrapping elements in columns or rows.
 *   It breaks the dependency upon adding utility classes to each child.
 *   It can be applied to container elements or components.
 
-## Examples
+# Examples
+
+## Basic flex layout
 
-### Basic
+### Basic flex example
 
 ```html
-<h3>
-  Basic flex -
-  <code>.pf-v5-l-flex</code>.
-</h3>
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
 </div>
-<br />
-<h3>
-  Flex nesting -
-  <code>.pf-v5-l-flex > .pf-v5-l-flex</code>.
-</h3>
+
+```
+
+### Nested flex example
+
+```html
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -68,8 +64,12 @@ The flex layout is based on the CSS Flex properties where the layout determines
     <div class="pf-v5-l-flex__item">Flex item</div>
   </div>
 </div>
-<br />
-<h3>Nested flex and items.</h3>
+
+```
+
+### Nested flex and items example
+
+```html
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -86,22 +86,35 @@ The flex layout is based on the CSS Flex properties where the layout determines
 
 ```
 
+### Basic flex layout overview
+
 The CSS approach, by keeping specificity low on base class properties and resetting css variable values at higher specificities, allows any spacer property to be overwritten with a single selector (specificity of 10 or greater).
 
-### Usage
+### Basic flex layout usage
 
 | Class | Applied to | Outcome |
 | -- | -- | -- |
 | `.pf-v5-l-flex` | `*` | Initiates the flex layout. **Required** |
 | `.pf-v5-l-flex__item` | `.pf-v5-l-flex > *` | Initiates a flex item. **Required** |
 
-### Spacing
+## Spacing system
+
+### Spacing system on parent example
+
+```html
+<div class="pf-v5-l-flex pf-m-space-items-2xl">
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+</div>
+
+```
+
+### Spacing system on children example
 
 ```html
-<h3>
-  Individually spaced items -
-  <code>.pf-m-spacer-{xs,sm,md,lg,xl,2xl,3xl}</code>.
-</h3>
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex__item pf-m-spacer-none">Item - none</div>
   <div class="pf-v5-l-flex__item pf-m-spacer-xs">Item - xs</div>
@@ -111,25 +124,72 @@ The CSS approach, by keeping specificity low on base class properties and resett
   <div class="pf-v5-l-flex__item pf-m-spacer-xl">Item - xl</div>
   <div class="pf-v5-l-flex__item pf-m-spacer-2xl">Item - 2xl</div>
   <div class="pf-v5-l-flex__item pf-m-spacer-3xl">Item - 3xl</div>
+  <div class="pf-v5-l-flex__item pf-m-spacer-4xl">Item - 4xl</div>
 </div>
-<br />
-<h3>
-  Flex with modified spacing -
-  <code>.pf-m-space-items-xl</code>.
-</h3>
-<div class="pf-v5-l-flex pf-m-space-items-xl">
+
+```
+
+### Spacing system on parent and children example
+
+```html
+<div class="pf-v5-l-flex pf-m-space-items-2xl">
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item pf-m-spacer-md">Flex item - md</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+</div>
+
+```
+
+### Spacing system usage
+
+| Class | Applied to | Outcome |
+| -- | -- | -- |
+| `.pf-m-space-items-{none, xs, sm, md, lg, xl, 2xl, 3xl, 4xl}{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies the spacer between direct children along the main axis of a flex layout. |
+| `.pf-m-spacer-{none, xs, sm, md, lg, xl, 2xl, 3xl, 4xl}{-on-[breakpoint]}` | `.pf-v5-l-flex > *` |  Modifies the spacer for any individual direct child along the main axis of a flex layout. |
+
+## Gap spacing
+
+### Row gap example
+
+```html
+<div class="pf-v5-l-flex pf-m-row-gap-2xl">
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
 </div>
-<br />
-<h3>
-  Flex with modified spacing -
-  <code>.pf-m-space-items-none</code>.
-</h3>
-<div class="pf-v5-l-flex pf-m-space-items-none">
+
+```
+
+### Column gap example
+
+```html
+<div class="pf-v5-l-flex pf-m-column-gap-2xl">
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
@@ -139,24 +199,43 @@ The CSS approach, by keeping specificity low on base class properties and resett
 
 ```
 
-**Applying `.pf-m-spacer-{size}` to direct descendants of `.pf-v5-l-flex` will override css variable value.**
+### Gap example
 
-**Applying `.pf-m-space-items-{size}` to `.pf-v5-l-flex` will override css variable values for direct descendants, excluding last child. This spacing can be overridden for direct descendant with `.pf-m-spacer-{size}`.**
+```html
+<div class="pf-v5-l-flex pf-m-gap-2xl">
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+  <div class="pf-v5-l-flex__item">Flex item</div>
+</div>
 
-### Usage
+```
+
+### Gap spacing usage
 
 | Class | Applied to | Outcome |
 | -- | -- | -- |
-| `.pf-m-spacer-{none, xs, sm, md, lg, xl, 2xl}{-on-[breakpoint]}` | `.pf-v5-l-flex > .pf-v5-l-flex`, `.pf-v5-l-flex__item` |  Modifies a nested flex layout or a flex item spacing. |
-| `.pf-m-space-items-{none, xs, sm, md, lg, xl, 2xl}{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies the flex layout direct descendant spacing. |
+| `.pf-m-gap{-[none, xs, sm, md, lg, xl, 2xl, 3xl, 4xl]}{-on-[breakpoint]}` | `.pf-v5-l-flex` | Modifies the space between columns and rows. |
+| `.pf-m-row-gap{-[none, xs, sm, md, lg, xl, 2xl, 3xl, 4xl]}{-on-[breakpoint]}` | `.pf-v5-l-flex` | Modifies the space between rows. |
+| `.pf-m-column-gap{-[none, xs, sm, md, lg, xl, 2xl, 3xl, 4xl]}{-on-[breakpoint]}` | `.pf-v5-l-flex` | Modifies the space between columns. |
+
+## Layout modifiers
 
-### Layout modifiers
+### Default layout example
 
 ```html
-<h3>
-  Default layout
-  <code>.pf-v5-l-flex</code>.
-</h3>
 <div class="pf-v5-l-flex ws-example-flex-border">
   <div class="pf-v5-l-flex__item">Flex item</div>
 
@@ -164,11 +243,12 @@ The CSS approach, by keeping specificity low on base class properties and resett
 
   <div class="pf-v5-l-flex__item">Flex item</div>
 </div>
-<br />
-<h3>
-  Inline flex
-  <code>.pf-m-inline-flex</code>.
-</h3>
+
+```
+
+### Inline flex layout example
+
+```html
 <div class="pf-v5-l-flex pf-m-inline-flex ws-example-flex-border">
   <div class="pf-v5-l-flex__item">Flex item</div>
 
@@ -176,12 +256,14 @@ The CSS approach, by keeping specificity low on base class properties and resett
 
   <div class="pf-v5-l-flex__item">Flex item</div>
 </div>
-<br />
-<h3>
-  Adjusting width with
-  <code>.pf-m-grow</code>. In this example, the first group is set to
-  <code>.pf-m-grow</code> and will occupy the remaining available space.
-</h3>
+
+```
+
+### Basic flex grow example
+
+Adjusting width with `.pf-m-grow`, which sets `flex-grow: 1`. In this example, the first group is set to `.pf-m-grow`, will occupy the remaining available space.
+
+```html
 <div class="pf-v5-l-flex">
   <div
     class="pf-v5-l-flex pf-m-grow ws-example-flex-border"
@@ -202,12 +284,14 @@ The CSS approach, by keeping specificity low on base class properties and resett
     <div class="pf-v5-l-flex__item">Flex item</div>
   </div>
 </div>
-<br />
-<h3>
-  Adjusting width with
-  <code>.pf-m-flex-1</code>. In this example, all groups are set to
-  <code>.pf-m-flex-1</code>. They will share available space equally.
-</h3>
+
+```
+
+### Flex grow 1 example
+
+Adjusting width with `.pf-m-flex-1`. In this example, all groups are set to `.pf-m-flex-1`. They will share available space equally.
+
+```html
 <div class="pf-v5-l-flex">
   <div
     class="pf-v5-l-flex pf-m-flex-1 ws-example-flex-border"
@@ -234,11 +318,12 @@ The CSS approach, by keeping specificity low on base class properties and resett
     <div class="pf-v5-l-flex__item">Flex item</div>
   </div>
 </div>
-<br />
-<h3>
-  Specifying column widths with
-  <code>.pf-m-flex-{1,2,3}</code>.
-</h3>
+
+```
+
+### Flex grow 1-4 example
+
+```html
 <div class="pf-v5-l-flex">
   <div
     class="pf-v5-l-flex pf-m-flex-1 ws-example-flex-border"
@@ -253,6 +338,8 @@ The CSS approach, by keeping specificity low on base class properties and resett
     <div class="pf-v5-l-flex__item">Flex item</div>
 
     <div class="pf-v5-l-flex__item">Flex item</div>
+
+    <div class="pf-v5-l-flex__item">Flex item</div>
   </div>
   <div
     class="pf-v5-l-flex pf-m-flex-3 ws-example-flex-border"
@@ -261,14 +348,18 @@ The CSS approach, by keeping specificity low on base class properties and resett
     <div class="pf-v5-l-flex__item">Flex item</div>
 
     <div class="pf-v5-l-flex__item">Flex item</div>
-
+  </div>
+  <div
+    class="pf-v5-l-flex pf-m-flex-4 ws-example-flex-border"
+    data-label=".pf-m-flex-4"
+  >
     <div class="pf-v5-l-flex__item">Flex item</div>
   </div>
 </div>
 
 ```
 
-### Usage
+### Layout modifiers usage
 
 | Class | Applied to | Outcome |
 | -- | -- | -- |
@@ -283,24 +374,22 @@ The CSS approach, by keeping specificity low on base class properties and resett
 | `.pf-m-flex-default{-on-[breakpoint]}` | `.pf-v5-l-flex > .pf-v5-l-flex`, `.pf-v5-l-flex__item` | Resets a nested flex layout or flex item flex shorthand property to 0 1 auto. |
 | `.pf-m-flex-none{-on-[breakpoint]}` | `.pf-v5-l-flex > .pf-v5-l-flex`, `.pf-v5-l-flex__item` | Modifies a nested flex layout or flex item flex shorthand property to none. |
 
-### Column layout modifiers
+## Column layout modifiers
+
+### Basic column example
 
 ```html
-<h3>
-  Flex column layout. When
-  <code>.pf-m-column</code> is applied to
-  <code>.pf-v5-l-flex</code>, spacing will be applied to margin-bottom for direct descendants.
-</h3>
 <div class="pf-v5-l-flex pf-m-column">
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
 </div>
-<br />
-<h3>
-  Stacking
-  <code>.pf-v5-l-flex</code> elements.
-</h3>
+
+```
+
+### Nested column example
+
+```html
 <div class="pf-v5-l-flex pf-m-column">
   <div class="pf-v5-l-flex">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -316,11 +405,7 @@ The CSS approach, by keeping specificity low on base class properties and resett
   </div>
 </div>
 <br />
-<h3>
-  Nesting
-  <code>.pf-v5-l-flex</code> elements and setting to
-  <code>.pf-m-column</code>.
-</h3>
+<br />
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex pf-m-column">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -341,13 +426,11 @@ The CSS approach, by keeping specificity low on base class properties and resett
 | -- | -- | -- |
 | `.pf-m-column{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies flex-direction property to column. |
 
-### Responsive layout modifiers
+## Responsive layouts
+
+### Flex direction responsive example
 
 ```html
-<h3>
-  Switching between flex-direction column and row at breakpoints (
-  <code>-on-lg</code>).
-</h3>
 <div class="pf-v5-l-flex pf-m-column pf-m-row-on-lg">
   <div class="pf-v5-l-flex">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -362,15 +445,12 @@ The CSS approach, by keeping specificity low on base class properties and resett
   </div>
 </div>
 <br />
-<h3>
-  Switching between flex-direction column and row at breakpoints (
-  <code>-on-lg</code>). If content is likely to wrap, modifiers will need to be used to control width. The example below wraps because the flex item expands in response to long paragraph text.
-</h3>
+<br />
 <div class="pf-v5-l-flex pf-m-column pf-m-row-on-lg">
   <div class="pf-v5-l-flex">
     <div class="pf-v5-l-flex__item">Flex item</div>
     <div class="pf-v5-l-flex__item">
-      <b>Because this text is long enough to wrap, this item's width will force the adjacent item to wrap.</b> Lorem ipsum dolor sit amet consectetur adipisicing elit. Est animi modi temporibus, alias qui obcaecati ullam dolor nam, nulla magni iste rem praesentium numquam provident amet ut nesciunt harum accusamus.
+      <b>Because this text is long enough to wrap, this item's width will force the adjacent item to wrap. If content is likely to wrap, modifiers will need to be used to control width.</b> Lorem ipsum dolor sit amet consectetur adipisicing elit. Est animi modi temporibus, alias qui obcaecati ullam dolor nam, nulla magni iste rem praesentium numquam provident amet ut nesciunt harum accusamus.
     </div>
   </div>
 
@@ -380,17 +460,16 @@ The CSS approach, by keeping specificity low on base class properties and resett
   </div>
 </div>
 <br />
-<h3>
-  Switching between flex-direction column and row at breakpoints (
-  <code>-on-lg</code>). To control the width of the flex item, set
-  <code>.pf-m-flex-1</code> on the flex group containing the long paragraph text.
-</h3>
+<br />
 <div class="pf-v5-l-flex pf-m-column pf-m-row-on-lg">
   <div class="pf-v5-l-flex pf-m-flex-1">
     <div class="pf-v5-l-flex__item">Flex item</div>
-    <div
-      class="pf-v5-l-flex__item pf-m-flex-1"
-    >Lorem ipsum dolor sit amet consectetur adipisicing elit. Est animi modi temporibus, alias qui obcaecati ullam dolor nam, nulla magni iste rem praesentium numquam provident amet ut nesciunt harum accusamus.</div>
+    <div class="pf-v5-l-flex__item pf-m-flex-1">
+      <b>
+        To control the width of the flex item, set
+        <code>.pf-m-flex-1</code>.
+      </b> Lorem ipsum dolor sit amet consectetur adipisicing elit. Est animi modi temporibus, alias qui obcaecati ullam dolor nam, nulla magni iste rem praesentium numquam provident amet ut nesciunt harum accusamus.
+    </div>
   </div>
 
   <div class="pf-v5-l-flex pf-m-column">
@@ -401,20 +480,20 @@ The CSS approach, by keeping specificity low on base class properties and resett
 
 ```
 
-### Usage
+### Responsive layouts usage
 
 | Class | Applied to | Outcome |
 | -- | -- | -- |
 | `.pf-m-column{-on-[breakpoint]}` | `.pf-v5-l-flex`  |  Modifies flex-direction property to column. |
 | `.pf-m-row{-on-[breakpoint]}` | `.pf-v5-l-flex`  |  Modifies flex-direction property to row. |
 
-### Alignment
+## Alignment
+
+### Basic align right example
+
+Aligning right with `.pf-m-align-right`. This solution will always align element right by setting margin-left: auto, including when wrapped.
 
 ```html
-<h3>
-  Aligning right with
-  <code>.pf-m-align-right</code>. This solution will always align element right by setting margin-left: auto, including when wrapped.
-</h3>
 <div class="pf-v5-l-flex ws-example-flex-border">
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
@@ -422,14 +501,22 @@ The CSS approach, by keeping specificity low on base class properties and resett
   <div class="pf-v5-l-flex__item pf-m-align-right">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
 </div>
-<br />
-<h3>Align right on single item.</h3>
+
+```
+
+### Align right on single item example
+
+```html
 <div class="pf-v5-l-flex ws-example-flex-border">
   <div class="pf-v5-l-flex__item pf-m-align-right">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
 </div>
-<br />
-<h3>Align right on multiple groups.</h3>
+
+```
+
+### Align right on multiple groups example
+
+```html
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -444,11 +531,12 @@ The CSS approach, by keeping specificity low on base class properties and resett
     <div class="pf-v5-l-flex__item">Flex item</div>
   </div>
 </div>
-<br />
-<h3>
-  Using
-  <code>.pf-m-flex-1</code> to align adjacent content.
-</h3>
+
+```
+
+#### Alignment using .pf-m-flex-1 example
+
+```html
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex pf-m-flex-1">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -461,11 +549,12 @@ The CSS approach, by keeping specificity low on base class properties and resett
     <div class="pf-v5-l-flex__item">Flex item</div>
   </div>
 </div>
-<br />
-<h3>
-  Aligning nested columns with
-  <code>.pf-m-align-self-flex-end</code>.
-</h3>
+
+```
+
+### Alignment using .pf-m-align-self-flex-end example
+
+```html
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex pf-m-column">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -477,11 +566,12 @@ The CSS approach, by keeping specificity low on base class properties and resett
     <div class="pf-v5-l-flex__item">Flex item</div>
   </div>
 </div>
-<br />
-<h3>
-  Aligning nested columns with
-  <code>.pf-m-align-self-center</code>.
-</h3>
+
+```
+
+### Aligning nested columns with .pf-m-align-self-center example
+
+```html
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex pf-m-column">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -493,11 +583,12 @@ The CSS approach, by keeping specificity low on base class properties and resett
     <div class="pf-v5-l-flex__item">Flex item</div>
   </div>
 </div>
-<br />
-<h3>
-  Aligning nested columns with
-  <code>.pf-m-align-self-baseline</code>.
-</h3>
+
+```
+
+### Aligning nested columns with .pf-m-align-self-baseline example
+
+```html
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex pf-m-column">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -509,11 +600,12 @@ The CSS approach, by keeping specificity low on base class properties and resett
     <div class="pf-v5-l-flex__item">Flex item</div>
   </div>
 </div>
-<br />
-<h3>
-  Aligning nested columns with
-  <code>.pf-m-align-self-stretch</code>.
-</h3>
+
+```
+
+### Aligning nested columns with .pf-m-align-self-stretch example
+
+```html
 <div class="pf-v5-l-flex">
   <div class="pf-v5-l-flex pf-m-column">
     <div class="pf-v5-l-flex__item">Flex item</div>
@@ -528,7 +620,7 @@ The CSS approach, by keeping specificity low on base class properties and resett
 
 ```
 
-### Usage
+### Alignment usage
 
 | Class | Applied to | Outcome |
 | -- | -- | -- |
@@ -540,24 +632,23 @@ The CSS approach, by keeping specificity low on base class properties and resett
 | `.pf-m-align-self-flex-baseline{-on-[breakpoint]}` | `.pf-v5-l-flex > .pf-v5-l-flex`, `.pf-v5-l-flex__item` | Modifies align-self property to baseline. |
 | `.pf-m-align-self-flex-stretch{-on-[breakpoint]}` | `.pf-v5-l-flex > .pf-v5-l-flex`, `.pf-v5-l-flex__item` | Modifies align-self property to stretch. |
 
-### Justification
+## Justification
+
+### Justify content flex end example
 
 ```html
-<h3>
-  Justify content with
-  <code>.pf-m-justify-content-flex-end</code>.
-</h3>
 <div class="pf-v5-l-flex pf-m-justify-content-flex-end ws-example-flex-border">
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
 </div>
-<br />
-<h3>
-  Justify content with
-  <code>.pf-m-justify-content-space-between</code>.
-</h3>
+
+```
+
+### Justify content space between example
+
+```html
 <div
   class="pf-v5-l-flex pf-m-justify-content-space-between ws-example-flex-border"
 >
@@ -565,11 +656,12 @@ The CSS approach, by keeping specificity low on base class properties and resett
   <div class="pf-v5-l-flex__item">Flex item</div>
   <div class="pf-v5-l-flex__item">Flex item</div>
 </div>
-<br />
-<h3>
-  Justify content with
-  <code>.pf-m-justify-content-flex-start</code>.
-</h3>
+
+```
+
+### Justify content flex start example
+
+```html
 <div
   class="pf-v5-l-flex pf-m-justify-content-flex-start ws-example-flex-border"
 >
@@ -580,48 +672,17 @@ The CSS approach, by keeping specificity low on base class properties and resett
 
 ```
 
-### Ordering
-
-Ordering - Ordering can be applied to nested <code>.pf-v5-l-flex</code> and <code>.pf-v5-l-flex\_\_item</code>s. Spacing may need to be managed based on how items are ordered. Because order could apply to an innumerable number of elements, order is set inline as `--pf-v5-l-flex--item--Order{-on-[breakpoint]}: {order}`.
-
-### First last ordering
-
-```html
-<div class="pf-v5-l-flex">
-  <div
-    class="pf-v5-l-flex__item pf-m-spacer-none"
-    style="--pf-v5-l-flex--item--Order: 2;"
-  >Item A</div>
-  <div class="pf-v5-l-flex__item">Item B</div>
-  <div
-    class="pf-v5-l-flex__item pf-m-spacer-md"
-    style="--pf-v5-l-flex--item--Order: -1;"
-  >Item C</div>
-</div>
-
-```
-
-### Responsive first last ordering
+| Class | Applied to | Outcome |
+| -- | -- | -- |
+| `.pf-m-justify-content-flex-end{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies justification property and descendant spacing. |
+| `.pf-m-justify-content-flex-space-between{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies justification property and descendant spacing. |
+| `.pf-m-justify-content-flex-start{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies justification property and descendant spacing, used primarily to reset spacing to default. |
 
-```html
-<div class="pf-v5-l-flex">
-  <div
-    class="pf-v5-l-flex__item pf-m-spacer-none-on-lg"
-    style="--pf-v5-l-flex--item--Order-on-lg: 2;"
-  >Item A</div>
-  <div
-    class="pf-v5-l-flex__item pf-m-spacer-none-on-md pf-m-spacer-md-on-lg"
-    style="--pf-v5-l-flex--item--Order: -1; --pf-v5-l-flex--item--Order-on-md: 1;"
-  >Item B</div>
-  <div
-    class="pf-v5-l-flex__item pf-m-spacer-md"
-    style="--pf-v5-l-flex--item--Order-on-md: -1;"
-  >Item C</div>
-</div>
+## Ordering
 
-```
+Ordering - Ordering can be applied to nested `.pf-v5-l-flex` and `.pf-v5-l-flex__item`s. Spacing may need to be managed based on how items are ordered. Because order could apply to an innumerable number of elements, order is set inline as `--pf-v5-l-flex--item--Order{-on-[breakpoint]}: {order}`.
 
-### Ordering example
+### Basic ordering example
 
 ```html
 <div class="pf-v5-l-flex">
@@ -659,7 +720,44 @@ Ordering - Ordering can be applied to nested <code>.pf-v5-l-flex</code> and <cod
 
 ```
 
-### Responsive ordering
+### First and last ordering example
+
+```html
+<div class="pf-v5-l-flex">
+  <div
+    class="pf-v5-l-flex__item pf-m-spacer-none"
+    style="--pf-v5-l-flex--item--Order: 2;"
+  >Item A</div>
+  <div class="pf-v5-l-flex__item">Item B</div>
+  <div
+    class="pf-v5-l-flex__item pf-m-spacer-md"
+    style="--pf-v5-l-flex--item--Order: -1;"
+  >Item C</div>
+</div>
+
+```
+
+### Responsive first last ordering example
+
+```html
+<div class="pf-v5-l-flex">
+  <div
+    class="pf-v5-l-flex__item pf-m-spacer-none-on-lg"
+    style="--pf-v5-l-flex--item--Order-on-lg: 2;"
+  >Item A</div>
+  <div
+    class="pf-v5-l-flex__item pf-m-spacer-none-on-md pf-m-spacer-md-on-lg"
+    style="--pf-v5-l-flex--item--Order: -1; --pf-v5-l-flex--item--Order-on-md: 1;"
+  >Item B</div>
+  <div
+    class="pf-v5-l-flex__item pf-m-spacer-md"
+    style="--pf-v5-l-flex--item--Order-on-md: -1;"
+  >Item C</div>
+</div>
+
+```
+
+### Responsive ordering example
 
 ```html
 <div class="pf-v5-l-flex">
@@ -703,7 +801,13 @@ Ordering - Ordering can be applied to nested <code>.pf-v5-l-flex</code> and <cod
 
 ```
 
-### List type
+### Ordering usage
+
+| Class | Applied to | Outcome |
+| -- | -- | -- |
+| `--pf-v5-l-flex--item--Order{-on-[breakpoint]}: {order}` | `.pf-v5-l-flex > .pf-v5-l-flex`, `.pf-v5-l-flex__item` | Modifies the flex layout element order property. |
+
+## Flex layout as list
 
 ```html
 <ul class="pf-v5-l-flex">
@@ -715,14 +819,6 @@ Ordering - Ordering can be applied to nested <code>.pf-v5-l-flex</code> and <cod
 
 ```
 
-### Usage
-
-| Class | Applied to | Outcome |
-| -- | -- | -- |
-| `.pf-m-justify-content-flex-end{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies justification property and descendant spacing. |
-| `.pf-m-justify-content-flex-space-between{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies justification property and descendant spacing. |
-| `.pf-m-justify-content-flex-start{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies justification property and descendant spacing, used primarily to reset spacing to default. |
-
 ## Documentation
 
 ### Usage
@@ -768,9 +864,17 @@ Ordering - Ordering can be applied to nested <code>.pf-v5-l-flex</code> and <cod
 | `.pf-m-align-right{-on-[breakpoint]}` | `.pf-v5-l-flex > .pf-v5-l-flex`, `.pf-v5-l-flex__item` | Modifies the flex layout element margin-left property to auto. |
 | `--pf-v5-l-flex--item--Order{-on-[breakpoint]}: {order}` | `.pf-v5-l-flex > .pf-v5-l-flex`, `.pf-v5-l-flex__item` | Modifies the flex layout element order property. |
 
-### Spacer system
+### Spacer system usage
+
+| Class | Applied to | Outcome |
+| -- | -- | -- |
+| `.pf-m-space-items-{none, xs, sm, md, lg, xl, 2xl, 3xl, 4xl}{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies the flex layout to add space between items on the main axis. |
+| `.pf-m-spacer-{none, xs, sm, md, lg, xl, 2xl, 3xl, 4xl}{-on-[breakpoint]}` | `.pf-v5-l-flex`, `.pf-v5-l-flex > .pf-v5-l-flex__item` |  Modifies the spacer for any direct child along the main axis of a flex layout. |
+
+### Gap spacing usage
 
 | Class | Applied to | Outcome |
 | -- | -- | -- |
-| `.pf-m-spacer-{none, xs, sm, md, lg, xl, 2xl}{-on-[breakpoint]}` | `.pf-v5-l-flex`, `.pf-v5-l-flex > .pf-v5-l-flex__item` |  Modifies a nested flex layout or a flex item spacing. |
-| `.pf-m-item-space-items-{none, xs, sm, md, lg, xl, 2xl}{-on-[breakpoint]}` | `.pf-v5-l-flex` |  Modifies the flex layout direct descendant spacing. |
+| `.pf-m-gap{-[none, xs, sm, md, lg, xl, 2xl, 3xl, 4xl]}{-on-[breakpoint]}` | `.pf-v5-l-flex` | Modifies the space between columns and rows. |
+| `.pf-m-row-gap{-[none, xs, sm, md, lg, xl, 2xl, 3xl, 4xl]}{-on-[breakpoint]}` | `.pf-v5-l-flex` | Modifies the space between rows. |
+| `.pf-m-column-gap{-[none, xs, sm, md, lg, xl, 2xl, 3xl, 4xl]}{-on-[breakpoint]}` | `.pf-v5-l-flex` | Modifies the space between columns. |