Editing and formatting utilities API page

1 files changed, 81 insertions, 160 deletions

diff --git a/site/content/docs/5.0/utilities/api.md b/site/content/docs/5.0/utilities/api.md
index 09af1738c0..7dd0d6ede5 100644
--- a/site/content/docs/5.0/utilities/api.md
+++ b/site/content/docs/5.0/utilities/api.md
@@ -7,21 +7,24 @@ aliases: "/docs/5.0/utilities/"
 toc: true
 ---
 
-The bootstrap utilities are generated with the utility API which can be used to change or extend Bootstrap's utility classes. If you don't have any idea what Sass maps are, you can consult the [official docs](https://sass-lang.com/documentation/values/maps) to get started.
+Bootstrap utilities are generated with our utility API and can be used to modify or extend our default set of utility classes via Sass. Our utility API is based on a series of Sass maps and functions for generating families of classes with various options. If you're unfamiliar with Sass maps, read up on the [official Sass docs](https://sass-lang.com/documentation/values/maps) to get started.
 
-The `$utilities` map contains all utilities and is later merged with your custom `$utilities` map if present. The utility map contains a keyed list of utility groups which accept the following options:
+The `$utilities` map contains all our utilities and is later merged with your custom `$utilities` map, if present. The utility map contains a keyed list of utility groups which accept the following options:
 
-- `property`: Name of the property, this can be a string or an array of strings (needed for eg. horizontal paddings or margins).
-- `responsive` _(optional)_: Boolean indicating if responsive classes need to be generated. `false` by default.
-- `rfs` _(optional)_: Variable to enable fluid rescaling. Have a look at the [RFS]({{< docsref "/getting-started/rfs" >}}) page to find out how this works. `false` by default.
-- `class` _(optional)_: Variable to change the class name if you don't want it to be the same as the property. In case you don't provide the `class` key and `property` key is an array of strings, the class name will be the first element of the `property` array.
-- `values`: This can be a list of values or a map if you don't want the class name to be the same as the value. If null is used as map key, it isn't rendered.
-- `print` _(optional)_: Boolean indicating if print classes need to be generated. `false` by default.
+{{< bs-table "table text-left" >}}
+| Option | Type | Description |
+| --- | --- | --- |
+| `property` | **Required** | Name of the property, this can be a string or an array of strings (e.g., horizontal paddings or margins). |
+| `values` | **Required** | List of values, or a map if you don't want the class name to be the same as the value. If `null` is used as map key, it isn't compiled. |
+| `class` | Optional | Variable for the class name if you don't want it to be the same as the property. In case you don't provide the `class` key and `property` key is an array of strings, the class name will be the first element of the `property` array. |
+| `responsive` | Optional | Boolean indicating if responsive classes need to be generated. `false` by default. |
+| `rfs` | Optional | Boolean to enable fluid rescaling. Have a look at the [RFS]({{< docsref "/getting-started/rfs" >}}) page to find out how this works. `false` by default. |
+| `print` | Optional | Boolean indicating if print classes need to be generated. `false` by default. |
+{{< /bs-table >}}
 
+## API explained
 
-## Adding utilities to the utility API
-
-All utility variables are added to the `$utilities` variable. Custom utility groups can added like this:
+All utility variables are added to the `$utilities` variable within our `_utilities.scss` stylesheet. Each group of utilities looks something like this:
 
 ```scss
 $utilities: (
@@ -38,30 +41,19 @@ $utilities: (
  );
 ```
 
-Output:
+Which outputs the following:
 
 ```css
-.opacity-0 {
-  opacity: 0;
-}
-.opacity-25 {
-  opacity: .25;
-}
-.opacity-50 {
-  opacity: .5;
-}
-.opacity-75 {
-  opacity: .75;
-}
-.opacity-100 {
-  opacity: 1;
-}
+.opacity-0 { opacity: 0; }
+.opacity-25 { opacity: .25; }
+.opacity-50 { opacity: .5; }
+.opacity-75 { opacity: .75; }
+.opacity-100 { opacity: 1; }
 ```
 
+### Custom class prefix
 
-## Changing the class prefix
-
-With the `class` option, the class prefix can be changed:
+Use the `class` option to change the class prefix used in the compiled CSS:
 
 ```scss
 $utilities: (
@@ -82,26 +74,16 @@ $utilities: (
 Output:
 
 ```css
-.o-0 {
-  opacity: 0;
-}
-.o-25 {
-  opacity: .25;
-}
-.o-50 {
-  opacity: .5;
-}
-.o-75 {
-  opacity: .75;
-}
-.o-100 {
-  opacity: 1;
-}
+.o-0 { opacity: 0; }
+.o-25 { opacity: .25; }
+.o-50 { opacity: .5; }
+.o-75 { opacity: .75; }
+.o-100 { opacity: 1; }
 ```
 
-## Responsive utilities
+### Responsive utilities
 
-With the `responsive` option, responsive utility classes can be generated:
+Add the `responsive` boolean to generate responsive utilities (e.g., `.opacity-md-25`) across [all breakpoints]({{< docsref "/layout/breakpoints" >}}).
 
 ```scss
 $utilities: (
@@ -122,95 +104,56 @@ $utilities: (
 Output:
 
 ```css
-.opacity-0 {
-  opacity: 0;
-}
-.opacity-25 {
-  opacity: .25;
-}
-.opacity-50 {
-  opacity: .5;
-}
-.opacity-75 {
-  opacity: .75;
-}
-.opacity-100 {
-  opacity: 1;
-}
+.opacity-0 { opacity: 0; }
+.opacity-25 { opacity: .25; }
+.opacity-50 { opacity: .5; }
+.opacity-75 { opacity: .75; }
+.opacity-100 { opacity: 1; }
+
 @media (min-width: 576px) {
-  .opacity-sm-0 {
-    opacity: 0;
-  }
-  .opacity-sm-25 {
-    opacity: .25;
-  }
-  .opacity-sm-50 {
-    opacity: .5;
-  }
-  .opacity-sm-75 {
-    opacity: .75;
-  }
-  .opacity-sm-100 {
-    opacity: 1;
-  }
+  .opacity-sm-0 { opacity: 0; }
+  .opacity-sm-25 { opacity: .25; }
+  .opacity-sm-50 { opacity: .5; }
+  .opacity-sm-75 { opacity: .75; }
+  .opacity-sm-100 { opacity: 1; }
 }
+
 @media (min-width: 768px) {
-  .opacity-md-0 {
-    opacity: 0;
-  }
-  .opacity-md-25 {
-    opacity: .25;
-  }
-  .opacity-md-50 {
-    opacity: .5;
-  }
-  .opacity-md-75 {
-    opacity: .75;
-  }
-  .opacity-md-100 {
-    opacity: 1;
-  }
+  .opacity-md-0 { opacity: 0; }
+  .opacity-md-25 { opacity: .25; }
+  .opacity-md-50 { opacity: .5; }
+  .opacity-md-75 { opacity: .75; }
+  .opacity-md-100 { opacity: 1; }
 }
+
 @media (min-width: 992px) {
-  .opacity-lg-0 {
-    opacity: 0;
-  }
-  .opacity-lg-25 {
-    opacity: .25;
-  }
-  .opacity-lg-50 {
-    opacity: .5;
-  }
-  .opacity-lg-75 {
-    opacity: .75;
-  }
-  .opacity-lg-100 {
-    opacity: 1;
-  }
+  .opacity-lg-0 { opacity: 0; }
+  .opacity-lg-25 { opacity: .25; }
+  .opacity-lg-50 { opacity: .5; }
+  .opacity-lg-75 { opacity: .75; }
+  .opacity-lg-100 { opacity: 1; }
 }
+
 @media (min-width: 1200px) {
-  .opacity-xl-0 {
-    opacity: 0;
-  }
-  .opacity-xl-25 {
-    opacity: .25;
-  }
-  .opacity-xl-50 {
-    opacity: .5;
-  }
-  .opacity-xl-75 {
-    opacity: .75;
-  }
-  .opacity-xl-100 {
-    opacity: 1;
-  }
+  .opacity-xl-0 { opacity: 0; }
+  .opacity-xl-25 { opacity: .25; }
+  .opacity-xl-50 { opacity: .5; }
+  .opacity-xl-75 { opacity: .75; }
+  .opacity-xl-100 { opacity: 1; }
+}
+
+@media (min-width: 1400px) {
+  .opacity-xxl-0 { opacity: 0; }
+  .opacity-xxl-25 { opacity: .25; }
+  .opacity-xxl-50 { opacity: .5; }
+  .opacity-xxl-75 { opacity: .75; }
+  .opacity-xxl-100 { opacity: 1; }
 }
 ```
 
-## Changing utilities
+### Changing utilities
 
-Overriding excising utilities is possible by using the same key. For example if you want more responsive overflow
-utility classes you can do this:
+Override existing utilities by using the same key. For example, if you want additional responsive overflow utility classes, you can do this:
 
 ```scss
 $utilities: (
@@ -222,16 +165,14 @@ $utilities: (
 );
 ```
 
+### Print utilities
 
-## Print utilities
-
-Enabling the `print` option will **also** generate utility classes for print.
+Enabling the `print` option will **also** generate utility classes for print, which are only applied within the `@media print { ... }` media query.
 
 ```scss
 $utilities: (
   "opacity": (
     property: opacity,
-    class: o,
     print: true,
     values: (
       0: 0,
@@ -247,42 +188,22 @@ $utilities: (
 Output:
 
 ```css
-.o-0 {
-  opacity: 0;
-}
-.o-25 {
-  opacity: .25;
-}
-.o-50 {
-  opacity: .5;
-}
-.o-75 {
-  opacity: .75;
-}
-.o-100 {
-  opacity: 1;
-}
+.opacity-0 { opacity: 0; }
+.opacity-25 { opacity: .25; }
+.opacity-50 { opacity: .5; }
+.opacity-75 { opacity: .75; }
+.opacity-100 { opacity: 1; }
 
 @media print {
-  .o-print-0 {
-    opacity: 0;
-  }
-  .o-print-25 {
-    opacity: .25;
-  }
-  .o-print-50 {
-    opacity: .5;
-  }
-  .o-print-75 {
-    opacity: .75;
-  }
-  .o-print-100 {
-    opacity: 1;
-  }
+  .opacity-print-0 { opacity: 0; }
+  .opacity-print-25 { opacity: .25; }
+  .opacity-print-50 { opacity: .5; }
+  .opacity-print-75 { opacity: .75; }
+  .opacity-print-100 { opacity: 1; }
 }
 ```
 
-## Removing utilities
+### Remove utilities
 
 Utilities can also be removed by changing the group key to `null`: