Add aspect ratio & highlighted background image classes. Deprecate ol…

…d image classes.

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: Images
+      url: /docs/patterns/images
+      status: Updated
+      notes: "We've added new classes for controlling image aspect ratio and background."
+    - component: Images
+      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,37 @@
 @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 +40,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,46 @@ 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).
+
+| CSS Class                      | Aspect ratio |
+| ------------------------------ | ------------ |
+| `p-image-container--16-9`      | 16:9         |
+| `p-image-container--3-2`       | 3:2          |
+| `p-image-container--2-3`       | 2:3          |
+| `p-image-container--cinematic` | 2.4:1        |
+| `p-image-container--square`    | 1:1          |
+
+<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 +52,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">