Remove govuk-focusable, govuk-focusable-fill mixins, introduce govuk-focus-text mixin.

CHANGELOG.md

@@ -4,6 +4,29 @@
 
 💥 Breaking changes:
 
+- Remove `govuk-focusable`, `govuk-focusable-fill` mixins, introduce `govuk-focus-text` mixin.
+
+  To migrate:
+
+  For many use cases where `govuk-focusable-fill` was used you can now use `govuk-focused-text`.
+
+  Before
+  ```scss
+  @include govuk-focusable-fill;
+  ```
+
+  After
+  ```scss
+  &:focus {
+    @include govuk-focused-text;
+  }
+  ```
+
+  For the `govuk-focusable` mixin, there is no general purpose mixin to replace this,
+  please read the new [TODO focus how to guide on the Design System website](#[TODO]).
+
+  ([PR #1361](https://github.com/alphagov/govuk-frontend/pull/1361))
+
 - Update positioning on table headers and cells to help improve readability
 
   To migrate: If you rely on a centered certain vertical alignment, you could add

src/components/accordion/_accordion.scss

@@ -132,7 +132,6 @@
       // backgrounds and box-shadows disappear, so we need to ensure there's a
       // transparent outline which will be set to a visible colour.
       outline: $govuk-focus-width solid transparent;
-      outline-offset: 0;
       color: $govuk-text-colour;
       // sass-lint:disable indentation
       box-shadow: inset 0 $govuk-accordion-border-width 0 0 $govuk-focus-colour,
@@ -202,7 +201,7 @@
     // We also want to avoid styling when the secttion is pressed or `:active`
     // to avoid the different focus styles from flashing quickly while the user interacts with the section.
     .govuk-accordion__section:not(.govuk-accordion__section--expanded) .govuk-accordion__section-button:focus:not(:active) {
-      @include govuk-focusable-text;
+      @include govuk-focused-text;
     }
 
     .govuk-accordion__controls {

src/components/button/_button.scss

@@ -89,7 +89,6 @@
       // Since Internet Explorer 8 does not support box-shadow, we want to force the user-agent outlines
       @include govuk-not-ie8 {
         outline: $govuk-focus-width solid transparent;
-        outline-offset: 0;
       }
       // Since Internet Explorer does not support `:not()` we set a clearer focus style to match user-agent outlines.
       @include govuk-if-ie8 {

src/components/details/_details.scss

@@ -32,7 +32,9 @@
       color: $govuk-link-hover-colour;
     }
 
-    @include govuk-focusable-text-link;
+    &:focus {
+      @include govuk-focused-text;
+    }
   }
 
   // ...but only underline the text, not the arrow

src/components/error-summary/_error-summary.scss

@@ -10,9 +10,12 @@
     @include govuk-text-colour;
     @include govuk-responsive-padding(4);
     @include govuk-responsive-margin(8, "bottom");
-    @include govuk-focusable;
 
     border: $govuk-border-width solid $govuk-error-colour;
+
+    &:focus {
+      outline: $govuk-focus-width solid $govuk-focus-colour;
+    }
   }
 
   .govuk-error-summary__title {
@@ -38,7 +41,6 @@
   }
 
   .govuk-error-summary__list a {
-    @include govuk-focusable-text-link;
     @include govuk-typography-weight-bold;
 
     // Override default link styling to use error colour
@@ -49,10 +51,8 @@
       color: $govuk-error-colour;
     }
 
-    // When focussed, the text colour needs to be darker to ensure that colour
-    // contrast is still acceptable
     &:focus {
-      color: $govuk-focus-text-colour;
+      @include govuk-focused-text;
     }
   }
 

src/components/file-upload/_file-upload.scss

@@ -12,7 +12,6 @@
   .govuk-file-upload {
     @include govuk-font($size: 19);
     @include govuk-text-colour;
-    @include govuk-focusable;
     padding-top: $component-padding;
     padding-bottom: $component-padding;
 
@@ -23,6 +22,8 @@
       margin-left: -$component-padding;
       padding-right: $component-padding;
       padding-left: $component-padding;
+
+      outline: $govuk-focus-width solid $govuk-focus-colour;
       // Use `box-shadow` to add border instead of changing `border-width`
       // (which changes element size) and since `outline` is already used for the
       // yellow focus state.
@@ -45,9 +46,7 @@
       padding-right: $component-padding;
       padding-left: $component-padding;
 
-      // Emulate `govuk-focusable` mixin styles for this component in FF
       outline: $govuk-focus-width solid $govuk-focus-colour;
-      outline-offset: 0;
 
       box-shadow: inset 0 0 0 4px $govuk-input-border-colour;
     }

src/components/footer/_footer.scss

@@ -63,7 +63,9 @@
       }
     }
 
-    @include govuk-focusable-text-link;
+    &:focus {
+      @include govuk-focused-text;
+    }
 
     // alphagov/govuk_template includes a specific a:link:focus selector
     // designed to make unvisited links a slightly darker blue when focussed, so

src/components/header/_header.scss

@@ -76,12 +76,8 @@
       text-decoration: underline;
     }
 
-    @include govuk-focusable-text-link;
-
-    // When focussed, the text colour needs to be darker to ensure that colour
-    // contrast is still acceptable
     &:focus {
-      color: $govuk-focus-text-colour;
+      @include govuk-focused-text;
     }
 
     // alphagov/govuk_template includes a specific a:link:focus selector
