From 0c9e065819852c89805260621a2080ff87d6adda Mon Sep 17 00:00:00 2001
From: "beeps (Kim Grey)" <kimberly.grey@digital.cabinet-office.gov.uk>
Date: Fri, 12 May 2023 10:15:53 +0100
Subject: [PATCH 01/13] Add deprecation warnings for defunct organisations

Produce a Sass compile warning if a defunct organisation is being referenced, with information on the
new/replacement organisation.
---
 src/govuk/helpers/_colour.scss                |   4 +
 src/govuk/helpers/colour.unit.test.js         |  23 +++
 .../settings/_colours-organisations.scss      | 133 +++++++++++-------
 3 files changed, 111 insertions(+), 49 deletions(-)

diff --git a/src/govuk/helpers/_colour.scss b/src/govuk/helpers/_colour.scss
index 5672b84b29..74ead9d4d9 100644
--- a/src/govuk/helpers/_colour.scss
+++ b/src/govuk/helpers/_colour.scss
@@ -59,6 +59,10 @@
 
   $org-colour: map-get($govuk-colours-organisations, $organisation);
 
+  @if map-has-key($org-colour, deprecation-message) {
+    @warn map-get($org-colour, deprecation-message);
+  }
+
   @if $websafe and map-has-key($org-colour, colour-websafe) {
     @return map-get($org-colour, colour-websafe);
   } @else {
diff --git a/src/govuk/helpers/colour.unit.test.js b/src/govuk/helpers/colour.unit.test.js
index a1fac2e1a1..4ed82ffcc9 100644
--- a/src/govuk/helpers/colour.unit.test.js
+++ b/src/govuk/helpers/colour.unit.test.js
@@ -110,6 +110,10 @@ describe('@function govuk-organisation-colour', () => {
       ),
       'broom-regulatory-control': (
         colour: #A81223
+      ),
+      'house-elf-equalities-office': (
+        colour: #786999,
+        deprecation-message: 'The House Elf Equalities Office was disbanded in 2007.'
       )
     );
 
@@ -170,6 +174,25 @@ describe('@function govuk-organisation-colour', () => {
     })
   })
 
