diff --git a/CHANGELOG.md b/CHANGELOG.md index b0551f47e3..013d37e221 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,63 +3,41 @@ ## Unreleased ### Breaking changes -Where applicable, you must make the following changes when you migrate to this release, or your service may break. +This release contains a lot of breaking changes, but we expect many of them will only affect a small number of users. However, to make sure your service still works after you upgrade, you should read the release notes and make any required changes. #### Check your accordions still display as expected -[See the new design for accordions, and read the revised guidance, particularly about when, and when not, to use accordions](https://design-system.service.gov.uk/components/accordion/). +We've changed the design of the accordion. You can [see its new look, and read the revised guidance, particularly about when, and when not, to use accordions](https://design-system.service.gov.uk/components/accordion/). -You should check that your accordions still display as expected if you: +You should check your accordions still display as expected if you: - have applied any custom styles to your accordions -- use accordions in non-standard ways +- use accordions in non-standard ways (for example, to display accordions, other components, tables or large images) - have section headings that contain unusual formatting (for example, wrappers) -You do not need to make changes to the content that accordions hide or show - this release's changes do not affect it. +You do not need to make changes to the content that accordions hide or show, as this release's changes do not affect it. These changes were introduced in [pull request #2257: Update accordion design](https://github.com/alphagov/govuk-frontend/pull/2257). Thanks to [Mia Allers](https://github.com/mia-allers-gds), [Owen Jones](https://github.com/owenatgov), [Nikin Nagewadia](https://github.com/nnagewad) and [Chris Yoong](https://github.com/chris-gds) for their contributions. -#### Review and revise the accordion's summary line content - -If you're already using the summary line, review your use to make sure you actually need it. - -If you need to keep the summary line, [review the accordion guidance](https://design-system.service.gov.uk/components/accordion/) and make it as short as possible. - #### Only use the accordion’s summary line for ‘phrasing content’ -The summary line is now inside the HTML `button` element, so you can only add ['phrasing content'](https://html.spec.whatwg.org/#phrasing-content) to it. Do not use any non-phrasing content, as the resulting HTML will not be valid. +The summary line is now inside the HTML `button` element, so you can only add ['phrasing content'](https://www.w3.org/TR/2011/WD-html5-20110525/content-models.html#phrasing-content-0) to it. Do not use any non-phrasing content, as the resulting HTML will not be valid. This change was introduced in [pull request #2257: Update accordion design](https://github.com/alphagov/govuk-frontend/pull/2257). -#### Remove deprecated `govuk-main-wrapper` and `govuk-main-wrapper--l` mixins - -We've removed the `govuk-main-wrapper` and `govuk-main-wrapper--l` mixins which we deprecated in [GOV.UK Frontend v3.0.0](https://github.com/alphagov/govuk-frontend/releases/tag/v3.0.0). - -Remove any use of these mixins in your own Sass. You can replace these mixins with direct references to the [spacing mixins](https://design-system.service.gov.uk/styles/spacing/#spacing-on-custom-components). - -This change was introduced in [pull request #2385: Remove deprecated `govuk-main-wrapper` and `govuk-main-wrapper--l` mixins](https://github.com/alphagov/govuk-frontend/pull/2385). - -#### Remove deprecated `$govuk-border-width-form-element-error` variable - -In [GOV.UK Frontend v3.8.0](https://github.com/alphagov/govuk-frontend/releases/tag/v3.8.0), we made the border width of form elements in their error state the same as for form elements in their normal state, and deprecated the `$govuk-border-width-form-element-error` variable. - -Before, an element's border got thicker to show the element was in an error state. However, elements in their focused state also have a thicker border. As a result, when users focused an element in an error state, the only visible border-change was from red to black. Not all users could perceive this change. So, we reduced the element border's width, to make sure its thickness changes when users focus. - -We've now removed `$govuk-border-width-form-element-error` completely. +#### Review and revise the accordion's summary line content -If you’re referencing `$govuk-border-width-form-element-error` in your own Sass, you must remove it. If you're also defining your own error state, you only need to change the border colour. +Only add a summary line if you need to, as it's likely to make the button text too long. -You should avoid overriding the border width. For example, replace `border: $govuk-border-width-form-element-error solid $govuk-error-colour;` with `border-color: $govuk-error-colour;`. +If you're already using the summary line, review your use of the summary line to make sure you actually need it. -You should also remove any override of `$govuk-border-width-form-element-error` from your Sass. This override no longer does anything. - -This change was introduced in [pull request #1963: Remove deprecated `$govuk-border-width-form-element-error` variable](https://github.com/alphagov/govuk-frontend/pull/1963). +If you need to keep the summary line, [review the accordion guidance](https://design-system.service.gov.uk/components/accordion/) and make the summary line as short as possible. #### Update the HTML for summary lists -We've updated the HTML for the summary list component to avoid nesting `` elements within `
` elements, which is invalid HTML. This update only affects summary lists that include a mix of rows with and without actions. +We've updated the HTML for the summary list component to avoid nesting `` elements within `
` elements, which is invalid HTML. This update only affects you if you have summary lists that include a mix of rows with and without actions. You can [read more about adding actions to rows](https://design-system.service.gov.uk/components/summary-list/#adding-actions-to-each-row). -Do not include an empty `` within the rows that do not have any actions. Instead, add the `govuk-summary-list__row--no-actions` modifier class to the row. +If you're not using Nunjucks macros, do not include an empty `` within the rows that do not have any actions. Instead, add the `govuk-summary-list__row--no-actions` modifier class to the row. This change was introduced in [pull request #2323: Avoid invalid nesting of `` within a `
` in summary list](https://github.com/alphagov/govuk-frontend/pull/2323). Thanks to [Malcolm Hire]( https://github.com/malcolmhire) for reporting this issue. @@ -67,7 +45,7 @@ This change was introduced in [pull request #2323: Avoid invalid nesting of `` rather than the `
    `. Check that the additional classes are still doing what you expect. +Any additional classes passed using the `navigationClasses` Nunjucks option are now applied to the `