Remove compatibility mode

[owenatgov]

What we'll do

We'll remove compatibility mode from GOV.UK Frontend.

Compatibility mode exists to make it easier for users to migrate from our old frameworks (GOV.UK Elements, GOV.UK Frontend Toolkit and GOV.UK Template).

When compatibility mode is enabled, GOV.UK Frontend:

• uses the old colour palette
• uses the old GOV.UK font from GOV.UK Template
• overrides some of the CSS in the legacy frameworks
• no longer uses rem for font sizes

Why we're doing it

We're making changes to the typography scale used in GOV.UK Frontend.

Without significant effort from us (to support two different typography scales), users who have enabled compatibility mode would see a mix of different sized text in their services.

Given that the Design System is now a live service and it's been nearly 5 years since the last release of GOV.UK Elements, we think it's now time to retire compatibility mode.

How this impacts our users

Teams that are still using our old frameworks will not be able to migrate directly to v5.0 or above. However, they will still have a migration path – they'll just need to finish migrating to the latest version of GOV.UK Frontend v4 (which will still support compatibility mode) and then upgrade to v5 in a separate step.

Epic lead

Owen

Who needs to work on this

Developers

Done when

In v4.x we will:

Tasks

Preview Give feedback

1. Investigate where compatibility mode is being used in govuk-frontend
2. Assess if there are any functions that compatibility mode facilitates that we want to keep
3. Deprecate settings managed by compatibility mode variables #2787
   tech debt +1
   
4. Allow users to suppress deprecation warnings #2890
   tech debt +1
   
5. Deprecate compatibility mode variables #2788
   tech debt +1
   
6. Let teams know we will be retiring compatibility mode in v5.0 #2789
   community tech debt +2
   
7. Update docs to identify compatibility mode information and associated variables, mixins and settings as unavailable from 5.0 govuk-frontend-docs#207
   Effort: hours +1
   

In v5.0 we will:

Tasks

Preview Give feedback

1. Remove px instead of rem setting from codebase #2790
   breaking change tech debt +2
   
2. Remove legacy font setting and tabular font separation setting from codebase #2791
   breaking change tech debt +2
   
3. Remove legacy colour palette setting from codebase #2792
   breaking change tech debt +2
   
4. Remove govuk-compatibility mixin from codebase #2793
   breaking change tech debt +2
   
5. Remove legacy design system implementations from the review app #2794
   tech debt +1
   
6. Remove compatibility mode variables #2795
   breaking change tech debt +2
   
7. Write up unified changelog entry for compatibility mode removal changes #3583
   documentation 🕔 hours +2
   

[owenatgov]

Where we use compatibility

The compatibility variables, excluding tests, are referenced in the following places:

• https://github.com/alphagov/govuk-frontend/blob/main/app/assets/scss/app-legacy-ie8.scss
• https://github.com/alphagov/govuk-frontend/blob/main/app/assets/scss/app-legacy.scss
• https://github.com/alphagov/govuk-frontend/blob/main/src/govuk/settings/_compatibility.scss
• https://github.com/alphagov/govuk-frontend/blob/main/src/govuk/settings/_colours-palette.scss
• https://github.com/alphagov/govuk-frontend/blob/main/src/govuk/settings/_typography-font.scss
• https://github.com/alphagov/govuk-frontend/blob/main/src/govuk/settings/_typography-responsive.scss

The first 2 we can ignore and remove once this work is ready to go out with 5.0 as they are examples of compatibility mode in use in our own review app.

The rest however are specifying settings for the rest of the codebase. The compatibility setting is a private array which is used in the govuk-compatibility mixin and the rest set the following global variables:

• $govuk-use-legacy-palette
• $govuk-use-legacy-font
• $govuk-typography-use-rem

All 4 of these impact various components, styles and helpers. See the below table for which components/styles/helpers are impacted and how each of these use the compatibility settings:

Component/Style/Helper	govuk-compatibility	$govuk-use-legacy-palette	$govuk-use-legacy-font	$govuk-typography-use-rem
Back link			✅
Breadcrumbs			✅
Button	✅		✅
Footer	✅	✅
Header			✅
Input				✅
Table	✅
Tag			✅
Select				✅
Section break	✅
Colour		✅
Links	✅
Typography				✅

Before we proceed with deprecation, we should decide if any of these settings currently managed via compatibility mode vars are worth keeping and then expose them more explicitly for use by teams. My personal view is that as most of these pertain to legacy instances of govuk-frontend, they should simply be deprecated and removed. The sole exception is $govuk-typography-use-rem however I'm skeptical about how useful this is and if we should be shipping it as an option outside the scope of compatibility mode. I will confer with the team before proceeding.

