Updates responsive embeds with new class names and CSS variables

- Renames .embed-responsive-XbyY classes to .embed-responsive-XxY
- Simplifies the Sass map to just be key and value, ratio and percentage
- Builds .embed-responsive-* modifiers with CSS variables
- Updates docs to show power of CSS variables
- Add notes to the Migration guide

5 files changed, 57 insertions, 40 deletions

diff --git a/scss/_variables.scss b/scss/_variables.scss
index 8f47509d6..fa4ad19f1 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -378,22 +378,10 @@ $transition-collapse:         height .35s ease !default;
 
 // scss-docs-start embed-responsive-aspect-ratios
 $embed-responsive-aspect-ratios: (
-  "21by9": (
-    x: 21,
-    y: 9
-  ),
-  "16by9": (
-    x: 16,
-    y: 9
-  ),
-  "4by3": (
-    x: 4,
-    y: 3
-  ),
-  "1by1": (
-    x: 1,
-    y: 1
-  )
+  "1x1": 100%,
+  "4x3": 75%,
+  "16x9": 56.25%,
+  "21x9": 42.857142%
 ) !default;
 // scss-docs-end embed-responsive-aspect-ratios
 
diff --git a/scss/helpers/_embed.scss b/scss/helpers/_embed.scss
index 924fc0e6d..8dbb7487d 100644
--- a/scss/helpers/_embed.scss
+++ b/scss/helpers/_embed.scss
@@ -1,11 +1,13 @@
 // Credit: Nicolas Gallagher and SUIT CSS.
 
 .embed-responsive {
+
   position: relative;
   width: 100%;
 
   &::before {
     display: block;
+    padding-top: var(--aspect-ratio);
     content: "";
   }
 
@@ -24,8 +26,6 @@
 
 @each $key, $ratio in $embed-responsive-aspect-ratios {
   .embed-responsive-#{$key} {
-    &::before {
-      padding-top: percentage(map-get($ratio, y) / map-get($ratio, x));
-    }
+    --aspect-ratio: #{$ratio};
   }
 }
diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss
index 87dcd1565..2c8f7e2e0 100644
--- a/site/assets/scss/_component-examples.scss
+++ b/site/assets/scss/_component-examples.scss
@@ -164,6 +164,19 @@
     margin-top: .5rem;
     margin-bottom: .5rem;
   }
