Re-add and deprecate govuk-colour $legacy parameter

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

@@ -1,6 +1,7 @@
 @import "../settings/compatibility";
 @import "../settings/colours-palette";
 @import "../settings/colours-organisations";
+@import "../settings/warnings";
 
 ////
 /// @group helpers/colour
@@ -12,10 +13,22 @@
 ///   (`$govuk-colours`)
 /// @return {Colour} Representation of named colour
 ///
+/// @deprecated The `$legacy` parameter is deprecated and has been made
+///   non-operational, as the legacy colour palette has been removed.
+///   The parameter will be removed in the next major version.
+///
 /// @throw if `$colour` is not a colour from the colour palette
 /// @access public
 
-@function govuk-colour($colour) {
+@function govuk-colour($colour, $legacy: false) {
+  // Output a warning if $legacy is set to anything. This can't use the
+  // `_warning` mixin due to being a function, so we handle it manually.
+  @if $legacy and not index($govuk-suppressed-warnings, "legacy-palette") {
+    @warn "The `$legacy` parameter is deprecated and is non-operational. It " +
+      "will be removed in the next major version. To silence this warning, " +
+      "update $govuk-suppressed-warnings with key: \"legacy-palette\"";
+  }
+
   @if type-of($colour) == "color" {
     // stylelint-disable-next-line scss/function-quote-no-quoted-strings-inside
     $colour: quote("#{$colour}");

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

@@ -83,6 +83,27 @@ describe('@function govuk-colour', () => {
         'Unknown colour `hooloovoo`'
       )
   })
+
+  it('throws a deprecation warning if the $legacy parameter is used', async () => {
+    const sass = `
+      ${sassBootstrap}
+
+      .foo {
+        color: govuk-colour('red', $legacy: 'blue');
+      }
+    `
+
+    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 `$legacy` parameter is deprecated and is non-operational. It ' +
+        'will be removed in the next major version. To silence this warning, ' +
+        'update $govuk-suppressed-warnings with key: "legacy-palette"'
+      ]))
+  })
 })
 
 describe('@function govuk-organisation-colour', () => {