docs(layout): improve css utility descriptions and headers

brandyscarney · brandyscarney · commit 0867d49deac9 · 2025-07-28T18:12:04.000-04:00
diff --git a/docs/layout/css-utilities.md b/docs/layout/css-utilities.md
@@ -18,7 +18,7 @@ If your app was not started using an available Ionic Framework starter, the styl
 
 ## Text Modification
 
-### Text Alignment
+### Text Align
 
 ```html
 <ion-grid>
@@ -76,7 +76,7 @@ If your app was not started using an available Ionic Framework starter, the styl
 | `.ion-text-wrap`    | `white-space: normal` | Sequences of whitespace are collapsed. Newline characters in the source are handled as other whitespace. Breaks lines as necessary to fill line boxes.              |
 | `.ion-text-nowrap`  | `white-space: nowrap` | Collapses whitespace as for `normal`, but suppresses line breaks (text wrapping) within text.                                                                       |
 
-### Text Transformation
+### Text Transform
 
 ```html
 <ion-grid>
@@ -125,7 +125,7 @@ The table below shows the default behavior, where `{modifier}` is any of the fol
 
 ## Element Placement
 
-### Float Elements
+### Float
 
 The [float](https://developer.mozilla.org/en-US/docs/Web/CSS/float) CSS property specifies that an element should be placed along the left or right side of its container, where text and inline elements will wrap around it. This way, the element is taken from the normal flow of the web page, though still remaining a part of the flow, contrary to absolute positioning.
 
@@ -188,8 +188,12 @@ The table below shows the default behavior, where `{modifier}` is any of the fol
 
 ## Element Display
 
+### Display
+
 The [display](https://developer.mozilla.org/en-US/docs/Web/CSS/display) CSS property sets whether an element is treated as a block or inline box and the layout used for its children, such as flow layout, grid or flex. It can also be used to completely hide an element from the layout.
 
+Ionic provides the following utility classes for `display`:
+
 | Class       | Style Rule      | Description                 |
 | ----------- | --------------- | --------------------------- |
 | `.ion-display-none` | `display: none` | Turns off the display of an element so that it has no effect on layout (the document is rendered as though the element did not exist). |
@@ -236,7 +240,7 @@ The following classes are deprecated and will be removed in the next major relea
 
 ## Content Space
 
-### Element Padding
+### Padding
 
 The padding class sets the padding area of an element. The padding area is the space between the content of the element and its border.
 
@@ -286,7 +290,7 @@ The default amount of `padding` to be applied is `16px` and is set by the `--ion
 | `.ion-padding-horizontal` | `padding: 0 16px`      | Applies padding to the left and right. |
 | `.ion-no-padding`         | `padding: 0`           | Applies no padding to all sides.       |
 
-### Element Margin
+### Margin
 
 The margin area extends the border area with an empty area used to separate the element from its neighbors.
 
@@ -344,8 +348,12 @@ Flexbox properties are divided into two categories: **container properties** tha
 
 ### Align Items
 
+The [align-items](https://developer.mozilla.org/en-US/docs/Web/CSS/align-items) CSS property sets the [align-self](#align-self) value on all direct children as a group. In flexbox, it controls the alignment of items on the cross axis. In grid layout, it controls the alignment of items on the block axis within their grid areas.
+
 <img src={require('@site/static/img/layout/align-items.png').default} />
 
+Ionic provides the following utility classes for `align-items`:
+
 | Class                          | Style Rule                       | Description                                                                 |
 | ------------------------------ | -------------------------------- | --------------------------------------------------------------------------- |
 | `.ion-align-items-start`       | `align-items: flex-start`        | Items are packed toward the start on the cross axis.                        |
@@ -356,8 +364,14 @@ Flexbox properties are divided into two categories: **container properties** tha
 
 ### Align Content
 
+The [align-content](https://developer.mozilla.org/en-US/docs/Web/CSS/align-content) CSS property sets the distribution of space between and around content items along a flexbox's cross axis, or a grid or block-level element's block axis.
+
+This property has no effect on single line flex containers (i.e., ones with `flex-wrap: nowrap`).
+
 <img src={require('@site/static/img/layout/align-content.png').default} />
 
+Ionic provides the following utility classes for `align-content`:
+
 | Class                          | Style Rule                       | Description                                                                 |
 | ------------------------------ | -------------------------------- | --------------------------------------------------------------------------- |
 | `.ion-align-content-start`     | `align-content: flex-start`      | Lines are packed toward the start of the cross axis.                        |
@@ -369,8 +383,12 @@ Flexbox properties are divided into two categories: **container properties** tha
 
 ### Justify Content
 
+The [justify-content](https://developer.mozilla.org/en-US/docs/Web/CSS/justify-content) CSS property defines how the browser distributes space between and around content items along the main axis of a flex container and the inline axis of grid and multicol containers.
+
 <img src={require('@site/static/img/layout/justify-content.png').default} />
 
+Ionic provides the following utility classes for `justify-content`:
+
 | Class                          | Style Rule                       | Description                                                                 |
 | ------------------------------ | -------------------------------- | --------------------------------------------------------------------------- |
 | `.ion-justify-content-start`   | `justify-content: flex-start`    | Items are packed toward the start on the main axis.                         |
@@ -382,8 +400,12 @@ Flexbox properties are divided into two categories: **container properties** tha
 
 ### Flex Direction
 
+The [flex-direction](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-direction) CSS property sets how flex items are placed in the flex container defining the main axis and the direction (normal or reversed).
+
 <img src={require('@site/static/img/layout/flex-direction.png').default} />
 
+Ionic provides the following utility classes for `flex-direction`:
+
 | Class                          | Style Rule                       | Description                                                                 |
 | ------------------------------ | -------------------------------- | --------------------------------------------------------------------------- |
 | `.ion-flex-row`                | `flex-direction: row`            | Items are placed in the same direction as the text direction.               |
@@ -393,8 +415,12 @@ Flexbox properties are divided into two categories: **container properties** tha
 
 ### Flex Wrap
 
+The [flex-wrap](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-wrap) CSS property sets whether flex items are forced onto one line or can wrap onto multiple lines. If wrapping is allowed, it sets the direction that lines are stacked.
+
 <img src={require('@site/static/img/layout/flex-wrap.png').default} />
 
+Ionic provides the following utility classes for `flex-wrap`:
+
 | Class                          | Style Rule                       | Description                                                                 |
 | ------------------------------ | -------------------------------- | --------------------------------------------------------------------------- |
 | `.ion-flex-nowrap`             | `flex-wrap: nowrap`              | Items will all be on one line.                                              |
@@ -435,8 +461,14 @@ Flex item properties control how individual flex items behave within their flex
 
 ### Align Self
 
+The [align-self](https://developer.mozilla.org/en-US/docs/Web/CSS/align-self) CSS property overrides a grid or flex item's align-items value. In grid, it aligns the item inside the grid area. In flexbox, it aligns the item on the cross axis.
+
+The property doesn't apply to block-level boxes, or to table cells. If a flexbox item's cross-axis margin is `auto`, then `align-self` is ignored.
+
 <img src={require('@site/static/img/layout/align-self.png').default} />
 
+Ionic provides the following utility classes for `align-self`:
+
 | Class                      | Style Rule               | Description                                                            |
 | -------------------------- | ------------------------ | ---------------------------------------------------------------------- |
 | `.ion-align-self-start`    | `align-self: flex-start` | Item is packed toward the start on the cross axis.                     |
@@ -448,7 +480,7 @@ Flex item properties control how individual flex items behave within their flex
 
 ### Flex
 
-The `flex` property is a shorthand for `flex-grow`, `flex-shrink` and `flex-basis`. It controls how flex items grow and shrink within their container.
+The [flex](https://developer.mozilla.org/en-US/docs/Web/CSS/flex) CSS property is a shorthand property for `flex-grow`, `flex-shrink` and `flex-basis`. It sets how a flex item will grow or shrink to fit the space available in its flex container.
 
 ```html
 <ion-grid>
@@ -502,6 +534,8 @@ The `flex` property is a shorthand for `flex-grow`, `flex-shrink` and `flex-basi
 </ion-grid>
 ```
 
+Ionic provides the following utility classes for `flex`:
+
 | Class               | Style Rule            | Description                                                                 |
 | ------------------- | --------------------- | --------------------------------------------------------------------------- |
 | `.ion-flex-1`       | `flex: 1`             | Item grows and shrinks equally with other flex items.                      |
@@ -511,6 +545,8 @@ The `flex` property is a shorthand for `flex-grow`, `flex-shrink` and `flex-basi
 
 ### Flex Grow
 
+The [flex-grow](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-grow) CSS property sets the flex grow factor, which specifies how much of the flex container's positive free space, if any, should be assigned to the flex item's main size.
+
 ```html
 <ion-grid>
   <ion-row>
@@ -527,13 +563,17 @@ The `flex` property is a shorthand for `flex-grow`, `flex-shrink` and `flex-basi
 </ion-grid>
 ```
 
+Ionic provides the following utility classes for `flex-grow`:
+
 | Class                | Style Rule           | Description                                                                 |
 | -------------------- | -------------------- | --------------------------------------------------------------------------- |
 | `.ion-flex-grow-0`   | `flex-grow: 0`       | Item does not grow beyond its content size.                                |
 | `.ion-flex-grow-1`   | `flex-grow: 1`       | Item grows to fill available space proportionally.                         |
 
 ### Flex Shrink
 
+The [flex-shrink](https://developer.mozilla.org/en-US/docs/Web/CSS/flex-shrink) CSS property sets the flex shrink factor of a flex item. If the size of all flex items is larger than the flex container, the flex items can shrink to fit according to their `flex-shrink` value. Each flex line's negative free space is distributed between the line's flex items that have a `flex-shrink` value greater than `0`.
+
 ```html
 <ion-grid>
   <ion-row>
@@ -550,13 +590,17 @@ The `flex` property is a shorthand for `flex-grow`, `flex-shrink` and `flex-basi
 </ion-grid>
 ```
 
+Ionic provides the following utility classes for `flex-shrink`:
+
 | Class                  | Style Rule             | Description                                                                 |
 | ---------------------- | ---------------------- | --------------------------------------------------------------------------- |
 | `.ion-flex-shrink-0`   | `flex-shrink: 0`       | Item does not shrink below its content size.                               |
 | `.ion-flex-shrink-1`   | `flex-shrink: 1`       | Item shrinks proportionally when container is too small.                   |
 
 ### Order
 
+The [order](https://developer.mozilla.org/en-US/docs/Web/CSS/order) CSS property sets the order to lay out an item in a flex or grid container. Items in a container are sorted by ascending `order` value and then by their source code order. Items not given an explicit `order` value are assigned the default value of `0`.
+
 ```html
 <ion-grid>
   <ion-row>
@@ -576,6 +620,8 @@ The `flex` property is a shorthand for `flex-grow`, `flex-shrink` and `flex-basi
 </ion-grid>
 ```
 
+Ionic provides the following utility classes for `order`:
+
 | Class               | Style Rule    | Description                                                                 |
 | ------------------- | ------------- | --------------------------------------------------------------------------- |
 | `.ion-order-first`  | `order: -1`   | Item appears first in the flex container.                                  |
@@ -610,7 +656,7 @@ The table below shows the default behavior, where `{property}` is one of the fol
 
 ## Border Display
 
-The border display CSS property determines if the border should be visible or not. The property can be applied to the ion-header and the ion-footer.
+The `.ion-no-border` utility class can be used to remove borders from Ionic components. This class can be applied to the `ion-header` and `ion-footer` components.
 
 ```html
 <ion-header class="ion-no-border">
diff --git a/versioned_docs/version-v5/api/item.md b/versioned_docs/version-v5/api/item.md
@@ -52,7 +52,7 @@ The below chart details the item slots and where it will place the element insid
 | `end`   | Placed to the right of all other content in LTR, and to the `left` in RTL. |
 | none    | Placed inside of the input wrapper.                                        |
 
-### Text Alignment
+### Text Align
 
 Items left align text and add an ellipsis when the text is wider than the item. See the [CSS Utilities Documentation](../layout/css-utilities.md) for classes that can be added to `<ion-item>` to transform the text.
 
diff --git a/versioned_docs/version-v5/layout/css-utilities.md b/versioned_docs/version-v5/layout/css-utilities.md
@@ -12,7 +12,7 @@ If your app was not started using an available Ionic Framework starter, the styl
 
 ## Text Modification
 
-### Text Alignment
+### Text Align
 
 ```html
 <ion-grid>
@@ -70,7 +70,7 @@ If your app was not started using an available Ionic Framework starter, the styl
 | `.ion-text-wrap`    | `white-space: normal` | Sequences of whitespace are collapsed. Newline characters in the source are handled as other whitespace. Breaks lines as necessary to fill line boxes.              |
 | `.ion-text-nowrap`  | `white-space: nowrap` | Collapses whitespace as for `normal`, but suppresses line breaks (text wrapping) within text.                                                                       |
 
-### Text Transformation
+### Text Transform
 
 ```html
 <ion-grid>
@@ -203,7 +203,7 @@ There are also additional classes to modify the visibility based on the screen s
 
 ## Content Space
 
-### Element Padding
+### Padding
 
 The padding class sets the padding area of an element. The padding area is the space between the content of the element and its border.
 
@@ -253,7 +253,7 @@ The default amount of `padding` to be applied is `16px` and is set by the `--ion
 | `.ion-padding-horizontal` | `padding: 0 16px`      | Applies padding to the left and right. |
 | `.ion-no-padding`         | `padding: 0`           | Applies no padding to all sides.       |
 
-### Element Margin
+### Margin
 
 The margin area extends the border area with an empty area used to separate the element from its neighbors.
 
@@ -493,7 +493,7 @@ The default amount of `margin` to be applied is `16px` and is set by the `--ion-
 
 ## Border Display
 
-The border display CSS property determines if the border should be visible or not. The property can be applied to the ion-header and the ion-footer.
+The `.ion-no-border` utility class can be used to remove borders from Ionic components. This class can be applied to the `ion-header` and `ion-footer` components.
 
 ```html
 <ion-header class="ion-no-border">
diff --git a/versioned_docs/version-v6/layout/css-utilities.md b/versioned_docs/version-v6/layout/css-utilities.md
@@ -18,7 +18,7 @@ If your app was not started using an available Ionic Framework starter, the styl
 
 ## Text Modification
 
-### Text Alignment
+### Text Align
 
 ```html
 <ion-grid>
@@ -76,7 +76,7 @@ If your app was not started using an available Ionic Framework starter, the styl
 | `.ion-text-wrap`    | `white-space: normal` | Sequences of whitespace are collapsed. Newline characters in the source are handled as other whitespace. Breaks lines as necessary to fill line boxes.              |
 | `.ion-text-nowrap`  | `white-space: nowrap` | Collapses whitespace as for `normal`, but suppresses line breaks (text wrapping) within text.                                                                       |
 
-### Text Transformation
+### Text Transform
 
 ```html
 <ion-grid>
@@ -209,7 +209,7 @@ There are also additional classes to modify the visibility based on the screen s
 
 ## Content Space
 
-### Element Padding
+### Padding
 
 The padding class sets the padding area of an element. The padding area is the space between the content of the element and its border.
 
@@ -259,7 +259,7 @@ The default amount of `padding` to be applied is `16px` and is set by the `--ion
 | `.ion-padding-horizontal` | `padding: 0 16px`      | Applies padding to the left and right. |
 | `.ion-no-padding`         | `padding: 0`           | Applies no padding to all sides.       |
 
-### Element Margin
+### Margin
 
 The margin area extends the border area with an empty area used to separate the element from its neighbors.
 
@@ -499,7 +499,7 @@ The default amount of `margin` to be applied is `16px` and is set by the `--ion-
 
 ## Border Display
 
-The border display CSS property determines if the border should be visible or not. The property can be applied to the ion-header and the ion-footer.
+The `.ion-no-border` utility class can be used to remove borders from Ionic components. This class can be applied to the `ion-header` and `ion-footer` components.
 
 ```html
 <ion-header class="ion-no-border">
diff --git a/versioned_docs/version-v7/layout/css-utilities.md b/versioned_docs/version-v7/layout/css-utilities.md
@@ -20,7 +20,7 @@ If your app was not started using an available Ionic Framework starter, the styl
 
 ## Text Modification
 
-### Text Alignment
+### Text Align
 
 ```html
 <ion-grid>
@@ -78,7 +78,7 @@ If your app was not started using an available Ionic Framework starter, the styl
 | `.ion-text-wrap`    | `white-space: normal` | Sequences of whitespace are collapsed. Newline characters in the source are handled as other whitespace. Breaks lines as necessary to fill line boxes.              |
 | `.ion-text-nowrap`  | `white-space: nowrap` | Collapses whitespace as for `normal`, but suppresses line breaks (text wrapping) within text.                                                                       |
 
-### Text Transformation
+### Text Transform
 
 ```html
 <ion-grid>
@@ -228,7 +228,7 @@ There are also additional classes to modify the visibility based on the screen s
 
 ## Content Space
 
-### Element Padding
+### Padding
 
 The padding class sets the padding area of an element. The padding area is the space between the content of the element and its border.
 
@@ -278,7 +278,7 @@ The default amount of `padding` to be applied is `16px` and is set by the `--ion
 | `.ion-padding-horizontal` | `padding: 0 16px`      | Applies padding to the left and right. |
 | `.ion-no-padding`         | `padding: 0`           | Applies no padding to all sides.       |
 
-### Element Margin
+### Margin
 
 The margin area extends the border area with an empty area used to separate the element from its neighbors.
 
@@ -518,7 +518,7 @@ The default amount of `margin` to be applied is `16px` and is set by the `--ion-
 
 ## Border Display
 
-The border display CSS property determines if the border should be visible or not. The property can be applied to the ion-header and the ion-footer.
+The `.ion-no-border` utility class can be used to remove borders from Ionic components. This class can be applied to the `ion-header` and `ion-footer` components.
 
 ```html
 <ion-header class="ion-no-border">
