From da0984d294480bdfc97a21878e2c7c3476d45e52 Mon Sep 17 00:00:00 2001
From: David Wheatley <hi@davwheat.dev>
Date: Thu, 29 Apr 2021 18:44:25 +0100
Subject: [PATCH 1/2] Add focus ring mixin

These mixins allow us to restore default browser focus rings on elements which no longer have them.
---
 less/common/mixins.less               |  1 +
 less/common/mixins/accessibility.less | 96 +++++++++++++++++++++++++++
 2 files changed, 97 insertions(+)
 create mode 100644 less/common/mixins/accessibility.less

diff --git a/less/common/mixins.less b/less/common/mixins.less
index 716edaed9a..af6c77ec65 100644
--- a/less/common/mixins.less
+++ b/less/common/mixins.less
@@ -1,3 +1,4 @@
+@import "mixins/accessibility.less";
 @import "mixins/border-radius.less";
 @import "mixins/clearfix.less";
 @import "mixins/light-contents.less";
diff --git a/less/common/mixins/accessibility.less b/less/common/mixins/accessibility.less
new file mode 100644
index 0000000000..721c555409
--- /dev/null
+++ b/less/common/mixins/accessibility.less
@@ -0,0 +1,96 @@
+// This mixin should **only** be used in this file.
+.__priv-focus-ring-styles() {
+  // This uses the browser's default outline styles, rather than
+  // using custom ones, which could introduce more issues
+  //
+  // Source: https://css-tricks.com/copy-the-browsers-native-focus-styles
+  outline: 5px auto Highlight;
+  outline: 5px auto -webkit-focus-ring-color;
+}
+
+/**
+ * Adds a focus ring to an element.
+ *
+ * This is only shown when focus is provided via keyboard, using the
+ * `:focus-visible` selector, and `:-moz-focusring` for older Firefox.
+ */
+.add-keyboard-focus-ring() {
+  // We need to declare these separately, otherwise
+  // browsers will ignore `:focus-visible` as they
+  // don't understand `:-moz-focusring`
+
+  // These are the keyboard-only versions of :focus
+  &:-moz-focusring {
+    .focusRingStyles();
+  }
+
+  &:focus-visible {
+    .focusRingStyles();
+  }
+}
+
+/** 
+ * This mixin allows support for a custom focus
+ * selector to be supplied.
+ *
+ * For example...
+ * 
+ *? button { .addKeyboardFocusRing(":focus-within") }
+ * becomes
+ *? button:focus-within { <styles>  }
+ *
+ * AND
+ *
+ *? button { .addKeyboardFocusRing(" :focus-within") }
+ * becomes
+ *? button :focus-within { <styles>  }
+ */
+.add-keyboard-focus-ring(@customFocusSelector) {
+  @realFocusSelector: ~"@{customFocusSelector}";
+
+  &@{realFocusSelector} {
+    .focusRingStyles();
+  }
+}
+
+/**
+ * Allows an offset to be supplied for an a11y
+ * outline.
+ *
+ * Useful for elements whose content is right up
+ * against their bounds.
+ *
+ * `.addKeyboardFocusRingOffset(2px)` will add an
+ *  offset of 2 pixels to the outline.
+ */
+.add-keyboard-focus-ring-offset(@offset) {
+  .offset() {
+    outline-offset: @offset;
+  }
+
+  &:-moz-focusring {
+    .offset();
+  }
+  &:focus-visible {
+    .offset();
+  }
+}
+
+/**
+ * Allows an offset to be supplied for an a11y
+ * outline.
+ *
+ * Useful for elements whose content is right up
+ * against their bounds.
+ */
+.add-keyboard-focus-ring-offset(@customSelector, @offset) {
+  .offset() {
+    outline-offset: @offset;
+  }
+
+  @realFocusSelector: ~"@{customFocusSelector}";
+
+  &@{realFocusSelector} {
+    .offset();
+  }
+}

From 3734d13a9b7774a1bf76bb4b228d2df399db32f3 Mon Sep 17 00:00:00 2001
From: David Wheatley <hi@davwheat.dev>
Date: Thu, 29 Apr 2021 21:56:35 +0100
Subject: [PATCH 2/2] Add info about custom outline styles; use `#private`
 namespace and fix mixin name

I just learned that Less has namespaces! https://lesscss.org/features/#mixins-feature-namespaces
---
 less/common/mixins/accessibility.less | 26 +++++++++++++++-----------
 1 file changed, 15 insertions(+), 11 deletions(-)

diff --git a/less/common/mixins/accessibility.less b/less/common/mixins/accessibility.less
index 721c555409..cf35f08f96 100644
--- a/less/common/mixins/accessibility.less
+++ b/less/common/mixins/accessibility.less
@@ -1,11 +1,15 @@
-// This mixin should **only** be used in this file.
-.__priv-focus-ring-styles() {
-  // This uses the browser's default outline styles, rather than
-  // using custom ones, which could introduce more issues
-  //
-  // Source: https://css-tricks.com/copy-the-browsers-native-focus-styles
-  outline: 5px auto Highlight;
-  outline: 5px auto -webkit-focus-ring-color;
+// This mixin should **only** be used in this file. If you want to define your own
+// custom outline style(s), override this mixin in your own theme extension, or in
+// the Custom Less section of the Admin dashboard.
+#private {
+  .__focus-ring-styles() {
+    // This uses the browser's default outline styles, rather than
+    // using custom ones, which could introduce more issues
+
+    // Source: https://css-tricks.com/copy-the-browsers-native-focus-styles
+    outline: 5px auto Highlight;
+    outline: 5px auto -webkit-focus-ring-color;
+  }
 }
 
 /**
@@ -21,11 +25,11 @@
 
   // These are the keyboard-only versions of :focus
   &:-moz-focusring {
-    .focusRingStyles();
+    #private.__focus-ring-styles();
   }
 
   &:focus-visible {
-    .focusRingStyles();
+    #private.__focus-ring-styles();
   }
 }
 
@@ -49,7 +53,7 @@
   @realFocusSelector: ~"@{customFocusSelector}";
 
   &@{realFocusSelector} {
-    .focusRingStyles();
+    #private.__focus-ring-styles();
   }
 }