Update copy on new utility API docsutilities-functions-mixin

3 files changed, 55 insertions, 37 deletions

diff --git a/scss/mixins/_utilities.scss b/scss/mixins/_utilities.scss
index 0e9d7741b4..9c056f4828 100644
--- a/scss/mixins/_utilities.scss
+++ b/scss/mixins/_utilities.scss
@@ -96,7 +96,10 @@
   }
 }
 
+
+//
 // Helper functions and mixins for manipulating the utilities map
+//
 
 // Gets the map of options for a given utility
 @function utilities-get-options($utility-name) {
@@ -151,7 +154,6 @@
   );
 }
 
-
 // Set options for a given utility, merged with the existing ones by default.
 // To completely replace the existing options, set the 3rd `$merge` parameter to false
 @mixin utilities-set-options($utility-name, $options, $merge: true) {
@@ -180,10 +182,9 @@
   @include utilities-set-options($utility-name, ($option-name: $value));
 }
 
-// Add new values to a given utility.
-// If you want to completely reconfigure the values
-// use `utilities-set-option` to provide a new map
-// for the `values` option
+// Add new values to a given utility
+//
+// If you want to completely reconfigure the values use `utilities-set-option` to provide a new map for the `values` option
 @mixin utilities-add-values($utility-name, $values) {
   $existing-values: utilities-get-values($utility-name);
 
diff --git a/site/assets/scss/_variables.scss b/site/assets/scss/_variables.scss
index b460392d0f..c3036a21af 100644
--- a/site/assets/scss/_variables.scss
+++ b/site/assets/scss/_variables.scss
@@ -8,7 +8,7 @@ $bd-accent:       #ffe484;
 $dropdown-active-icon: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'><path fill='#292b2c' d='M2.3 6.73L.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/></svg>");
 
 $bd-gutter-x: 3rem;
-$bd-callout-variants: info, warning, danger !default;
+$bd-callout-variants: info, warning, danger, success !default;
 
 :root {
   --bd-purple: #{$bd-purple};
diff --git a/site/content/docs/5.2/utilities/api.md b/site/content/docs/5.2/utilities/api.md
index d1e074b89b..1a94c21618 100644
--- a/site/content/docs/5.2/utilities/api.md
+++ b/site/content/docs/5.2/utilities/api.md
@@ -366,27 +366,33 @@ All utilities generated by the API include `!important` to ensure they override
 
 ## Using the API
 
-Now that you're familiar with how the utilities API works, you can modify the default utilities and add your own. This can be done in two ways:
+{{< callout success >}}
+**New in v5.3.x!** We've added new mixins and functions to better help you use our utilities API. These replace our previous guidance of using Sass's built-in `map-merge()` function and add new functionality for [composing components with utilities](#get-values-and-options).
+{{< /callout >}}
 
-1. If you only need to override our default utilities or add new ones, we'll merge your `$utilities` variable with ours.
-2. If you require more fine-grained control, we provide mixins to let you update our default utilities configuration.
+Now that you're familiar with how the utilities API works, you can use it to modify our default utilities and even add your own custom utilities. This can be done in three ways:
 
-You may also want to refer to parts of the utilities configuration in your Sass code, the value of a specific utility especially. We provide getter functions to access those.
+1. [Creating your own `$utilities` map](#add-or-override-utilities) that gets automatically merged with our default `$utilities` map.
+2. [Modify our defaults using mixins](#modify-defaults) to add or remove utilities, update specific options, or modify utility values.
 
-### Adding or overriding utilities
+You can also use functions to [get specific utility values](#get-values-and-options) for your own use in your Sass.
+
+### Add or override utilities
+
+Add new keys to create your own utilities and override existing utilities by using the same key.
 
 If your code declares a `$utilities` map before importing `bootstrap/scss/utilities`, it'll be merged with our default map. Add new keys to create your own utilities and override existing utilities by using the same key.
 
 ```scss
 $utilities: (
-  // Adds a new cursor utility
+  // Add a new cursor utility
   "cursor": (
     property: cursor,
     class: cursor,
     responsive: true,
     values: auto pointer grab,
   ),
-  // Redefines the overflow utility
+  // Redefine the existing overflow utility
   "overflow": (
     responsive: true,
     property: overflow,
@@ -398,17 +404,17 @@ $utilities: (
 @import 'bootstrap/scss/utilities/api';
 ```
 
-### Modifying our defaults
+### Modify defaults
 
 After importing `bootstrap/scss/utilities`, you can use mixins to:
 
-- add or remove utilities
-- update utilities options, like `responsive`, `class`, `rtl`...
-- add, remove or update utility values
+- Add or remove utilities
+- Update utilities options, like `responsive`, `class`, `rtl`, etc
+- Add, remove or update utility values
 
-#### Adding and removing utilities
+#### Add and remove utilities
 
-`utilities-add` and `utilities-remove` mixins let you add and remove utilities from the configuration. Adding an existing utility will completely override it.
+The `utilities-add()` and `utilities-remove()` mixins let you add and remove utilities from the configuration. Adding an existing utility will completely override it.
 
 ```scss
 @import "bootstrap/scss/functions";
@@ -431,11 +437,11 @@ After importing `bootstrap/scss/utilities`, you can use mixins to:
 @import "bootstrap/scss/utilities/api";
 ```
 
-#### Updating utility options
+#### Update utility options
 
-`utilities-set-option` and `utilities-set-options` let you configure one or several options of a utility. `utilities-set-options` will merge the new options with the existing ones by default, but you can provide a third `$merge: false` argument to completely override them.
+The `utilities-set-option()` and `utilities-set-options()` mixins let you configure one or several options of a utility. `utilities-set-options()` will merge the new options with the existing ones by default, but you can provide a third `$merge: false` argument to completely override them.
 
-And if the utility does not exist, both mixins will create a new one.
+If the utility does not exist, both mixins will create a new one.
 
 ```scss
 @import "bootstrap/scss/functions";
@@ -444,13 +450,13 @@ And if the utility does not exist, both mixins will create a new one.
 @import "bootstrap/scss/mixins";
 @import "bootstrap/scss/utilities";
 
-// Let's make the overflow utility responsive
+// Modify existing overflow utility to be responsive
 @include utilities-set-option(overflow, responsive, true);
 
-// Or revert the class for the margin-start utilities to their v4 values
+// Change an existing utility's class name
 @include utilities-set-option(margin-start, class, ml);
 
-// Let's make line-height responsive and override its values
+// Make an existing utility responsive and override its values
 @include utilities-set-options(line-height, (
   responsive: true,
   values: (
@@ -464,9 +470,9 @@ And if the utility does not exist, both mixins will create a new one.
 @import 'bootstrap/scss/utilities/api';
 ```
 
-#### Updating utility values
+#### Update utility values
 
-If you want to keep most of the default values for a utility, and just add, remove or update a few, replacing the `values` option can be a bit of a burden to maintain. `utilities-add-values` and `utilities-remove-values` mixins will help you make these targeted updates.
+If you want to keep most of the default values for a utility and just add, remove, or update a few, replacing the `values` option can be overkill. Use the `utilities-add-values()` and `utilities-remove-values()` mixins to help you make more targeted updates.
 
 ```scss
 @import "bootstrap/scss/functions";
@@ -476,21 +482,21 @@ If you want to keep most of the default values for a utility, and just add, remo
 
 @import 'bootstrap/scss/utilities';
 
-// Let's add a few new values to the `flex` utility
+// Adds new values to the flex utility
 @include utilities-add-values(flex, (
   none: none,
   auto: auto
 ));
 
-// And remove the row-reverse and column-reverse from flex-direction
+// Remove specific values from the flex-direction utility
 @include utilities-remove-values(flex-direction, row-reverse, column-reverse);
 
 @import 'bootstrap/scss/utilities/api';
 ```
 
-### Getting utility values and options
+### Get values and options
 
-The `utilities-get-value` function let your grab a specific value of a utility. This can help you run some computations with it, either in Sass or with `calc()`. It also lets you access values that can be modified by other utilities, (like how `bg`, `text` and `border` can be affected by `bg-opacity`, `text-opacity` or `border-opacity` respectively).
+Use the `utilities-get-value()` function to get a specific value of a utility. This allows you to use and manipulate specific values from our utilities, like with Sass functions or `calc()`. It also lets you access values that can be modified by other utilities, like how `.bg-*`, `.text-*` and `.border-*` can be affected by `.bg-opacity-*`, `.text-opacity-*` or `.border-opacity-*` respectively.
 
 ```scss
 @import "bootstrap/scss/functions";
@@ -502,18 +508,29 @@ The `utilities-get-value` function let your grab a specific value of a utility.
 
 // The box will be configurable with the bg-opacity and text-opacity classes
 .box {
-  border: utilities-get-value(border, null);
   padding: map-get($spacers, 3);
-  background: utilities-get-value(background-color, body);
   color: utilities-get-value(color, body);
+  background: utilities-get-value(background-color, body);
+  border: utilities-get-value(border, null);
+}
+```
+
+This outputs the following:
+
+```css
+.box {
+  padding: 1rem;
+  color: rgba(var(--bs-body-color-rgb), var(--bs-text-opacity));
+  background: rgba(var(--bs-body-bg-rgb), var(--bs-bg-opacity));
+  border: var(--bs-border-width) var(--bs-border-style) var(--bs-border-color);
 }
 ```
 
 This is likely the function you'll use the most, but you can also:
 
-- access all the values of a utility with `utilities-get-values`, which will always return a map to simplify their processing
-- access a specific option with `utilities-get-option`
-- or even all the options with `utilities-get-options`
+- Access all the values of a utility with `utilities-get-values()`, which will always return a map to simplify their processing
+- Access a specific option with `utilities-get-option()`
+- Access all of a utility's options with `utilities-get-options()`
 
 ## Practical examples
 
@@ -568,7 +585,7 @@ This will now generate responsive variations of `.border` and `.border-0` for ea
 
 ### Rename utilities
 
-Missing v4 utilities, or used to another naming convention? The utilities API can be used to override the resulting `class` of a given utility—for example, to rename `.ms-*` utilities to oldish `.ml-*`:
+Missing v4 utilities or another naming convention? Override the `class` option to change the output of a given utility. For example, to rename `.ms-*` utilities to `.ml-*`:
 
 ```scss
 @import "bootstrap/scss/functions";