diff --git a/CHANGELOG.md b/CHANGELOG.md
index 2dc3c5263d..bfc41c6ddc 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -6,70 +6,47 @@ For advice on how to use these release notes see [our guidance on staying up to
### New features
-#### Precompiled CSS and JavaScript
-
-The precompiled CSS and JavaScript files found in our [GitHub releases](https://github.com/alphagov/govuk-frontend/releases) are now also published to [`govuk-frontend` on npm](https://www.npmjs.com/package/govuk-frontend).
-
-These changes were introduced in:
-
-- [pull request #3726: Default to ES modules with single Rollup config](https://github.com/alphagov/govuk-frontend/pull/3726)
-- [pull request #4241: Add new `govuk-frontend.min.css` package bundle](https://github.com/alphagov/govuk-frontend/pull/4241)
-
-#### Task list component added
+#### Added a new Task list component
-A new component has been added which creates lists of tasks that users need to complete.
+We’ve added a new component which creates lists of tasks that users need to complete.
Each task in the list can have a title, status, link and an optional hint. When a link is added, the whole row is clickable.
-This change was made in [pull request #2261: Task list component](https://github.com/alphagov/govuk-frontend/pull/2261).
+This change was made in [pull request #2261: Task list component.](https://github.com/alphagov/govuk-frontend/pull/2261).
-#### Tag design changes
-
-The design of the tag component has changed to improve accessibility and readability.
+#### Added focus style for links containing non-text content
-Text within the tag is no longer bold and uppercase with extra letter spacing, and is
-instead regular 19px text. Due to this, there may be changes to the width of existing tags.
+We've added a new focus style for use with non-text content, such as links containing images and focusable elements that are not form controls. This new style paints a visible yellow and black outline around the entire element, ensuring the focus style is visible in all situations.
-We now longer transform the content of tags to be uppercase automatically and instead recommend the content of tags be lower case with the first word in a tag's content be capitalised. Please check that the contents of tags and tags within phase banners in your service are using the correct capitalisation.
+For links containing images, we've added the `govuk-link-image` class. You should only use this class on links containing an image. If it also contains text, continue to use `govuk-link` instead.
-The colours have also changed to make them more distinguishable from buttons.
+```html
+
+
+
+```
-This change was made in:
+You can use these styles in your own code by including the `govuk-focused-box` Sass mixin.
-- [pull request #3502: Tag design changes](https://github.com/alphagov/govuk-frontend/pull/3502).
-- [pull request #3731: Remove the first letter modifier from the tag component](https://github.com/alphagov/govuk-frontend/pull/3731)
-- [pull request #4259: Add word breaking for long single word tags](https://github.com/alphagov/govuk-frontend/pull/4259)
+This change was made in [pull request #3819: Add linked image focus style](https://github.com/alphagov/govuk-frontend/pull/3819).
#### New link styles are now enabled by default
-In GOV.UK Frontend v3.12.0 we introduced new link styles which:
+In GOV.UK Frontend v3.12.0 we introduced new link styles which are now enabled by default. They have:
-- have underlines that are consistently thinner and a bit further away from the link text
-- have a clearer hover state, where the underline gets thicker to make the link stand out to users
+underlines that are consistently thinner and a bit further away from the link text
+a clearer hover state, where the underline gets thicker to make the link stand out to users
The new link styles are now enabled by default. If you are setting `$govuk-new-link-styles` to `true` in your Sass you can now remove this.
-This change was made in [pull request #3599: Enable new link styles by default](https://github.com/alphagov/govuk-frontend/pull/3599) and [pull request #3600: Remove new link styles feature flag](https://github.com/alphagov/govuk-frontend/pull/3600).
-
-#### Added focus style for links containing non-text content
-
-We've added a new focus style for use with non-text content, such as links containing images and focusable elements that aren't form controls. This new style paints a visible yellow and black outline around the entire element, ensuring that the focus style is visible in all situations.
-
-For links containing images, we've added the `govuk-link-image` class. This class should be used on links that _only_ contain an image. If it also contains text, continue to use `govuk-link` instead.
-
-```html
-
-
-
-```
-
-These styles can be used in your own code by including the `govuk-focused-box` Sass mixin.
+This change was made in:
-This change was made in [pull request #3819: Add linked image focus style](https://github.com/alphagov/govuk-frontend/pull/3819).
+- [pull request #3599: Enable new link styles by default](https://github.com/alphagov/govuk-frontend/pull/3599)
+- [pull request #3600: Remove new link styles feature flag](https://github.com/alphagov/govuk-frontend/pull/3600)
#### Customise inverse button colours
-For non-GOV.UK branded websites, you can now change the colours of inverse buttons — buttons intended for use on dark backgrounds.
+For non-GOV.UK branded websites, you can now change the colours of inverse buttons - buttons intended for use on dark backgrounds.
To change the inverse button's background colour, set the `$govuk-inverse-button-background-colour` Sass variable.
@@ -85,41 +62,77 @@ $govuk-inverse-button-text-colour: govuk-colour("black");
This change was made in [pull request #4043: Add ability to customise inverse button colours](https://github.com/alphagov/govuk-frontend/pull/4043).
+#### Precompiled CSS and JavaScript
+
+The precompiled CSS and JavaScript files found in our [GitHub releases](https://github.com/alphagov/govuk-frontend/releases) are now also published to [`govuk-frontend` on npm](https://www.npmjs.com/package/govuk-frontend).
+
+These changes were introduced in:
+
+- [pull request #3726: Default to ES modules with single Rollup config](https://github.com/alphagov/govuk-frontend/pull/3726)
+- [pull request #4241: Add new `govuk-frontend.min.css` package bundle](https://github.com/alphagov/govuk-frontend/pull/4241)
+
+#### Check your tags align with design changes to the Tag component
+
+We’ve changed the design of the tag component to improve accessibility and readability.
+
+Text within the tag is no longer bold and uppercase with extra letter spacing. It’s now regular 19px text with the first letter of a word capitalised and the rest of the content lowercase. Due to this, there might be changes to the width of existing tags.
+
+The colours have also changed to make them more distinguishable from buttons.
+
+Check your service is using the correct capitalisation in the contents of tags and tags within phase banners.
+
+This change was made in:
+
+- [pull request #3502: Tag design changes](https://github.com/alphagov/govuk-frontend/pull/3502)
+- [pull request #3731: Remove the first letter modifier from the tag component](https://github.com/alphagov/govuk-frontend/pull/3731)
+
### Breaking changes
You must make the following changes when you migrate to this release, or your service might break.
-#### Update component initialisation
+#### "Compatibility mode" features are no longer supported
-Remove `.init()` from individually instantiated components as initialisation now happens automatically:
+GOV.UK Frontend no longer supports compatibility with our old frameworks:
-```mjs
-new Radios($radio).init()
-```
+- GOV.UK Elements
+- GOV.UK Template
+- GOV.UK Frontend Toolkit.
-```mjs
-new Radios($radio)
-```
+You can no longer incrementally add GOV.UK Frontend to an existing service using one of these previous frameworks. We have removed the following Sass variables and one mixin which controlled compatibility mode:
-If you import the JavaScript using `window.GOVUKFrontend.initAll()`, you will not need to make any changes.
+- `$govuk-compatibility-govukelements`
+- `$govuk-compatibility-govuktemplate`
+- `$govuk-compatibility-govukfrontendtoolkit`
+- the `compatibility-mode` mixin which automatically checked if any of the 3 control variables were set to `true`
-This change was introduced in [pull request #4011: Remove component init() methods and initialise in constructor](https://github.com/alphagov/govuk-frontend/pull/4011).
+We’ve additionally removed features that were managed using the above variables. The following features and their corresponding variables have now been removed:
-#### Check that details components work as expected
+- access to the legacy colour palette using `$govuk-use-legacy-palette`
+- access to the legacy font using `$govuk-use-legacy-font`
+- use of legacy tabular fonts using `$govuk-font-family-tabular`
+- the ability to not use rem font sizes using `$govuk-typography-use-rem`
-The Details component no longer uses JavaScript, and is no longer polyfilled in older browsers.
+These changes were introduced in:
+
+- [pull request #3622: Remove compatibility mode variables](https://github.com/alphagov/govuk-frontend/pull/3622)
+- [pull request #3602: Remove compatibility-mode mixin](https://github.com/alphagov/govuk-frontend/pull/3602)
+- [pull request #3576: Remove legacy colour palette](https://github.com/alphagov/govuk-frontend/pull/3576)
+- [pull request #3574: Remove legacy and tabular fonts support](https://github.com/alphagov/govuk-frontend/pull/3574)
+- [pull request #3576: Remove $govuk-typography-use-rem setting](https://github.com/alphagov/govuk-frontend/pull/3575)
-If you aren’t using our Nunjucks macros, ensure you remove the `data-module="govuk-details"` attribute from all `` elements.
+#### Update the HTML for warning text
-If you have extended browser support requirements, check that the Details component works as expected in older browsers.
+We've removed the `.govuk-warning-text__assistive` class and its styles from GOV.UK Frontend. This class is unnecessary, as it duplicates the functionality of the `.govuk-visually-hidden` class already present in Frontend.
-This change was introduced in [pull request #3766: Remove JavaScript from Details component](https://github.com/alphagov/govuk-frontend/pull/3766).
+If you’re not using Nunjucks macros, update your warning text HTML to replace the `govuk-warning-text__assistive` class with the `govuk-visually-hidden` class.
+
+This change was introduced in [pull request #3569: Remove unnecessary class from Warning Text component](https://github.com/alphagov/govuk-frontend/pull/3569).
#### Update package file paths
In preparation for additional build targets, we've moved our package files into a directory called `dist`.
-##### Node.js and other bundlers
+##### If you’re using Node.js and other bundlers
Replace `govuk-frontend/govuk` with `govuk-frontend/dist/govuk` in any JavaScript `require()` or `import` file paths.
@@ -152,11 +165,13 @@ Next replace `` to import and ini
```
-If you import JavaScript using a different method, you might need to make some changes. Refer to the [detailed guidance on importing JavaScript](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#javascript).
+If you import JavaScript using a different method, you might need to make some changes.
+
+Refer to the [detailed guidance on importing JavaScript](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#javascript).
##### If you’re using Sass
-Replace `govuk-frontend/govuk` with `govuk-frontend/dist/govuk` in any [Sass](https://sass-lang.com/) `@import` paths.
+Replace `govuk-frontend/govuk` with `govuk-frontend/dist/govuk` in any Sass `@import` paths.
For example:
@@ -164,7 +179,7 @@ For example:
@import "node_modules/govuk-frontend/dist/govuk/all";
```
-If you’ve [added `node_modules/govuk-frontend` as a Sass import path](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#simplify-sass-import-paths), update it with the `/dist` suffix:
+If you’ve added [`node_modules/govuk-frontend` as a Sass import path](https://frontend.design-system.service.gov.uk/importing-css-assets-and-javascript/#simplify-sass-import-paths), update it with the `/dist` suffix:
```js
loadPaths: [
@@ -214,193 +229,188 @@ These changes were introduced in:
- [pull request #4261: Throw `ElementError` for missing elements during Character count instantiation](https://github.com/alphagov/govuk-frontend/pull/4261)
- [pull request #4266: Throw errors during accordion initialisation](https://github.com/alphagov/govuk-frontend/pull/4266)
-#### "Compatibility mode" features are no longer supported
-
-GOV.UK Frontend no longer supports compatibility with [our old frameworks](https://frontend.design-system.service.gov.uk/migrating-from-legacy-products/#migrate-from-our-old-frameworks): GOV.UK Elements, GOV.UK Template and GOV.UK Frontend Toolkit. You can no longer incrementally add GOV.UK Frontend to an existing service using one of these previous frameworks. We have removed the following Sass variables and one mixin which controlled compatibility mode:
-
-- `$govuk-compatibility-govukelements`
-- `$govuk-compatibility-govuktemplate`
-- `$govuk-compatibility-govukfrontendtoolkit`
-- The `compatibility-mode` mixin which automatically checked if any of the 3 control variables were set to `true`
+#### Check the Details component works as expected
-We have additionally removed features that were managed using the above variables. The following features and their corresponding variables have now been removed:
+The Details component no longer uses JavaScript, and is no longer polyfilled in older browsers.
-- Access to the legacy colour palette using `$govuk-use-legacy-palette`
-- Access to the legacy font using `$govuk-use-legacy-font`
-- Use of legacy tabular fonts using `$govuk-font-family-tabular`
-- The ability to not use rem font sizes using `$govuk-typography-use-rem`
+If you are not using our Nunjucks macros, make sure you remove the `data-module="govuk-details"` attribute from all `` elements.
-These changes were introduced in:
+If you have extended browser support requirements, check the Details component works as expected in older browsers.
-- [pull request #3622: Remove compatibility mode variables](https://github.com/alphagov/govuk-frontend/pull/3622)
-- [pull request #3602: Remove `compatibility-mode` mixin](https://github.com/alphagov/govuk-frontend/pull/3602)
-- [pull request #3576: Remove legacy colour palette](https://github.com/alphagov/govuk-frontend/pull/3576)
-- [pull request #3574: Remove legacy and tabular fonts support](https://github.com/alphagov/govuk-frontend/pull/3574)
-- [pull request #3576: Remove `$govuk-typography-use-rem` setting](https://github.com/alphagov/govuk-frontend/pull/3575)
+This change was introduced in [pull request #3766: Remove JavaScript from Details component](https://github.com/alphagov/govuk-frontend/pull/3766).
-#### Check that disabled buttons work as expected
+#### Check the ‘Disabled buttons’ work as expected
-The `disabled` attribute on disabled buttons created using our Nunjucks macros no longer includes a value.
+The `disabled` attribute on ‘Disabled buttons’ created using our Nunjucks macros no longer includes a value.
-If you are using `$button.getAttribute('disabled')` to check for the disabled attribute in JavaScript, this will now return an empty string. This may cause unexpected behaviour if you are relying on the return value being the string 'disabled' or being [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy).
+If you are using `$button.getAttribute('disabled')` to check for the disabled attribute in JavaScript, this will now return an empty string. This might cause unexpected behaviour if you are relying on the return value being the string 'disabled' or being [truthy](https://developer.mozilla.org/en-US/docs/Glossary/Truthy).
-Instead we recommend checking for the disabled attribute using [`$button.hasAttribute('disabled')`](https://developer.mozilla.org/en-US/docs/Web/API/Element/hasAttribute) or the [`$button.disabled` IDL attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLButtonElement/disabled).
+Instead, we recommend checking for the `disabled` attribute using [`$button.hasAttribute('disabled')`](https://developer.mozilla.org/en-US/docs/Web/API/Element/hasAttribute) or the [`$button.disabled` IDL attribute](https://developer.mozilla.org/en-US/docs/Web/API/HTMLButtonElement/disabled).
This change was introduced in [pull request #2830: Set the boolean disabled attribute consistently in the button component](https://github.com/alphagov/govuk-frontend/pull/2830).
-#### Check that the mobile menu button in the header component works as expected
+#### Check the mobile menu button in the Header component works as expected
-We've removed some styles from the `.govuk-header__menu-button` class. These styles were included on the mobile menu button to avoid introducing a breaking change in [GOV.UK Frontend v4.3.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.3.0).
+We've removed some styles from the `.govuk-header__menu-button` class. These styles were included on the mobile menu button to avoid introducing a breaking change in GOV.UK Frontend v4.3.0.
-If you're not using Nunjucks macros, and haven't done so already, add the `hidden` attribute to the button's HTML to ensure it continues working as expected. You do not need to make any changes if using the Nunjucks macro.
+If you're not using Nunjucks macros, and have not done so already, add the `hidden` attribute to the button's HTML to ensure it continues working as expected.
-When working correctly, the button should only be shown on narrow screens when JavaScript is available. It should be hidden on wider screens or if JavaScript is unavailable.
+You do not need to make any changes if using the Nunjucks macro.
-This change was introduced in [pull request #3596: Remove redundant display style from `.govuk-header__menu-button`](https://github.com/alphagov/govuk-frontend/pull/3596).
+When working correctly, the button should only show on narrow screens when JavaScript is available. It should be hidden on wider screens or if JavaScript is unavailable.
-#### Remove Internet Explorer 8 stylesheets, settings and mixins
-
-We no longer support Internet Explorer 8 (IE8) in GOV.UK Frontend and no longer provide dedicated stylesheets for the browser. Remove any references to these stylesheets from your HTML.
+This change was introduced in [pull request #3596: Remove redundant display style from .govuk-header\_\_menu-button](https://github.com/alphagov/govuk-frontend/pull/3596).
-We've removed the `govuk-if-ie8` and `govuk-not-ie8` mixins, and the `$govuk-is-ie8` and `$govuk-ie8-breakpoint` settings, that were deprecated in [GOV.UK Frontend v4.6.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.6.0).
+#### Check the Selects work as expected
-This change was introduced in [pull request #3559: Remove IE8-related Sass and CSS build tasks](https://github.com/alphagov/govuk-frontend/pull/3559).
+The `govukSelect` macro will no longer include an empty value attribute for options that do not have a value set.
-#### Remove deprecated `.govuk-button--disabled` class
+This means that the value of the select if that option is selected will now be the text content of the option, rather than an empty string.
-We've removed the `.govuk-button--disabled` class that we deprecated in [GOV.UK Frontend v4.6.0](https://github.com/alphagov/govuk-frontend/releases/tag/v4.6.0).
+If you need to maintain the existing behaviour, you can set the value to an empty string.
-Use the `disabled` attribute to mark `