Rename the classes and docs page, update everything accordingly

8 files changed, 82 insertions, 81 deletions

diff --git a/scss/_helpers.scss b/scss/_helpers.scss
index 2fb66e4ea..8f566d12f 100644
--- a/scss/_helpers.scss
+++ b/scss/_helpers.scss
@@ -1,6 +1,6 @@
 @import "helpers/clearfix";
 @import "helpers/colored-links";
-@import "helpers/embed";
+@import "helpers/ratio";
 @import "helpers/position";
 @import "helpers/visually-hidden";
 @import "helpers/stretched-link";
diff --git a/scss/_variables.scss b/scss/_variables.scss
index fa4ad19f1..6950af95c 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -376,14 +376,16 @@ $transition-base:             all .2s ease-in-out !default;
 $transition-fade:             opacity .15s linear !default;
 $transition-collapse:         height .35s ease !default;
 
-// scss-docs-start embed-responsive-aspect-ratios
-$embed-responsive-aspect-ratios: (
+// stylelint-disable function-blacklist
+// scss-docs-start aspect-ratios
+$aspect-ratios: (
   "1x1": 100%,
-  "4x3": 75%,
-  "16x9": 56.25%,
-  "21x9": 42.857142%
+  "4x3": calc(3 / 4 * 100%),
+  "16x9": calc(9 / 16 * 100%),
+  "21x9": calc(9 / 21 * 100%)
 ) !default;
-// scss-docs-end embed-responsive-aspect-ratios
+// scss-docs-end aspect-ratios
+// stylelint-enable function-blacklist
 
 // Typography
 //
diff --git a/scss/helpers/_embed.scss b/scss/helpers/_ratio.scss
index 8dbb7487d..fd2efb81e 100644
--- a/scss/helpers/_embed.scss
+++ b/scss/helpers/_ratio.scss
@@ -1,7 +1,6 @@
 // Credit: Nicolas Gallagher and SUIT CSS.
 
-.embed-responsive {
-
+.ratio {
   position: relative;
   width: 100%;
 
@@ -11,7 +10,7 @@
     content: "";
   }
 
-  .embed-responsive-item,
+  .ratio-item,
   iframe,
   embed,
   object,
@@ -24,8 +23,8 @@
   }
 }
 
-@each $key, $ratio in $embed-responsive-aspect-ratios {
-  .embed-responsive-#{$key} {
+@each $key, $ratio in $aspect-ratios {
+  .ratio-#{$key} {
     --aspect-ratio: #{$ratio};
   }
 }
diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss
index 2c8f7e2e0..4f031eec5 100644
--- a/site/assets/scss/_component-examples.scss
+++ b/site/assets/scss/_component-examples.scss
@@ -166,13 +166,13 @@
   }
 
   // Responsive embed helpers
