Add new image container component and deprecate legacy image variants

package.json

@@ -1,6 +1,6 @@
 {
   "name": "vanilla-framework",
-  "version": "4.12.2",
+  "version": "4.13.0",
   "author": {
     "email": "webteam@canonical.com",
     "name": "Canonical Webteam"

releases.yml

@@ -1,3 +1,13 @@
+- version: 4.13.0
+  features:
+    - component: Image container
+      url: /docs/patterns/images
+      status: New
+      notes: "We've added a new image container component for controlling image aspect ratio and background."
+    - component: Images / Legacy variants
+      url: /docs/patterns/images
+      status: Deprecated
+      notes: "We've deprecated the <code>p-image--bordered</code> and <code>p-image--shadowed</code> classes. Use <code>p-image-container is-highlighted</code> instead."
 - version: 4.12.0
   features:
     - component: Typography

scss/_patterns_image.scss

@@ -1,6 +1,60 @@
+/*
+  @classreference
+  image-container:
+    Image container:
+      .p-image-container:
+        Main element of the image component.
+      "&.is-highlighted":
+        Highlighted variant, to be used to highlight contents.
+      .p-image-container--16-9:
+        Wraps contents in a container with an aspect ratio of 16:9.
+      .p-image-container--3-2:
+        Wraps contents in a container with an aspect ratio of 3:2.
+      .p-image-container--2-3:
+        Wraps contents in a container with an aspect ratio of 2:3.
+      .p-image-container--cinematic:
+        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.
+    Image:
+      .p-image-container__image:
+        Image element within an image container.
+*/
+
 @import 'settings';
 
 @mixin vf-p-image {
+  .p-image-container,
+  [class^='p-image-container--'] {
+    align-items: center;
+    display: grid;
+    justify-content: center;
+    text-align: center;
+    .p-image-container__image {
+      object-fit: contain;
+    }
+    &.is-highlighted {
+      background: $colors--theme--background-alt;
+    }
+  }
+
+  .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;
+  }
+
+  // Deprecated; will be removed in v5
   .p-image--bordered {
     border: {
       color: $color-mid-light;
@@ -9,6 +63,7 @@
     }
   }
 
+  // Deprecated; will be removed in v5
   .p-image--shadowed {
     box-shadow: 0 1px 5px 1px transparentize($color-mid-light, 0.8);
   }

templates/docs/examples/patterns/image/container/aspect-ratio/16-9.html

@@ -0,0 +1,10 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Image Container / Aspect Ratio / 16:9{% endblock %}
+
+{% block standalone_css %}patterns_image{% endblock %}
+
+{% block content %}
+<div class="p-image-container--16-9 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 %}

templates/docs/examples/patterns/image/container/aspect-ratio/all.html

@@ -0,0 +1,37 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Image Container / Aspect Ratio / All{% endblock %}
+
+{% block standalone_css %}patterns_image{% endblock %}
+
+{% block content %}
+  <div>
+    <span>16:9</span>
+    <div class="p-image-container--16-9 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>
+    <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>
+    <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>
+    <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>
+    <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>
+{% endblock %}

templates/docs/examples/patterns/image/container/highlighted.html

@@ -0,0 +1,10 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Image Container / Highlighted{% endblock %}
+
+{% block standalone_css %}patterns_image{% endblock %}
+
+{% block content %}
+<div class="p-image-container is-highlighted">
+  <img class="p-image-container__image" src="https://assets.ubuntu.com/v1/9b4c074f-Kernelt%20industries-80-short.png" alt="" width="250">
+</div>
+{% endblock %}

templates/docs/patterns/images.md

@@ -4,10 +4,40 @@ context:
   title: Images | Components
 ---
 
-Enhance images by adding a variant style with a border or drop shadow.
+Enhance images by distinguishing them from their background or controlling their container's aspect ratio.
+
+## Highlighted image
+
+Insulate an image from its surroundings. This can help to emphasize the image
+and/or prevent its white space from becoming indistinguishable from the surrounding white space.
+
+<div class="embedded-example"><a href="/docs/examples/patterns/image/container/highlighted" class="js-example">
+View example of the image container with a highlighted background
+</a></div>
+
+## Image container with aspect ratio
+
+You can modify the aspect ratio of an image container to neatly wrap an image in a container of the desired aspect ratio.
+This is useful for aligning images or other content with mismatching aspect ratios.
+
+All image containers center the `.p-image-container__image` element inside them by default.
+If you need to change image alignment within the image container, use the [image position utility](/docs/utilities/image-position).
+
+See the [class references section](#class-reference) for more information on the available aspect ratio classes.
+
+<div class="embedded-example"><a href="/docs/examples/patterns/image/container/aspect-ratio/16-9" class="js-example">
+View example of image container with 16/9 aspect ratio
+</a></div>
 
 ## Image with border
 
+<div class="p-notification--caution">
+  <div class="p-notification__content">
+    <h3 class="p-notification__title">Deprecated</h3>
+    <p class="p-notification__message">Image with border is deprecated. Use `.p-image-container` with `.is-highlighted` modifier instead.</p>
+  </div>
+</div>
+
 A simple key-line around your image.
 
 <div class="embedded-example"><a href="/docs/examples/patterns/image/bordered/" class="js-example">
@@ -16,6 +46,13 @@ View example of image with border
 
 ## Image with drop shadow
 
+<div class="p-notification--caution">
+  <div class="p-notification__content">
+    <h3 class="p-notification__title">Deprecated</h3>
+    <p class="p-notification__message">Image with drop shadow is deprecated. Use `.p-image-container` with `.is-highlighted` modifier instead.</p>
+  </div>
+</div>
+
 Add depth using our drop shadow around your image.
 
 <div class="embedded-example"><a href="/docs/examples/patterns/image/shadowed/" class="js-example">
@@ -38,6 +75,10 @@ Adds spacing to the top of a media element. This is usually needed when image or
 View example of media element with spacing
 </a></div>
 
+## Class reference
+
+{{ class_reference("image-container") }}
+
 ## Import
 
 To import just this component into your project, copy the snippet below and include it in your main Sass file.