Merge pull request #4625 from alphagov/bk-presenting-branded-examples

Add callout macro

Author: domoscargin

src/components/cookie-banner/index.md

@@ -8,22 +8,23 @@ layout: layout-pane.njk
 ---
 
 {% from "_example.njk" import example %}
-{% from "_brand-callout.njk" import brandCallout %}
+{% from "_callout.njk" import callout %}
 
 Allow users to accept or reject cookies which are not essential to making your service work.
 
 {{ example({ group: "components", item: "cookie-banner", example: "default", html: true, nunjucks: true, open: false, loading: "eager" }) }}
 
-<strong class="govuk-tag brand-tag-green">
-  Brand
-</strong>
+{% call callout({ tagText: "Brand", colour: "green" }) %}
+
 <p class="govuk-body"><a href="#">See an example of the Cookie banner showing the refreshed GOV.UK branding</a>.</p>
 
+{% endcall %}
+
 If you use the page template, you'll also get the Cookie banner without having to add it, as it's included by default. However, if you want to customise the default Cookie banner, read the [page template guidance about customising components](/styles/page-template/#changing-template-content).
 
-{% call brandCallout({ text: "Brand", classes: "brand-tag-green" }) %}
+{% call callout({ tagText: "Brand", colour: "green", isInset: "true" }) %}
 
-<h2>Brand changes to the {{title}} component</h2>
+<h2 class="app-callout__heading">Brand changes to the {{title}} component</h2>
 <p class="govuk-body">From 25 June 2025, the {{title}} component will change to support a wider refresh of the GOV.UK brand. </p>
 
 <p class="govuk-body">The Cookie banner component’s background colour will change to light blue.</p>

src/components/footer/index.md

@@ -8,23 +8,24 @@ layout: layout-pane.njk
 ---
 
 {% from "_example.njk" import example %}
-{% from "_brand-callout.njk" import brandCallout %}
+{% from "_callout.njk" import callout %}
 {%- from "govuk/components/tag/macro.njk" import govukTag -%}
 
 The GOV.UK footer provides copyright, licensing and other information about your service.
 
 {{ example({ group: "components", item: "footer", example: "default", id: "default-1", html: true, nunjucks: true, open: false, size: "m", loading: "eager" }) }}
 
-<strong class="govuk-tag brand-tag-green">
-  Brand
-</strong>
+{% call callout({ tagText: "Brand", colour: "green" }) %}
+
 <p class="govuk-body"><a href="#">See an example of the GOV.UK footer showing the refreshed GOV.UK branding</a>.</p>
 
+{% endcall %}
+
 If you use the page template, you'll also get the footer without having to add it, as it's included by default. However, if you want to customise the default footer, read the [page template guidance about customising components](/styles/page-template/#changing-template-content).
 
-{% call brandCallout({ text: "Brand", classes: "brand-tag-green" }) %}
+{% call callout({ tagText: "Brand", colour: "green", isInset: "true" }) %}
 
-<h2>Brand changes to the {{title}} component</h2><p class="govuk-body">From 25 June 2025, the {{title}} component will change to support a wider refresh of the GOV.UK brand.</p>
+<h2 class="app-callout__heading">Brand changes to the {{title}} component</h2><p class="govuk-body">From 25 June 2025, the {{title}} component will change to support a wider refresh of the GOV.UK brand.</p>
 
 <p class="govuk-body">The updated {{title}} component:</p>
 <ul class="govuk-list">
@@ -48,7 +49,7 @@ Make it clear whether content is available for re-use - and if it is, under what
 ### Update to refresh the GOV.UK brand
 
 <strong class="govuk-tag brand-tag-green">
-  Brand
+  Brand<span class="govuk-visually-hidden"> note</span>
 </strong>
 
 If you use the Nunjucks macro and page template across your service, you can enable the brand refresh by setting the page template’s `rebrand` option to `true`. This will automatically make all needed changes related to the brand refresh.

src/components/header/index.md

@@ -8,22 +8,22 @@ layout: layout-pane.njk
 ---
 
 {% from "_example.njk" import example %}
-{% from "_brand-callout.njk" import brandCallout %}
+{% from "_callout.njk" import callout %}
 
 The GOV.UK header component tells users they’re using a service on GOV.UK and lets them use GOV.UK-wide tools. Also known as the GOV.UK masthead.
 
 {{ example({ group: "components", item: "header", example: "default", id: "default-1", html: true, nunjucks: true, open: false, loading: "eager" }) }}
 
-<strong class="govuk-tag brand-tag-green">
-  Brand
-</strong>
+{% call callout({ tagText: "Brand", colour: "green" }) %}
+
 <p class="govuk-body"><a href="#">See an example of the GOV.UK header showing the refreshed GOV.UK branding</a>.</p>
+{% endcall %}
 
 If you use the page template, you'll also get the GOV.UK header without having to add it, as it's included by default. However, if you want to customise the default GOV.UK header, read the [page template guidance about customising components](/styles/page-template/#changing-template-content).
 
-{% call brandCallout({ text: "Brand", classes: "brand-tag-green" }) %}
+{% call callout({ tagText: "Brand", colour: "green", isInset: "true" }) %}
 
-<h2>Brand changes to the {{title}} component</h2>
+<h2 class="app-callout__heading">Brand changes to the {{title}} component</h2>
 <p class="govuk-body">From 25 June 2025, the {{title}} component will change to support a wider refresh of the GOV.UK brand. </p>
 
 <p class="govuk-body">The updated {{title}} component:</p>
@@ -64,7 +64,7 @@ For guidance on how to plan your header and navigation, see the [Help users navi
 ### Update to refresh the GOV.UK brand
 
 <strong class="govuk-tag brand-tag-green">
-  Brand
+  Brand<span class="govuk-visually-hidden"> note</span>
 </strong>
 
 If you use the Nunjucks macro and page template across your service, you can enable the brand refresh by setting the page template’s `rebrand` option to `true`. This will automatically make all needed changes related to the brand refresh.

src/components/service-navigation/index.md

@@ -8,14 +8,14 @@ layout: layout-pane.njk
 ---
 
 {% from "_example.njk" import example %}
-{% from "_brand-callout.njk" import brandCallout %}
+{% from "_callout.njk" import callout %}
 {% from "govuk/components/inset-text/macro.njk" import govukInsetText %}
 
 Service navigation helps users understand that they’re using your service and lets them navigate around your service.
 
-{% call brandCallout({ text: "Brand", classes: "brand-tag-green" }) %}
+{% call callout({ tagText: "Brand", colour: "green", isInset: "true" }) %}
 
-<h2>Brand changes to the {{title}} component</h2><p class="govuk-body">From 25 June 2025, the {{title}} component will change to support a wider refresh of the GOV.UK brand.</p>
+<h2 class="app-callout__heading">Brand changes to the {{title}} component</h2><p class="govuk-body">From 25 June 2025, the {{title}} component will change to support a wider refresh of the GOV.UK brand.</p>
 
 <p class="govuk-body">The updated {{title}} component:</p>
 <ul class="govuk-list">
@@ -27,11 +27,12 @@ Service navigation helps users understand that they’re using your service and
 
 {{ example({ group: "components", item: "service-navigation", example: "default", html: true, nunjucks: true, open: false, loading: "eager" }) }}
 
-<strong class="govuk-tag brand-tag-green">
-  Brand
-</strong>
+{% call callout({ tagText: "Brand", colour: "green" }) %}
+
 <p class="govuk-body"><a href="#">See an example of the Service navigation showing the refreshed GOV.UK branding</a>.</p>
 
+{% endcall %}
+
 If you use the page template, you'll also get the Service navigation without having to add it, as it's included by default. However, if you want to customise the default Service navigation, read the [page template guidance about customising components](/styles/page-template/#changing-template-content).
 
 ## When to use this component
@@ -51,7 +52,7 @@ For guidance on how to plan your header and navigation, see the [Help users navi
 ### Update to refresh the GOV.UK brand
 
 <strong class="govuk-tag brand-tag-green">
-  Brand
+  Brand<span class="govuk-visually-hidden"> note</span>
 </strong>
 
 If you use the Nunjucks macro and page template across your service, you can enable the brand refresh by setting the page template’s `rebrand` option to `true`. This will automatically make all needed changes related to the brand refresh.
@@ -67,7 +68,7 @@ Apply a class `govuk-header--full-width-border` to the GOV.UK header.
 {{ example({ group: "components", item: "service-navigation", example: "with-govuk-header", html: true, nunjucks: true, open: false }) }}
 
 <strong class="govuk-tag brand-tag-green">
-  Brand
+  Brand<span class="govuk-visually-hidden"> note</span>
 </strong>
 
 You do not need to change the bottom border of the updated GOV.UK header component with the refreshed GOV.UK branding.

src/stylesheets/components/_callout.scss

@@ -0,0 +1,47 @@
+// Change callout <h2>'s to look like <h3>'s
+// Selector specificity needs to outweigh `.app-content h2`
+.app-callout {
+  .app-callout__heading {
+    @extend %govuk-heading-m;
+    max-width: 30em;
+  }
+
+  // Add highlight styling for callout content
+  &:target {
+    outline-offset: 6px;
+    outline-style: solid;
+    outline-width: 4px;
+  }
+}
+
+.app-callout__tag {
+  margin-top: 1px;
+  margin-top: govuk-spacing(2);
+  margin-bottom: govuk-spacing(1);
+}
+
+.app-callout--blue {
+  border-left-color: govuk-colour("blue");
+
+  .app-callout__tag {
+    color: #0f385c;
+    background-color: #d2e2f1;
+  }
+
+  &:target {
+    outline-color: govuk-colour("blue");
+  }
+}
+
+.app-callout--green {
+  border-left-color: #11875a;
+
+  &:target {
+    outline-color: govuk-colour("green");
+  }
+
+  .app-callout__tag {
+    color: #09442d;
+    background-color: #cfe7de;
+  }
+}

src/stylesheets/main.scss

@@ -46,6 +46,7 @@ $app-code-color: #d13118;
 
 // App-specific components
 @import "components/back-to-top";
+@import "components/callout";
 @import "components/category-nav";
 @import "components/contact-panel";
 @import "components/cookies-page";
@@ -414,22 +415,6 @@ pre .language-plaintext {
   background-color: $app-light-grey;
 }
 
-.app-wcag-callout {
-  border-left-color: govuk-colour("blue");
-}
-
-// Change headings in WCAG callouts to look like H3s,
-// even though they semantically are H2s
-.app-wcag-callout h2 {
-  @extend %govuk-heading-m;
-  max-width: 30em;
-}
-
-.app-wcag-callout__tag {
-  margin-top: 1px;
-  margin-bottom: govuk-spacing(2);
-}
-
 .app-wcag-note {
   margin-top: govuk-spacing(6);
 
@@ -443,28 +428,3 @@ pre .language-plaintext {
 .app-campaign-cookie-banner .govuk-grid-column-two-thirds {
   width: 100%;
 }
-
-.brand-tag-blue {
-  margin-top: govuk-spacing(2);
-  margin-bottom: govuk-spacing(1);
-  color: #0f385c;
-  background-color: #d2e2f1;
-}
-
-.brand-tag-green {
-  margin-top: govuk-spacing(2);
-  margin-bottom: govuk-spacing(1);
-  color: #09442d;
-  background-color: #cfe7de;
-}
-
-.app-brand-callout {
-  border-left-color: #11875a;
-}
-
-// Change headings in WCAG callouts to look like H3s,
-// even though they semantically are H2s
-.app-brand-callout h2 {
-  @extend %govuk-heading-m;
-  max-width: 30em;
-}

views/partials/_brand-callout.njk

@@ -0,0 +1,26 @@
+{% from "govuk/components/inset-text/macro.njk" import govukInsetText -%}
+{% from "govuk/components/tag/macro.njk" import govukTag -%}
+
+{% macro callout(params) -%}
+  {% set calloutContent -%}
+    {{ govukTag({
+      html: params.tagText + '<span class="govuk-visually-hidden"> note</span>',
+      classes: "app-callout__tag"
+    }) }}
+    {% if params.heading -%}
+      <h2 class="app-callout__heading">{{ params.heading }}</h2>
+    {% endif -%}
+    {{ caller() if caller else params.content | safe }}
+  {% endset -%}
+
+  {% if params.isInset === "true" -%}
+    {{ govukInsetText({
+      id: params.id if params.id,
+      html: calloutContent,
+      classes: "app-callout app-callout--" + params.colour
+    }) }}
+  {% else -%}
+    <div {% if params.id %}{{ params.id }} {% endif %}class="app-callout app-callout--{{params.colour}}" role="note">{{ calloutContent | trim | safe }}</div>
+  {% endif -%}
+
+{% endmacro %}

views/partials/_callout.njk

@@ -5,7 +5,7 @@
 {% set tagContent -%}
   {{- govukTag({
     text: "WCAG 2.2",
-    classes: "app-wcag-callout__tag"
+    classes: "app-callout__tag"
   }) }}
   <h2>
     {{ params.heading if params.heading else "New WCAG 2.2 criteria affect this " + params.type }}
@@ -25,6 +25,6 @@
 
 {{ govukInsetText({
   html: tagContent,
-  classes: "app-wcag-callout"
+  classes: "app-callout app-callout--blue"
 }) }}
 {% endmacro %}

views/partials/_wcag-callout.njk

@@ -4,7 +4,7 @@
 <div class="app-wcag-note" id="{{params.id}}" role="note">
   {{ govukTag({
     text: "WCAG 2.2",
-    classes: "app-wcag-callout__tag"
+    classes: "app-callout__tag"
   }) }}
   {{ caller() if caller else params.content | safe }}
 </div>