Update Suru to support hero sections with 25/75 and 50/50 main suru backgrounds

.spelling

@@ -91,4 +91,5 @@ Heydon
 Pickering
 alt
 WCAG
-A11y
+A11y
+standalone

releases.yml

@@ -12,6 +12,10 @@
       url: /docs/patterns/section#hero-sections
       status: New
       notes: We've introduced a new hero variant to the section component using <code>p-section--hero</code>.
+    - component: Suru
+      url: /docs/patterns/suru
+      status: Updated
+      notes: We've updated the Suru component to work as a hero section container, added new backgrounds for 25/75 and 50/50 splits, and updated the theme support.
 - version: 4.7.0
   features:
     - component: Navigation / 25/75 split

scss/_patterns_suru.scss

@@ -1,16 +1,61 @@
 @import 'settings';
 
 @mixin vf-p-suru {
-  .p-suru {
-    aspect-ratio: calc(2216 / 428); // aspect ratio calculated from image dimensions
-    background-image: url('#{$assets-path}7f34ade9-website_suru_25.jpg');
-    background-size: contain;
-    margin: 0 auto;
-    max-width: $grid-max-width;
-
-    &.is-dark {
-      aspect-ratio: calc(2580 / 501); // aspect ratio calculated from image dimensions
-      background-image: url('#{$assets-path}9469ef82-1_website_suru_DARK_25%20(1)122.jpg');
+  // add suru backgrounds to the themes
+  @at-root {
+    :root,
+    .is-light,
+    .is-paper {
+      // new suru backgrounds don't have while (light) version,
+      // they need paper background
+      --vf-suru-background: #{$color-paper};
+      --vf-suru-25-75: url('#{$assets-path}505636a6-0000_suru-main-25x75-light.png');
+      --vf-suru-50-50: url('#{$assets-path}e66e280b-0001_suru-main-50x50-light.png');
+    }
+
+    .is-dark {
+      --vf-suru-background: #{$colors--theme--background-default};
+      --vf-suru-25-75: url('#{$assets-path}7ccd4f39-0003_suru-main-25x75-dark.png');
+      --vf-suru-50-50: url('#{$assets-path}70c2bbcd-0002_suru-main-50x50-dark.png');
+    }
+  }
+
+  .p-suru,
+  .p-suru--25-75,
+  .p-suru--50-50 {
+    background-color: var(--vf-suru-background);
+
+    // padding top based on p-section--hero
+    // bottom padding not needed (as it's covered by the suru background image)
+    padding-top: $spv--large;
+
+    // on large screens, same as %section-padding--shallow
+    @media (min-width: $breakpoint-large) {
+      padding-top: $spv--x-large;
+    }
+
+    // for backwards compatibility with p-suru used as a standalone component
+    // we remove top padding if there are no children
+    // for this to work there can't be any whitespace in the suru element
+    // <div class="p-suru"></div>
+    &:-moz-only-whitespace,
+    &:empty {
+      padding-top: 0;
+    }
+
+    &::after {
+      aspect-ratio: calc(2600 / 471); // aspect ratio calculated from image dimensions
+      background-image: var(--vf-suru-25-75);
+      background-size: contain;
+      content: '';
+      display: block;
+      margin: 0 auto;
+      max-width: $grid-max-width;
+    }
+
+    &.p-suru--50-50::after {
+      // aspect ratio of 50/50 background is the same, so no need to override
+      background-image: var(--vf-suru-50-50);
     }
   }
 }

scss/standalone/patterns_suru.scss

@@ -2,3 +2,6 @@
 @include vf-base;
 
 @include vf-p-suru;
+
+// needed for example
+@include vf-p-grid;

templates/docs/examples/brochure/_50-50.html

@@ -53,5 +53,3 @@ <h2>Trial at no extra cost for existing Ubuntu Advantage customers</h2>
     </div>
   </div>
 </section>
-
-<div class="p-suru"></div>

templates/docs/examples/brochure/hero-25-75.html

@@ -8,36 +8,37 @@
 {% block content %}
 
 <section>
-    <div class="row--25-75">
-        <div class="col">
-            <h1>H1: 2-3 words</h1>
-        </div>
-        <div class="col">
-            <div class="p-section">
-                <p class="p-heading--2">H2: 5-15 words, up to 3 rows of copy...</p>
+    <div class="p-suru--25-75">
+        <div class="row--25-75">
+            <div class="col">
+                <h1>H1: 2-3 words</h1>
+            </div>
+            <div class="col">
+                <div class="p-section">
+                    <p class="p-heading--2">H2: 5-15 words, up to 3 rows of copy...</p>
+                </div>
             </div>
         </div>
-    </div>
-    <div class="row--25-75">
-        <div class="col">
-            <img src="https://assets.ubuntu.com/v1/b200e162-design.svg" alt="" width="80">
-        </div>
-        <div class="col">
-            <div class="p-section">
-                <p>Multi-cloud (also referred to as multi cloud or multicloud) is a concept that refers to using multiple clouds from more than one cloud service provider at the same time. The term is also used to refer to the simultaneous running of bare metal, virtualised and containerised workloads.</p>
+        <div class="row--25-75">
+            <div class="col">
+                <img src="https://assets.ubuntu.com/v1/b200e162-design.svg" alt="" width="80">
+            </div>
+            <div class="col">
+                <div class="p-section">
+                    <p>Multi-cloud (also referred to as multi cloud or multicloud) is a concept that refers to using multiple clouds from more than one cloud service provider at the same time. The term is also used to refer to the simultaneous running of bare metal, virtualised and containerised workloads.</p>
+                </div>
             </div>
         </div>
-    </div>
-    <div class="row--25-75">
-        <div class="col">
-            <hr />
-            <a href="#" class="p-button--positive">CTA up to 3 words</a>
-            <a href="#" class="p-button">Optional button</a>
-            <a href="#">Link CTA up to 5 words</a>
-            <!-- p-section spacing not needed because it's followed by suru -->
+        <div class="row--25-75">
+            <div class="col">
+                <hr />
+                <a href="#" class="p-button--positive">CTA up to 3 words</a>
+                <a href="#" class="p-button">Optional button</a>
+                <a href="#">Link CTA up to 5 words</a>
+                <!-- p-section spacing not needed because it's followed by suru -->
+            </div>
         </div>
     </div>
-    <div class="p-suru"></div>
 </section>
 
 {% endblock %}

templates/docs/examples/brochure/hero-75-offset.html

@@ -8,24 +8,25 @@
 {% block content %}
 
 <section>
-    <div class="row--25-75">
-        <div class="col">
-            <div class="p-section">
-                <h1 class="u-no-margin--bottom">H1: 3-5 words</h1>
-                <p class="p-heading--2">H2: 5-15 words, up to 3 rows of copy...</p>
+    <div class="p-suru--25-75">
+        <div class="row--25-75">
+            <div class="col">
+                <div class="p-section">
+                    <h1 class="u-no-margin--bottom">H1: 3-5 words</h1>
+                    <p class="p-heading--2">H2: 5-15 words, up to 3 rows of copy...</p>
+                </div>
+                <div class="p-section">
+                    <p>Multi-cloud (also referred to as multi cloud or multicloud) is a concept that refers to using multiple clouds from more than one cloud service provider at the same time. The term is also used to refer to the simultaneous running of bare metal, virtualised and containerised workloads.</p>
+                    <p>In conjunction with a hybrid cloud architecture, the multi-cloud approach enables organisations to optimise their infrastructure costs. Multi-cloud reflects the reality of most organisations today and is expected to become the standard for cloud infrastructure in the coming years.</p>
+                </div>
+                <hr />
+                <a href="#" class="p-button--positive">CTA up to 3 words</a>
+                <a href="#" class="p-button">Optional button</a>
+                <a href="#">Link CTA up to 5 words</a>
+                <!-- p-section spacing not needed because it's followed by suru -->
             </div>
-            <div class="p-section">
-                <p>Multi-cloud (also referred to as multi cloud or multicloud) is a concept that refers to using multiple clouds from more than one cloud service provider at the same time. The term is also used to refer to the simultaneous running of bare metal, virtualised and containerised workloads.</p>
-                <p>In conjunction with a hybrid cloud architecture, the multi-cloud approach enables organisations to optimise their infrastructure costs. Multi-cloud reflects the reality of most organisations today and is expected to become the standard for cloud infrastructure in the coming years.</p>
-            </div>
-            <hr />
-            <a href="#" class="p-button--positive">CTA up to 3 words</a>
-            <a href="#" class="p-button">Optional button</a>
-            <a href="#">Link CTA up to 5 words</a>
-            <!-- p-section spacing not needed because it's followed by suru -->
         </div>
     </div>
-    <div class="p-suru"></div>
 </section>
 
 {% endblock %}

templates/docs/examples/patterns/suru/50-50-dark.html

@@ -0,0 +1,15 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Suru / 50/50 Dark{% endblock %}
+
+{% block standalone_css %}patterns_suru{% endblock %}
+
+{% set is_dark = True %}
+{% block content %}
+<div class="p-suru--50-50">
+    <div class="row--50-50">
+        <div class="col">
+            <h1>Suru 50/50</h1>
+        </div>
+    </div>
+</div>
+{% endblock %}

templates/docs/examples/patterns/suru/50-50.html

@@ -0,0 +1,15 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Suru / 50/50{% endblock %}
+
+{% block standalone_css %}patterns_suru{% endblock %}
+
+{% set is_paper = True %}
+{% block content %}
+<div class="p-suru--50-50">
+    <div class="row--50-50">
+        <div class="col">
+            <h1>Suru 50/50</h1>
+        </div>
+    </div>
+</div>
+{% endblock %}

templates/docs/examples/patterns/suru/dark.html

@@ -3,11 +3,13 @@
 
 {% block standalone_css %}patterns_suru{% endblock %}
 
-{% block style %}
-{# default dark background on the exanple body #}
-<style>body { background: #262626; }</style>
-{% endblock %}
-
+{% set is_dark = True %}
 {% block content %}
-<div class="p-suru is-dark"></div>
-{% endblock %}
+<div class="p-suru--25-75">
+    <div class="row--25-75">
+        <div class="col">
+            <h1>Suru 25/75</h1>
+        </div>
+    </div>
+</div>
+{% endblock %}

templates/docs/examples/patterns/suru/default.html

@@ -5,5 +5,11 @@
 
 {% set is_paper = True %}
 {% block content %}
-<div class="p-suru"></div>
+<div class="p-suru--25-75">
+    <div class="row--25-75">
+        <div class="col">
+            <h1>Suru 25/75</h1>
+        </div>
+    </div>
+</div>
 {% endblock %}

templates/docs/examples/patterns/suru/standalone.html

@@ -0,0 +1,9 @@
+{% extends "_layouts/examples.html" %}
+{% block title %}Suru / Standalone{% endblock %}
+
+{% block standalone_css %}patterns_suru{% endblock %}
+
+{% set is_paper = True %}
+{% block content %}
+<div class="p-suru"></div>
+{% endblock %}

templates/docs/patterns/suru.md

@@ -8,10 +8,36 @@ The Suru component can be used to display a visual separation between two sectio
 
 By default, Suru should be used on the paper background. When used on dark background, add `is-dark` modifier class.
 
+## Main 25/75
+
+Use `.p-suru--25-75` to create a hero section with the main 25/75 Suru background. Suru component provides the necessary hero padding, background colour and the Suru image.
+
 <div class="embedded-example"><a href="/docs/examples/patterns/suru/default" class="js-example">
+View example of the main 25/75 Suru component
+</a></div>
+
+## Main 50/50
+
+Use `.p-suru--50/50` to create a hero section with the main 50/50 Suru background. Suru component provides the necessary hero padding, background colour and the Suru image.
+
+<div class="embedded-example"><a href="/docs/examples/patterns/suru/50-50" class="js-example">
+View example of the main 50/50 Suru component
+</a></div>
+
+## Standalone
+
+If needed, Suru can be used as a standalone component. This is useful when you need to create a visual separation between two sections of content.
+
+<div class="embedded-example"><a href="/docs/examples/patterns/suru/standalone" class="js-example">
 View example of the default Suru component
 </a></div>
 
+## Theming
+
+Suru component is supported in paper and dark themes. When used in light theme, the paper version of the Suru component is used.
+
+You can change the theme by setting `is-dark` or `is-paper` modifier class on the component itself, or on any parent element.
+
 <div class="embedded-example"><a href="/docs/examples/patterns/suru/dark" class="js-example">
 View example of the dark Suru component
 </a></div>