@@ -170,14 +166,16 @@
       text-decoration: underline;
     }
 
+    &:focus {
+      @include govuk-focused-text;
+    }
+
     &::after {
       @include govuk-shape-arrow($direction: down, $base: 10px, $display: inline-block);
       content: "";
       margin-left: govuk-spacing(1);
     }
 
-    @include govuk-focusable-text-link;
-
     @include mq ($from: tablet) {
       top: govuk-spacing(3);
     }

src/components/input/_input.scss

@@ -9,7 +9,6 @@
 @include govuk-exports("govuk/component/input") {
   .govuk-input {
     @include govuk-font($size: 19);
-    @include govuk-focusable;
 
     box-sizing: border-box;
     width: 100%;
@@ -26,6 +25,9 @@
     appearance: none;
 
     &:focus {
+      outline: $govuk-focus-width solid $govuk-focus-colour;
+      // Ensure outline appears outside of the element
+      outline-offset: 0;
       // Double the border by adding its width again. Use `box-shadow` for this // instead of changing `border-width` - this is for consistency with
       // components such as textarea where we avoid changing `border-width` as
       // it will change the element size. Also, `outline` cannot be utilised

src/components/select/_select.scss

@@ -9,7 +9,6 @@
 @include govuk-exports("govuk/component/select") {
   .govuk-select {
     @include govuk-font($size: 19, $line-height: 1.25);
-    @include govuk-focusable;
 
     box-sizing: border-box; // should this be global?
     max-width: 100%;
@@ -18,6 +17,9 @@
     border: $govuk-border-width-form-element solid $govuk-input-border-colour;
 
     &:focus {
+      outline: $govuk-focus-width solid $govuk-focus-colour;
+      // Ensure outline appears outside of the element
+      outline-offset: 0;
       // Double the border by adding its width again. Use `box-shadow` to do
       // this instead of changing `border-width` (which changes element size) and
       // since `outline` is already used for the yellow focus state.

src/components/skip-link/_skip-link.scss

@@ -6,7 +6,6 @@
   .govuk-skip-link {
     @include govuk-visually-hidden-focusable;
     @include govuk-typography-common;
-    @include govuk-focusable-fill;
     @include govuk-link-style-text;
     @include govuk-typography-responsive($size: 16);
 
@@ -23,5 +22,10 @@
       padding-right: unquote("max(#{govuk-spacing(3)}, #{$padding-safe-area-right})");
       padding-left: unquote("max(#{govuk-spacing(3)}, #{$padding-safe-area-left})");
     }
+
+    &:focus {
+      outline: $govuk-focus-width solid $govuk-focus-colour;
+      background-color: $govuk-focus-colour;
+    }
   }
 }

src/components/textarea/_textarea.scss

@@ -9,7 +9,6 @@
 @include govuk-exports("govuk/component/textarea") {
   .govuk-textarea {
     @include govuk-font($size: 19, $line-height: 1.25);
-    @include govuk-focusable;
 
     box-sizing: border-box; // should this be global?
     display: block;
@@ -26,6 +25,9 @@
     -webkit-appearance: none;
 
     &:focus {
+      outline: $govuk-focus-width solid $govuk-focus-colour;
+      // Ensure outline appears outside of the element
+      outline-offset: 0;
       // Double the border by adding its width again. Use `box-shadow` to do
       // this instead of changing `border-width` (which changes element size) and
       // since `outline` is already used for the yellow focus state.

src/helpers/_all.scss

@@ -1,7 +1,7 @@
 @import "clearfix";
 @import "colour";
 @import "device-pixels";
-@import "focusable";
+@import "focused";
 @import "font-faces";
 @import "grid";
 @import "links";

src/helpers/_focused.scss

@@ -0,0 +1,32 @@
+////
+/// @group helpers
+////
+
+/// Focused text
+///
+/// Provides an outline to clearly indicate when the target element is focused.
+/// Used for interactive text-based elements.
+///
+/// @access public
+
+@mixin govuk-focused-text {
+  // When colours are overridden, for example when users have a dark mode,
+  // backgrounds and box-shadows disappear, so we need to ensure there's a
+  // transparent outline which will be set to a visible colour.
+
+  // Since Internet Explorer 8 does not support box-shadow, we want to force the user-agent outlines
+  @include govuk-not-ie8 {
+    outline: $govuk-focus-width solid transparent;
+  }
+  color: $govuk-focus-text-colour;
+  background-color: $govuk-focus-colour;
+  // sass-lint:disable indentation
+  box-shadow: -5px -1px 0 1px $govuk-focus-colour,
+              5px -1px 0 1px $govuk-focus-colour,
+              -3px 1px 0 3px $govuk-focus-text-colour,
+              3px 1px 0 3px $govuk-focus-text-colour;
+  // sass-lint:enable indentation
+  // When link is focussed, hide the default underline since the
+  // box shadow adds the "underline"
+  text-decoration: none;
+}

src/helpers/_links.scss

@@ -10,7 +10,10 @@
 
 @mixin govuk-link-common {
   @include govuk-typography-common;
-  @include govuk-focusable-text-link;
+
+  &:focus {
+    @include govuk-focused-text;
+  }
 }
 
 /// Default link style mixin