Responsive image aspect ratio variants (#5308)

* Add responsive image container aspect ratio classes * Add responsive image container aspect ratio example * tweak aspect ratio responsive mixin calling * Add responsive image container aspect ratio class reference * Add more responsive aspect ratio examples, and add them to image container docs page * Add responsive aspect ratio class release note * Better explain aspect ratio classnames table * fix mdspell errors * Add image combined as a responsive example * Widen image container aspect ratio class names list * Explain motive behind responsive aspect ratio classes * Move image container breakpoint bounds to _settings_breakpoints * use width inequalities rather than min/max-width
canonical · Aug 20, 2024 · 75e90fa · 75e90fa
1 parent 2e1b69c
commit 75e90fa
Show file tree

Hide file tree

Showing 8 changed files with 387 additions and 30 deletions.
diff --git a/releases.yml b/releases.yml
@@ -16,6 +16,10 @@
       url: /docs/base/separators
       status: New
       notes: We've added <code>.is-highlighted</code> and <code>.is-highlighted.is-accent</code> classes to the base horizontal rule.
+    - component: Image container
+      url: /docs/patterns/images#image-container-with-aspect-ratio
+      status: New
+      notes: We've added new breakpoint-specific aspect ratio classes to the image container component.
 - version: 4.15.0
   features:
     - component: CTA Block

diff --git a/scss/_patterns_image.scss b/scss/_patterns_image.scss
@@ -18,13 +18,63 @@
         Wraps contents in a container with an aspect ratio of 2.4:1.
       .p-image-container--square:
         Wraps contents in a container with an aspect ratio of 1:1.
+      .p-image-container--(16-9|3-2|2-3|cinematic|square)-on-(small|medium|large):
+        Wraps contents in a container with the specified aspect ratio on the specified breakpoint.
     Image:
       .p-image-container__image:
         Image element within an image container.
 */
 
 @import 'settings';
 
+// Mapping of aspect ratio class names to their `aspect-ratio` values (width / height).
+$aspect-ratios: (
+  '16-9': calc(16 / 9),
+  '3-2': calc(3 / 2),
+  '2-3': calc(2 / 3),
+  'cinematic': 2.4,
+  'square': 1,
+);
+
+@mixin aspect-ratio-classes {
+  @each $aspect-ratio, $aspect-ratio-value in $aspect-ratios {
+    .p-image-container--#{$aspect-ratio} {
+      aspect-ratio: $aspect-ratio-value;
+    }
+  }
+
+  @each $breakpoint-name, $breakpoint-bounds-pair in $breakpoint-bounds {
+    $min-width: map-get($breakpoint-bounds-pair, min);
+    $max-width: map-get($breakpoint-bounds-pair, max);
+
+    @if $min-width and $max-width {
+      @media ($min-width <= width < $max-width) {
+        @each $aspect-ratio, $aspect-ratio-value in $aspect-ratios {
+          .p-image-container--#{$aspect-ratio}-on-#{$breakpoint-name} {
+            aspect-ratio: $aspect-ratio-value;
+          }
+        }
+      }
+    } @else if $min-width {
+      @media (width >= $min-width) {
+        @each $aspect-ratio, $aspect-ratio-value in $aspect-ratios {
+          .p-image-container--#{$aspect-ratio}-on-#{$breakpoint-name} {
+            aspect-ratio: $aspect-ratio-value;
+          }
+        }
+      }
+    } @else if $max-width {
+      @media (width < $max-width) {
+        @each $aspect-ratio, $aspect-ratio-value in $aspect-ratios {
+          .p-image-container--#{$aspect-ratio}-on-#{$breakpoint-name} {
+            aspect-ratio: $aspect-ratio-value;
+          }
+        }
+      }
+    }
+  }
+}
+
 @mixin vf-p-image {
   .p-image-container,
   [class^='p-image-container--'] {
@@ -54,21 +104,7 @@
     }
   }
 
