**BREAKING** Refactor organisation styles and upgrade to govuk-frontend v5.7.1

CHANGELOG.md

@@ -7,6 +7,10 @@
   useful summary for people upgrading their application, not a replication
   of the commit log.
 
+## Unreleased
+
+* Refactor organisation styles and upgrade to govuk-frontend v5.7.1 ([PR #4321](https://github.com/alphagov/govuk_publishing_components/pull/4321))
+
 ## 44.11.0
 
 * Extend chart component to allow headings to be removed from the DOM ([PR #4362](https://github.com/alphagov/govuk_publishing_components/pull/4362))

app/assets/stylesheets/govuk_publishing_components/components/_share-links.scss

@@ -150,3 +150,15 @@ $column-width: 9.5em;
     @include govuk-font(19, $weight: bold);
   }
 }
+
+.gem-c-share-links--black-icons {
+  .gem-c-share-links__link-icon {
+    color: govuk-colour("black");
+  }
+}
+
+.gem-c-share-links--black-links {
+  .gem-c-share-links__label {
+    color: govuk-colour("black");
+  }
+}

app/assets/stylesheets/govuk_publishing_components/components/helpers/_brand-colours.scss

@@ -1,21 +1,6 @@
 @mixin organisation-brand-colour {
   @each $organisation in map-keys($govuk-colours-organisations) {
     .brand--#{$organisation} {
-      .brand__color {
-        color: govuk-organisation-colour($organisation);
-
-        &:link,
-        &:visited,
-        &:active {
-          color: govuk-organisation-colour($organisation);
-        }
-
-        &:hover,
-        &:focus {
-          color: $govuk-focus-text-colour;
-        }
-      }
-
       // the & declaration allows border-color to also be applied to the parent
       // element as required by the heading component, adds 2KB to the CSS
       &.brand__border-color,
@@ -32,21 +17,6 @@
 // the "the" prefix was dropped, this is maintained here for backwards
 // compatibility
 .brand--the-office-of-the-leader-of-the-house-of-commons {
-  .brand__color {
-    color: govuk-organisation-colour("office-of-the-leader-of-the-house-of-commons");
-
-    &:link,
-    &:visited,
-    &:active {
-      color: govuk-organisation-colour("office-of-the-leader-of-the-house-of-commons");
-    }
-
-    &:hover,
-    &:focus {
-      color: $govuk-focus-text-colour;
-    }
-  }
-
   &.brand__border-color,
   .brand__border-color {
     border-color: govuk-organisation-colour("office-of-the-leader-of-the-house-of-commons", $contrast-safe: false);
@@ -88,11 +58,9 @@
   }
 }
 
-// new colour for DSIT for use until govuk-frontend#3523 has been released
-
 .brand--department-for-science-innovation-and-technology {
   &.brand__border-color,
   .brand__border-color {
-    border-color: #045f71;
+    border-color: govuk-organisation-colour("department-for-science-innovation-technology", $contrast-safe: false);
   }
 }

app/views/govuk_publishing_components/components/_share_links.html.erb

@@ -11,16 +11,16 @@
   flexbox ||= false
   square_icons ||= false
 
-  brand ||= false
-  brand_helper = GovukPublishingComponents::AppHelpers::BrandHelper.new(brand)
+  black_icons ||= false
+  black_links ||= false
 
   classes = %w(gem-c-share-links govuk-!-display-none-print)
   classes << "gem-c-share-links--stacked" if stacked
   classes << "gem-c-share-links--columns" if columns
   classes << "gem-c-share-links--flexbox" if flexbox
   classes << "gem-c-share-links--square-icons" if square_icons
-
-  classes << brand_helper.brand_class
+  classes << "gem-c-share-links--black-icons" if black_icons
+  classes << "gem-c-share-links--black-links" if black_links
 
   data_attributes ||= {}
   ((data_attributes[:module] ||= "") << " " << "ga4-link-tracker").strip! if track_as_sharing || track_as_follow
@@ -76,7 +76,7 @@
             target: "_blank",
             rel: "noopener noreferrer external",
             data: data_attributes,
-            class: "govuk-link govuk-link--no-underline gem-c-share-links__link #{brand_helper.color_class}" do %>
+            class: "govuk-link govuk-link--no-underline gem-c-share-links__link" do %>
             <span class="gem-c-share-links__link-icon">
               <% if link[:icon] == 'facebook' %>
                 <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" width="0" height="0" class="gem-c-share-links__svg">

app/views/govuk_publishing_components/components/docs/contents_list.yml

@@ -190,10 +190,10 @@ examples:
               text: "تقديم الطلب"
     context:
       right_to_left: true
-  with_branding:
-    description: Where this component could be used on an organisation page (such as the [Attorney General's Office](https://www.gov.uk/government/organisations/attorney-generals-office)) branding can be applied for link colours and border colours. See the [branding documentation](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) for more details.
+  with_number_10_branding:
+    description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
     data:
-      brand: 'department-for-environment-food-rural-affairs'
+      brand: 'prime-ministers-office-10-downing-street'
       format_numbers: true
       contents:
         - href: "#first-thing"

app/views/govuk_publishing_components/components/docs/document_list.yml

@@ -130,10 +130,10 @@ examples:
         metadata:
           public_updated_at: 2017-07-19 15:01:48
           document_type: 'Statutory guidance'
-  with_branding:
-    description: Where this component could be used on an organisation page (such as the [Attorney General's Office](https://www.gov.uk/government/organisations/attorney-generals-office)) branding can be applied for link colours and border colours. See the [branding documentation](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) for more details.
+  with_number_10_branding:
+    description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
     data:
-      brand: 'attorney-generals-office'
+      brand: 'prime-ministers-office-10-downing-street'
       items:
       - link:
           text: 'School behaviour and attendance: parental responsibility measures'

app/views/govuk_publishing_components/components/docs/image_card.yml

@@ -172,10 +172,10 @@ examples:
       href: '/no-valid-links-here'
       heading_text: 'John McJohnson'
       description: 'Deputy director for Parks and Small Trees'
-  with_branding:
+  with_number_10_branding:
     description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
     data:
-      brand: "department-for-work-pensions"
+      brand: 'prime-ministers-office-10-downing-street'
       href: "/again-not-a-page"
       image_src: "https://assets.publishing.service.gov.uk/government/uploads/system/uploads/feature/image/62756/s300_courts-of-justice.JPG"
       image_alt: "some meaningful alt text please"

app/views/govuk_publishing_components/components/docs/share_links.yml

@@ -80,10 +80,20 @@ examples:
           icon: 'facebook'
         }
       ]
-  with_branding:
-    description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
+  with_black_icons:
     data:
-      brand: 'attorney-generals-office'
+      black_icons: true
+      links: [
+        {
+          href: 'share',
+          text: 'Follow the Attorney General on Twitter',
+          hidden_text: '',
+          icon: 'twitter'
+        }
+      ]
+  with_black_links:
+    data:
+      black_links: true
       links: [
         {
           href: 'share',
@@ -208,7 +218,6 @@ examples:
   with_all_icons:
     data:
       stacked: true
-      brand: 'hm-treasury'
       links: [
         {
           href: '/facebook-share-link',

app/views/govuk_publishing_components/components/docs/subscription_links.yml

@@ -45,10 +45,10 @@ examples:
     data:
       email_signup_link: '/foreign-travel-advice/singapore/email-signup'
       feed_link_box_value: 'https://www.gov.uk/government/organisations/attorney-generals-office.atom'
-  with_branding:
+  with_number_10_branding:
     description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
     data:
-      brand: 'attorney-generals-office'
+      brand: 'prime-ministers-office-10-downing-street'
       email_signup_link: '/foreign-travel-advice/singapore/email-signup'
       feed_link: '/foreign-travel-advice/singapore.atom'
   with_data_attributes_on_links:

app/views/govuk_publishing_components/components/docs/translation_nav.yml

@@ -61,10 +61,10 @@ examples:
           active: true
     context:
       right_to_left: true
-  with_branding:
+  with_number_10_branding:
     description: Organisation [colour branding](https://github.com/alphagov/govuk_publishing_components/blob/main/docs/component_branding.md) can be added to the component as shown.
     data:
-      brand: 'wales-office'
+      brand: 'prime-ministers-office-10-downing-street'
       translations:
       - locale: 'en'
         base_path: '/en'

docs/component_branding.md

@@ -2,15 +2,19 @@
 
 ## Overview
 
-Organisation pages in whitehall ([example](https://www.gov.uk/government/organisations/attorney-generals-office)) have department-specific branding on them. This includes specific colours for links and borders. These pages are being migrated out of whitehall and will use components for their frontend, which means some components need a sensible way of displaying these colours.
+Organisation pages in `collections` have some department-specific branding on them. Custom border colours are used on all organisation pages ([example](https://www.gov.uk/government/organisations/attorney-generals-office)), and custom colours for links are used on [Prime Minister's Office, 10 Downing Street](https://www.gov.uk/government/organisations/prime-ministers-office-10-downing-street).
+
+[Most colours now come from govuk-frontend](https://github.com/alphagov/govuk-frontend/blob/main/packages/govuk-frontend/src/govuk/settings/_colours-organisations.scss), however custom colours can be added to [_brand_colours.scss](https://github.com/alphagov/govuk_publishing_components/blob/main/app/assets/stylesheets/govuk_publishing_components/components/helpers/_brand-colours.scss) if required.
 
 This work follows [this RFC](https://github.com/alphagov/govuk_publishing_components/pull/287) to discuss the approach taken.
 
+**Note: as of October 2024, the use of brand colours for styling was reduced to just borders and accents for most organisations. Brand colours should not be added to text or links, except for in specific agreed circumstances. Text and links should ideally always use our default styles for accessibility and to ensure that the user journey across GOV.UK is consistent from a design perspective.**
+
 ## Adding to a component
 
 To add colours to a component, modify the component to follow the example below.
 
-```
+```erb
 <%
   brand ||= false
   brand_helper = GovukPublishingComponents::AppHelpers::BrandHelper.new(brand)
@@ -22,12 +26,43 @@ To add colours to a component, modify the component to follow the example below.
   </div>
 
   <a href="#" class="<%= brand_helper.color_class %>">
-    Example element that requires coloured text
+    Rare use case where a link requires coloured text
   </a>
 </div>
 ```
 
-Note that the helper must be called for each element that needs a border or link colour applying. This allows for flexibility if one is required but not the other.
+The above will style borders with colours from the design system automatically, as we have a SASS mixin for this in `_brand_colours.scss` that will map the class to its colour in the design system.
+
+If your use case fits one of these scenarios:
+- you need to use `brand_helper.color_class`
+- a new brand name or colour outside of the design system needs to be used
+- styles other than the border colour are needed
+
+Then a new class in `_brand_colours.scss` will need to be created, that is namespaced to the brand name:
+
+```scss
+.brand--your-brand-name-here {
+  .brand__color {
+    &:link,
+    &:visited,
+    &:active {
+      color: govuk-colour("black"); // link colours ideally shouldn't be changed, so this is only shown here for demonstration purposes.
+    }
+
+    &:hover,
+    &:focus {
+      color: $govuk-focus-text-colour;
+    }
+  }
+
+  &.brand__border-color,
+  .brand__border-color {
+    border-color: govuk-colour("black"); // your border colour here
+  }
+}
+```
+
+Note that the helper must be called for each element that needs a border or other brand-specific colour applied. This allows for flexibility if one is required but not the other.
 
 The `border_color_class` method/class can also be applied to the main element of a component if needed, for example where the component is only one element. This is currently not possible with `color_class` as there is no requirement for this.
 
@@ -49,6 +84,6 @@ The component can then be passed a string matching the required brand, for examp
 
 ```
 <%= render "govuk_publishing_components/components/example-component", {
-  brand: 'attorney-generals-office'
+  brand: 'prime-ministers-office-10-downing-street'
 } %>
 ```

package.json

@@ -38,7 +38,7 @@
     "accessible-autocomplete": "^3.0.1",
     "axe-core": "^4.10.1",
     "chartkick": "^5.0.1",
-    "govuk-frontend": "5.7.0",
+    "govuk-frontend": "5.7.1",
     "govuk-single-consent": "^3.0.9",
     "sortablejs": "^1.15.3"
   },

spec/components/share_links_spec.rb

@@ -100,9 +100,24 @@ def links
     assert_select '.gem-c-share-links__link[data-ga4-link="{\"event_name\":\"navigation\",\"type\":\"overwritten type 2\",\"index_link\":1,\"index_total\":1,\"section\":\"This is another section\"}"]'
   end
 
-  it "adds branding correctly" do
-    render_component(links: [links[0]], brand: "attorney-generals-office")
-    assert_select ".gem-c-share-links.brand--attorney-generals-office .gem-c-share-links__link.brand__color"
+  it "adds black links correctly" do
+    render_component(links: [links[0]], black_links: true)
+    assert_select ".gem-c-share-links.gem-c-share-links--black-links"
+  end
+
+  it "has no black links by default" do
+    render_component(links: [links[0]])
+    assert_select ".gem-c-share-links.gem-c-share-links--black-links", false
+  end
+
+  it "adds black icons correctly" do
+    render_component(links: [links[0]], black_icons: true)
+    assert_select ".gem-c-share-links.gem-c-share-links--black-icons"
+  end
+
+  it "has no black icons by default" do
+    render_component(links: [links[0]])
+    assert_select ".gem-c-share-links.gem-c-share-links--black-icons", false
   end
 
   it "arranges in columns" do

yarn.lock

@@ -1443,10 +1443,10 @@ gopd@^1.0.1:
   dependencies:
     get-intrinsic "^1.1.3"
 
-[email protected].0:
-  version "5.7.0"
-  resolved "https://registry.yarnpkg.com/govuk-frontend/-/govuk-frontend-5.7.0.tgz#e6cd1bbb8dce25f86391b1f8d26bed95dabfbb75"
-  integrity sha512-kAaJbOCAJMYT30UN7rVHIWzQUvNjFq5Mw+FSIH2SM6xuCdCwyUcl+WYqxvYRqltWh6ZuAlzND0Rxr61lUoCGJA==
+[email protected].1:
+  version "5.7.1"
+  resolved "https://registry.yarnpkg.com/govuk-frontend/-/govuk-frontend-5.7.1.tgz#d4c561ebf8c0b76130f31df8c2e4d70d340cd63f"
+  integrity sha512-jF1cq5rn57kxZmJRprUZhTQ31zaBBK4b5AyeJaPX3Yhg22lk90Mx/dQLvOk/ycV3wM7e0y+s4IPvb2fFaPlCGg==
 
 govuk-single-consent@^3.0.9:
   version "3.0.9"
@@ -2917,16 +2917,7 @@ [email protected]:
   resolved "https://registry.yarnpkg.com/statuses/-/statuses-2.0.1.tgz#55cb000ccf1d48728bd23c685a063998cf1a1b63"
   integrity sha512-RwNA9Z/7PrK06rYLIzFMlaF+l73iwpzsqRIFgbMLbTcLD6cOao82TaWefPXQvB2fOC4AjuYSEndS7N/mTCbkdQ==
 
-"string-width-cjs@npm:string-width@^4.2.0":
-  version "4.2.3"
-  resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
-  integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==
-  dependencies:
-    emoji-regex "^8.0.0"
-    is-fullwidth-code-point "^3.0.0"
-    strip-ansi "^6.0.1"
-
-[email protected], string-width@^4.1.0, string-width@^4.2.3:
+"string-width-cjs@npm:string-width@^4.2.0", [email protected], string-width@^4.1.0, string-width@^4.2.3:
   version "4.2.3"
   resolved "https://registry.yarnpkg.com/string-width/-/string-width-4.2.3.tgz#269c7117d27b05ad2e536830a8ec895ef9c6d010"
   integrity sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==
@@ -2989,14 +2980,7 @@ string_decoder@~1.1.1:
   dependencies:
     safe-buffer "~5.1.0"
 
-"strip-ansi-cjs@npm:strip-ansi@^6.0.1":
-  version "6.0.1"
-  resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9"
-  integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==
-  dependencies:
-    ansi-regex "^5.0.1"
-
-[email protected], strip-ansi@^6.0.0, strip-ansi@^6.0.1:
+"strip-ansi-cjs@npm:strip-ansi@^6.0.1", [email protected], strip-ansi@^6.0.0, strip-ansi@^6.0.1:
   version "6.0.1"
   resolved "https://registry.yarnpkg.com/strip-ansi/-/strip-ansi-6.0.1.tgz#9e26c63d30f53443e9489495b2105d37b67a85d9"
   integrity sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==