Defend against a:link:focus in GOV.UK Template

app/views/examples/links/index.njk

@@ -12,6 +12,7 @@
 {% set variants = {
   'Link': '',
   'Link with no visited state': 'govuk-link--no-visited-state',
+  'Text link': 'govuk-link--text-colour',
   'Muted link': 'govuk-link--muted'
 } %}
 
@@ -42,7 +43,7 @@
 
       {% for state_description, state_class in states %}
         <p class="govuk-body">
-          <a href="#" class="govuk-link {{ variant_class }} {{ state_class }}">
+          <a href="/" class="govuk-link {{ variant_class }} {{ state_class }}">
             {{ state_description}}
           </a>
         </p>

src/back-link/_back-link.scss

@@ -4,7 +4,8 @@
 
   .govuk-c-back-link {
     @include govuk-font-regular-16;
-    @include govuk-focusable-fill;
+    @include govuk-link-common;
+    @include govuk-link-style-text;
 
     display: inline-block;
     position: relative;
@@ -22,13 +23,6 @@
     // Underline is provided by a bottom border
     text-decoration: none;
 
-    &:link,
-    &:visited,
-    &:hover,
-    &:active {
-      @include govuk-text-colour;
-    }
-
     // Prepend left pointing arrow
     &:before {
       @include govuk-shape-arrow($direction: left, $base: 10px, $height: 6px);

src/breadcrumbs/_breadcrumbs.scss

@@ -103,13 +103,7 @@
   }
 
   .govuk-c-breadcrumbs__link {
-    @include govuk-focusable-fill;
-
-    &:link,
-    &:visited,
-    &:hover,
-    &:active {
-      color: $govuk-text-colour;
-    }
+    @include govuk-link-common;
+    @include govuk-link-style-text;
   }
 }

src/button/_button.scss

@@ -46,6 +46,17 @@
       text-decoration: none;
     }
 
