docs: add info on modifying and adding utilities

1 files changed, 42 insertions, 0 deletions

diff --git a/site/content/docs/5.0/utilities/api.md b/site/content/docs/5.0/utilities/api.md
index 7dd0d6ede5..aee021b4fb 100644
--- a/site/content/docs/5.0/utilities/api.md
+++ b/site/content/docs/5.0/utilities/api.md
@@ -212,3 +212,45 @@ $utilities: (
   "float": null,
 );
 ```
+
+## Adding to existing utilities
+
+Add new utilities with `map-merge`.Start by importing the utilities stylesheet, then use `map-merge` to add new properties and values.s
+
+```scss
+@import "bootstrap/scss/utilities";
+
+$utilities: map-merge(
+  $utilities,
+  (
+    "font-size": (
+      responsive: true,
+      property: font-weight,
+      values: $display-font-sizes,
+    )
+  )
+);
+```
+
+## Modifying existing utilities
+
+Modify existing utilities with `map-get` and `map-merge`. Once again, be sure to import the utilities stylesheet before your custom utilities.
+
+```scss
+@import "bootstrap/scss/utilities";
+
+$utilities: map-merge(
+  $utilities,
+  (
+    "width": map-merge(
+      map-get($utilities, "width"),
+      (
+        values: map-merge(
+          map-get(map-get($utilities, "width"), "values"),
+          (10: 10%),
+        ),
+      ),
+    ),
+  )
+);
+```