Update organisation colours

CHANGELOG.md

@@ -6,6 +6,28 @@ For advice on how to use these release notes see [our guidance on staying up to
 
 ### New features
 
+#### We've updated the list of organisations and brand colours included in Frontend
+
+We've overhauled the list of organisations and organisation brand colours that are shipped with GOV.UK Frontend.
+
+The previous list was outdated and had not kept up with changes to the machinery of government. We have updated the list to:
+
+- add all current government departments and their brand colours
+- add variants of brand colours that meet a 4.5:1 contrast ratio against white, where required
+- provide warnings if defunct organisations are still being referenced in your Sass code
+
+To enable these changes, set the feature flag variable `$govuk-new-organisation-colours` to `true` before you import GOV.UK Frontend in your Sass files:
+
+```scss
+// application.scss
+$govuk-new-organisation-colours: true;
+@import "govuk-frontend/all";
+```
+
+You can also silence warnings about defunct organisations by adding `organisation-colours` to the [`$govuk-suppressed-warnings`](https://frontend.design-system.service.gov.uk/sass-api-reference/#govuk-suppressed-warnings) setting.
+
+This change was introduced in [pull request #3407: Update organisation colours](https://github.com/alphagov/govuk-frontend/pull/3407).
+
 #### Stop long words breaking out of components with `govuk-!-text-break-word`
 
 We've added a new override class to help display long or unpredictable words on narrow screens, such as an email address entered by a user.
@@ -20,6 +42,18 @@ Sass users can also use the `govuk-text-break-word` mixin.
 
 This change was introduced in [pull request #5159: Add break-word typography helper](https://github.com/alphagov/govuk-frontend/pull/5159).
 
+### Recommended changes
+
+#### Update the `$websafe` parameter on the `govuk-organisation-colour` function
+
+The `govuk-organisation-colour` Sass function's `$websafe` parameter on has been renamed to `$contrast-safe`.
+
+This is to more accurately describe the functionality of the parameter.
+
+The old parameter name will stop working in the next major version of GOV.UK Frontend.
+
+This change was introduced in [pull request #3407: Update organisation colours](https://github.com/alphagov/govuk-frontend/pull/3407).
+
 ### Fixes
 
 We've made fixes to GOV.UK Frontend in the following pull requests:

packages/govuk-frontend-review/src/stylesheets/app.scss

@@ -1,8 +1,12 @@
 $govuk-show-breakpoints: true;
 $govuk-new-typography-scale: true;
+$govuk-new-organisation-colours: true;
+
+$govuk-suppressed-warnings: ("organisation-colours");
 
 @import "govuk/all";
 @import "partials/app";
 @import "partials/code";
 @import "partials/banner";
+@import "partials/organisation-swatch";
 @import "partials/prose";

packages/govuk-frontend-review/src/stylesheets/partials/_organisation-swatch.scss

@@ -0,0 +1,18 @@
+.app-organisation-swatch {
+  padding-left: govuk-spacing(3);
+  border-left: 6px solid #777777;
+
+  h2 {
+    color: #777777;
+  }
+}
+
+@each $key, $map in $govuk-colours-organisations {
+  .app-organisation-swatch--#{$key} {
+    border-left-color: govuk-organisation-colour($key, $contrast-safe: false);
+
+    h2 {
+      color: govuk-organisation-colour($key);
+    }
+  }
+}

packages/govuk-frontend-review/src/views/examples/organisation-colours/index.njk

@@ -0,0 +1,210 @@
+{% from "govuk/components/back-link/macro.njk" import govukBackLink %}
+
+{% extends "layouts/examples.njk" %}
+
+{% block beforeContent %}
+  {{ govukBackLink({
+    href: "/"
+  }) }}
+{% endblock %}
+
+{% set organisations = {
+  "attorney-generals-office": {
+    "name": "Attorney General's Office",
+    "start": 1315
+  },
+  "cabinet-office": {
+    "name": "Cabinet Office",
+    "start": 1916
+  },
+  "civil-service": {
+    "name": "Civil Service"
+  },
+  "department-for-business-trade": {
+    "name": "Department for Business and Trade",
+    "start": 2023
+  },
+  "department-for-business-energy-industrial-strategy": {
+    "name": "Department for Business, Energy and Industrial Strategy",
+    "start": 2016,
+    "end": 2023
+  },
+  "department-for-business-innovation-skills": {
+    "name": "Department for Business, Innovation and Skills",
+    "start": 2009,
+    "end": 2016
+  },
+  "department-for-communities-local-government": {
+    "name": "Department for Communities and Local Government",
+    "start": 2006,
+    "end": 2018
+  },
+  "department-for-culture-media-sport": {
+    "name": "Department for Culture, Media and Sport",
+    "start": 1997
+  },
+  "department-for-digital-culture-media-sport": {
+    "name": "Department for Digital, Culture, Media and Sport",
+    "start": 2017,
+    "end": 2023
+  },
+  "department-for-education": {
+    "name": "Department for Education",
+    "start": 2010
+  },
+  "department-for-energy-security-net-zero": {
+    "name": "Department for Energy Security and Net Zero",
+    "start": 2023
+  },
+  "department-for-environment-food-rural-affairs": {
+    "name": "Department for Environment, Food and Rural Affairs",
+    "start": 2001
+  },
+  "department-for-exiting-the-european-union": {
+    "name": "Department for Exiting the European Union",
+    "start": 2016,
+    "end": 2020
+  },
+  "department-for-international-development": {
+    "name": "Department for International Development",
+    "start": 1997,
+    "end": 2020
+  },
+  "department-for-international-trade": {
+    "name": "Department for International Trade",
+    "start": 2016,
+    "end": 2023
+  },
+  "department-for-levelling-up-housing-communities": {
+    "name": "Department for Levelling Up, Housing and Communities",
+    "start": 2021,
+    "end": 2024
+  },
+  "department-for-science-innovation-technology": {
+    "name": "Department for Science, Innovation and Technology",
+    "start": 2023
+  },
+  "department-for-transport": {
+    "name": "Department for Transport",
+    "start": 2002
+  },
+  "department-for-work-pensions": {
+    "name": "Department for Work and Pensions",
+    "start": 2001
+  },
+  "department-of-energy-climate-change": {
+    "name": "Department of Energy and Climate Change",
+    "start": 2008,
+    "end": 2016
+  },
+  "department-of-health": {
+    "name": "Department of Health",
+    "start": 1988,
+    "end": 2018
+  },
+  "department-of-health-social-care": {
+    "name": "Department of Health and Social Care",
+    "start": 2018
+  },
+  "foreign-commonwealth-office": {
+    "name": "Foreign and Commonwealth Office",
+    "start": 1968,
+    "end": 2020
+  },
+  "foreign-commonwealth-development-office": {
+    "name": "Foreign, Commonwealth and Development Office",
+    "start": 2020
+  },
+  "hm-government": {
+    "name": "HM Government",
+    "start": 1707
+  },
+  "hm-revenue-customs": {
+    "name": "HM Revenue and Customs",
+    "start": 2005
+  },
+  "hm-treasury": {
+    "name": "HM Treasury"
+  },
+  "home-office": {
+    "name": "Home Office",
+    "start": 1782
+  },
+  "ministry-of-defence": {
+    "name": "Ministry of Defence",
+    "start": 1964
+  },
+  "ministry-of-housing-communities-local-government": {
+    "name": "Ministry of Housing, Communities and Local Government",
+    "start": 2018
+  },
+  "ministry-of-justice": {
+    "name": "Ministry of Justice",
+    "start": 2007
+  },
+  "northern-ireland-office": {
+    "name": "Northern Ireland Office",
+    "start": 1972
+  },
+  "office-of-the-advocate-general-for-scotland": {
+    "name": "Office of the Advocate General for Scotland",
+    "start": 1999
+  },
+  "office-of-the-leader-of-the-house-of-commons": {
+    "name": "Office of the Leader of the House of Commons",
+    "start": 1721
+  },
+  "office-of-the-leader-of-the-house-of-lords": {
+    "name": "Office of the Leader of the House of Lords",
+    "start": 1721
+  },
+  "office-of-the-secretary-of-state-for-scotland": {
+    "name": "Office of the Secretary of State for Scotland",
+    "start": 2018
+  },
+  "office-of-the-secretary-of-state-for-wales": {
+    "name": "Office of the Secretary of State for Wales",
+    "start": 2018
+  },
+  "prime-ministers-office-10-downing-street": {
+    "name": "Prime Minister's Office, 10 Downing Street",
+    "start": 2022
+  },
+  "scotland-office": {
+    "name": "Scotland Office",
+    "start": 1999,
+    "end": 2018
+  },
+  "uk-export-finance": {
+    "name": "UK Export Finance",
+    "start": 1919
+  },
+  "uk-trade-investment": {
+    "name": "UK Trade and Investment",
+    "start": 2003,
+    "end": 2016
+  },
+  "wales-office": {
+    "name": "Wales Office",
+    "start": 1999,
+    "end": 2018
+  }
+} %}
+
+{% block content %}
+  <div class="govuk-grid-row">
+    <div class="govuk-grid-column-two-thirds">
+      <h1 class="govuk-heading-xl">
+        Organisation colours
+      </h1>
+      <p class="govuk-body">Only includes organisations and departments that existed from 2010 onwards.</p>
+
+      {%- for key, data in organisations %}
+        <div class="app-organisation-swatch app-organisation-swatch--{{ key }}">
+          <h2 class="govuk-heading-s">{{ data.name }}</h2>
+          <p class="govuk-body">{{ data.start | default("????") }}&ndash;{{ data.end }}</p>
+        </div>
+      {%- endfor %}
+    </div>
+  </div>
+{% endblock %}

packages/govuk-frontend/src/govuk/helpers/_colour.scss

@@ -42,25 +42,61 @@
 /// Get the colour for a government organisation
 ///
 /// @param {String} $organisation - Organisation name, lowercase, hyphenated
-/// @param {Boolean} $websafe [true] - By default a 'websafe' version of the
-///   colour will be returned which meets contrast requirements . If you want to
-///   use the non-websafe version you can set this to `false` but your should
-///   ensure that you still meets contrast requirements for accessibility - for
-///   example, do not use the non-websafe version for text.
+/// @param {Boolean} $websafe - Deprecated. Use $contrast-safe instead.
+/// @param {Boolean} $contrast-safe [true] - By default a version of the colour
+///   will be returned which has a minimum 4.5:1 contrast ratio when used with
+///   white, as per the WCAG 2.1 Level AA guidelines. If you want to use the
+///   non-contrast safe version you can set this to `false` but your should
+///   ensure that you still meets contrast requirements for accessibility -
+///   for example, do not use the non-contrast safe version for text.
 ///
 /// @return {Colour} Representation of colour for organisation
 /// @throw if `$organisation` is not a known organisation
 /// @access public
 
-@function govuk-organisation-colour($organisation, $websafe: true) {
+@function govuk-organisation-colour($organisation, $websafe: null, $contrast-safe: true) {
+  // Check if the $organisation exists in the aliases map. If so, change the
+  // value of $organisation to the aliased value.
+  @if map-has-key($_govuk_colours-organisations-aliases, $organisation) {
+    $organisation: map-get($_govuk_colours-organisations-aliases, $organisation);
+  }
+
+  // Check to see if the organisation exists
   @if not map-has-key($govuk-colours-organisations, $organisation) {
     @error "Unknown organisation `#{$organisation}`";
   }
 
+  // Output a warning if $websafe is set.
+  @if $websafe and not index($govuk-suppressed-warnings, "organisation-colour-websafe-param") {
+    @warn _warning-text("organisation-colour-websafe-param",
+      "The `$websafe` parameter of `govuk-organisation-colour` has been " +
+      "renamed to `$contrast-safe`. The old parameter name will be removed in " +
+      "the next major version."
+    );
+  }
+
   $org-colour: map-get($govuk-colours-organisations, $organisation);
 
-  @if $websafe and map-has-key($org-colour, colour-websafe) {
-    @return map-get($org-colour, colour-websafe);
+  @if map-has-key($org-colour, deprecation-message) and not index($govuk-suppressed-warnings, "organisation-colours") {
+    @warn _warning-text(
+      "organisation-colours",
+      map-get($org-colour, deprecation-message)
+    );
+  }
+
+  // If the $websafe parameter is being used (it has been explicitly set as true
+  // or false), assume the user hasn't updated to use $contrast-safe yet and map
+  // the old parameter's value onto the new parameter.
+  @if type-of($websafe) != "null" {
+    $contrast-safe: $websafe;
+  }
+
+  // Determine the contrast-safe key to use depending on whether it's the new
+  // palette or the legacy palette
+  $safe-key: if($govuk-new-organisation-colours, "contrast-safe", "colour-websafe");
+
+  @if $contrast-safe and map-has-key($org-colour, $safe-key) {
+    @return map-get($org-colour, $safe-key);
   } @else {
     @return map-get($org-colour, colour);
   }