Merge pull request #5627 from alphagov/deprecate-legacy-org-colours

Deprecate legacy organisation colour palette

CHANGELOG.md

@@ -4,6 +4,16 @@ For advice on how to use these release notes see [our guidance on staying up to
 
 ## Unreleased
 
+### Deprecated features
+
+#### Migrate to the new organisation colour palette
+
+The legacy organisation colour palette has been deprecated and will be removed in the next major version.
+
+If your service uses the organisation colour palette, make sure that things still look as expected with the `$govuk-new-organisation-colours` feature flag enabled.
+
+This change was introduced in [pull request #5627: Deprecate legacy organisation colour palette](https://github.com/alphagov/govuk-frontend/pull/5627).
+
 ### Fixes
 
 We've made fixes to GOV.UK Frontend in the following pull requests:

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

@@ -67,7 +67,7 @@
   }
 
   // Output a warning if $websafe is set.
-  @if $websafe and not index($govuk-suppressed-warnings, "organisation-colour-websafe-param") {
+  @if $websafe and _should-warn("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 " +
@@ -77,7 +77,7 @@
 
   $org-colour: map-get($govuk-colours-organisations, $organisation);
 
-  @if map-has-key($org-colour, deprecation-message) and not index($govuk-suppressed-warnings, "organisation-colours") {
+  @if map-has-key($org-colour, deprecation-message) and _should-warn("organisation-colours") {
     @warn _warning-text(
       "organisation-colours",
       map-get($org-colour, deprecation-message)

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

@@ -1,3 +1,5 @@
+@import "../settings/warnings";
+
 ////
 /// @group settings/colours
 ////
@@ -11,6 +13,7 @@
 ///
 /// @type Boolean
 /// @access public
+/// @deprecated Using new organisation colours will become the default in Frontend v6.0.
 
 $govuk-new-organisation-colours: false !default;
 
@@ -211,6 +214,7 @@ $_govuk-organisation-colours: (
 ///   nor provide better contrast than the base colour.
 ///
 /// @access private
+/// @deprecated Migrate to using the new organisation colour palette instead.
 
 $_govuk-legacy-organisation-colours: (
   "attorney-generals-office": (
@@ -349,11 +353,20 @@ $_govuk-legacy-organisation-colours: (
 /// @type Map
 /// @access public
 
-$govuk-colours-organisations: if(
-  $govuk-new-organisation-colours,
-  $_govuk-organisation-colours,
-  $_govuk-legacy-organisation-colours
-) !default;
+$govuk-colours-organisations: $_govuk-legacy-organisation-colours !default;
+
+@if $govuk-new-organisation-colours and $govuk-colours-organisations == $_govuk-legacy-organisation-colours {
+  $govuk-colours-organisations: $_govuk-organisation-colours;
+}
+
+// Output a deprecation warning if the legacy colour palette is being used.
+// Remove in next major version.
+@if $govuk-colours-organisations == $_govuk-legacy-organisation-colours {
+  @include _warning(
+    "legacy-organisation-colours",
+    "The legacy organisation colour palette has been deprecated and will be removed in the next major version."
+  );
+}
 
 /// Organisation colour aliases
 ///

packages/govuk-frontend/src/govuk/settings/colours.unit.test.js

@@ -1,4 +1,15 @@
 const { compileSassString } = require('@govuk-frontend/helpers/tests')
+const { sassNull } = require('sass-embedded')
+
+// Create a mock warn function that we can use to override the native @warn
+// function, that we can make assertions about post-render.
+const mockWarnFunction = jest.fn().mockReturnValue(sassNull)
+
+const sassConfig = {
+  logger: {
+    warn: mockWarnFunction
+  }
+}
 
 describe('Organisation colours', () => {
   it('should define contrast-safe colours that meet contrast requirements', async () => {
@@ -57,4 +68,49 @@ describe('Organisation colours', () => {
 
     await expect(compileSassString(sass)).resolves.not.toThrow()
   })
+
+  describe('legacy deprecation message', () => {
+    it('throws a deprecation warning if the legacy palette is being used', async () => {
+      const sass = `
+      @import "settings/colours-organisations";
+    `
+
+      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).toHaveBeenCalledWith(
+        'The legacy organisation colour palette has been deprecated and will be removed in the next major version. To silence this warning, update $govuk-suppressed-warnings with key: "legacy-organisation-colours"',
+        expect.anything()
+      )
+    })
+
+    it('does not throw a deprecation warning if the new palette is being used', async () => {
+      const sass = `
+      $govuk-new-organisation-colours: true;
+      @import "settings/colours-organisations";
+    `
+
+      await compileSassString(sass, sassConfig)
+
+      // Expect our mocked @warn function to have not been called
+      expect(mockWarnFunction).not.toHaveBeenCalled()
+    })
+
+    it('does not throw a deprecation warning if the palette has been customised', async () => {
+      const sass = `
+      $govuk-colours-organisations: (
+        "department-of-administrative-affairs": (
+          colour: "#226623"
+        )
+      );
+      @import "settings/colours-organisations";
+    `
+
+      await compileSassString(sass, sassConfig)
+
+      // Expect our mocked @warn function to have not been called
+      expect(mockWarnFunction).not.toHaveBeenCalled()
+    })
+  })
 })