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.

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

@@ -62,6 +62,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 {

packages/govuk-frontend/src/govuk/helpers/colour.test.js

@@ -116,6 +116,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.'
       )
     );
 
@@ -182,6 +186,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}

packages/govuk-frontend/src/govuk/settings/_colours-organisations.scss

@@ -11,136 +11,163 @@
 ///   `$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-communities": (
+    colour: #012169
   ),
-  "department-for-levelling-up-housing-and-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;