Move states docs and rewrite to match existing examples

1 files changed, 34 insertions, 56 deletions

diff --git a/site/content/docs/5.0/utilities/api.md b/site/content/docs/5.0/utilities/api.md
index a0ba976d81..abe2a922af 100644
--- a/site/content/docs/5.0/utilities/api.md
+++ b/site/content/docs/5.0/utilities/api.md
@@ -17,6 +17,7 @@ The `$utilities` map contains all our utilities and is later merged with your cu
 | `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. |
+| `state` | Optional | List of pseudo-class variants like `:hover` or `:focus` to generate for the utility. No default value. |
 | `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. |
@@ -81,6 +82,39 @@ Output:
 .o-100 { opacity: 1; }
 ```
 
+## States
+
+Use the `state` option to generate pseudo-class variations. Example pseudo-classes are `:hover` and `:focus`. When a list of states are provided, classnames are created for that pseudo-class. For example, to change opacity on hover, add `state: hover` and you'll get `.opacity-hover:hover` in your compiled CSS.
+
+Need multiple pseudo-classes? Use a space-separated list of states: `state: hover focus`.
+
+```scss
+$utilities: (
+  "opacity": (
+    property: opacity,
+    class: opacity,
+    state: hover,
+    values: (
+      0: 0,
+      25: .25,
+      50: .5,
+      75: .75,
+      100: 1,
+    )
+  )
+);
+```
+
+Output:
+
+```css
+.opacity-0-hover:hover { opacity: 0; }
+.opacity-25-hover:hover { opacity: .25; }
+.opacity-50-hover:hover { opacity: .5; }
+.opacity-75-hover:hover { opacity: .75; }
+.opacity-100-hover:hover { opacity: 1; }
+```
+
 ### Responsive utilities
 
 Add the `responsive` boolean to generate responsive utilities (e.g., `.opacity-md-25`) across [all breakpoints]({{< docsref "/layout/breakpoints" >}}).
@@ -264,59 +298,3 @@ $utilities: map-merge(
   )
 );
 ```
-
-## Adding pseudo-classes to utilities
-
-With the `state` option, pseudo-class utilities can be generated:
-
-```scss
-$utilities: (
-  "shadow": (
-    property: box-shadow,
-    state: hover focus,
-    class: shadow,
-    values: (
-      null: $box-shadow,
-      sm: $box-shadow-sm,
-      lg: $box-shadow-lg,
-      none: none,
-    )
-  )
-);
-```
-
-Output:
-
-```css
-.shadow-hover:hover {
-  box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15) !important;
-}
-
-.shadow-focus:focus {
-  box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15) !important;
-}
-
-.shadow-sm-hover:hover {
-  box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075) !important;
-}
-
-.shadow-sm-focus:focus {
-  box-shadow: 0 0.125rem 0.25rem rgba(0, 0, 0, 0.075) !important;
-}
-
-.shadow-lg-hover:hover {
-  box-shadow: 0 1rem 3rem rgba(0, 0, 0, 0.175) !important;
-}
-
-.shadow-lg-focus:focus {
-  box-shadow: 0 1rem 3rem rgba(0, 0, 0, 0.175) !important;
-}
-
-.shadow-none-hover:hover {
-  box-shadow: none !important;
-}
-
-.shadow-none-focus:focus {
-  box-shadow: none !important;
-}
-```