Merge pull request #1294 from nhsuk/nhsuk-type-scale

Deprecate 24px from typography scale

Author: colinrotherham

CHANGELOG.md

@@ -94,6 +94,14 @@ This was added in [pull request #1291: Add Sass warning suppression functionalit
 
 :wastebasket: **Deprecated features**
 
+#### Stop using `nhsuk-u-font-size-24` and '24' on the typography scale
+
+We have deprecated point 24 (24px large screens, 20px small screens) on the typography scale, including the font utility class `nhsuk-u-font-size-24` that uses point 24.
+
+We will be removing this class and point 24 on the typography scale in a future release. You will no longer be able to call the Sass mixins `nhsuk-font()` or `nhsuk-font-size()` with `$size` set to '24'.
+
+This change was introduced in [#1294: Deprecate 24 on the typography scale](https://github.com/nhsuk/nhsuk-frontend/pull/1294)
+
 #### Replace Sass mixins for media queries
 
 If you're using the `mq()` Sass mixin to output CSS media queries, you must replace it with the `nhsuk-media-query()` mixin.
@@ -208,6 +216,17 @@ After:
 
 :recycle: **Changes**
 
+We've completed changes to fully replace 24px with 26px from the typography scale in [pull request #1294](https://github.com/nhsuk/nhsuk-frontend/issues/1294) for the following:
+
+- Do and Don't list title
+- Pagination "Previous" and "Next" titles
+- Panel text content
+- Table and warning callout headings
+- Lead paragraph `.nhsuk-body-l` class
+- Lede text `.nhsuk-lede-text` class
+
+We've made changes to NHS.UK frontend in the following pull requests:
+
 - [#1077: Secondary button has been restyled to improve its visual hierarchy and prevent users from interpreting it as a disabled button](https://github.com/nhsuk/nhsuk-frontend/pull/1077)
 - [#1198: Reverse button has been restyled to better match other buttons](https://github.com/nhsuk/nhsuk-frontend/pull/1198)
 

packages/components/pagination/_index.scss

@@ -119,7 +119,7 @@
 .nhsuk-pagination__title {
   display: block;
 
-  @include nhsuk-font-size(24);
+  @include nhsuk-font-size(26);
 
   @include nhsuk-media-query($media-type: print) {
     &::after {

packages/components/panel/_index.scss

@@ -30,7 +30,7 @@ $nhsuk-border-width-panel: nhsuk-spacing(1);
   color: $color_nhsuk-white;
   padding: nhsuk-spacing(5) - $nhsuk-border-width-panel; /* [2] */
 
-  @include nhsuk-font-size(24);
+  @include nhsuk-font-size(26);
   @include nhsuk-responsive-margin(4, "bottom");
 
   @include nhsuk-media-query($until: tablet) {

packages/core/settings/_typography.scss

@@ -86,6 +86,24 @@ $nhsuk-typography-scale: (
     )
   ),
   24: (
+    null: (
+      font-size: 20px,
+      line-height: 28px
+    ),
+    tablet: (
+      font-size: 24px,
+      line-height: 31px
+    ),
+    print: (
+      font-size: 16pt,
+      line-height: 1.25
+    ),
+    deprecation: (
+      key: "nhsuk-typography-scale-24",
+      message: "24 on the typography scale is deprecated and will be removed in the next major version."
+    )
+  ),
+  _24: (
     null: (
       font-size: 20px,
       line-height: 28px

packages/core/settings/_warnings.scss

@@ -63,7 +63,8 @@ $nhsuk-suppressed-warnings: () !default;
 /// Check whether a key is present in the suppressed warnings list.
 ///
 /// @param {String} $key - The key to be checked against `$nhsuk-suppressed-warnings`.
-/// @access private
+///
+/// @link https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
 
 @function _should-warn($key) {
   @return list.index($nhsuk-suppressed-warnings, $key) == null;
@@ -73,7 +74,8 @@ $nhsuk-suppressed-warnings: () !default;
 ///
 /// @param {String} $key - The key needed to suppress the warning.
 /// @param {String} $message - The warning text.
-/// @access private
+///
+/// @link https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
 
 @function _warning-text($key, $message) {
   @return $message + " To silence this warning, update $nhsuk-suppressed-warnings " + 'with key: "#{$key}"';

packages/core/styles/_typography.scss

@@ -139,7 +139,7 @@ h6,
   display: block;
   margin-top: 0;
 
-  @include nhsuk-font-size(24);
+  @include nhsuk-font-size(26);
   @include nhsuk-responsive-margin(5, "bottom");
 }
 
@@ -185,13 +185,13 @@ address {
 /// 2. Reduces the spacing between the page heading and the lede text
 
 .nhsuk-lede-text {
-  @include nhsuk-font(24);
+  @include nhsuk-font(26);
   @include nhsuk-responsive-margin(7, "bottom");
 
   // [1]
   p,
   ul {
-    @include nhsuk-font(24);
+    @include nhsuk-font(26);
   }
 }
 

packages/core/tools/_mixins.scss

@@ -235,7 +235,7 @@
   position: relative;
   top: -16px; // [5]
 
-  @include nhsuk-font-size(24);
+  @include nhsuk-font-size(26);
 
   @include nhsuk-media-query($until: tablet) {
     margin-left: -25px;

packages/core/tools/_typography.scss

@@ -1,5 +1,6 @@
 @use "sass:map";
 @use "sass:math";
+@use "sass:string";
 @use "../settings" as *;
 @use "functions" as *;
 @use "ifff" as *;
@@ -93,6 +94,7 @@
 ///
 /// Example font map:
 ///
+/// ```scss
 /// 19: (
 ///   null: (
 ///     font-size: 16px,
@@ -107,34 +109,59 @@
 ///     line-height: 1.15
 ///   )
 /// );
+/// ```
 ///
-/// @example scss
-///   .foo {
-///     @include nhsuk-font-size(19);
-///   }
-///
-///   .foo {
-///     @include nhsuk-font-size(36, $important: true);
-///   }
-///
-/// @param {Number} $size - Point from the spacing scale (the size as it would
-///   appear on tablet and above)
+/// @param {Number | String} $size - Point from the typography scale (the size
+///   as it would appear on tablet and above)
 /// @param {Number} $line-height [false] - Non responsive custom line
 ///   height. Omit to use the line height from the font map.
 /// @param {Boolean} $important [false] - Whether to mark declarations as
 ///   `!important`.
 ///
-/// @throw if `$size` is not a valid point from the spacing scale
+/// @throw if `$size` is not a valid point from the typography scale
 ///
 /// @link https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
 
 @mixin nhsuk-font-size($size, $line-height: false, $important: false) {
-  @if not map.has-key($nhsuk-typography-scale, $size) {
-    @error "Unknown font size `#{$size}` - expected a point from the typography scale.";
+  // Flag font sizes that start with underscores so we can suppress warnings on
+  // deprecated sizes used internally, for example `nhsuk-font($size: "_24")`
+  $size-internal-use-only: string.slice(#{$size}, 1, 1) == "_";
+
+  // Remove underscore from font sizes flagged for internal use
+  @if $size-internal-use-only {
+    $size: string.slice(#{$size}, 2);
   }
 
+  // Check for a font map exactly matching the given size
   $font-map: map.get($nhsuk-typography-scale, $size);
 
+  // No match? Try with string type (e.g. $size: "16" not 16)
+  @if not $font-map {
+    @each $font-size in map.keys($nhsuk-typography-scale) {
+      @if not $font-map and "#{$font-size}" == "#{$size}" {
+        $font-map: map.get($nhsuk-typography-scale, $font-size);
+      }
+    }
+  }
+
+  // Still no match? Throw error
+  @if not $font-map {
+    @error "Unknown font size `#{$size}` - expected a point from the typography scale.";
+  }
+
+  // Check for a deprecation within the typography scale
+  $deprecation: map.get($font-map, "deprecation");
+
+  @if $deprecation {
+    // Warn on deprecated font sizes unless flagged for internal use
+    @if not $size-internal-use-only {
+      @include nhsuk-warning(map.get($deprecation, "key"), map.get($deprecation, "message"));
+    }
+
+    // remove the deprecation map keys so they do not break the breakpoint loop
+    $font-map: map.remove($font-map, "deprecation");
+  }
+
   @each $breakpoint, $breakpoint-map in $font-map {
     $font-size: map.get($breakpoint-map, "font-size");
     $font-size-rem: nhsuk-px-to-rem($font-size);
@@ -180,14 +207,15 @@
 
 /// Font size and line height helper (deprecated)
 ///
-/// @param {Number} $size - Point from the spacing scale (the size as it would
-///   appear on tablet and above)
+/// @param {Number | Boolean | String} $size - Point from the typography scale
+///   (the size as it would appear on tablet and above). Use `false` to avoid
+///   setting a size.
 /// @param {Number} $override-line-height [false] - Non responsive custom line
 ///   height. Omit to use the line height from the font map.
 /// @param {Boolean} $important [false] - Whether to mark declarations as
 ///   `!important`.
 ///
-/// @throw if `$size` is not a valid point from the spacing scale
+/// @throw if `$size` is not a valid point from the typography scale (or false)
 ///
 /// @alias nhsuk-font-size
 /// @deprecated Use `nhsuk-font-size` instead
@@ -200,7 +228,7 @@
   @include nhsuk-font-size($size, $override-line-height, $important);
 }
 
-/// Font
+/// Font helper
 ///
 /// @example scss
 ///   .foo {

packages/core/tools/typography.unit.test.mjs

@@ -243,6 +243,37 @@ describe('Typography tools', () => {
       })
     })
 
+    it('outputs CSS when passing size as a string', async () => {
+      const sass = `
+        ${sassBootstrap}
+
+        .foo {
+          @include nhsuk-font-size($size: "14")
+        }
+      `
+
+      const results = compileStringAsync(sass, {
+        loadPaths: ['packages']
+      })
+
+      await expect(results).resolves.toMatchObject({
+        css: outdent`
+          .foo {
+            font-size: 12px;
+            font-size: 0.75rem;
+            line-height: 1.25;
+          }
+          @media (min-width: 30em) {
+            .foo {
+              font-size: 14px;
+              font-size: 0.875rem;
+              line-height: 1.42857;
+            }
+          }
+        `
+      })
+    })
+
     it('outputs CSS using points as strings', async () => {
       const sass = `
         @use "core/settings/breakpoints" as * with (
@@ -312,6 +343,28 @@ describe('Typography tools', () => {
       )
     })
 
+    it('throws a deprecation warning if a point on the scale is deprecated', async () => {
+      const sass = `
+        ${sassBootstrap}
+
+        .foo {
+          @include nhsuk-font-size($size: 16)
+        }
+      `
+
+      await compileStringAsync(sass, {
+        loadPaths: ['packages'],
+        logger
+      })
+
+      // Expect our mocked @warn function to have been called once with a single
+      // argument, which should be the deprecation notice
+      expect(logger.warn).toHaveBeenCalledWith(
+        'This point on the scale is deprecated. To silence this warning, update $nhsuk-suppressed-warnings with key: "test-key"',
+        expect.anything()
+      )
+    })
+
     describe('when $important is set to true', () => {
       it('marks font size and line height as important', async () => {
         const sass = `

packages/core/utilities/_typography.scss

@@ -18,8 +18,16 @@
 ///
 /// @link https://github.com/alphagov/govuk-frontend Original code taken from GDS (Government Digital Service)
 
-@each $size in map.keys($nhsuk-typography-scale) {
+// nhsuk-u-font-size-24 is deprecated
+@each $size, $font-map in $nhsuk-typography-scale {
   .nhsuk-u-font-size-#{$size} {
+    $font-map: map.get($nhsuk-typography-scale, $size);
+
+    // Add underscore to deprecated typography scale keys
+    @if map.has-key($font-map, "deprecation") {
+      $size: _#{$size};
+    }
+
     @include nhsuk-font-size($size, $important: true);
   }
 }