Redo aspect ratio docs

scss/_utilities.scss

@@ -17,8 +17,15 @@ $utilities: map.merge(
     ),
     // scss-docs-end utils-vertical-align
     // scss-docs-start utils-aspect-ratio
-    "aspect-ratio": (
+    "aspect-ratio-attr": (
+      selector: "attr-includes",
+      class: "ratio-",
       property: aspect-ratio,
+      values: var(--#{$prefix}ratio),
+    ),
+    "aspect-ratio": (
+      // property: aspect-ratio,
+      property: --#{$prefix}ratio,
       class: ratio,
       values: $aspect-ratios
     ),

scss/_variables.scss

@@ -307,10 +307,10 @@ $transition-collapse-width:   width .35s ease !default;
 // scss-docs-start aspect-ratios
 $aspect-ratios: (
   "auto": auto,
-  "4x3": 4 / 3,
-  "1x1": 1 / 1,
-  "16x9": 16 / 9,
-  "21x9": 21 / 9
+  "4x3": #{"4 / 3"},
+  "1x1": #{"1 / 1"},
+  "16x9": #{"16 / 9"},
+  "21x9": #{"21 / 9"}
 ) !default;
 // scss-docs-end aspect-ratios
 

site/src/content/docs/utilities/aspect-ratio.mdx

@@ -1,67 +1,68 @@
 ---
-title: Aspect Ratio
-description: Use generated pseudo elements to make an element maintain the aspect ratio of your choosing. Perfect for responsively handling video or slideshow embeds based on the width of the parent.
+title: Aspect ratio
+description: Make elements maintain specific aspect ratios. Perfect for handling videos, slideshow embeds, and more based on the width of the parent.
 toc: true
 ---
 
-Use the ratio utility to manage the aspect ratios of content like `<iframe>`s, `<embed>`s, `<video>`s, and `<object>`s. These helpers also can be used on any standard HTML child element (e.g., a `<div>` or `<img>`). Customize the available aspect ratios with the Sass variable or the utility API.
+## Reference
 
-<Callout>
-**Pro-Tip!** You don't need `frameborder="0"` on your `<iframe>`s as we override that for you in [Reboot]([[docsref:/content/reboot]]).
-</Callout>
+<BsTable>
+| Class | Styles |
+| --- | --- |
+| `.ratio-auto` | `aspect-ratio: auto;` |
+| `.ratio-1x1` | `aspect-ratio: 1 / 1;` |
+| `.ratio-4x3` | `aspect-ratio: 4 / 3;` |
+| `.ratio-16x9` | `aspect-ratio: 16 / 9;` |
+| `.ratio-21x9` | `aspect-ratio: 21 / 9;` |
+</BsTable>
 
 ## Example
 
-Add your ratio utility to the element you want to modify, like an `<iframe>`. Ratio utilities also pair well with any width utilities, as shown below.
+Add your ratio utility to the element you want to modify, like an `<iframe>`, `<video>`, or less semantic elements like `<div>`. Ratio utilities also pair well with any width utilities, as shown below. Customize the available aspect ratios with the Sass variable or the utility API.
+
+Heads up—you can omit `frameborder="0"` on your `<iframe>`s as that is overridden for you in [Reboot]([[docsref:/content/reboot]]).
 
 <Example code={`<iframe class="w-100 ratio-16x9" src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" title="YouTube video" allowfullscreen></iframe>`} />
 
-## Aspect ratios
-
-Aspect ratios can be customized with modifier classes. By default the following ratio classes are provided:
+Swap the `.ratio-*` class for a different aspect ratio.
 
 <Example class="bd-example-ratios" code={`<div class="ratio-auto">
     <div>Auto</div>
   </div>
   <div class="w-25 ratio-1x1">
-    <div>1x1</div>
+    <div>1×1</div>
   </div>
   <div class="w-50 ratio-4x3">
-    <div>4x3</div>
+    <div>4×3</div>
   </div>
   <div class="w-75 ratio-16x9">
-    <div>16x9</div>
+    <div>16×9</div>
   </div>
   <div class="w-100 ratio-21x9">
-    <div>21x9</div>
+    <div>21×9</div>
   </div>`} />
 
-## Custom ratios
+## How it works
 
-{/* mdo-do: do we bring these back?
+Aspect ratios are a combination pairing of attribute and class utilities. The attribute utility sets a CSS variable to all `.ratio-` classes, while the specific ratio utility class sets the value for that variable.
 
-Each `.ratio-*` class includes a CSS custom property (or CSS variable) in the selector. You can override this CSS variable to create custom aspect ratios on the fly with some quick math on your part.
+```css
+[class*="ratio-"] {
+  aspect-ratio: var(--bs-ratio);
+}
 
-For example, to create a 2x1 aspect ratio, set `--bs-aspect-ratio: 50%` on the `.ratio`.
-
-<Example class="bd-example-ratios" code={`<div class="ratio" style="--bs-aspect-ratio: 50%;">
-    <div>2x1</div>
-  </div>`} />
-
-This CSS variable makes it easy to modify the aspect ratio across breakpoints. The following is 4x3 to start, but changes to a custom 2x1 at the medium breakpoint.
-
-```scss
-.ratio-4x3 {
-  @include media-breakpoint-up(md) {
-    --bs-aspect-ratio: 50%; // 2x1
-  }
+.ratio-1x1 {
+  --bs-ratio: 1 / 1;
 }
 ```
 
-<Example class="bd-example-ratios bd-example-ratios-breakpoint" code={`<div class="ratio ratio-4x3">
-    <div>4x3, then 2x1</div>
+## Custom ratios
+
+Because of the combination of attribute and class utilities, you can use custom ratios by setting the CSS variable to the desired ratio.
+
+<Example class="bd-example-ratios" code={`<div class="ratio-custom" style="--bs-ratio: 4 / 1;">
+    <div>4×1</div>
   </div>`} />
-*/}
 
 ## Sass map
 

site/src/scss/_component-examples.scss

@@ -183,13 +183,15 @@
   // Ratio helpers
   .bd-example-ratios {
     [class*="ratio"] {
+      color-scheme: dark;
       display: flex;
       align-items: center;
       justify-content: center;
       margin-bottom: 1rem;
-      color: var(--bs-secondary-color);
-      background-color: var(--bs-tertiary-bg);
+      color: var(--bs-fg-3);
+      background-color: var(--bs-bg-1);
       border: var(--bs-border-width) solid var(--bs-border-color);
+      @include border-radius(var(--bs-border-radius));
     }
   }