Make link hover state clearer with thick underline

We have a long-standing issue (#1417) [1] from an audit in May 2019 about the link hover state not being clear:

> The colour change when a user hovers over a link is not clear and this was especially difficult for low vision users to determine.
>
> Ensuring that the state change is distinctive would benefit low vision users in particular, while benefiting all mouse users in general.

This was raised as a usability issue rather than a WCAG failure.

We’ve been keeping an eye on browser support for the `text-decoration-thickness` property, and its introduction into Chrome 87 means that all evergreen browsers now support it. We can therefore use `text-decoration-thickess` as a way to differentiate the link on hover.

Some of the rationale for this is included in a comment around the time of the previous working group review [2]. The broad intention is that the thicker underline is a state change that can work across any combination of text colour and background colour, as long as the link has enough contrast in its default state.

We set the underline to a minimum width to 3px with a max to 0.12em. The aim is to make the state change clear whilst avoiding the underline crashing into the text below at larger sizes. A minimum 3px width ensures at least a 2px change from the default 1px thickness. It’s a bit close with 16px body-s text, but if you set the minimum width too low, the hover thickness at 19px stays too thin. [3]

We're retaining the existing colour change on hover, as without the colour change there would be no state change in browsers that don't support `text-decoration-thickness`, including IE11. We can revisit this decision as and when our browser support requirements change. [4]

[1]: #1417
[2]: #1417 (comment)
[3]: alphagov/govuk-design-system#1578 (comment)
[4]: alphagov/govuk-design-system#1578 (comment)

Co-authored-by: Chris Thomas <[email protected]>

src/govuk/helpers/_links.scss

@@ -34,6 +34,12 @@
   @if ($govuk-link-underline-offset) {
     text-underline-offset: $govuk-link-underline-offset;
   }
+
+  @if ($govuk-link-hover-underline-thickness) {
+    &:hover {
+      text-decoration-thickness: $govuk-link-hover-underline-thickness;
+    }
+  }
 }
 
 /// Default link style mixin

src/govuk/helpers/links.test.js

@@ -3,7 +3,7 @@
 const { renderSass } = require('../../../lib/jest-helpers')
 
 const sassConfig = {
-  outputStyle: 'nested'
+  outputStyle: 'compact'
 }
 
 describe('@mixin govuk-link-decoration', () => {
@@ -66,4 +66,34 @@ describe('@mixin govuk-link-decoration', () => {
       expect(results.css.toString()).not.toContain('text-underline-offset')
     })
   })
+
+  it('sets text-decoration-thickness on hover', async () => {
+    const sass = `
+    $govuk-link-hover-underline-thickness: 10px;
+      @import "base";
+
+      .foo {
+        @include govuk-link-decoration;
+      }`
+
+    const results = await renderSass({ data: sass, ...sassConfig })
+
+    expect(results.css.toString()).toContain('.foo:hover { text-decoration-thickness: 10px; }')
+  })
+
+  describe('when $govuk-link-hover-underline-thickness is falsey', () => {
+    it('does not set a hover state', async () => {
+      const sass = `
+      $govuk-link-hover-underline-thickness: false;
+      @import "base";
+
+      .foo {
+          @include govuk-link-decoration;
+      }`
+
+      const results = await renderSass({ data: sass, ...sassConfig })
+
+      expect(results.css.toString()).not.toContain(':hover')
+    })
+  })
 })

src/govuk/settings/_measurements.scss

@@ -112,6 +112,14 @@ $govuk-hover-width: 10px !default;
 /// @access public
 $govuk-link-underline-thickness: 1px !default;
 
+/// Link hover state underline thickness
+///
+/// Set to false to disable setting a thickness
+///
+/// @type Number
+/// @access public
+$govuk-link-hover-underline-thickness: unquote("max(3px, .12em)") !default;
+
 /// Link underline offset.
 ///
 /// Set to false to disable setting an offset