-  .embed-responsive {
+  .ratio {
     display: inline-block;
     color: $gray-600;
     background-color: $gray-100;
     border: $border-width solid $border-color;
   }
-  .embed-responsive-item {
+  .ratio-item {
     display: flex;
     align-items: center;
     justify-content: center;
diff --git a/site/content/docs/5.0/helpers/embed.md b/site/content/docs/5.0/helpers/embed.md
deleted file mode 100644
index 28f1550da..000000000
--- a/site/content/docs/5.0/helpers/embed.md
+++ /dev/null
@@ -1,62 +0,0 @@
----
-layout: docs
-title: Embeds
-description: Create responsive video or slideshow embeds based on the width of the parent by creating an intrinsic ratio that scales on any device.
-group: helpers
-toc: true
----
-
-## About
-
-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).
-
-{{< 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 class. As mentioned above, the `.embed-responsive-item` isn't strictly required, but we encourage it.
-
-{{< example >}}
-<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 >}}
-
-## Aspect ratios
-
-Aspect ratios can be customized with modifier classes. By default the following ratio classes are provided:
-
-{{< example html >}}
-<div class="embed-responsive embed-responsive-1x1" style="width: 10rem;">
-  <div class="embed-responsive-item">1x1</div>
-</div>
-<div class="embed-responsive embed-responsive-4x3" style="width: 10rem;">
-  <div class="embed-responsive-item">4x3</div>
-</div>
-<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
-
-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>
-{{< /example >}}
-
-## Sass 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/helpers/ratio.md b/site/content/docs/5.0/helpers/ratio.md
new file mode 100644
index 000000000..6feaab248
--- /dev/null
+++ b/site/content/docs/5.0/helpers/ratio.md
@@ -0,0 +1,62 @@
+---
+layout: docs
+title: Ratios
+description: Use generated psuedo 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.
+group: helpers
+toc: true
+---
+
+## About
+
+Rules are directly applied to `<iframe>`, `<embed>`, `<video>`, and `<object>` elements. You can also use an explicit use an explicit descendant class, `.ratio-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).
+
+{{< 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 `.ratio` and an aspect ratio class. As mentioned above, the `.ratio-item` isn't strictly required, but we encourage it.
+
+{{< example >}}
+<div class="ratio ratio-16x9">
+  <iframe class="ratio-item" src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" title="YouTube video" allowfullscreen></iframe>
+</div>
+{{< /example >}}
+
+## Aspect ratios
+
+Aspect ratios can be customized with modifier classes. By default the following ratio classes are provided:
+
+{{< example html >}}
+<div class="ratio ratio-1x1" style="width: 10rem;">
+  <div class="ratio-item">1x1</div>
+</div>
+<div class="ratio ratio-4x3" style="width: 10rem;">
+  <div class="ratio-item">4x3</div>
+</div>
+<div class="ratio ratio-16x9" style="width: 10rem;">
+  <div class="ratio-item">16x9</div>
+</div>
+<div class="ratio ratio-21x9" style="width: 10rem;">
+  <div class="ratio-item">21x9</div>
+</div>
+{{< /example >}}
+
+## Custom ratios
+
+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.
+
+For example, to create a 2x1 aspect ratio, set `--aspect-ratio: 50%` on the `.ratio`.
+
+{{< example html >}}
+<div class="ratio" style="--aspect-ratio: 50%; width: 10rem;">
+  <div class="ratio-item">2x1</div>
+</div>
+{{< /example >}}
+
+## Sass map
+
+Within `_variables.scss`, you can change the aspect ratios you want to use. Here's our default `$ratio-aspect-ratios` map. Modify the map as you like and recompile your Sass to put them to use.
+
+{{< scss-docs name="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 e7dac066c..219ff6f86 100644
--- a/site/content/docs/5.0/migration.md
+++ b/site/content/docs/5.0/migration.md
@@ -74,10 +74,10 @@ toc: true
 
 ### 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" >}}).
+- Responsive embed helpers have been renamed to [ratio helpers]({{< docsref "/helpers/ratio" >}}) with new class names and improved behaviors, as well as a helpful CSS variable.
+  - Classes have been renamed to change `by` to `x` in the aspect ratrio. For example, `.ratio-16by9` is now `.ratio-16x9`.
+  - The `$embed-responsive-aspect-ratios` Sass map has been renamed to `$aspect-ratios` and its values have been simplified to include the class name and the percentage as the `key: value` pair.
+  - CSS variables are now generated and included for each value in the Sass map. Modify the `--aspect-ratio` variable on the `.ratio` to create any [custom aspect ratio]({{< docsref "/helpers/ratio#custom-ratios" >}}).
 
 ---
 
diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
index 5550c3075..5ff66041a 100644
--- a/site/data/sidebar.yml
+++ b/site/data/sidebar.yml
@@ -79,7 +79,7 @@
   pages:
     - title: Clearfix
     - title: Colored links
-    - title: Embed
+    - title: Ratio
     - title: Position
     - title: Visually hidden
     - title: Stretched link