From 9f60659d1dda28146e1c5cb6fe5a3e2b0d42b266 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Wed, 23 Sep 2020 11:06:21 -0700
Subject: [PATCH] Updates to .ratio selectors and docs

- Remove group selector for ratio items
- Drop the .ratio-item entirely
- Update docs to explain updated approach
- Update Migration guide to reflect the latest
---
 scss/helpers/_ratio.scss                  |  6 +-----
 site/assets/scss/_component-examples.scss | 11 ++++++-----
 site/content/docs/5.0/helpers/ratio.md    | 20 +++++++++++---------
 site/content/docs/5.0/migration.md        |  1 +
 4 files changed, 19 insertions(+), 19 deletions(-)

diff --git a/scss/helpers/_ratio.scss b/scss/helpers/_ratio.scss
index fd2efb81e4..3c0ff330a7 100644
--- a/scss/helpers/_ratio.scss
+++ b/scss/helpers/_ratio.scss
@@ -10,11 +10,7 @@
     content: "";
   }
 
-  .ratio-item,
-  iframe,
-  embed,
-  object,
-  video {
+  > * {
     position: absolute;
     top: 0;
     left: 0;
diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss
index 5ced393519..13e25bfc88 100644
--- a/site/assets/scss/_component-examples.scss
+++ b/site/assets/scss/_component-examples.scss
@@ -174,11 +174,12 @@
     color: $gray-600;
     background-color: $gray-100;
     border: $border-width solid $border-color;
-  }
-  .ratio-item {
-    display: flex;
-    align-items: center;
-    justify-content: center;
+
+    > div {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+    }
   }
 }
 .bd-example-ratios-breakpoint {
diff --git a/site/content/docs/5.0/helpers/ratio.md b/site/content/docs/5.0/helpers/ratio.md
index df24c1c604..e46d28279e 100644
--- a/site/content/docs/5.0/helpers/ratio.md
+++ b/site/content/docs/5.0/helpers/ratio.md
@@ -8,7 +8,9 @@ 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).
+Use the ratio helper to manage the aspect ratios of external 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>`). Styles are applied from the parent `.ratio` class directly to the child.
+
+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" >}}).
@@ -16,11 +18,11 @@ Rules are directly applied to `<iframe>`, `<embed>`, `<video>`, and `<object>` e
 
 ## 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.
+Wrap any embed, like an `<iframe>`, in a parent element with `.ratio` and an aspect ratio class. The immediate child element is automatically sized thanks to our universal selector `.ratio > *`.
 
 {{< 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>
+  <iframe src="https://www.youtube.com/embed/zpOULjyy-n8?rel=0" title="YouTube video" allowfullscreen></iframe>
 </div>
 {{< /example >}}
 
@@ -30,16 +32,16 @@ Aspect ratios can be customized with modifier classes. By default the following
 
 {{< example class="bd-example-ratios" >}}
 <div class="ratio ratio-1x1">
-  <div class="ratio-item">1x1</div>
+  <div>1x1</div>
 </div>
 <div class="ratio ratio-4x3">
-  <div class="ratio-item">4x3</div>
+  <div>4x3</div>
 </div>
 <div class="ratio ratio-16x9">
-  <div class="ratio-item">16x9</div>
+  <div>16x9</div>
 </div>
 <div class="ratio ratio-21x9">
-  <div class="ratio-item">21x9</div>
+  <div>21x9</div>
 </div>
 {{< /example >}}
 
@@ -51,7 +53,7 @@ For example, to create a 2x1 aspect ratio, set `--aspect-ratio: 50%` on the `.ra
 
 {{< example class="bd-example-ratios" >}}
 <div class="ratio" style="--aspect-ratio: 50%;">
-  <div class="ratio-item">2x1</div>
+  <div>2x1</div>
 </div>
 {{< /example >}}
 
@@ -67,7 +69,7 @@ This CSS variable makes it easy to modify the aspect ratio across breakpoints. T
 
 {{< example class="bd-example-ratios bd-example-ratios-breakpoint" >}}
 <div class="ratio ratio-4x3">
-  <div class="ratio-item">4x3, then 2x1</div>
+  <div>4x3, then 2x1</div>
 </div>
 {{< /example >}}
 
diff --git a/site/content/docs/5.0/migration.md b/site/content/docs/5.0/migration.md
index 219ff6f863..2ddd6e27b1 100644
--- a/site/content/docs/5.0/migration.md
+++ b/site/content/docs/5.0/migration.md
@@ -76,6 +76,7 @@ toc: true
 
 - 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`.
+  - We've dropped the `.embed-responsive-item` and element group selector in favor of a simpler `.ratio > *` selector. No more class needed, and the ratio helper now works with any HTML element.
   - 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" >}}).