Deprecate settings associated with compatibility mode

CHANGELOG.md

@@ -72,6 +72,19 @@ This will enable screen reader users to have a better, more coherent experience
 
 This was added in [pull request #2677: Amend error summary markup to fix page load focus bug in JAWS 2022](https://github.com/alphagov/govuk-frontend/pull/2677).
 
+### Deprecated features
+
+#### Stop using settings associated with legacy codebases
+
+In GOV.UK Frontend v5.0 we will stop supporting compatibility with legacy codebases. As part of this, we are deprecating settings controlled by compatibility mode variables. This includes the `govuk-compatibility` mixin and the following settings:
+
+- `$govuk-use-legacy-palette`
+- `$govuk-use-legacy-font`
+- `$govuk-typography-use-rem`
+- `$govuk-font-family-tabular`
+
+This was introduced in [pull request #2844: Deprecate compatibility mode settings](https://github.com/alphagov/govuk-frontend/pull/2844).
+
 ### Fixes
 
 We’ve made fixes to GOV.UK Frontend in the following pull requests:

src/govuk/components/button/_index.scss

@@ -119,7 +119,7 @@ $govuk-button-text-colour: govuk-colour("white") !default;
     // we need to override the text colour for that combination of selectors so
     // so that unvisited links styled as buttons do not end up with dark blue
     // text when focussed.
-    @include govuk-compatibility(govuk_template) {
+    @include _govuk-compatibility(govuk_template) {
       &:link:focus {
         color: $govuk-button-text-colour;
       }
@@ -202,7 +202,7 @@ $govuk-button-text-colour: govuk-colour("white") !default;
     // we need to override the text colour for that combination of selectors so
     // so that unvisited links styled as buttons do not end up with dark blue
     // text when focussed.
-    @include govuk-compatibility(govuk_template) {
+    @include _govuk-compatibility(govuk_template) {
       &:link:focus {
         color: $govuk-secondary-button-text-colour;
       }
@@ -234,7 +234,7 @@ $govuk-button-text-colour: govuk-colour("white") !default;
     // we need to override the text colour for that combination of selectors so
     // so that unvisited links styled as buttons do not end up with dark blue
     // text when focussed.
-    @include govuk-compatibility(govuk_template) {
+    @include _govuk-compatibility(govuk_template) {
       &:link:focus {
         color: $govuk-warning-button-text-colour;
       }

src/govuk/components/footer/_index.scss

@@ -52,7 +52,7 @@
     // alphagov/govuk_template includes a specific a:link:focus selector
     // designed to make unvisited links a slightly darker blue when focussed, so
     // we need to override the text colour for that combination of selectors.
-    @include govuk-compatibility(govuk_template) {
+    @include _govuk-compatibility(govuk_template) {
       &:link:focus {
         @include govuk-text-colour;
       }

src/govuk/components/table/_index.scss

@@ -21,7 +21,7 @@
     vertical-align: top;
     // GOV.UK Elements sets the font-size and line-height for all headers and cells
     // in tables.
-    @include govuk-compatibility(govuk_elements) {
+    @include _govuk-compatibility(govuk_elements) {
       font-size: inherit;
       line-height: inherit;
     }

src/govuk/core/_section-break.scss

@@ -6,7 +6,7 @@
 
     // fix double-width section break and forced visible section break
     // when combined with styles from alphagov/elements
-    @include govuk-compatibility(govuk_elements) {
+    @include _govuk-compatibility(govuk_elements) {
       height: 0;
     }
   }

src/govuk/helpers/_links.scss

@@ -102,7 +102,7 @@
   // we need to override the text colour for that combination of selectors so
   // so that unvisited links styled as buttons do not end up with dark blue
   // text when focussed.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       color: $govuk-focus-text-colour;
     }
@@ -150,7 +150,7 @@
   // we need to override the text colour for that combination of selectors so
   // so that unvisited links styled as buttons do not end up with dark blue
   // text when focussed.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       color: $govuk-focus-text-colour;
     }
@@ -198,7 +198,7 @@
   // we need to override the text colour for that combination of selectors so
   // so that unvisited links styled as buttons do not end up with dark blue
   // text when focussed.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       color: $govuk-focus-text-colour;
     }
@@ -241,7 +241,7 @@
   // alphagov/govuk_template includes a specific a:link:focus selector designed
   // to make unvisited links a slightly darker blue when focussed, so we need to
   // override the text colour for that combination of selectors.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       @include govuk-text-colour;
     }
@@ -286,7 +286,7 @@
   // alphagov/govuk_template includes a specific a:link:focus selector designed
   // to make unvisited links a slightly darker blue when focussed, so we need to
   // override the text colour for that combination of selectors.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       @include govuk-text-colour;
     }
@@ -329,7 +329,7 @@
   // alphagov/govuk_template includes a specific a:link:focus selector designed
   // to make unvisited links a slightly darker blue when focussed, so we need to
   // override the text colour for that combination of selectors.
-  @include govuk-compatibility(govuk_template) {
+  @include _govuk-compatibility(govuk_template) {
     &:link:focus {
       color: $govuk-focus-text-colour;
     }

src/govuk/helpers/colour.test.js

@@ -1,7 +1,16 @@
+const sass = require('node-sass')
 const { renderSass } = require('../../../lib/jest-helpers')
 
+// 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(sass.NULL)
+
 const sassConfig = {
-  outputStyle: 'compact'
+  outputStyle: 'compact',
+  functions: {
+    '@warn': mockWarnFunction
+  }
 }
 
 describe('@function govuk-colour', () => {
@@ -120,6 +129,20 @@ describe('@function govuk-colour', () => {
           'Unknown colour `hooloovoo`'
         )
     })
+
+    it('outputs a deprecation warning when set to true', async () => {
+      const sass = `${sassBootstrap}`
+
+      await renderSass({ data: sass, ...sassConfig }).then(() => {
+        // Expect our mocked @warn function to have been called once with a single
+        // argument, which should be the deprecation notice
+        return expect(mockWarnFunction.mock.calls[0][0].getValue())
+          .toEqual(
+            '$govuk-use-legacy-palette is deprecated. ' +
+            'Only the modern colour palette will be supported from v5.0'
+          )
+      })
+    })
   })
 
   describe('when $govuk-use-legacy-palette is false', () => {

src/govuk/helpers/typography.test.js

@@ -1,9 +1,18 @@
-const outdent = require('outdent')
 
+const sass = require('node-sass')
+const outdent = require('outdent')
 const { renderSass } = require('../../../lib/jest-helpers')
 
+// 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(sass.NULL)
+
 const sassConfig = {
-  outputStyle: 'nested'
+  outputStyle: 'nested',
+  functions: {
+    '@warn': mockWarnFunction
+  }
 }
 
 const sassBootstrap = `
@@ -391,6 +400,22 @@ describe('@mixin govuk-typography-responsive', () => {
                 line-height: 1.42857 !important; } }`)
       })
     })
+
+    it('outputs a deprecation warning when set to false', async () => {
+      const sass = `
+        $govuk-typography-use-rem: false;
+        ${sassBootstrap}`
+
+      await renderSass({ data: sass, ...sassConfig }).then(() => {
+        // Get the argument of the last @warn call, which we expect to be the
+        // deprecation notice
+        return expect(mockWarnFunction.mock.calls.at(-1)[0].getValue())
+          .toEqual(
+            '$govuk-typography-use-rem is deprecated. ' +
+            'From version 5.0, GOV.UK Frontend will not support disabling rem font sizes'
+          )
+      })
+    })
   })
 
   describe('when compatibility mode is set', () => {
@@ -572,3 +597,22 @@ describe('@mixin govuk-typography-responsive', () => {
     })
   })
 })
