Add .gap utilities (#32074)

* Add gap utilities

* Update .bundlewatch.config.json

* Revamp headings on this page for better organization

Co-authored-by: XhmikosR <xhmikosr@gmail.com>

3 files changed, 29 insertions, 7 deletions

diff --git a/.bundlewatch.config.json b/.bundlewatch.config.json
index 3833ae9a6c..4bfffbab44 100644
--- a/.bundlewatch.config.json
+++ b/.bundlewatch.config.json
@@ -22,7 +22,7 @@
     },
     {
       "path": "./dist/css/bootstrap-utilities.min.css",
-      "maxSize": "6 kB"
+      "maxSize": "6.25 kB"
     },
     {
       "path": "./dist/css/bootstrap.css",
@@ -30,7 +30,7 @@
     },
     {
       "path": "./dist/css/bootstrap.min.css",
-      "maxSize": "21.75 kB"
+      "maxSize": "22 kB"
     },
     {
       "path": "./dist/js/bootstrap.bundle.js",
diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index cf6d4c8c52..03c71d1c24 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -196,6 +196,12 @@ $utilities: map-merge(
       class: flex,
       values: wrap nowrap wrap-reverse
     ),
+    "gap": (
+      responsive: true,
+      property: gap,
+      class: gap,
+      values: $spacers
+    ),
     "justify-content": (
       responsive: true,
       property: justify-content,
diff --git a/site/content/docs/5.0/utilities/spacing.md b/site/content/docs/5.0/utilities/spacing.md
index b3e96d8032..baf743c84f 100644
--- a/site/content/docs/5.0/utilities/spacing.md
+++ b/site/content/docs/5.0/utilities/spacing.md
@@ -1,16 +1,18 @@
 ---
 layout: docs
 title: Spacing
-description: Bootstrap includes a wide range of shorthand responsive margin and padding utility classes to modify an element's appearance.
+description: Bootstrap includes a wide range of shorthand responsive margin, padding, and gap utility classes to modify an element's appearance.
 group: utilities
 toc: true
 ---
 
-## How it works
+## Margin and padding
 
 Assign responsive-friendly `margin` or `padding` values to an element or a subset of its sides with shorthand classes. Includes support for individual properties, all properties, and vertical and horizontal properties. Classes are built from a default Sass map ranging from `.25rem` to `3rem`.
 
-## Notation
+Using the CSS Grid layout module? Consider using [the gap utility](#gap).
+
+### Notation
 
 Spacing utilities that apply to all breakpoints, from `xs` to `xxl`, have no breakpoint abbreviation in them. This is because those classes are applied from `min-width: 0` and up, and thus are not bound by a media query. The remaining breakpoints, however, do include a breakpoint abbreviation.
 
@@ -43,7 +45,7 @@ Where *size* is one of:
 
 (You can add more sizes by adding entries to the `$spacers` Sass map variable.)
 
-## Examples
+### Examples
 
 Here are some representative examples of these classes:
 
@@ -82,7 +84,7 @@ Additionally, Bootstrap also includes an `.mx-auto` class for horizontally cente
 </div>
 ```
 
-### Negative margin
+## Negative margin
 
 In CSS, `margin` properties can utilize negative values (`padding` cannot). These negative margins are **disabled by default**, but can be enabled in Sass by setting `$enable-negative-margins: true`.
 
@@ -93,3 +95,17 @@ The syntax is nearly the same as the default, positive margin utilities, but wit
   margin-top: -0.25rem !important;
 }
 ```
+
+## Gap
+
+When using `display: grid`, you can make use of `gap` utilities on the parent grid container. This can save on having to add margin utilities to individual grid items (children of a `display: grid` container). Gap utilities are responsive by default, and are generated via our utilities API, based on the `$spacers` Sass map.
+
+{{< example html >}}
+<div class="d-grid gap-3">
+  <div class="p-2 bg-light border">Grid item 1</div>
+  <div class="p-2 bg-light border">Grid item 2</div>
+  <div class="p-2 bg-light border">Grid item 3</div>
+</div>
+{{< /example >}}
+
+Support includes responsive options for all of Bootstrap's grid breakpoints, as well as six sizes from the `$spacers` map (`0`–`5`). There is no `.gap-auto` utility class as it's effectively the same as `.gap-0`.