+  it('outputs a warning if the organisation has been deprecated', async () => {
+    const sass = `
+      ${sassBootstrap}
+
+      .foo {
+        color: govuk-organisation-colour('house-elf-equalities-office');
+      }
+    `
+
+    await compileSassString(sass, sassConfig)
+
+    // Expect our mocked @warn function to have been called once with a single
+    // argument, which should be the deprecation notice
+    expect(mockWarnFunction.mock.calls[0])
+      .toEqual(expect.arrayContaining([
+        'The House Elf Equalities Office was disbanded in 2007.'
+      ]))
+  })
+
   it('throws an error if a non-existent organisation is requested', async () => {
     const sass = `
       ${sassBootstrap}
diff --git a/src/govuk/settings/_colours-organisations.scss b/src/govuk/settings/_colours-organisations.scss
index cf3193a7bc..2d96f81786 100644
--- a/src/govuk/settings/_colours-organisations.scss
+++ b/src/govuk/settings/_colours-organisations.scss
@@ -11,136 +11,171 @@
 ///   `$organisation`. We use `websafe` to mean strong enough contrast against
 ///   white to be used for copy and meet the AAA (large text) and AA (smaller
 ///   copy) WCAG guidelines.
+/// @prop $organisation.deprecation-message - Marks this organisation as
+///   deprecated (usually because it has ceased to exist). Value is the
+///   deprecation message output to the terminal when compiling.
 ///
 /// @access public
 
 $govuk-colours-organisations: (
   "attorney-generals-office": (
-    colour: #9f1888,
-    colour-websafe: #a03a88
+    colour: #9f1888
   ),
   "cabinet-office": (
-    colour: #005abb,
-    colour-websafe: #347da4
+    colour: #005abb
   ),
   "civil-service": (
     colour: #af292e
   ),
+  "department-for-business-trade": (
+    colour: #e52d13,
+    colour-websafe: #ce2911
+  ),
+  "department-for-business-energy-industrial-strategy": (
+    colour: #003479,
+    deprecation-message:
+      "`department-for-business-energy-industrial-strategy` was dissolved in 2023. It was replaced by `department-for-business-trade`, `department-for-energy-security-net-zero` and `department-science-innovation-technology`."
+  ),
   "department-for-business-innovation-skills": (
     colour: #003479,
-    colour-websafe: #347da4
+    deprecation-message:
+      "`department-for-business-innovation-skills` became `department-for-business-energy-industrial-strategy` in 2016. As of 2023, it is equivalent to `department-for-business-trade` or `department-science-innovation-technology`."
   ),
-  "department-for-communities-and-local-government": (
+  "department-for-communities-local-government": (
     colour: #009999,
-    colour-websafe: #37836e
+    colour-websafe: #008383,
+    deprecation-message:
+      "`department-for-communities-local-government` became `ministry-of-housing-communities-local-government` in 2018. As of 2023, it is equivalent to `department-for-levelling-up-housing-communities`."
   ),
   "department-for-culture-media-sport": (
+    colour: #d40072
+  ),
+  "department-for-digital-culture-media-sport": (
     colour: #d40072,
-    colour-websafe: #a03155
+    deprecation-message:
+      "`department-for-digital-culture-media-sport` became `department-for-culture-media-sport` in 2023."
   ),
   "department-for-education": (
     colour: #003a69,
     colour-websafe: #347ca9
   ),
+  "department-for-energy-security-net-zero": (
+    colour: #00a33b,
+    colour-websafe: #008530
+  ),
   "department-for-environment-food-rural-affairs": (
     colour: #00a33b,
-    colour-websafe: #008938
+    colour-websafe: #008530
   ),
   "department-for-international-development": (
     colour: #002878,
-    colour-websafe: #405e9a
+    deprecation-message:
+      "`department-for-international-development` was merged into `foreign-commonwealth-development-office` in 2020."
   ),
   "department-for-international-trade": (
     colour: #cf102d,
-    colour-websafe: #005ea5
+    deprecation-message: "`department-for-international-trade` was merged into `department-for-business-trade` in 2023."
   ),
-  "department-for-business-and-trade": (
-    colour: #cf102d,
-    colour-websafe: #005ea5
-  ),
-  "department-for-levelling-up-housing-and-communities": (
+  "department-for-levelling-up-housing-communities": (
     colour: #012169
   ),
+  "department-for-science-innovation-technology": (
+    colour: #00f9f8,
+    colour-websafe: #00807f
+  ),
   "department-for-transport": (
-    colour: #006c56,
-    colour-websafe: #398373
+    colour: #006c56
   ),
   "department-for-work-pensions": (
     colour: #00beb7,
-    colour-websafe: #37807b
+    colour-websafe: #007e7a
   ),
   "department-of-energy-climate-change": (
     colour: #009ddb,
-    colour-websafe: #2b7cac
+    colour-websafe: #007aaa,
+    deprecation-message:
+      "`department-of-energy-climate-change` was merged into `department-for-business-energy-industrial-strategy` in 2016. As of 2023, it is equivalent to `department-for-energy-security-net-zero`."
   ),
   "department-of-health": (
     colour: #00ad93,
-    colour-websafe: #39836e
+    colour-websafe: #008672,
+    deprecation-message: "`department-of-health` became `department-of-health-social-care` in 2018."
   ),
-  "foreign-commonwealth-development-office": (
-    colour: #012169
+  "department-of-health-social-care": (
+    colour: #00ad93,
+    colour-websafe: #008672
   ),
   "foreign-commonwealth-office": (
     colour: #003e74,
-    colour-websafe: #406e97
+    deprecation-message: "`foreign-commonwealth-office` became `foreign-commonwealth-development-office` in 2018."
+  ),
+  "foreign-commonwealth-development-office": (
+    colour: #012169
   ),
   "government-equalities-office": (
-    colour: #9325b2
+    colour: #005abb,
+    deprecation-message: "`government-equalities-office` is deprecated. Use `cabinet-office` instead."
   ),
   "hm-government": (
-    colour: #0076c0,
-    colour-websafe: #347da4
+    colour: #266ebc
   ),
   "hm-revenue-customs": (
     colour: #009390,
-    colour-websafe: #008670
+    colour-websafe: #007e7b
   ),
   "hm-treasury": (
-    colour: #af292e,
-    colour-websafe: #832322
+    colour: #af292e
   ),
   "home-office": (
-    colour: #9325b2,
-    colour-websafe: #9440b2
+    colour: #9325b2
   ),
   "ministry-of-defence": (
-    colour: #4d2942,
-    colour-websafe: #5a5c92
+    colour: #4d2942
+  ),
+  "ministry-of-housing-communities-local-government": (
+    colour: #009999,
+    colour-websafe: #008383,
+    deprecation-message:
+      "`ministry-of-housing-communities-local-government` became `department-for-levelling-up-housing-communities` in 2021."
   ),
   "ministry-of-justice": (
-    colour: #231f20,
-    colour-websafe: #5a5c92
+    colour: #231f20
   ),
   "northern-ireland-office": (
-    colour: #002663,
-    colour-websafe: #3e598c
+    colour: #002663
   ),
   "office-of-the-advocate-general-for-scotland": (
-    colour: #002663,
-    colour-websafe: #005ea5
+    colour: #002663
   ),
   "office-of-the-leader-of-the-house-of-commons": (
-    colour: #317023,
-    colour-websafe: #005f8f
+    colour: #317023
   ),
   "office-of-the-leader-of-the-house-of-lords": (
-    colour: #9c132e,
-    colour-websafe: #c2395d
+    colour: #9c132e
+  ),
+  "office-of-the-secretary-of-state-for-scotland": (
+    colour: #002663
+  ),
+  "office-of-the-secretary-of-state-for-wales": (
+    colour: #a33038
+  ),
+  "prime-ministers-office-10-downing-street": (
+    colour: #0b0c0c
   ),
   "scotland-office": (
     colour: #002663,
-    colour-websafe: #405c8a
+    deprecation-message: "`scotland-office` became `office-of-the-secretary-of-state-for-scotland` in 2018."
   ),
   "uk-export-finance": (
-    colour: #005747,
-    colour-websafe: #005ea5
+    colour: #d0132f
   ),
   "uk-trade-investment": (
     colour: #c80651,
-    colour-websafe: #005ea5
+    deprecation-message:
+      "`uk-trade-investment` became `department-for-international-trade` in 2016. As of 2023, it is equivalent to `department-for-business-trade`."
   ),
   "wales-office": (
     colour: #a33038,
-    colour-websafe: #7a242a
+    deprecation-message: "`wales-office` became `office-of-the-secretary-of-state-for-wales` in 2018."
   )
 ) !default;

From b692fe190778bc69308cffceb25a6fb17ae2805c Mon Sep 17 00:00:00 2001
From: "beeps (Kim Grey)" <kimberly.grey@digital.cabinet-office.gov.uk>
Date: Thu, 18 May 2023 12:57:24 +0100
Subject: [PATCH 02/13] Rename 'websafe' to 'contrast-safe'

Renames property in colour map from 'colour-websafe' to 'contrast-safe'.

Renames parameter on govuk-organisation-colour from `$websafe` to `$contrast-safe`. The old parameter name still works but is now deprecated.
---
 src/govuk/helpers/_colour.scss                | 34 ++++++++++++++-----
 src/govuk/helpers/colour.unit.test.js         | 28 ++++++++++++---
 .../settings/_colours-organisations.scss      | 30 ++++++++--------
 3 files changed, 65 insertions(+), 27 deletions(-)

diff --git a/src/govuk/helpers/_colour.scss b/src/govuk/helpers/_colour.scss
index 74ead9d4d9..d6272e67e6 100644
--- a/src/govuk/helpers/_colour.scss
+++ b/src/govuk/helpers/_colour.scss
@@ -42,29 +42,47 @@
 /// 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) {
   @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 "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. To silence this warning, update " +
+      "$govuk-suppressed-warnings with key: " +
+      "\"organisation-colour-websafe-param\"";
+  }
+
   $org-colour: map-get($govuk-colours-organisations, $organisation);
 
   @if map-has-key($org-colour, deprecation-message) {
     @warn map-get($org-colour, deprecation-message);
   }
 
-  @if $websafe and map-has-key($org-colour, colour-websafe) {
-    @return map-get($org-colour, colour-websafe);
+  // 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;
+  }
+
+  @if $contrast-safe and map-has-key($org-colour, contrast-safe) {
+    @return map-get($org-colour, contrast-safe);
   } @else {
     @return map-get($org-colour, colour);
   }
diff --git a/src/govuk/helpers/colour.unit.test.js b/src/govuk/helpers/colour.unit.test.js
index 4ed82ffcc9..e97096bef4 100644
--- a/src/govuk/helpers/colour.unit.test.js
+++ b/src/govuk/helpers/colour.unit.test.js
@@ -106,7 +106,7 @@ describe('@function govuk-organisation-colour', () => {
     $govuk-colours-organisations: (
       'floo-network-authority': (
         colour: #EC22FF,
-        colour-websafe: #9A00A8
+        contrast-safe: #9A00A8
       ),
       'broom-regulatory-control': (
         colour: #A81223
@@ -120,7 +120,7 @@ describe('@function govuk-organisation-colour', () => {
     @import "helpers/colour";
   `
 
-  it('returns the websafe colour for a given organisation by default', async () => {
+  it('returns the contrast-safe colour for a given organisation by default', async () => {
     const sass = `
       ${sassBootstrap}
 
@@ -138,7 +138,7 @@ describe('@function govuk-organisation-colour', () => {
     })
   })
 
-  it('falls back to the default colour if a websafe colour is not explicitly defined', async () => {
+  it('falls back to the default colour if a contrast-safe colour is not explicitly defined', async () => {
     const sass = `
       ${sassBootstrap}
 
@@ -156,7 +156,27 @@ describe('@function govuk-organisation-colour', () => {
     })
   })
 
-  it('can be overridden to return the non-websafe colour', async () => {
+  it('can be overridden to return the non-contrast-safe colour ($contrast-safe parameter)', async () => {
+    const sass = `
+      ${sassBootstrap}
+
+      .foo {
+        border-color: govuk-organisation-colour('floo-network-authority', $contrast-safe: false);
+      }
+    `
+
+    await expect(compileSassString(sass, sassConfig))
+      .resolves
+      .toMatchObject({
+        css: outdent`
+          .foo {
+            border-color: #EC22FF;
+          }
+        `
+      })
+  })
+
+  it('can be overridden to return the non-contrast-safe colour (deprecated $websafe parameter)', async () => {
     const sass = `
       ${sassBootstrap}
 
diff --git a/src/govuk/settings/_colours-organisations.scss b/src/govuk/settings/_colours-organisations.scss
index 2d96f81786..aef59f2e5d 100644
--- a/src/govuk/settings/_colours-organisations.scss
+++ b/src/govuk/settings/_colours-organisations.scss
@@ -7,9 +7,9 @@
 /// @type Map
 ///
 /// @prop $organisation.colour - Colour for the given `$organisation`
-/// @prop $organisation.colour-websafe - Websafe colour for the given
-///   `$organisation`. We use `websafe` to mean strong enough contrast against
-///   white to be used for copy and meet the AAA (large text) and AA (smaller
+/// @prop $organisation.contrast-safe - 'Contrast safe' colour for the given
+///   `$organisation`. This colour has at least a 4.5:1 contrast against
+///   white, to be used for copy and meet the AAA (large text) and AA (smaller
 ///   copy) WCAG guidelines.
 /// @prop $organisation.deprecation-message - Marks this organisation as
 ///   deprecated (usually because it has ceased to exist). Value is the
@@ -29,7 +29,7 @@ $govuk-colours-organisations: (
   ),
   "department-for-business-trade": (
     colour: #e52d13,
-    colour-websafe: #ce2911
+    contrast-safe: #ce2911
   ),
   "department-for-business-energy-industrial-strategy": (
     colour: #003479,
@@ -43,7 +43,7 @@ $govuk-colours-organisations: (
   ),
   "department-for-communities-local-government": (
     colour: #009999,
-    colour-websafe: #008383,
+    contrast-safe: #008383,
     deprecation-message:
       "`department-for-communities-local-government` became `ministry-of-housing-communities-local-government` in 2018. As of 2023, it is equivalent to `department-for-levelling-up-housing-communities`."
   ),
@@ -57,15 +57,15 @@ $govuk-colours-organisations: (
   ),
   "department-for-education": (
     colour: #003a69,
-    colour-websafe: #347ca9
+    contrast-safe: #347ca9
   ),
   "department-for-energy-security-net-zero": (
     colour: #00a33b,
-    colour-websafe: #008530
+    contrast-safe: #008530
   ),
   "department-for-environment-food-rural-affairs": (
     colour: #00a33b,
-    colour-websafe: #008530
+    contrast-safe: #008530
   ),
   "department-for-international-development": (
     colour: #002878,
@@ -81,29 +81,29 @@ $govuk-colours-organisations: (
   ),
   "department-for-science-innovation-technology": (
     colour: #00f9f8,
-    colour-websafe: #00807f
+    contrast-safe: #00807f
   ),
   "department-for-transport": (
     colour: #006c56
   ),
   "department-for-work-pensions": (
     colour: #00beb7,
-    colour-websafe: #007e7a
+    contrast-safe: #007e7a
   ),
   "department-of-energy-climate-change": (
     colour: #009ddb,
-    colour-websafe: #007aaa,
+    contrast-safe: #007aaa,
     deprecation-message:
       "`department-of-energy-climate-change` was merged into `department-for-business-energy-industrial-strategy` in 2016. As of 2023, it is equivalent to `department-for-energy-security-net-zero`."
   ),
   "department-of-health": (
     colour: #00ad93,
-    colour-websafe: #008672,
+    contrast-safe: #008672,
     deprecation-message: "`department-of-health` became `department-of-health-social-care` in 2018."
   ),
   "department-of-health-social-care": (
     colour: #00ad93,
-    colour-websafe: #008672
+    contrast-safe: #008672
   ),
   "foreign-commonwealth-office": (
     colour: #003e74,
@@ -121,7 +121,7 @@ $govuk-colours-organisations: (
   ),
   "hm-revenue-customs": (
     colour: #009390,
-    colour-websafe: #007e7b
+    contrast-safe: #007e7b
   ),
   "hm-treasury": (
     colour: #af292e
@@ -134,7 +134,7 @@ $govuk-colours-organisations: (
   ),
   "ministry-of-housing-communities-local-government": (
     colour: #009999,
-    colour-websafe: #008383,
+    contrast-safe: #008383,
     deprecation-message:
       "`ministry-of-housing-communities-local-government` became `department-for-levelling-up-housing-communities` in 2021."
   ),

From b062d2841a23763c51e329deb365c782da81a068 Mon Sep 17 00:00:00 2001
From: beeps <kimberly.grey@digital.cabinet-office.gov.uk>
Date: Mon, 16 Oct 2023 11:03:33 +0100
Subject: [PATCH 03/13] Run unit tests through Prettier

Prettier configuration has been updated since these changes were originally made
---
 src/govuk/helpers/colour.unit.test.js | 15 +++++++--------
 1 file changed, 7 insertions(+), 8 deletions(-)

diff --git a/src/govuk/helpers/colour.unit.test.js b/src/govuk/helpers/colour.unit.test.js
index e97096bef4..2e3ab1282d 100644
--- a/src/govuk/helpers/colour.unit.test.js
+++ b/src/govuk/helpers/colour.unit.test.js
@@ -165,15 +165,13 @@ describe('@function govuk-organisation-colour', () => {
       }
     `
 
-    await expect(compileSassString(sass, sassConfig))
-      .resolves
-      .toMatchObject({
-        css: outdent`
+    await expect(compileSassString(sass, sassConfig)).resolves.toMatchObject({
+      css: outdent`
           .foo {
             border-color: #EC22FF;
           }
         `
-      })
+    })
   })
 
   it('can be overridden to return the non-contrast-safe colour (deprecated $websafe parameter)', async () => {
@@ -207,10 +205,11 @@ describe('@function govuk-organisation-colour', () => {
 
     // Expect our mocked @warn function to have been called once with a single
     // argument, which should be the deprecation notice
-    expect(mockWarnFunction.mock.calls[0])
-      .toEqual(expect.arrayContaining([
+    expect(mockWarnFunction.mock.calls[0]).toEqual(
+      expect.arrayContaining([
         'The House Elf Equalities Office was disbanded in 2007.'
-      ]))
+      ])
+    )
   })
 
   it('throws an error if a non-existent organisation is requested', async () => {

From 39161ea548d53b378c474de3ea10165d0ea0a6fb Mon Sep 17 00:00:00 2001
From: beeps <kimberly.grey@digital.cabinet-office.gov.uk>
Date: Mon, 16 Oct 2023 11:49:33 +0100
Subject: [PATCH 04/13] Add ability to alias old organisation key names to new

---
 src/govuk/helpers/_colour.scss                |  7 ++++++
 src/govuk/helpers/colour.unit.test.js         | 24 +++++++++++++++++++
 .../settings/_colours-organisations.scss      | 22 +++++++++++++++++
 3 files changed, 53 insertions(+)

diff --git a/src/govuk/helpers/_colour.scss b/src/govuk/helpers/_colour.scss
index d6272e67e6..5b3077e881 100644
--- a/src/govuk/helpers/_colour.scss
+++ b/src/govuk/helpers/_colour.scss
@@ -55,6 +55,13 @@
 /// @access public
 
 @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}`";
   }
diff --git a/src/govuk/helpers/colour.unit.test.js b/src/govuk/helpers/colour.unit.test.js
index 2e3ab1282d..b67c81e1cf 100644
--- a/src/govuk/helpers/colour.unit.test.js
+++ b/src/govuk/helpers/colour.unit.test.js
@@ -225,4 +225,28 @@ describe('@function govuk-organisation-colour', () => {
       'Unknown organisation `muggle-born-registration-commission`'
     )
   })
+
+  it('aliases renamed organisation keys to the equivalent key', async () => {
+    const sass = `
+      $govuk-colours-organisations: (
+        'department-for-business-trade': (
+          colour: #e52d13
+        )
+      );
+
+      @import "helpers/colour";
+
+      .foo {
+        color: govuk-organisation-colour('department-for-business-and-trade');
+      }
+    `
+
+    await expect(compileSassString(sass, sassConfig)).resolves.toMatchObject({
+      css: outdent`
+          .foo {
+            color: #e52d13;
+          }
+        `
+    })
+  })
 })
diff --git a/src/govuk/settings/_colours-organisations.scss b/src/govuk/settings/_colours-organisations.scss
index aef59f2e5d..28df7fca1c 100644
--- a/src/govuk/settings/_colours-organisations.scss
+++ b/src/govuk/settings/_colours-organisations.scss
@@ -179,3 +179,25 @@ $govuk-colours-organisations: (
     deprecation-message: "`wales-office` became `office-of-the-secretary-of-state-for-wales` in 2018."
   )
 ) !default;
+
+/// Organisation colour aliases
+///
+/// Some organisations have been renamed within our code over time. Here we
+/// map the prior key to the new equivalent key.
+///
+/// Note: This is for internal renames only. If a department has changed name
+/// or brand colour in a machinery of government change, it should be added to
+/// $govuk-colours-organisations as a new entry with any superseded
+/// organisations marked deprecated.
+///
+/// @type Map
+///
+/// @access private
+
+$_govuk-colours-organisations-aliases: (
+  // Various keys used to include the word 'and' when most others did not.
+  // We removed all the extra 'and's.
+  "department-for-business-and-trade": "department-for-business-trade",
+  "department-for-communities-and-local-government": "department-for-communities-local-government",
+  "department-for-levelling-up-housing-and-communities": "department-for-levelling-up-housing-communities"
+);

From d3109858b046548dc5f11793b78df45e07909521 Mon Sep 17 00:00:00 2001
From: beeps <kimberly.grey@digital.cabinet-office.gov.uk>
Date: Mon, 16 Oct 2023 12:36:14 +0100
Subject: [PATCH 05/13] Update organisation colours

Updates the organisation colours based on draft brand documents provided by Design102. These colours likely do not match the specific shades
used within departments and their own design systems, but they are based on the most authoritative source we have currently.

The exceptions to this are:
- DSIT, which Design102 has yet to provide a specific colour for. The colour used here is derived from the one used on DSIT's public-facing
comms instead.
- DESNZ, which we also do not have a prescribed coloru for. The colour here is also from public-facing comms.
- Home Office, which provisionally uses the colour from the HO Design System rather than the draft identity guidelines.
- Prime Minister's Office, which uses the off-black from GOV.UK instead of the pure black from the draft identity guidelines.
---
 .../settings/_colours-organisations.scss      | 68 +++++++++----------
 1 file changed, 33 insertions(+), 35 deletions(-)

diff --git a/src/govuk/settings/_colours-organisations.scss b/src/govuk/settings/_colours-organisations.scss
index 28df7fca1c..b3ca33323e 100644
--- a/src/govuk/settings/_colours-organisations.scss
+++ b/src/govuk/settings/_colours-organisations.scss
@@ -19,17 +19,17 @@
 
 $govuk-colours-organisations: (
   "attorney-generals-office": (
-    colour: #9f1888
+    colour: #a91c8e
   ),
   "cabinet-office": (
-    colour: #005abb
+    colour: #0056b8
   ),
   "civil-service": (
-    colour: #af292e
+    colour: #b2292e
   ),
   "department-for-business-trade": (
     colour: #e52d13,
-    contrast-safe: #ce2911
+    contrast-safe: #e02c13
   ),
   "department-for-business-energy-industrial-strategy": (
     colour: #003479,
@@ -43,12 +43,12 @@ $govuk-colours-organisations: (
   ),
   "department-for-communities-local-government": (
     colour: #009999,
-    contrast-safe: #008383,
+    contrast-safe: #008080,
     deprecation-message:
       "`department-for-communities-local-government` became `ministry-of-housing-communities-local-government` in 2018. As of 2023, it is equivalent to `department-for-levelling-up-housing-communities`."
   ),
   "department-for-culture-media-sport": (
-    colour: #d40072
+    colour: #d6006e
   ),
   "department-for-digital-culture-media-sport": (
     colour: #d40072,
@@ -56,16 +56,15 @@ $govuk-colours-organisations: (
       "`department-for-digital-culture-media-sport` became `department-for-culture-media-sport` in 2023."
   ),
   "department-for-education": (
-    colour: #003a69,
-    contrast-safe: #347ca9
+    colour: #003764
   ),
   "department-for-energy-security-net-zero": (
     colour: #00a33b,
-    contrast-safe: #008530
+    contrast-safe: #00852f
   ),
   "department-for-environment-food-rural-affairs": (
-    colour: #00a33b,
-    contrast-safe: #008530
+    colour: #00af43,
+    contrast-safe: #008733
   ),
   "department-for-international-development": (
     colour: #002878,
@@ -81,83 +80,82 @@ $govuk-colours-organisations: (
   ),
   "department-for-science-innovation-technology": (
     colour: #00f9f8,
-    contrast-safe: #00807f
+    contrast-safe: #008180
   ),
   "department-for-transport": (
-    colour: #006c56
+    colour: #006853
   ),
   "department-for-work-pensions": (
-    colour: #00beb7,
-    contrast-safe: #007e7a
+    colour: #00bcb5,
+    contrast-safe: #00857e
   ),
   "department-of-energy-climate-change": (
     colour: #009ddb,
-    contrast-safe: #007aaa,
+    contrast-safe: #007db3,
     deprecation-message:
       "`department-of-energy-climate-change` was merged into `department-for-business-energy-industrial-strategy` in 2016. As of 2023, it is equivalent to `department-for-energy-security-net-zero`."
   ),
   "department-of-health": (
     colour: #00ad93,
-    contrast-safe: #008672,
+    contrast-safe: #008573,
     deprecation-message: "`department-of-health` became `department-of-health-social-care` in 2018."
   ),
   "department-of-health-social-care": (
-    colour: #00ad93,
-    contrast-safe: #008672
+    colour: #00a990,
+    contrast-safe: #008674
   ),
   "foreign-commonwealth-office": (
     colour: #003e74,
     deprecation-message: "`foreign-commonwealth-office` became `foreign-commonwealth-development-office` in 2018."
   ),
   "foreign-commonwealth-development-office": (
-    colour: #012169
+    colour: #002269
   ),
   "government-equalities-office": (
-    colour: #005abb,
+    colour: #0056b8,
     deprecation-message: "`government-equalities-office` is deprecated. Use `cabinet-office` instead."
   ),
   "hm-government": (
     colour: #266ebc
   ),
   "hm-revenue-customs": (
-    colour: #009390,
-    contrast-safe: #007e7b
+    colour: #008476
   ),
   "hm-treasury": (
-    colour: #af292e
+    colour: #b2292e
   ),
   "home-office": (
-    colour: #9325b2
+    colour: #732282
   ),
   "ministry-of-defence": (
-    colour: #4d2942
+    colour: #532a45
   ),
   "ministry-of-housing-communities-local-government": (
     colour: #009999,
-    contrast-safe: #008383,
+    contrast-safe: #008080,
     deprecation-message:
       "`ministry-of-housing-communities-local-government` became `department-for-levelling-up-housing-communities` in 2021."
   ),
   "ministry-of-justice": (
-    colour: #231f20
+    colour: #000000
   ),
   "northern-ireland-office": (
-    colour: #002663
+    colour: #00205c
   ),
   "office-of-the-advocate-general-for-scotland": (
-    colour: #002663
+    colour: #00205c
   ),
   "office-of-the-leader-of-the-house-of-commons": (
-    colour: #317023
+    colour: #497629
   ),
   "office-of-the-leader-of-the-house-of-lords": (
-    colour: #9c132e
+    colour: #9c182f
   ),
   "office-of-the-secretary-of-state-for-scotland": (
-    colour: #002663
+    colour: #00205c
   ),
   "office-of-the-secretary-of-state-for-wales": (
-    colour: #a33038
+    colour: #a8353a
   ),
   "prime-ministers-office-10-downing-street": (
     colour: #0b0c0c
@@ -167,7 +165,7 @@ $govuk-colours-organisations: (
     deprecation-message: "`scotland-office` became `office-of-the-secretary-of-state-for-scotland` in 2018."
   ),
   "uk-export-finance": (
-    colour: #d0132f
+    colour: #cf102d
   ),
   "uk-trade-investment": (
     colour: #c80651,

From 12d1f50e267648cdf37029be69e9b4f36a616cc5 Mon Sep 17 00:00:00 2001
From: beeps <kimberly.grey@digital.cabinet-office.gov.uk>
Date: Mon, 16 Oct 2023 16:52:54 +0100
Subject: [PATCH 06/13] Re-add `colour-websafe` keys to organisation colours

Re-add and deprecate `colour-websafe`. We still want to rename it, but this is to avoid a breaking change in the mean time.
---
 src/govuk/settings/_colours-organisations.scss | 13 +++++++++++++
 1 file changed, 13 insertions(+)

diff --git a/src/govuk/settings/_colours-organisations.scss b/src/govuk/settings/_colours-organisations.scss
index b3ca33323e..bc4ea3e275 100644
--- a/src/govuk/settings/_colours-organisations.scss
+++ b/src/govuk/settings/_colours-organisations.scss
@@ -11,6 +11,9 @@
 ///   `$organisation`. This colour has at least a 4.5:1 contrast against
 ///   white, to be used for copy and meet the AAA (large text) and AA (smaller
 ///   copy) WCAG guidelines.
+/// @prop $organisation.colour-websafe - Deprecated. Use `contrast-safe`
+///   instead. The values of both `colour-websafe` and `contrast-safe` should
+///   be the same.
 /// @prop $organisation.deprecation-message - Marks this organisation as
 ///   deprecated (usually because it has ceased to exist). Value is the
 ///   deprecation message output to the terminal when compiling.
@@ -29,6 +32,7 @@ $govuk-colours-organisations: (
   ),
   "department-for-business-trade": (
     colour: #e52d13,
+    colour-websafe: #e02c13,
     contrast-safe: #e02c13
   ),
   "department-for-business-energy-industrial-strategy": (
@@ -43,6 +47,7 @@ $govuk-colours-organisations: (
   ),
   "department-for-communities-local-government": (
     colour: #009999,
+    colour-websafe: #008080,
     contrast-safe: #008080,
     deprecation-message:
       "`department-for-communities-local-government` became `ministry-of-housing-communities-local-government` in 2018. As of 2023, it is equivalent to `department-for-levelling-up-housing-communities`."
@@ -60,10 +65,12 @@ $govuk-colours-organisations: (
   ),
   "department-for-energy-security-net-zero": (
     colour: #00a33b,
+    colour-websafe: #00852f,
     contrast-safe: #00852f
   ),
   "department-for-environment-food-rural-affairs": (
     colour: #00af43,
+    colour-websafe: #008733,
     contrast-safe: #008733
   ),
   "department-for-international-development": (
@@ -80,6 +87,7 @@ $govuk-colours-organisations: (
   ),
   "department-for-science-innovation-technology": (
     colour: #00f9f8,
+    colour-websafe: #008180,
     contrast-safe: #008180
   ),
   "department-for-transport": (
@@ -87,21 +95,25 @@ $govuk-colours-organisations: (
   ),
   "department-for-work-pensions": (
     colour: #00bcb5,
+    colour-websafe: #00857e,
     contrast-safe: #00857e
   ),
   "department-of-energy-climate-change": (
     colour: #009ddb,
+    colour-websafe: #007db3,
     contrast-safe: #007db3,
     deprecation-message:
       "`department-of-energy-climate-change` was merged into `department-for-business-energy-industrial-strategy` in 2016. As of 2023, it is equivalent to `department-for-energy-security-net-zero`."
   ),
   "department-of-health": (
     colour: #00ad93,
+    colour-websafe: #008573,
     contrast-safe: #008573,
     deprecation-message: "`department-of-health` became `department-of-health-social-care` in 2018."
   ),
   "department-of-health-social-care": (
     colour: #00a990,
+    colour-websafe: #008674,
     contrast-safe: #008674
   ),
   "foreign-commonwealth-office": (
@@ -132,6 +144,7 @@ $govuk-colours-organisations: (
   ),
   "ministry-of-housing-communities-local-government": (
     colour: #009999,
+    colour-websafe: #008080,
     contrast-safe: #008080,
     deprecation-message:
       "`ministry-of-housing-communities-local-government` became `department-for-levelling-up-housing-communities` in 2021."

From f9afb0a8f4433144bfa490af751b880043d4ca25 Mon Sep 17 00:00:00 2001
From: beeps <kimberly.grey@digital.cabinet-office.gov.uk>
Date: Thu, 4 Jan 2024 09:54:47 +0000
Subject: [PATCH 07/13] Update warnings and associated tests

---
 src/govuk/helpers/_colour.scss        | 13 ++++++++-----
 src/govuk/helpers/colour.unit.test.js |  2 +-
 2 files changed, 9 insertions(+), 6 deletions(-)

diff --git a/src/govuk/helpers/_colour.scss b/src/govuk/helpers/_colour.scss
index 5b3077e881..fbedb811d9 100644
--- a/src/govuk/helpers/_colour.scss
+++ b/src/govuk/helpers/_colour.scss
@@ -68,17 +68,20 @@
 
   // Output a warning if $websafe is set.
   @if $websafe and not index($govuk-suppressed-warnings, "organisation-colour-websafe-param") {
-    @warn "The `$websafe` parameter of `govuk-organisation-colour` has been " +
+    @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. To silence this warning, update " +
-      "$govuk-suppressed-warnings with key: " +
-      "\"organisation-colour-websafe-param\"";
+      "the next major version."
+    );
   }
 
   $org-colour: map-get($govuk-colours-organisations, $organisation);
 
   @if map-has-key($org-colour, deprecation-message) {
-    @warn map-get($org-colour, deprecation-message);
+    @warn _warning-text(
+      "organisation-colour-websafe-param",
+      map-get($org-colour, deprecation-message)
+    );
   }
 
   // If the $websafe parameter is being used (it has been explicitly set as true
diff --git a/src/govuk/helpers/colour.unit.test.js b/src/govuk/helpers/colour.unit.test.js
index b67c81e1cf..e2b78431a7 100644
--- a/src/govuk/helpers/colour.unit.test.js
+++ b/src/govuk/helpers/colour.unit.test.js
@@ -207,7 +207,7 @@ describe('@function govuk-organisation-colour', () => {
     // argument, which should be the deprecation notice
     expect(mockWarnFunction.mock.calls[0]).toEqual(
       expect.arrayContaining([
-        'The House Elf Equalities Office was disbanded in 2007.'
+        'The House Elf Equalities Office was disbanded in 2007. To silence this warning, update $govuk-suppressed-warnings with key: "organisation-colour-websafe-param"'
       ])
     )
   })

From 440fe318568333d32f65e9f62e561c32c64946b4 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Fri, 23 Feb 2024 13:49:46 +0000
Subject: [PATCH 08/13] Place new organisation colours behind a feature flag

---
 src/govuk/helpers/_colour.scss                |   8 +-
 src/govuk/helpers/colour.unit.test.js         |  71 +++++++
 .../settings/_colours-organisations.scss      | 192 ++++++++++++++++--
 src/govuk/settings/colours.unit.test.js       |  29 +++
 4 files changed, 279 insertions(+), 21 deletions(-)

diff --git a/src/govuk/helpers/_colour.scss b/src/govuk/helpers/_colour.scss
index fbedb811d9..ed6c578540 100644
--- a/src/govuk/helpers/_colour.scss
+++ b/src/govuk/helpers/_colour.scss
@@ -91,8 +91,12 @@
     $contrast-safe: $websafe;
   }
 
-  @if $contrast-safe and map-has-key($org-colour, contrast-safe) {
-    @return map-get($org-colour, contrast-safe);
+  // 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);
   }
diff --git a/src/govuk/helpers/colour.unit.test.js b/src/govuk/helpers/colour.unit.test.js
index e2b78431a7..58ce873091 100644
--- a/src/govuk/helpers/colour.unit.test.js
+++ b/src/govuk/helpers/colour.unit.test.js
@@ -103,6 +103,7 @@ describe('@function govuk-colour', () => {
 
 describe('@function govuk-organisation-colour', () => {
   const sassBootstrap = `
+    $govuk-new-organisation-colours: true;
     $govuk-colours-organisations: (
       'floo-network-authority': (
         colour: #EC22FF,
@@ -249,4 +250,74 @@ describe('@function govuk-organisation-colour', () => {
         `
     })
   })
+
+  describe('legacy palette', () => {
+    const sassBootstrapLegacy = `
+      $govuk-colours-organisations: (
+        'floo-network-authority': (
+          colour: #EC22FF,
+          colour-websafe: #9A00A8
+        ),
+        'broom-regulatory-control': (
+          colour: #A81223
+        )
+      );
+
+      @import "helpers/colour";
+    `
+
+    it('returns the contrast-safe colour for a given organisation by default', async () => {
+      const sass = `
+        ${sassBootstrapLegacy}
+
+        .foo {
+          color: govuk-organisation-colour('floo-network-authority');
+        }
+      `
+
+      await expect(compileSassString(sass, sassConfig)).resolves.toMatchObject({
+        css: outdent`
+          .foo {
+            color: #9A00A8;
+          }
+        `
+      })
+    })
+
+    it('falls back to the default colour if a contrast-safe colour is not explicitly defined', async () => {
+      const sass = `
+        ${sassBootstrapLegacy}
+
+        .foo {
+          color: govuk-organisation-colour('broom-regulatory-control');
+        }
+      `
+
+      await expect(compileSassString(sass, sassConfig)).resolves.toMatchObject({
+        css: outdent`
+          .foo {
+            color: #A81223;
+          }
+        `
+      })
+    })
+
+    it('can be overridden to return the non-contrast-safe colour ($websafe parameter)', async () => {
+      const sass = `
+        ${sassBootstrapLegacy}
+
+        .foo {
+          border-color: govuk-organisation-colour('floo-network-authority', $websafe: false);
+        }
+      `
+
+      await expect(compileSassString(sass, sassConfig)).resolves.toMatchObject({
+        css: outdent`
+          .foo {
+            border-color: #EC22FF;
+          }
+        `
+      })
+    })
+  })
 })
diff --git a/src/govuk/settings/_colours-organisations.scss b/src/govuk/settings/_colours-organisations.scss
index bc4ea3e275..f8f57c5180 100644
--- a/src/govuk/settings/_colours-organisations.scss
+++ b/src/govuk/settings/_colours-organisations.scss
@@ -2,7 +2,19 @@
 /// @group settings/colours
 ////
 
-/// Organisation colours
+/// Feature flag for updated organisation list and colours
+///
+/// When set to true, $govuk-colours-organisations will use the new
+/// organisation list and colour selection.
+///
+/// Should be removed in 6.0.
+///
+/// @type Boolean
+/// @access public
+
+$govuk-new-organisation-colours: false !default;
+
+/// Current organisation colours
 ///
 /// @type Map
 ///
@@ -11,16 +23,13 @@
 ///   `$organisation`. This colour has at least a 4.5:1 contrast against
 ///   white, to be used for copy and meet the AAA (large text) and AA (smaller
 ///   copy) WCAG guidelines.
-/// @prop $organisation.colour-websafe - Deprecated. Use `contrast-safe`
-///   instead. The values of both `colour-websafe` and `contrast-safe` should
-///   be the same.
 /// @prop $organisation.deprecation-message - Marks this organisation as
 ///   deprecated (usually because it has ceased to exist). Value is the
 ///   deprecation message output to the terminal when compiling.
 ///
-/// @access public
+/// @access private
 
-$govuk-colours-organisations: (
+$_govuk-organisation-colours: (
   "attorney-generals-office": (
     colour: #a91c8e
   ),
@@ -32,7 +41,6 @@ $govuk-colours-organisations: (
   ),
   "department-for-business-trade": (
     colour: #e52d13,
-    colour-websafe: #e02c13,
     contrast-safe: #e02c13
   ),
   "department-for-business-energy-industrial-strategy": (
@@ -47,10 +55,9 @@ $govuk-colours-organisations: (
   ),
   "department-for-communities-local-government": (
     colour: #009999,
-    colour-websafe: #008080,
     contrast-safe: #008080,
     deprecation-message:
-      "`department-for-communities-local-government` became `ministry-of-housing-communities-local-government` in 2018. As of 2023, it is equivalent to `department-for-levelling-up-housing-communities`."
+      "`department-for-communities-local-government` became `ministry-of-housing-communities-local-government` in 2018. As of 2021, it is equivalent to `department-for-levelling-up-housing-communities`."
   ),
   "department-for-culture-media-sport": (
     colour: #d6006e
@@ -65,12 +72,10 @@ $govuk-colours-organisations: (
   ),
   "department-for-energy-security-net-zero": (
     colour: #00a33b,
-    colour-websafe: #00852f,
     contrast-safe: #00852f
   ),
   "department-for-environment-food-rural-affairs": (
     colour: #00af43,
-    colour-websafe: #008733,
     contrast-safe: #008733
   ),
   "department-for-international-development": (
@@ -87,7 +92,6 @@ $govuk-colours-organisations: (
   ),
   "department-for-science-innovation-technology": (
     colour: #00f9f8,
-    colour-websafe: #008180,
     contrast-safe: #008180
   ),
   "department-for-transport": (
@@ -95,25 +99,21 @@ $govuk-colours-organisations: (
   ),
   "department-for-work-pensions": (
     colour: #00bcb5,
-    colour-websafe: #00857e,
     contrast-safe: #00857e
   ),
   "department-of-energy-climate-change": (
     colour: #009ddb,
-    colour-websafe: #007db3,
     contrast-safe: #007db3,
     deprecation-message:
       "`department-of-energy-climate-change` was merged into `department-for-business-energy-industrial-strategy` in 2016. As of 2023, it is equivalent to `department-for-energy-security-net-zero`."
   ),
   "department-of-health": (
     colour: #00ad93,
-    colour-websafe: #008573,
     contrast-safe: #008573,
     deprecation-message: "`department-of-health` became `department-of-health-social-care` in 2018."
   ),
   "department-of-health-social-care": (
     colour: #00a990,
-    colour-websafe: #008674,
     contrast-safe: #008674
   ),
   "foreign-commonwealth-office": (
@@ -144,7 +144,6 @@ $govuk-colours-organisations: (
   ),
   "ministry-of-housing-communities-local-government": (
     colour: #009999,
-    colour-websafe: #008080,
     contrast-safe: #008080,
     deprecation-message:
       "`ministry-of-housing-communities-local-government` became `department-for-levelling-up-housing-communities` in 2021."
@@ -189,6 +188,163 @@ $govuk-colours-organisations: (
     colour: #a33038,
     deprecation-message: "`wales-office` became `office-of-the-secretary-of-state-for-wales` in 2018."
   )
+);
+
+/// Legacy organisation colours
+///
+/// These are the colours included with Frontend prior to 5.3.0. They will be
+/// removed in a future major version of Frontend.
+///
+/// @type Map
+///
+/// @prop $organisation.colour - Colour for the given `$organisation`
+/// @prop $organisation.colour-websafe - Optional alternative shade of the
+///   organisation colour. Despite the name, is not guaranteed to be websafe
+///   nor provide better contrast than the base colour.
+///
+/// @access private
+
+$_govuk-legacy-organisation-colours: (
+  "attorney-generals-office": (
+    colour: #9f1888,
+    colour-websafe: #a03a88
+  ),
+  "cabinet-office": (
+    colour: #005abb,
+    colour-websafe: #347da4
+  ),
+  "civil-service": (
+    colour: #af292e
+  ),
+  "department-for-business-innovation-skills": (
+    colour: #003479,
+    colour-websafe: #347da4
+  ),
+  "department-for-communities-local-government": (
+    colour: #009999,
+    colour-websafe: #37836e
+  ),
+  "department-for-culture-media-sport": (
+    colour: #d40072,
+    colour-websafe: #a03155
+  ),
+  "department-for-education": (
+    colour: #003a69,
+    colour-websafe: #347ca9
+  ),
+  "department-for-environment-food-rural-affairs": (
+    colour: #00a33b,
+    colour-websafe: #008938
+  ),
+  "department-for-international-development": (
+    colour: #002878,
+    colour-websafe: #405e9a
+  ),
+  "department-for-international-trade": (
+    colour: #cf102d,
+    colour-websafe: #005ea5
+  ),
+  "department-for-business-trade": (
+    colour: #cf102d,
+    colour-websafe: #005ea5
+  ),
+  "department-for-levelling-up-housing-communities": (
+    colour: #012169
+  ),
+  "department-for-transport": (
+    colour: #006c56,
+    colour-websafe: #398373
+  ),
+  "department-for-work-pensions": (
+    colour: #00beb7,
+    colour-websafe: #37807b
+  ),
+  "department-of-energy-climate-change": (
+    colour: #009ddb,
+    colour-websafe: #2b7cac
+  ),
+  "department-of-health": (
+    colour: #00ad93,
+    colour-websafe: #39836e
+  ),
+  "foreign-commonwealth-development-office": (
+    colour: #012169
+  ),
+  "foreign-commonwealth-office": (
+    colour: #003e74,
+    colour-websafe: #406e97
+  ),
+  "government-equalities-office": (
+    colour: #9325b2
+  ),
+  "hm-government": (
+    colour: #0076c0,
+    colour-websafe: #347da4
+  ),
+  "hm-revenue-customs": (
+    colour: #009390,
+    colour-websafe: #008670
+  ),
+  "hm-treasury": (
+    colour: #af292e,
+    colour-websafe: #832322
+  ),
+  "home-office": (
+    colour: #9325b2,
+    colour-websafe: #9440b2
+  ),
+  "ministry-of-defence": (
+    colour: #4d2942,
+    colour-websafe: #5a5c92
+  ),
+  "ministry-of-justice": (
+    colour: #231f20,
+    colour-websafe: #5a5c92
+  ),
+  "northern-ireland-office": (
+    colour: #002663,
+    colour-websafe: #3e598c
+  ),
+  "office-of-the-advocate-general-for-scotland": (
+    colour: #002663,
+    colour-websafe: #005ea5
+  ),
+  "office-of-the-leader-of-the-house-of-commons": (
+    colour: #317023,
+    colour-websafe: #005f8f
+  ),
+  "office-of-the-leader-of-the-house-of-lords": (
+    colour: #9c132e,
+    colour-websafe: #c2395d
+  ),
+  "scotland-office": (
+    colour: #002663,
+    colour-websafe: #405c8a
+  ),
+  "uk-export-finance": (
+    colour: #005747,
+    colour-websafe: #005ea5
+  ),
+  "uk-trade-investment": (
+    colour: #c80651,
+    colour-websafe: #005ea5
+  ),
+  "wales-office": (
+    colour: #a33038,
+    colour-websafe: #7a242a
+  )
+);
+
+/// Set public organisation colours variable to one of the two maps.
+/// Users can also pass their own map to this to override it entirely.
+///
+/// @type Map
+/// @access public
+
+$govuk-colours-organisations: if(
+  $govuk-new-organisation-colours,
+  $_govuk-organisation-colours,
+  $_govuk-legacy-organisation-colours
 ) !default;
 
 /// Organisation colour aliases
@@ -206,8 +362,6 @@ $govuk-colours-organisations: (
 /// @access private
 
 $_govuk-colours-organisations-aliases: (
-  // Various keys used to include the word 'and' when most others did not.
-  // We removed all the extra 'and's.
   "department-for-business-and-trade": "department-for-business-trade",
   "department-for-communities-and-local-government": "department-for-communities-local-government",
   "department-for-levelling-up-housing-and-communities": "department-for-levelling-up-housing-communities"
diff --git a/src/govuk/settings/colours.unit.test.js b/src/govuk/settings/colours.unit.test.js
index 5bcf9e2407..e542e80fee 100644
--- a/src/govuk/settings/colours.unit.test.js
+++ b/src/govuk/settings/colours.unit.test.js
@@ -2,6 +2,35 @@ const { compileSassString } = require('@govuk-frontend/helpers/tests')
 
 describe('Organisation colours', () => {
   it('should define websafe colours that meet contrast requirements', async () => {
+    const sass = `
+      $govuk-new-organisation-colours: true;
+
+      @import "settings/colours-palette";
+      @import "settings/colours-organisations";
+      @import "settings/colours-applied";
+      @import "helpers/colour";
+
+      @import "sass-color-helpers/stylesheets/color-helpers";
+
+      $minimum-contrast: 4.5;
+
+      @each $organisation in map-keys($govuk-colours-organisations) {
+
+        $colour: govuk-organisation-colour($organisation);
+        $contrast: ch-color-contrast($govuk-body-background-colour, $colour);
+
+        @if ($contrast < $minimum-contrast) {
+          @error "Contrast ratio for #{$organisation} too low."
+          + " #{$colour} on #{$govuk-body-background-colour} has a contrast of: #{$contrast}."
+          + " Must be higher than #{$minimum-contrast} for WCAG AA support.";
+        }
+      }
+    `
+
+    await expect(compileSassString(sass)).resolves
+  })
+
+  it('should define websafe colours that meet contrast requirements (legacy colours)', async () => {
     const sass = `
       @import "settings/colours-palette";
       @import "settings/colours-organisations";

From 46dea9d88c0466ba113ce803858d84abea32a7d9 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Fri, 23 Feb 2024 16:38:00 +0000
Subject: [PATCH 09/13] Add DExEU to list of organisations

---
 src/govuk/settings/_colours-organisations.scss | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/src/govuk/settings/_colours-organisations.scss b/src/govuk/settings/_colours-organisations.scss
index f8f57c5180..7c89fc7a19 100644
--- a/src/govuk/settings/_colours-organisations.scss
+++ b/src/govuk/settings/_colours-organisations.scss
@@ -78,6 +78,11 @@ $_govuk-organisation-colours: (
     colour: #00af43,
     contrast-safe: #008733
   ),
+  "department-for-exiting-the-european-union": (
+    colour: #009fe3,
+    contrast-safe: #007db6,
+    deprecation-message: "`department-for-exiting-the-european-union` was dissolved in 2020."
+  ),
   "department-for-international-development": (
     colour: #002878,
     deprecation-message:

From 50e7dd7872a32a5139b1a560c2fbbf9da2dd3b94 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Fri, 23 Feb 2024 16:39:20 +0000
Subject: [PATCH 10/13] Fix organisation colour deprecations not being
 suppressable

---
 src/govuk/helpers/_colour.scss | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/govuk/helpers/_colour.scss b/src/govuk/helpers/_colour.scss
index ed6c578540..fc17e9fa9b 100644
--- a/src/govuk/helpers/_colour.scss
+++ b/src/govuk/helpers/_colour.scss
@@ -77,9 +77,9 @@
 
   $org-colour: map-get($govuk-colours-organisations, $organisation);
 
-  @if map-has-key($org-colour, deprecation-message) {
+  @if map-has-key($org-colour, deprecation-message) and not index($govuk-suppressed-warnings, "organisation-colours") {
     @warn _warning-text(
-      "organisation-colour-websafe-param",
+      "organisation-colours",
       map-get($org-colour, deprecation-message)
     );
   }

From 8908ba3366dfc3b7e1a0fc35396f7c8a09e6157b Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Mon, 15 Apr 2024 13:48:37 +0100
Subject: [PATCH 11/13] Fix outdated test

---
 src/govuk/helpers/colour.unit.test.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/govuk/helpers/colour.unit.test.js b/src/govuk/helpers/colour.unit.test.js
index 58ce873091..beaefdf3ca 100644
--- a/src/govuk/helpers/colour.unit.test.js
+++ b/src/govuk/helpers/colour.unit.test.js
@@ -208,7 +208,7 @@ describe('@function govuk-organisation-colour', () => {
     // argument, which should be the deprecation notice
     expect(mockWarnFunction.mock.calls[0]).toEqual(
       expect.arrayContaining([
-        'The House Elf Equalities Office was disbanded in 2007. To silence this warning, update $govuk-suppressed-warnings with key: "organisation-colour-websafe-param"'
+        'The House Elf Equalities Office was disbanded in 2007. To silence this warning, update $govuk-suppressed-warnings with key: "organisation-colours"'
       ])
     )
   })

From 3019b16b0f24edc4bd57a7ea44755cfddf5fe13d Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Fri, 12 Jul 2024 09:47:48 +0100
Subject: [PATCH 12/13] Update for DLUHC -> MHCLG name change

---
 src/govuk/settings/_colours-organisations.scss | 11 +++++------
 1 file changed, 5 insertions(+), 6 deletions(-)

diff --git a/src/govuk/settings/_colours-organisations.scss b/src/govuk/settings/_colours-organisations.scss
index 7c89fc7a19..779f671409 100644
--- a/src/govuk/settings/_colours-organisations.scss
+++ b/src/govuk/settings/_colours-organisations.scss
@@ -57,7 +57,7 @@ $_govuk-organisation-colours: (
     colour: #009999,
     contrast-safe: #008080,
     deprecation-message:
-      "`department-for-communities-local-government` became `ministry-of-housing-communities-local-government` in 2018. As of 2021, it is equivalent to `department-for-levelling-up-housing-communities`."
+      "`department-for-communities-local-government` became `ministry-of-housing-communities-local-government` in 2018."
   ),
   "department-for-culture-media-sport": (
     colour: #d6006e
@@ -93,7 +93,9 @@ $_govuk-organisation-colours: (
     deprecation-message: "`department-for-international-trade` was merged into `department-for-business-trade` in 2023."
   ),
   "department-for-levelling-up-housing-communities": (
-    colour: #012169
+    colour: #012169,
+    deprecation-message:
+      "`department-for-levelling-up-housing-communities` was renamed to `ministry-of-housing-communities-local-government` in 2024."
   ),
   "department-for-science-innovation-technology": (
     colour: #00f9f8,
@@ -148,10 +150,7 @@ $_govuk-organisation-colours: (
     colour: #532a45
   ),
   "ministry-of-housing-communities-local-government": (
-    colour: #009999,
-    contrast-safe: #008080,
-    deprecation-message:
-      "`ministry-of-housing-communities-local-government` became `department-for-levelling-up-housing-communities` in 2021."
+    colour: #00625e
   ),
   "ministry-of-justice": (
     colour: #000000

From f127925d672344abff62d95a7c18f8088281fd30 Mon Sep 17 00:00:00 2001
From: beeps <hi+github@berly.kim>
Date: Tue, 6 Aug 2024 10:09:47 +0100
Subject: [PATCH 13/13] Clean up various parts

- Update review app example for 2024 MOG change
- Rename organisation colour test to match what is actually being tested
- Move incorrectly located changelog entry
---
 src/govuk/settings/colours.unit.test.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/govuk/settings/colours.unit.test.js b/src/govuk/settings/colours.unit.test.js
index e542e80fee..b3ae3c4979 100644
--- a/src/govuk/settings/colours.unit.test.js
+++ b/src/govuk/settings/colours.unit.test.js
@@ -1,7 +1,7 @@
 const { compileSassString } = require('@govuk-frontend/helpers/tests')
 
 describe('Organisation colours', () => {
-  it('should define websafe colours that meet contrast requirements', async () => {
+  it('should define contrast-safe colours that meet contrast requirements', async () => {
     const sass = `
       $govuk-new-organisation-colours: true;