+
+describe('$govuk-font-family-tabular value is specified', () => {
+  it('outputs a deprecation warning when set', async () => {
+    const sass = `
+    $govuk-font-family-tabular: monospace;
+      ${sassBootstrap}`
+
+    await renderSass({ data: sass, ...sassConfig }).then(() => {
+      // Get the argument of the last @warn call, which we expect to be the
+      // deprecation notice
+      return expect(mockWarnFunction.mock.calls.at(-1)[0].getValue())
+        .toEqual(
+          '$govuk-font-family-tabular is deprecated. ' +
+          'From version 5.0, GOV.UK Frontend will not support using a separate ' +
+          'font-face for tabular numbers'
+        )
+    })
+  })
+})

src/govuk/settings/_colours-palette.scss

@@ -15,6 +15,8 @@
 ///
 /// @type Boolean
 /// @access public
+/// @deprecated Will be removed in v5.0 with the rest of the compatibility mode
+/// suite of tools and settings
 
 $govuk-use-legacy-palette: if(
   (
@@ -26,6 +28,16 @@ $govuk-use-legacy-palette: if(
   false
 ) !default;
 
+// Only show the deprecation warning if user is setting $govuk-use-legacy-palette
+// manually instead of automatically via compatibility variables
+@if $govuk-use-legacy-palette == true and
+  $govuk-compatibility-govukfrontendtoolkit == false and
+  $govuk-compatibility-govuktemplate == false and
+  $govuk-compatibility-govukelements == false {
+  @warn "$govuk-use-legacy-palette is deprecated. " +
+    "Only the modern colour palette will be supported from v5.0";
+}
+
 /// Modern colour palette
 ///
 /// This exists only because you cannot easily set a !default variable

src/govuk/settings/_typography-font.scss

@@ -13,6 +13,8 @@
 ///
 /// @type Boolean
 /// @access public
+/// @deprecated Will be removed in v5.0 with the rest of the compatibility mode
+/// suite of tools and settings
 
 $govuk-use-legacy-font: if(
   (
@@ -24,6 +26,17 @@ $govuk-use-legacy-font: if(
   false
 ) !default;
 
+// Only show the deprecation warning if user is setting $govuk-use-legacy-font
+// manually instead of automatically via compatibility variables
+@if $govuk-use-legacy-font == true and
+  $govuk-compatibility-govukfrontendtoolkit == false and
+  $govuk-compatibility-govuktemplate == false and
+  $govuk-compatibility-govukelements == false {
+  @warn "$govuk-use-legacy-font is deprecated. " +
+    "From version 5.0, GOV.UK Frontend will only support the included version " +
+    "of GDS Transport";
+}
+
 // =========================================================
 // Font families
 // =========================================================
@@ -43,13 +56,23 @@ $govuk-font-family: if(
 ///
 /// @type List
 /// @access public
+/// @deprecated Will be removed in v5.0 with the rest of the compatibility mode
+/// suite of tools and settings
 
 $govuk-font-family-tabular: if(
   $govuk-use-legacy-font,
   $govuk-font-family-nta-tabular,
   false
 ) !default;
 
+// Only show the deprecation warning if user is setting $govuk-font-family-tabular
+// manually instead of automatically via $govuk-use-legacy-font
+@if $govuk-font-family-tabular != false and $govuk-use-legacy-font == false {
+  @warn "$govuk-font-family-tabular is deprecated. " +
+    "From version 5.0, GOV.UK Frontend will not support using a separate " +
+    "font-face for tabular numbers";
+}
+
 /// Font families to use for print media
 ///
 /// We recommend that you use system fonts when printing. This will avoid issues

src/govuk/settings/_typography-responsive.scss

@@ -13,6 +13,8 @@
 ///
 /// @type Boolean
 /// @access public
+/// @deprecated Will be removed in v5.0 with the rest of the compatibility mode
+/// suite of tools and settings
 
 $govuk-typography-use-rem: if(
   (
@@ -24,6 +26,16 @@ $govuk-typography-use-rem: if(
   true
 ) !default;
 
+// Only show the deprecation warning if user is setting $govuk-typography-use-rem
+// manually instead of automatically via compatibility variables
+@if $govuk-typography-use-rem == false and
+  $govuk-compatibility-govukfrontendtoolkit == false and
+  $govuk-compatibility-govuktemplate == false and
+  $govuk-compatibility-govukelements == false {
+  @warn "$govuk-typography-use-rem is deprecated. " +
+    "From version 5.0, GOV.UK Frontend will not support disabling rem font sizes";
+}
+
 /// Root font size
 ///
 /// This is used to calculate rem sizes for the typography, and should match the

src/govuk/tools/_compatibility.scss

@@ -2,6 +2,20 @@
 /// @group tools/compatibility-mode
 ////
 
+/// Temporary private version of govuk-compatibility to avoid deprecation warnings
+///
+/// @access private
+
+@mixin _govuk-compatibility($product) {
+  @if map-has-key($_govuk-compatibility, $product) {
+    @if map-get($_govuk-compatibility, $product) == true {
+      @content;
+    }
+  } @else {
+    @error "Non existent product '#{$product}'";
+  }
+}
+
 /// Conditional Compatibility Mixin
 ///
 /// Selectively output a block (available to the mixin as @content) if a given
@@ -24,13 +38,13 @@
 ///   this product
 /// @throw Errors if product name is not recognised
 /// @access public
+/// @deprecated Will be removed in v5.0 with the rest of the compatibility mode
+/// suite of tools and settings
 
 @mixin govuk-compatibility($product) {
-  @if map-has-key($_govuk-compatibility, $product) {
-    @if map-get($_govuk-compatibility, $product) == true {
-      @content;
-    }
-  } @else {
-    @error "Non existent product '#{$product}'";
+  @warn "govuk-compatibility is deprecated. " +
+    "From version 5.0, GOV.UK Frontend will not support compatibility mode";
+  @include _govuk-compatibility($product) {
+    @content;
   }
 }