+    // alphagov/govuk_template includes a specific a:link:focus selector
+    // designed to make unvisited links a slightly darker blue when focussed, so
+    // we need to override the text colour for that combination of selectors so
+    // so that unvisited links styled as buttons do not end up with dark blue
+    // text when focussed.
+    @include govuk-compatibility(govuk_template) {
+      &:link:focus {
+        color: $govuk-button-text-colour;
+      }
+    }
+
     // Fix unwanted button padding in Firefox
     &:-moz-focus-inner {
       padding: 0;

src/error-summary/_error-summary.scss

@@ -44,16 +44,26 @@
 
   .govuk-c-error-summary__list a {
     @include govuk-focusable-fill;
+    @include govuk-typography-weight-bold;
 
+    // Override default link styling to use error colour
     &:link,
     &:visited,
     &:hover,
-    &:active {
-      @include govuk-typography-weight-bold;
-
+    &:active,
+    &:focus {
       color: $govuk-error-colour;
       text-decoration: underline;
     }
+
+    // alphagov/govuk_template includes a specific a:link:focus selector
+    // designed to make unvisited links a slightly darker blue when focussed, so
+    // we need to override the text colour for that combination of selectors.
+    @include govuk-compatibility(govuk_template) {
+      &:link:focus {
+        color: $govuk-error-colour;
+      }
+    }
   }
 
 }

src/footer/_footer.scss

@@ -39,6 +39,20 @@
     &:active {
       color: $govuk-footer-link-hover;
     }
+
+    // Use text colour when focussed
+    &:focus {
+      color: $govuk-text-colour;
+    }
+
+    // alphagov/govuk_template includes a specific a:link:focus selector
+    // designed to make unvisited links a slightly darker blue when focussed, so
+    // we need to override the text colour for that combination of selectors.
+    @include govuk-compatibility(govuk_template) {
+      &:link:focus {
+        @include govuk-text-colour;
+      }
+    }
   }
 
   .govuk-c-footer__section-break {

src/globals/_common.scss

@@ -8,6 +8,7 @@
 @import "settings/colours-palette";
 @import "settings/colours-organisations";
 @import "settings/colours-applied";
+@import "settings/compatibility";
 @import "settings/spacing";
 @import "settings/measurements";
 @import "settings/typography-font-stacks";
@@ -17,6 +18,7 @@
 @import "settings/paths";
 
 // Tools
+@import "tools/compatibility";
 @import "tools/exports";
 @import "tools/file-url";
 @import "tools/iff";

src/globals/core/_links.scss

@@ -1,85 +1,179 @@
-@include govuk-exports("links") {
+/// Common link mixin
+///
+/// Provides the typography and focus state, regardless of link style.
+@mixin govuk-link-common {
+  @include govuk-typography-common;
+  @include govuk-focusable-fill;
 
-  // We use placeholder classes here so that we can @extend from the prose scope
-  // without also applying every other occurrence of the .govuk-link selector to
-  // the prose scope.
+  // Override the tap highlight colour (the color of the highlight that
+  // appears when a link is tapped on some mobile devices). This is
+  // ever-so-slightly darker than the default.
+  -webkit-tap-highlight-color: rgba($govuk-black, .3);
+}
 
-  %govuk-link {
-    @include govuk-typography-common;
-    @include govuk-focusable-fill;
+/// Default link style mixin
+///
+/// Provides the default unvisited, visited, hover and active states for links.
+///
+/// If you use this mixin in a component you must also include the
+/// govuk-link-common mixin in order to get the focus state.
+///
+/// @example scss
+///   .govuk-c-component__link {
+///     @include govuk-link-common;
+///     @include govuk-link-style-muted;
+///   }
+@mixin govuk-link-style-default {
+  &:link {
+    color: $govuk-link-colour;
+  }
 
-    // Override the tap highlight colour (the color of the highlight that
-    // appears when a link is tapped on some mobile devices). This is
-    // ever-so-slightly darker than the default.
-    -webkit-tap-highlight-color: rgba($govuk-black, .3);
+  &:visited {
+    color: $govuk-link-visited-colour;
+  }
 
-    &:link {
-      color: $govuk-link-colour;
-    }
+  &:hover {
+    color: $govuk-link-hover-colour;
+  }
 
-    &:visited {
-      color: $govuk-link-visited-colour;
-    }
+  &:active {
+    color: $govuk-link-active-colour;
+  }
+}
+
+/// Muted style link mixin
+///
+/// Used for secondary links on a page - the link will appear in muted colours
+/// regardless of visited state.
+///
+/// If you use this mixin in a component you must also include the
+/// govuk-link-common mixin in order to get the focus state.
+///
+/// @example scss
+///   .govuk-c-component__link {
+///     @include govuk-link-common;
+///     @include govuk-link-style-muted;
+///   }
+@mixin govuk-link-style-muted {
+  &:link,
+  &:visited,
+  &:hover,
+  &:active {
+    color: $govuk-grey-1;
+  }
 
-    &:hover {
-      color: $govuk-link-hover-colour;
+  // When focussed, the text colour needs to be darker to ensure that colour
+  // contrast is still acceptable
+  &:focus {
+    color: $govuk-text-colour;
+  }
+
+  // alphagov/govuk_template includes a specific a:link:focus selector designed
+  // to make unvisited links a slightly darker blue when focussed, so we need to
+  // override the text colour for that combination of selectors.
+  @include govuk-compatibility(govuk_template) {
+    &:link:focus {
+      @include govuk-text-colour;
     }
+  }
+}
+
+/// Text style link mixin
+///
+/// Overrides the colour of links to match the text colour. Generally used by
+/// navigation components, such as breadcrumbs or the back link.
+///
+/// If you use this mixin in a component you must also include the
+/// govuk-link-common mixin in order to get the focus state.
+///
+/// @example scss
+///   .govuk-c-component__link {
+///     @include govuk-link-common;
+///     @include govuk-link-style-text;
+///   }
+@mixin govuk-link-style-text($include-common-styles: true) {
+  // Override link colour to use text colour
+  &:link,
+  &:visited,
+  &:hover,
+  &:active,
+  &:focus {
+    @include govuk-text-colour;
+  }
 
-    &:active {
-      color: $govuk-link-active-colour;
+  // alphagov/govuk_template includes a specific a:link:focus selector designed
+  // to make unvisited links a slightly darker blue when focussed, so we need to
+  // override the text colour for that combination of selectors.
+  @include govuk-compatibility(govuk_template) {
+    &:link:focus {
+      @include govuk-text-colour;
     }
+  }
+}
 
-    @include mq($media-type: print) {
-
-      // When printing, append the the destination URL to the link text, as long
-      // as the URL starts with either `/`, `http://` or `https://`.
-      &[href^="/"],
-      &[href^="http://"],
-      &[href^="https://"] {
-        &::after {
-          content: " (" attr(href) ")";
-          font-size: 90%;
-
-          // Because the URLs may be very long, ensure that they may be broken
-          // at arbitrary points if there are no otherwise acceptable break
-          // points in the line
-          word-wrap: break-word;
-        }
+/// Print friendly link mixin
+///
+/// When printing, append the the destination URL to the link text, as long
+/// as the URL starts with either `/`, `http://` or `https://`.
+@mixin govuk-link-print-friendly {
+  @include mq($media-type: print) {
+
+    &[href^="/"],
+    &[href^="http://"],
+    &[href^="https://"] {
+      &::after {
+        content: " (" attr(href) ")";
+        font-size: 90%;
+
+        // Because the URLs may be very long, ensure that they may be broken
+        // at arbitrary points if there are no otherwise acceptable break
+        // points in the line
+        word-wrap: break-word;
       }
     }
   }
+}
+
+// Export placeholders and concrete classes
+
+@include govuk-exports("links") {
+
+  // We use a placeholder class here so that we can @extend from the prose scope
+  // without also applying every other occurrence of the .govuk-link selector to
+  // the prose scope.
+
+  %govuk-link {
+    @include govuk-link-common;
+    @include govuk-link-style-default;
+    @include govuk-link-print-friendly;
+  }
 
   .govuk-link {
     @extend %govuk-link;
   }
 
-  // Muted link variant
-  //
-  // Used for secondary links on a page - the link will appear in muted colours
-  // regardless of visited state.
+  // Variant classes should always be used in conjunction with the .govuk-link
+  // class, so we do not need the common link styles as they will be inherited.
+
   .govuk-link--muted {
-    &:link,
-    &:visited,
-    &:hover,
-    &:active {
-      color: $govuk-grey-1;
-    }
+    @include govuk-link-style-muted;
+  }
 
-    // When focussed, the text colour needs to be darker to ensure that colour
-    // contrast is still acceptable
-    &:focus {
-      color: $govuk-black;
-    }
+  .govuk-link--text-colour {
+    @include govuk-link-style-text;
   }
 
-  // 'No visited state' link variant
+  // 'No visited state' link mixin
   //
   // Used in cases where it is not helpful to distinguish between visited and
   // non-visited links.
   //
   // For example, navigation links to pages with dynamic content like admin
   // dashboards. The content on the page is changing all the time, so the fact
   // that you’ve visited it before is not important.
+  //
+  // This is not abstracted as a mixin because it does not provide states for
+  // all pseudo-selectors so it does not make sense to use it in composition.
   .govuk-link--no-visited-state {
     &:visited {
       color: $govuk-link-colour;