-  .p-image-container--16-9 {
-    aspect-ratio: 16/9;
-  }
-  .p-image-container--3-2 {
-    aspect-ratio: 3/2;
-  }
-  .p-image-container--2-3 {
-    aspect-ratio: 2/3;
-  }
-  .p-image-container--cinematic {
-    aspect-ratio: 2.4/1;
-  }
-  .p-image-container--square {
-    aspect-ratio: 1/1;
-  }
+  @include aspect-ratio-classes;
 
   // Deprecated; will be removed in v5
   .p-image--bordered {

diff --git a/scss/_settings_breakpoints.scss b/scss/_settings_breakpoints.scss
@@ -5,3 +5,19 @@ $breakpoint-large: 1036px !default;
 $breakpoint-navigation-threshold: $breakpoint-large !default;
 $breakpoint-heading-threshold: $breakpoint-large !default;
 $breakpoint-x-large: 1681px !default; // exclude most laptops
+
+// Mapping of breakpoint names to the min and max widths at which they apply.
+$breakpoint-bounds: (
+  small: (
+    min: null,
+    max: $breakpoint-small,
+  ),
+  medium: (
+    min: $breakpoint-small,
+    max: $breakpoint-large,
+  ),
+  large: (
+    min: $breakpoint-large,
+    max: null,
+  ),
+);
diff --git a/templates/docs/examples/patterns/image/container/aspect-ratio/all.html b/templates/docs/examples/patterns/image/container/aspect-ratio/all.html
@@ -4,44 +4,47 @@
 {% block standalone_css %}patterns_image{% endblock %}
 
 {% block content %}
-  <div>
+  <section>
     <span>16:9</span>
     {% include 'docs/examples/patterns/image/container/aspect-ratio/16-9.html' %}
-  </div>
-  <div>
+  </section>
+  <section>
     <span>16:9 (with 16:9 image)</span>
     <div class="p-image-container--16-9 is-highlighted">
       <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/7c9867c1-16x9.png" width="1200" alt="">
     </div>
-  </div>
-  <div>
+  </section>
+  <section>
     <span>3:2</span>
     <div class="p-image-container--3-2 is-highlighted">
       <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
     </div>
-  </div>
-  <div>
+  </section>
+  <section>
     <span>2:3</span>
     <div class="p-image-container--2-3 is-highlighted">
       <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
     </div>
-  </div>
-  <div>
+  </section>
+  <section>
     <span>2:3 (with 2:3 image)</span>
     <div class="p-image-container--2-3 is-highlighted">
       <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/e97cdac9-2x3.png" width="1200" alt="">
     </div>
-  </div>
-  <div>
+  </section>
+  <section>
     <span>2.4:1 (Cinematic)</span>
     <div class="p-image-container--cinematic is-highlighted">
       <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
     </div>
-  </div>
-  <div>
+  </section>
+  <section>
     <span>1:1 (Square)</span>
     <div class="p-image-container--square is-highlighted">
       <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
     </div>
-  </div>
+  </section>
+  <section>
+    {% include 'docs/examples/patterns/image/container/aspect-ratio/responsive-all.html' %}
+  </section>
 {% endblock %}
diff --git a/templates/docs/examples/patterns/image/container/aspect-ratio/responsive-all.html b/templates/docs/examples/patterns/image/container/aspect-ratio/responsive-all.html
@@ -0,0 +1,140 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Image Container / Aspect Ratio / Responsive / All{% endblock %}
+
+{% block standalone_css %}patterns_image{% endblock %}
+
+{% block content %}
+  <section>
+    <span>Cinematic on large, 16:9 on medium, 2:3 on small</span>
+    {% include 'docs/examples/patterns/image/container/aspect-ratio/responsive.html' %}
+  </section>
+
+  <section>
+    <span>Cinematic on large, 16:9 on medium</span>
+    <div class="p-image-container--cinematic-on-large p-image-container--16-9-on-medium is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>Cinematic on large, 2:3 on small</span>
+    <div class="p-image-container--cinematic-on-large p-image-container--2-3-on-small is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>16:9 on medium, 2:3 on small</span>
+    <div class="p-image-container--16-9-on-medium p-image-container--2-3-on-small is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>Cinematic on large</span>
+    <div class="p-image-container--cinematic-on-large is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>Cinematic on large, 16:9 on medium</span>
+    <div class="p-image-container--cinematic-on-large p-image-container--16-9-on-medium is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>Cinematic on large, 2:3 on small</span>
+    <div class="p-image-container--cinematic-on-large p-image-container--2-3-on-small is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>16:9 on medium</span>
+    <div class="p-image-container--16-9-on-medium is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>16:9 on medium, 2:3 on small</span>
+    <div class="p-image-container--16-9-on-medium p-image-container--2-3-on-small is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>2:3 on small</span>
+    <div class="p-image-container--2-3-on-small is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>16:9 on medium</span>
+    <div class="p-image-container--16-9-on-medium is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>Cinematic on large, 16:9 on medium, 2:3 on small</span>
+    <div class="p-image-container--cinematic-on-large p-image-container--16-9-on-medium p-image-container--2-3-on-small is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>Cinematic on large, 16:9 on medium</span>
+    <div class="p-image-container--cinematic-on-large p-image-container--16-9-on-medium is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>Cinematic on large, 2:3 on small</span>
+    <div class="p-image-container--cinematic-on-large p-image-container--2-3-on-small is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>16:9 on medium, 2:3 on small</span>
+    <div class="p-image-container--16-9-on-medium p-image-container--2-3-on-small is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>16:9 on medium</span>
+    <div class="p-image-container--16-9-on-medium is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+  <section>
+    <span>2:3 on small</span>
+    <div class="p-image-container--2-3-on-small is-highlighted">
+      <img class="p-image-container__image"
+           src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+    </div>
+  </section>
+
+{% endblock %}
diff --git a/templates/docs/examples/patterns/image/container/aspect-ratio/responsive.html b/templates/docs/examples/patterns/image/container/aspect-ratio/responsive.html
@@ -0,0 +1,11 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Image Container / Aspect Ratio / Responsive{% endblock %}
+
+{% block standalone_css %}patterns_image{% endblock %}
+
+{% block content %}
+  <div class="p-image-container--cinematic-on-large p-image-container--16-9-on-medium p-image-container--2-3-on-small is-highlighted">
+    <img class="p-image-container__image"
+         src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" width="300" alt="">
+  </div>
+{% endblock %}