+
+  // Responsive embed helpers
+  .embed-responsive {
+    display: inline-block;
+    color: $gray-600;
+    background-color: $gray-100;
+    border: $border-width solid $border-color;
+  }
+  .embed-responsive-item {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
 }
 
 .bd-example-modal {
diff --git a/site/content/docs/5.0/helpers/embed.md b/site/content/docs/5.0/helpers/embed.md
index 78d3f265d..28f1550da 100644
--- a/site/content/docs/5.0/helpers/embed.md
+++ b/site/content/docs/5.0/helpers/embed.md
@@ -8,16 +8,18 @@ toc: true
 
 ## About
 
-Rules are directly applied to `<iframe>`, `<embed>`, `<video>`, and `<object>` elements; optionally use an explicit descendant class `.embed-responsive-item` when you want to match the styling for other attributes.
+Rules are directly applied to `<iframe>`, `<embed>`, `<video>`, and `<object>` elements. You can also use an explicit use an explicit descendant class, `.embed-responsive-item`, when you want to match the styling for other attributes. Aspect ratios are declared in a Sass map and included in each class via CSS variable, which also allows [custom aspect ratios](#custom-ratios).
 
-**Pro-Tip!** You don't need to include `frameborder="0"` in your `<iframe>`s as we override that for you in [reboot]({{< docsref "/content/reboot" >}}).
+{{< callout info >}}
+**Pro-Tip!** You don't need `frameborder="0"` on your `<iframe>`s as we override that for you in [Reboot]({{< docsref "/content/reboot" >}}).
+{{< /callout >}}
 
 ## Example
 
-Wrap any embed like an `<iframe>` in a parent element with `.embed-responsive` and an aspect ratio. The `.embed-responsive-item` isn't strictly required, but we encourage it.
+Wrap any embed, like an `<iframe>`, in a parent element with `.embed-responsive` and an aspect ratio class. As mentioned above, the `.embed-responsive-item` isn't strictly required, but we encourage it.
 
 {{< example >}}
-<div class="embed-responsive embed-responsive-16by9">
+<div class="embed-responsive embed-responsive-16x9">
   <iframe class="embed-responsive-item" src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" title="YouTube video" allowfullscreen></iframe>
 </div>
 {{< /example >}}
@@ -26,28 +28,35 @@ Wrap any embed like an `<iframe>` in a parent element with `.embed-responsive` a
 
 Aspect ratios can be customized with modifier classes. By default the following ratio classes are provided:
 
-{{< highlight html >}}
-<!-- 21:9 aspect ratio -->
-<div class="embed-responsive embed-responsive-21by9">
-  <iframe class="embed-responsive-item" src="..."></iframe>
+{{< example html >}}
+<div class="embed-responsive embed-responsive-1x1" style="width: 10rem;">
+  <div class="embed-responsive-item">1x1</div>
 </div>
-
-<!-- 16:9 aspect ratio -->
-<div class="embed-responsive embed-responsive-16by9">
-  <iframe class="embed-responsive-item" src="..."></iframe>
+<div class="embed-responsive embed-responsive-4x3" style="width: 10rem;">
+  <div class="embed-responsive-item">4x3</div>
 </div>
-
-<!-- 4:3 aspect ratio -->
-<div class="embed-responsive embed-responsive-4by3">
-  <iframe class="embed-responsive-item" src="..."></iframe>
+<div class="embed-responsive embed-responsive-16x9" style="width: 10rem;">
+  <div class="embed-responsive-item">16x9</div>
+</div>
+<div class="embed-responsive embed-responsive-21x9" style="width: 10rem;">
+  <div class="embed-responsive-item">21x9</div>
 </div>
+{{< /example >}}
+
+## Custom ratios
 
-<!-- 1:1 aspect ratio -->
-<div class="embed-responsive embed-responsive-1by1">
-  <iframe class="embed-responsive-item" src="..."></iframe>
+Each `.embed-responsive-*` 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.
+
+For example, to create a 2x1 aspect ratio, set `--aspect-ratio: 50%` on the `.embed-responsive`.
+
+{{< example html >}}
+<div class="embed-responsive" style="--aspect-ratio: 50%; width: 10rem;">
+  <div class="embed-responsive-item">2x1</div>
 </div>
-{{< /highlight >}}
+{{< /example >}}
+
+## Sass map
 
-Within `_variables.scss`, you can change the aspect ratios you want to use. Here's an example of the `$embed-responsive-aspect-ratios` map:
+Within `_variables.scss`, you can change the aspect ratios you want to use. Here's our default `$embed-responsive-aspect-ratios` map. Modify the map as you like and recompile your Sass to put them to use.
 
 {{< scss-docs name="embed-responsive-aspect-ratios" file="scss/_variables.scss" >}}
diff --git a/site/content/docs/5.0/migration.md b/site/content/docs/5.0/migration.md
index 91cfb456d..e7dac066c 100644
--- a/site/content/docs/5.0/migration.md
+++ b/site/content/docs/5.0/migration.md
@@ -72,6 +72,13 @@ toc: true
 
 - Renamed `whiteList` option to `allowList`.
 
+### Helpers
+
+- [Responsive embed helpers]({{< docsref "/helpers/embed" >}}) have new modifier classes and include CSS variables.
+  - Classes have been renamed to change `by` to `x` in the aspect ratrio. For example, `.embed-responsive-16by9` is now `.responsive-16x9`.
+  - The `$embed-responsive-aspect-ratios` has been simplified to include the class name and the percentage as the `key: value` pair. This requires some math on your part when customizing, but ultimately makes it simpler on our end.
+  - CSS variables are now generated and included for each value in the Sass map. Modify the `--aspect-ratio` variable on the `.embed-responsive` to create any [custom aspect ratio]({{< docsref "/helpers/embed#custom-ratios" >}}).
+
 ---
 
 ## v5.0.0-alpha1