[36degrees]

Thanks for the investigation and write up @owenatgov – that's really helpful.

Digging in to the $govuk-use-legacy-font setting a little more, there are a couple of related things that I think we should consider removing at the same time.

Font family definitions

There's a slightly odd file in settings called 'typography-font-families' which contains the various font stacks that are used depending on whether $govuk-use-legacy-font is enabled or not.

govuk-frontend/src/govuk/settings/_typography-font-families.scss

Lines 5 to 32 in c31c4be

	/// List of font families to use if using GDS Transport (the default font
	/// 'stack' for GOV.UK)
	///
	/// @type List
	/// @access public
	$govuk-font-family-gds-transport: "GDS Transport", arial, sans-serif;
	/// List of font families to use if using NTA (old font 'stack' for
	/// GOV.UK)
	///
	/// @type List
	/// @access public
	/// @deprecated To be removed once support for compatibility mode is dropped
	$govuk-font-family-nta: "nta", arial, sans-serif;
	/// List of font families to use if using the 'tabular numbers' subset of NTA
	/// (the default font 'stack' for GOV.UK)
	///
	/// Because ntatabularnumbers only includes the digits 0-10, all other glyphs
	/// will 'fall-through' the stack to NTA.
	///
	/// @type List
	/// @access public
	/// @deprecated To be removed once support for compatibility mode is dropped
	$govuk-font-family-nta-tabular: "ntatabularnumbers", $govuk-font-family-nta;

These aren't really 'settings' at all, they're more like constants that represented the different options that might be used for $govuk-font-family (more on the tabular font family later…).

$govuk-font-family-nta and $govuk-font-family-nta-tabular should be removed at the same time we get rid of $govuk-use-legacy-font.

This leaves only $govuk-font-family-gds-transport which will effectively then be the default value for $govuk-font-family.

govuk-frontend/src/govuk/settings/_typography-font.scss

Lines 36 to 40 in c31c4be

	$govuk-font-family: if(
	$govuk-use-legacy-font,
	$govuk-font-family-nta,
	$govuk-font-family-gds-transport
	) !default;

We should get rid of the extra abstraction layer by removing the 'typography-font-families' file and all of the variables within it, and just have:

$govuk-font-family: "GDS Transport", arial, sans-serif !default;

Using a separate font face for tabular numbers

In GOV.UK Template, the way that we implemented tabular numbers was to have a separate font face with only the numbers 0-9 in tabular form ('ntatabularnumbers'). For all other characters, the browser would 'fall through' the font stack to the main font ('nta').

When we revised the font for GOV.UK Frontend, we added the tabular numbers as alternate glyphs in the font, which are controlled using the font-variant-numeric CSS property (falling back to font-feature-settings in older browsers).

The govuk-font helper accommodates for both approaches, by switching the font face out if there is a tabular font-face defined, and otherwise setting font-variant-numeric.

govuk-frontend/src/govuk/helpers/_typography.scss

Lines 186 to 199 in c31c4be

	@if $tabular {
	// if govuk-font-family-tabular is set use $govuk-font-family-tabular
	@if $govuk-font-family-tabular {
	@include govuk-typography-common($font-family: $govuk-font-family-tabular);
	} @else {
	@include govuk-typography-common;
	font-feature-settings: "tnum" 1;
	@supports (font-variant-numeric: tabular-nums) {
	font-feature-settings: normal;
	font-variant-numeric: tabular-nums;
	}
	}
	} @else {

There's a chance that there are teams out there who have their own font and are relying on the alternate font face approach, who aren't using compatibility mode, but I think it's very unlikely.

I'd suggest that we:

• deprecate and remove the $govuk-font-family-tabular setting
• update the govuk-font helper to only support the font-variant-numeric approach

(We might also consider removing font-feature-settings if we're happy with the browser support for font-variant-numeric. Notably, this means that IE11 would no longer have tabular numbers. This isn't related to compatibility mode, just might be worth considering at the same time.)

If we wanted to err on the side of caution, we could keep $govuk-font-family-tabular and the logic in govuk-font around for v5 and remove it in v6.

[owenatgov]

Thanks for the high quality sleuthing @36degrees. I've shuffled both these into the removal of $govuk-use-legacy-font (proper issue incoming) as they're both informed by that setting.

[owenatgov]

@36degrees recently raised a valid point about if this would create noise from deprecation warnings for users who are staying on v4. We've decided that we're going to keep an eye on this after we release v5 and update v4 to remove the warnings if users still on v4 complain about this.