From 31f1a70b421763887366223f5c29a0da3e9344eb Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Thu, 18 Apr 2019 17:07:41 +0100
Subject: [PATCH 01/13] Add new palette and toggle for legacy palette

---
 src/settings/_colours-palette.scss | 71 +++++++++++++++++++++++++++---
 1 file changed, 65 insertions(+), 6 deletions(-)

diff --git a/src/settings/_colours-palette.scss b/src/settings/_colours-palette.scss
index 898e50824b..3d6abcbb46 100644
--- a/src/settings/_colours-palette.scss
+++ b/src/settings/_colours-palette.scss
@@ -2,16 +2,26 @@
 /// @group settings/colours
 ////
 
-/// Colour palette
-///
-/// @type Map
+/// Use 'legacy' colour palette
 ///
-/// @prop $colour - Representation for the given $colour, where $colour is the
-///   friendly name for the colour (e.g. "red": #ff0000);
+/// Whether or not to use the colour palette from GOV.UK Elements / Frontend
+/// Toolkit, for teams that are migrating to GOV.UK Frontend and may be using
+/// components from both places in a single application.
 ///
+/// @type Boolean
 /// @access public
 
-$govuk-colours: (
+$govuk-use-legacy-palette: true !default;
+
+/// Legacy colour palette
+///
+/// This exists only because you cannot easily set a !default variable
+/// conditionally (thanks to the way scope works in Sass) so we set
+/// `$govuk-colour-palette` using the `if` function.
+///
+/// @access private
+
+$_govuk-colour-palette-legacy: (
   "purple": #2e358b,
   "light-purple": #6f72af,
   "bright-purple": #912b88,
@@ -34,4 +44,53 @@ $govuk-colours: (
   "grey-3": #dee0e2,
   "grey-4": #f8f8f8,
   "white": #ffffff
+);
+
+/// Modern colour palette
+///
+/// This exists only because you cannot easily set a !default variable
+/// conditionally (thanks to the way scope works in Sass) so we set
+/// `$govuk-colour-palette` using the `if` function.
+///
+/// @access private
+
+$_govuk-colour-palette-modern: (
+  "red": #d4351c,
+  "yellow": #ffdd00,
+  "green": #00703c,
+  "blue": #1d70b8,
+  "dark-blue": #003078,
+  "light-blue": #5694ca,
+
+  "black": #0b0c0c,
+  "dark-grey": #6f777b,
+  "mid-grey": #b1b4b6,
+  "light-grey": #f3f2f1,
+  "white": #ffffff,
+
+  "purple": #2e358b,
+  "light-purple": #6f72af,
+  "bright-purple": #912b88,
+  "pink": #d53880,
+  "light-pink": #f499be,
+  "bright-red": #df3034,
+  "orange": #f47738,
+  "brown": #b58840,
+  "light-green": #85994b,
+  "turquoise": #28a197
+);
+
+/// Colour palette
+///
+/// @type Map
+///
+/// @prop $colour - Representation for the given $colour, where $colour is the
+///   friendly name for the colour (e.g. "red": #ff0000);
+///
+/// @access public
+
+$govuk-colours: if(
+  $govuk-use-legacy-palette,
+  $_govuk-colour-palette-legacy,
+  $_govuk-colour-palette-modern
 ) !default;

From e9c9b7f672dab1e6213056ab774a0148ed3d051a Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:12:14 +0100
Subject: [PATCH 02/13] Allow govuk-colour function to return 'legacy' colours

This will allow us to maintain the existing colour palette for users of GOV.UK Frontend who are migrating, and using it alongside GOV.UK Elements, Template or Frontend Toolkit.
---
 src/helpers/_colour.scss   |  23 +++++-
 src/helpers/colour.test.js | 147 ++++++++++++++++++++++++++++++++++---
 2 files changed, 160 insertions(+), 10 deletions(-)

diff --git a/src/helpers/_colour.scss b/src/helpers/_colour.scss
index e2a34153d6..2fc311e73c 100644
--- a/src/helpers/_colour.scss
+++ b/src/helpers/_colour.scss
@@ -9,11 +9,32 @@
 ///
 /// @param {String} $colour - Name of colour from the colour palette
 ///   (`$govuk-colours`)
+/// @param {String} $legacy - Either the name of colour from the legacy palette
+///   or a colour literal, to return instead when in 'legacy mode' - matching
+///   the palette from GOV.UK Template, Elements or Frontend Toolkit
 /// @return {Colour} Representation of named colour
+///
+/// @example scss - Using legacy colours from the palette
+///  .foo {
+///    background-colour: govuk-colour("mid-grey", $legacy: "grey-2");
+///  }
+///
+/// @example scss - Using legacy colour literals
+///  .foo {
+///    background-colour: govuk-colour("green", $legacy: #BADA55);
+///  }
+///
 /// @throw if `$colour` is not a colour from the colour palette
 /// @access public
 
-@function govuk-colour($colour) {
+@function govuk-colour($colour, $legacy: false) {
+  @if ($govuk-use-legacy-palette and $legacy) {
+    @if (type-of($legacy) == "color") {
+      @return $legacy;
+    }
+    $colour: $legacy;
+  }
+
   $colour: quote($colour);
 
   @if not map-has-key($govuk-colours, $colour) {
diff --git a/src/helpers/colour.test.js b/src/helpers/colour.test.js
index f619ddf889..dc99ae9bdf 100644
--- a/src/helpers/colour.test.js
+++ b/src/helpers/colour.test.js
@@ -13,15 +13,19 @@ const sassConfig = {
 }
 
 describe('@function govuk-colour', () => {
-  const sassBootstrap = `
-    $govuk-colours: (
-      "red": #ff0000,
-      "green": #00ff00,
-      "blue": #0000ff
-    );
-
-    @import "helpers/colour";
-  `
+  let sassBootstrap = ``
+
+  beforeEach(() => {
+    sassBootstrap = `
+      $govuk-colours: (
+        "red": #ff0000,
+        "green": #00ff00,
+        "blue": #0000ff
+      );
+
+      @import "helpers/colour";
+    `
+  })
 
   it('returns a colour from the colour palette', async () => {
     const sass = `
@@ -63,6 +67,131 @@ describe('@function govuk-colour', () => {
         'Unknown colour `hooloovoo`'
       )
   })
+
+  describe('when $govuk-use-legacy-palette is true', () => {
+    beforeEach(() => {
+      sassBootstrap = `
+        $govuk-use-legacy-palette: true;
+        ${sassBootstrap}
+      `
+    })
+
+    it('returns the legacy colour if specified', async () => {
+      const sass = `
+        ${sassBootstrap}
+
+        .foo {
+          color: govuk-colour('red', $legacy: 'blue');
+        }`
+
+      const results = await sassRender({ data: sass, ...sassConfig })
+
+      expect(results.css.toString().trim()).toBe('.foo { color: #0000ff; }')
+    })
+
+    it('returns the legacy literal if specified', async () => {
+      const sass = `
+        ${sassBootstrap}
+
+        .foo {
+          color: govuk-colour('red', $legacy: #BADA55);
+        }`
+
+      const results = await sassRender({ data: sass, ...sassConfig })
+
+      expect(results.css.toString().trim()).toBe('.foo { color: #BADA55; }')
+    })
+
+    it('does not error if the non-legacy colour does not exist', async () => {
+      const sass = `
+        ${sassBootstrap}
+
+        .foo {
+          color: govuk-colour('hooloovoo', $legacy: 'blue');
+        }`
+
+      const results = await sassRender({ data: sass, ...sassConfig })
+
+      expect(results.css.toString().trim()).toBe('.foo { color: #0000ff; }')
+    })
+
+    it('throws an error if the legacy colour does not exist', async () => {
+      const sass = `
+        ${sassBootstrap}
+        .foo {
+          color: govuk-colour('red', $legacy: 'hooloovoo');
+        }`
+
+      await expect(sassRender({ data: sass, ...sassConfig }))
+        .rejects
+        .toThrow(
+          'Unknown colour `hooloovoo`'
+        )
+    })
+  })
+
+  describe('when $govuk-use-legacy-palette is false', () => {
+    beforeEach(() => {
+      sassBootstrap = `
+        $govuk-use-legacy-palette: false;
+        ${sassBootstrap}
+      `
+    })
+
+    it('does not return the legacy colour', async () => {
+      const sass = `
+        ${sassBootstrap}
+
+        .foo {
+          color: govuk-colour('red', $legacy: 'blue');
+        }`
+
+      const results = await sassRender({ data: sass, ...sassConfig })
+
+      expect(results.css.toString().trim()).toBe('.foo { color: #ff0000; }')
+    })
+
+    it('does not returns the legacy literal when specified', async () => {
+      const sass = `
+        ${sassBootstrap}
+
+        .foo {
+          color: govuk-colour('red', $legacy: #BADA55);
+        }`
+
+      const results = await sassRender({ data: sass, ...sassConfig })
+
+      expect(results.css.toString().trim()).toBe('.foo { color: #ff0000; }')
+    })
+
+    it('throws an error if the non-legacy colour does not exist', async () => {
+      const sass = `
+        ${sassBootstrap}
+
+        .foo {
+          color: govuk-colour('hooloovoo', $legacy: 'blue');
+        }`
+
+      await expect(sassRender({ data: sass, ...sassConfig }))
+        .rejects
+        .toThrow(
+          'Unknown colour `hooloovoo`'
+        )
+    })
+
+    it('does not error if the legacy colour does not exist', async () => {
+      const sass = `
+        ${sassBootstrap}
+
+        .foo {
+          color: govuk-colour('red', $legacy: 'hooloovoo');
+        }`
+
+      const results = await sassRender({ data: sass, ...sassConfig })
+
+      expect(results.css.toString().trim()).toBe('.foo { color: #ff0000; }')
+    })
+  })
 })
 
 describe('@function govuk-organisation-colour', () => {

From d2b4f581f57883de9c4000300848f2a42e41a12b Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:13:18 +0100
Subject: [PATCH 03/13] Remove 'bright red' from modern palette

We are removing this because the red in the palette has been updated, and there is now very little difference between 'red' and 'bright red'.
---
 src/settings/_colours-palette.scss | 1 -
 1 file changed, 1 deletion(-)

diff --git a/src/settings/_colours-palette.scss b/src/settings/_colours-palette.scss
index 3d6abcbb46..b723c6f0b6 100644
--- a/src/settings/_colours-palette.scss
+++ b/src/settings/_colours-palette.scss
@@ -73,7 +73,6 @@ $_govuk-colour-palette-modern: (
   "bright-purple": #912b88,
   "pink": #d53880,
   "light-pink": #f499be,
-  "bright-red": #df3034,
   "orange": #f47738,
   "brown": #b58840,
   "light-green": #85994b,

From 79eb57113d3fd81aadbb43cdc5ebb3002973f972 Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:14:03 +0100
Subject: [PATCH 04/13] Update purple to match the visited link colour

---
 src/settings/_colours-palette.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/settings/_colours-palette.scss b/src/settings/_colours-palette.scss
index b723c6f0b6..c7b6c03ec0 100644
--- a/src/settings/_colours-palette.scss
+++ b/src/settings/_colours-palette.scss
@@ -61,6 +61,7 @@ $_govuk-colour-palette-modern: (
   "blue": #1d70b8,
   "dark-blue": #003078,
   "light-blue": #5694ca,
+  "purple": #4c2c92,
 
   "black": #0b0c0c,
   "dark-grey": #6f777b,
@@ -68,7 +69,6 @@ $_govuk-colour-palette-modern: (
   "light-grey": #f3f2f1,
   "white": #ffffff,
 
-  "purple": #2e358b,
   "light-purple": #6f72af,
   "bright-purple": #912b88,
   "pink": #d53880,

From 8f69c94a5363909c957a21f20d949b0cb58d9779 Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:17:28 +0100
Subject: [PATCH 05/13] Update 'applied' colour palette

---
 src/settings/_colours-applied.scss | 14 +++++++-------
 1 file changed, 7 insertions(+), 7 deletions(-)

diff --git a/src/settings/_colours-applied.scss b/src/settings/_colours-applied.scss
index e09ea81c9b..ba1777bb30 100644
--- a/src/settings/_colours-applied.scss
+++ b/src/settings/_colours-applied.scss
@@ -31,7 +31,7 @@ $govuk-text-colour: govuk-colour("black") !default;
 /// @type Colour
 /// @access public
 
-$govuk-canvas-background-colour: govuk-colour("grey-3") !default;
+$govuk-canvas-background-colour: govuk-colour("light-grey", $legacy: "grey-3") !default;
 
 /// Body background colour
 ///
@@ -56,7 +56,7 @@ $govuk-print-text-colour: #000000 !default;
 /// @type Colour
 /// @access public
 
-$govuk-secondary-text-colour: govuk-colour("grey-1") !default;
+$govuk-secondary-text-colour: govuk-colour("dark-grey", $legacy: "grey-1") !default;
 
 /// Focus colour
 ///
@@ -94,7 +94,7 @@ $govuk-error-colour: govuk-colour("red") !default;
 /// @type Colour
 /// @access public
 
-$govuk-border-colour: govuk-colour("grey-2") !default;
+$govuk-border-colour: govuk-colour("mid-grey", $legacy: "grey-2");
 
 /// Input border colour
 ///
@@ -112,7 +112,7 @@ $govuk-input-border-colour: govuk-colour("black") !default;
 /// @type Colour
 /// @access public
 
-$govuk-hover-colour: govuk-colour("grey-3") !default;
+$govuk-hover-colour: govuk-colour("mid-grey", $legacy: "grey-3");
 
 
 // =============================================================================
@@ -131,18 +131,18 @@ $govuk-link-colour: govuk-colour("blue") !default;
 /// @type Colour
 /// @access public
 
-$govuk-link-visited-colour: #4c2c92 !default;
+$govuk-link-visited-colour: govuk-colour("purple", $legacy: #4c2c92) !default;
 
 /// Link hover colour
 ///
 /// @type Colour
 /// @access public
 
-$govuk-link-hover-colour: govuk-colour("light-blue") !default;
+$govuk-link-hover-colour: govuk-colour("dark-blue", $legacy: "light-blue") !default;
 
 /// Active link colour
 ///
 /// @type Colour
 /// @access public
 
-$govuk-link-active-colour: govuk-colour("light-blue") !default;
+$govuk-link-active-colour: govuk-colour("black", $legacy: "light-blue") !default;

From 3dee0379306a04958e203f4a3d0100d25ad7c534 Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:30:15 +0100
Subject: [PATCH 06/13] Update footer component to use new palette

---
 src/components/footer/_footer.scss | 44 ++++++++++++++++++++++--------
 1 file changed, 33 insertions(+), 11 deletions(-)

diff --git a/src/components/footer/_footer.scss b/src/components/footer/_footer.scss
index f113a8a802..09604bbf20 100644
--- a/src/components/footer/_footer.scss
+++ b/src/components/footer/_footer.scss
@@ -7,11 +7,24 @@
 @include govuk-exports("govuk/component/footer") {
 
   $govuk-footer-background: $govuk-canvas-background-colour;
-  $govuk-footer-border-top: #a1acb2;
-  $govuk-footer-border: govuk-colour("grey-2");
-  $govuk-footer-text: #454a4c;
+  $govuk-footer-border: $govuk-border-colour;
+  // This variable can be removed entirely once the legacy palette goes away,
+  // as it'll just be the same as $govuk-footer-border.
+  $govuk-footer-border-top: $govuk-border-colour;
+  $govuk-footer-text: $govuk-text-colour;
   $govuk-footer-link: $govuk-footer-text;
-  $govuk-footer-link-hover: #171819;
+  $govuk-footer-link-hover: false;
+
+  @if ($govuk-use-legacy-palette) {
+    // sass-lint:disable no-color-literals
+    $govuk-footer-border-top: #a1acb2;
+    $govuk-footer-border: govuk-colour("grey-2");
+    $govuk-footer-text: #454a4c;
+    $govuk-footer-link: $govuk-footer-text;
+
+    // Only used with the legacy palette
+    $govuk-footer-link-hover: #171819;
+  }
 
   // Based on the govuk-crest-2x.png image dimensions.
   $govuk-footer-crest-image-width-2x: 250px;
@@ -33,14 +46,23 @@
   .govuk-footer__link {
     @include govuk-focusable-fill;
 
-    &:link,
-    &:visited {
-      color: $govuk-footer-link;
-    }
+    @if ($govuk-use-legacy-palette) {
+      &:link,
+      &:visited {
+        color: $govuk-footer-link;
+      }
 
-    &:hover,
-    &:active {
-      color: $govuk-footer-link-hover;
+      &:hover,
+      &:active {
+        color: $govuk-footer-link-hover;
+      }
+    } @else {
+      &:link,
+      &:visited,
+      &:hover,
+      &:active {
+        color: $govuk-footer-link;
+      }
     }
 
     // When focussed, the text colour needs to be darker to ensure that colour

From b86845bfcb81a99620c6e697599428a23e10ee68 Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:31:37 +0100
Subject: [PATCH 07/13] Update accordions to use new grey

The hover style for this component will eventually change, but to keep changes contained we're just updating it with the closest colour right now.
---
 src/components/accordion/_accordion.scss | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/src/components/accordion/_accordion.scss b/src/components/accordion/_accordion.scss
index 4e72fe2afb..668f45ba20 100644
--- a/src/components/accordion/_accordion.scss
+++ b/src/components/accordion/_accordion.scss
@@ -92,7 +92,8 @@
 
     // Section headers have a grey background on hover as an additional affodance
     .govuk-accordion__section-header:hover {
-      background-color: govuk-colour("grey-4");
+      background-color: govuk-colour("light-grey", $legacy: "grey-4");
+
       // For devices that can't hover such as touch devices,
       // remove hover state as it can be stuck in that state (iOS).
       @media (hover: none) {

From 2d20b27aaf13bc1ace71e3869955a44f68fb125d Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:31:50 +0100
Subject: [PATCH 08/13] Update tabs to use new grey

---
 src/components/tabs/_tabs.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/tabs/_tabs.scss b/src/components/tabs/_tabs.scss
index 79db524e04..bbb61e7fe5 100644
--- a/src/components/tabs/_tabs.scss
+++ b/src/components/tabs/_tabs.scss
@@ -82,7 +82,7 @@
         padding-left: govuk-spacing(4);
         float: left;
         color: govuk-colour("black");
-        background-color: govuk-colour("grey-4");
+        background-color: govuk-colour("light-grey", $legacy: "grey-4");
         text-align: center;
         text-decoration: none;
 

From 6af6a92b3a7f3c8c8d4c45f24f7c7c9befbc781a Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:32:00 +0100
Subject: [PATCH 09/13] Update tags to use new grey

---
 src/components/tag/_tag.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/tag/_tag.scss b/src/components/tag/_tag.scss
index d3fe9b10d5..b7e78161bb 100644
--- a/src/components/tag/_tag.scss
+++ b/src/components/tag/_tag.scss
@@ -28,6 +28,6 @@
   }
 
   .govuk-tag--inactive {
-    background-color: govuk-colour("grey-1");
+    background-color: govuk-colour("dark-grey", $legacy: "grey-1");
   }
 }

From 241d7abd8b2d958fb0d2d2eac0d964a84b267688 Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:32:30 +0100
Subject: [PATCH 10/13] Update button to use new green from the palette
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Finally.

🎉
---
 src/components/button/_button.scss | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/components/button/_button.scss b/src/components/button/_button.scss
index d132662375..fdc6760bcc 100644
--- a/src/components/button/_button.scss
+++ b/src/components/button/_button.scss
@@ -3,14 +3,13 @@
 @import "../../helpers/all";
 
 @include govuk-exports("govuk/component/button") {
-  // Primary button variables
-  $govuk-button-colour: #00823b; // sass-lint:disable no-color-literals
+  $govuk-button-colour: govuk-colour("green", $legacy: #00823b); // sass-lint:disable no-color-literals
   $govuk-button-hover-colour: govuk-shade($govuk-button-colour, 20%);
   $govuk-button-shadow-colour: govuk-shade($govuk-button-colour, 60%);
   $govuk-button-text-colour: govuk-colour("white");
 
   // Secondary button variables
-  $govuk-secondary-button-colour: govuk-colour("grey-3");
+  $govuk-secondary-button-colour: govuk-colour("light-grey", $legacy: "grey-3");
   $govuk-secondary-button-hover-colour: govuk-shade($govuk-secondary-button-colour, 10%);
   $govuk-secondary-button-shadow-colour: govuk-shade($govuk-secondary-button-colour, 40%);
   $govuk-secondary-button-text-colour: govuk-colour("black");

From bb63dba1308060c9840aba04abc4c81657a0fa80 Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:34:50 +0100
Subject: [PATCH 11/13] Update panel to use green background

This addresses an issue with low colour contrast between the text (white) and the background (turquoise) whilst simplifying the palette
---
 src/components/panel/_panel.scss | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/components/panel/_panel.scss b/src/components/panel/_panel.scss
index 7215b527e4..d0267f7fc5 100644
--- a/src/components/panel/_panel.scss
+++ b/src/components/panel/_panel.scss
@@ -23,7 +23,7 @@
 
   .govuk-panel--confirmation {
     color: govuk-colour("white");
-    background: govuk-colour("turquoise");
+    background: govuk-colour("green", $legacy: "turquoise");
   }
 
   .govuk-panel__title {

From 351d11dd9f1e6d05efa8de1e6587cdf56d68d732 Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Tue, 23 Apr 2019 16:40:53 +0100
Subject: [PATCH 12/13] Link colour palette to compatibility mode

---
 src/helpers/_colour.scss           | 1 +
 src/settings/_colours-palette.scss | 6 +++++-
 src/settings/colours.test.js       | 1 +
 3 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/helpers/_colour.scss b/src/helpers/_colour.scss
index 2fc311e73c..b6f9ae708e 100644
--- a/src/helpers/_colour.scss
+++ b/src/helpers/_colour.scss
@@ -1,3 +1,4 @@
+@import "../settings/compatibility";
 @import "../settings/colours-palette";
 @import "../settings/colours-organisations";
 
diff --git a/src/settings/_colours-palette.scss b/src/settings/_colours-palette.scss
index c7b6c03ec0..4e16625147 100644
--- a/src/settings/_colours-palette.scss
+++ b/src/settings/_colours-palette.scss
@@ -11,7 +11,11 @@
 /// @type Boolean
 /// @access public
 
-$govuk-use-legacy-palette: true !default;
+$govuk-use-legacy-palette: if((
+    $govuk-compatibility-govukfrontendtoolkit or
+    $govuk-compatibility-govuktemplate or
+    $govuk-compatibility-govukelements
+  ), true, false) !default;
 
 /// Legacy colour palette
 ///
diff --git a/src/settings/colours.test.js b/src/settings/colours.test.js
index 15efd83f34..7c6f9ffa9f 100644
--- a/src/settings/colours.test.js
+++ b/src/settings/colours.test.js
@@ -15,6 +15,7 @@ const sassConfig = {
 describe('Organisation colours', () => {
   it('should define websafe colours that meet contrast requirements', async () => {
     const sass = `
+      @import "settings/compatibility";
       @import "settings/colours-palette";
       @import "settings/colours-organisations";
       @import "settings/colours-applied";

From 272d90327568110a61d004b3e547c80089417551 Mon Sep 17 00:00:00 2001
From: Oliver Byford <oliver.byford@digital.cabinet-office.gov.uk>
Date: Mon, 29 Apr 2019 14:58:28 +0100
Subject: [PATCH 13/13] Document in changelog

---
 CHANGELOG.md | 90 ++++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 88 insertions(+), 2 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 22e0c65b61..2827e5243c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,16 +4,100 @@
 
 💥 Breaking changes:
 
+- The colour palette has been updated.
+
+  **Note:** If you are using [compatibility mode], the existing palette will be
+  preserved.
+
+  Purple, red, yellow, green, blue and light blue have all been updated to new
+  colours.
+
+  Dark blue has been added, and bright red has been removed.
+
+  Greys 1-through-4 have been replaced with dark, mid and light-grey. As a
+  general rule of thumb, dark grey replaces grey-1 and is designed to be used as
+  a foreground colour; light grey replaces both grey-3 and grey-4 and is
+  designed to be used as a background colour, and mid-grey replaces grey-2 and
+  is designed to be used for borders.
+
+  To migrate you'll need to update any references to bright-red, grey-1, grey-2,
+  grey-3 or grey-4 to use the new colours from the palette.
+
+  | Colour        | Before    | After     | Notes                             |
+  | ------------- | --------- | --------- | --------------------------------- |
+  | purple        | `#2e358b` | `#4c2c92` | updated - matches visited links   |
+  | light-purple  | `#6f72af` | `#6f72af` |                                   |
+  | bright-purple | `#912b88` | `#912b88` |                                   |
+  | pink          | `#d53880` | `#d53880` |                                   |
+  | light-pink    | `#f499be` | `#f499be` |                                   |
+  | red           | `#b10e1e` | `#d4351c` | updated                           |
+  | bright-red    | `#df3034` |           | removed - similar to the new red  |
+  | orange        | `#f47738` | `#f47738` |                                   |
+  | brown         | `#b58840` | `#b58840` |                                   |
+  | yellow        | `#ffbf47` | `#ffdd00` | updated                           |
+  | light-green   | `#85994b` | `#85994b` |                                   |
+  | green         | `#006435` | `#00703c` | updated                           |
+  | turquoise     | `#28a197` | `#28a197` |                                   |
+  | light-blue    | `#2b8cc4` | `#5694ca` | updated                           |
+  | blue          | `#005ea5` | `#1d70b8` | updated                           |
+  | dark-blue     |           | `#003078` | added                             |
+  | black         | `#0b0c0c` | `#0b0c0c` |                                   |
+  | grey-1        | `#6f777b` |           | removed                           |
+  | dark-grey     |           | `#6f777b` | added                             |
+  | grey-2        | `#bfc1c3` |           | removed                           |
+  | mid-grey      |           | `#b1b4b6` | added                             |
+  | grey-3        | `#dee0e2` |           | removed                           |
+  | grey-4        | `#f8f8f8` |           | removed                           |
+  | light-grey    |           | `#f3f2f1` | added                             |
+  | white         | `#ffffff` | `#ffffff` |                                   |
+
+  ([PR #1288](https://github.com/alphagov/govuk-frontend/pull/1288))
+
+- The button component now uses the green from the colour palette, instead of
+  a custom green used only for the button.
+
+  **Note:** If you are using [compatibility mode], the existing button colour
+  will be preserved.
+
+  ([PR #1288](https://github.com/alphagov/govuk-frontend/pull/1288))
+
+- The confirmation panel now uses a green background rather than a turquoise
+  background.
+
+  **Note:** If you are using [compatibility mode], the existing turquoise panel
+  colour will be preserved.
+
+  ([PR #1288](https://github.com/alphagov/govuk-frontend/pull/1288))
+
+- Links now get darker when hovered, rather than lighter.
+
+  **Note:** If you are using [compatibility mode], the existing link hover style
+  will be preserved.
+
+  ([PR #1288](https://github.com/alphagov/govuk-frontend/pull/1288))
+
 - Pull Request Title goes here
 
   Description goes here (optional)
 
-  To migrate you need to change: X
-
   ([PR #N](https://github.com/alphagov/govuk-frontend/pull/N))
 
 🆕 New features:
 
+- A new setting `$govuk-use-legacy-palette` has been added, which by default
+  will be true if any of the `$govuk-compatibility-*` settings are true.
+
+  When set to `true`, the existing colour palette from v2.x of GOV.UK Frontend
+  will be used.
+
+  ([PR #1288](https://github.com/alphagov/govuk-frontend/pull/1288))
+
+- The `govuk-colour` function has been updated to add a `$legacy` argument,
+  which allows you to specify a colour (either a literal, or a name of a colour
+  from the legacy palette) to use when `$govuk-use-legacy-palette` is true.
+
+  ([PR #1288](https://github.com/alphagov/govuk-frontend/pull/1288))
+
 - Pull Request Title goes here
 
   Description goes here (optional)
@@ -28,6 +112,8 @@
 
   ([PR #N](https://github.com/alphagov/govuk-frontend/pull/N))
 
+[compatibility mode]: https://github.com/alphagov/govuk-frontend/blob/master/docs/installation/installing-with-npm.md#compatibility-mode
+
 ## 2.11.0 (Feature release)
 
 🆕 New features: