Merge pull request #3407 from alphagov/update-organisation-colours

Update organisation colours

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);
   }

src/govuk/helpers/colour.unit.test.js

@@ -103,20 +103,25 @@ describe('@function govuk-colour', () => {
 
 describe('@function govuk-organisation-colour', () => {
   const sassBootstrap = `
+    $govuk-new-organisation-colours: true;
     $govuk-colours-organisations: (
       'floo-network-authority': (
         colour: #EC22FF,
-        colour-websafe: #9A00A8
+        contrast-safe: #9A00A8
       ),
       'broom-regulatory-control': (
         colour: #A81223
+      ),
+      'house-elf-equalities-office': (
+        colour: #786999,
+        deprecation-message: 'The House Elf Equalities Office was disbanded in 2007.'
       )
     );
 
     @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}
 
@@ -134,7 +139,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}
 
@@ -152,7 +157,25 @@ 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}
 
@@ -170,6 +193,26 @@ 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. To silence this warning, update $govuk-suppressed-warnings with key: "organisation-colours"'
+      ])
+    )
+  })
+
   it('throws an error if a non-existent organisation is requested', async () => {
     const sass = `
       ${sassBootstrap}
@@ -183,4 +226,98 @@ 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;
+          }
+        `
+    })
+  })
+
+  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;
+          }
+        `
+      })
+    })
+  })
 })