Helper and utilsglobal-focus-vars

8 files changed, 86 insertions, 10 deletions

diff --git a/scss/_helpers.scss b/scss/_helpers.scss
index 644b693fbc..6126781cde 100644
--- a/scss/_helpers.scss
+++ b/scss/_helpers.scss
@@ -1,6 +1,7 @@
 @import "helpers/clearfix";
 @import "helpers/color-bg";
 @import "helpers/colored-links";
+@import "helpers/focus-ring";
 @import "helpers/ratio";
 @import "helpers/position";
 @import "helpers/stacks";
diff --git a/scss/_root.scss b/scss/_root.scss
index 6eff503cee..7061bcc548 100644
--- a/scss/_root.scss
+++ b/scss/_root.scss
@@ -77,12 +77,15 @@
 
   // Focus styles
   // scss-docs-start root-focus-variables
-  --#{$variable-prefix}focus-ring-width: #{$focus-ring-width};
-  --#{$variable-prefix}focus-ring-opacity: #{$focus-ring-opacity};
-  --#{$variable-prefix}focus-ring-color: #{$focus-ring-color};
-  --#{$variable-prefix}focus-ring-blur: #{$focus-ring-blur};
-  // By default, there is no `--bs-focus-ring-offset-x` or `--bs-focus-ring-offset-y`, but we provide CSS variables with fallbacks to initial `0` values
-  --#{$variable-prefix}focus-ring-box-shadow: var(--#{$variable-prefix}focus-ring-offset-x, 0) var(--#{$variable-prefix}focus-ring-offset-y, 0) var(--#{$variable-prefix}focus-ring-blur) var(--#{$variable-prefix}focus-ring-width) var(--#{$variable-prefix}focus-ring-color);
+  --#{$prefix}focus-ring-width: #{$focus-ring-width};
+  --#{$prefix}focus-ring-opacity: #{$focus-ring-opacity};
+  --#{$prefix}focus-ring-color: #{$focus-ring-color};
+  --#{$prefix}focus-ring-blur: #{$focus-ring-blur};
+  // --#{$prefix}focus-ring-offset: 0 0 0 1px var(--#{$prefix}focus-ring-offset-color, var(--#{$prefix}body-bg));
+  --#{$prefix}focus-ring-offset-width: 1px;
+  --#{$prefix}focus-ring-offset-color: var(--#{$prefix}body-bg);
+
+  // By default, there is no `--bs-focus-ring-x` or `--bs-focus-ring-y`, but we provide CSS variables with fallbacks to initial `0` values
+  --#{$prefix}focus-ring-box-shadow: 0 0 0 var(--#{$prefix}focus-ring-offset-width) var(--#{$prefix}focus-ring-offset-color), var(--#{$prefix}focus-ring-x, 0) var(--#{$prefix}focus-ring-y, 0) var(--#{$prefix}focus-ring-blur) var(--#{$prefix}focus-ring-width) var(--#{$prefix}focus-ring-color);
   // scss-docs-end root-focus-variables
-  // stylelint-enable custom-property-empty-line-before
 }
diff --git a/scss/_variables.scss b/scss/_variables.scss
index 6cb065f11b..b956d6f045 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -515,7 +515,8 @@ $focus-ring-width:      .25rem !default;
 $focus-ring-opacity:    .25 !default;
 $focus-ring-color:      rgba($primary, $focus-ring-opacity) !default;
 $focus-ring-blur:       0 !default;
-$focus-ring-box-shadow: 0 0 $focus-ring-blur $focus-ring-width $focus-ring-color !default;
+$focus-ring-offset:     0 0 0 1px var(--#{$prefix}focus-ring-offset-color, var(--#{$prefix}body-bg)) !default;
+$focus-ring-box-shadow: $focus-ring-offset, 0 0 $focus-ring-blur $focus-ring-width $focus-ring-color !default;
 // scss-docs-end focus-ring-variables
 
 // scss-docs-start caret-variables
diff --git a/scss/helpers/_focus-ring.scss b/scss/helpers/_focus-ring.scss
new file mode 100644
index 0000000000..0a9509b1d0
--- /dev/null
+++ b/scss/helpers/_focus-ring.scss
@@ -0,0 +1,16 @@
+// stylelint-disable indentation, function-disallowed-list, declaration-colon-newline-after, value-list-comma-newline-after, value-list-comma-space-after
+
+.focus-ring:focus {
+  outline: 0;
+  // By default, there is no `--bs-focus-ring-x` or `--bs-focus-ring-y`, but we provide CSS variables with fallbacks to initial `0` values
+  box-shadow: 0 0 0 var(--#{$prefix}focus-ring-offset-width) var(--#{$prefix}focus-ring-offset-color, var(--#{$prefix}body-bg)),
+              var(--#{$prefix}focus-ring-x, 0)
+              var(--#{$prefix}focus-ring-y, 0)
+              var(--#{$prefix}focus-ring-blur)
+              calc(var(--#{$prefix}focus-ring-width) + var(--#{$prefix}focus-ring-offset-width))
+              var(--#{$prefix}focus-ring-color);
+}
+
+@each $state, $value in $theme-colors {
+  .focus-ring-#{$state}:focus { --#{$prefix}focus-ring-color: rgba(#{to-rgb($value)}, var(--bs-focus-ring-opacity)); }
+}
diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss
index 8f39b2209a..0c964768ad 100644
--- a/site/assets/scss/_component-examples.scss
+++ b/site/assets/scss/_component-examples.scss
@@ -383,3 +383,8 @@
   border: solid $border-color;
   border-width: 1px 0;
 }
+
+.focused {
+  outline: 0;
+  box-shadow: var(--#{$variable-prefix}focus-ring-offset), var(--#{$variable-prefix}focus-ring-x, 0) var(--#{$variable-prefix}focus-ring-y, 0) var(--#{$variable-prefix}focus-ring-blur) var(--#{$variable-prefix}focus-ring-width) var(--#{$variable-prefix}focus-ring-color);
+}
diff --git a/site/content/docs/5.2/customize/css-variables.md b/site/content/docs/5.2/customize/css-variables.md
index 92415f8506..477bbbe7df 100644
--- a/site/content/docs/5.2/customize/css-variables.md
+++ b/site/content/docs/5.2/customize/css-variables.md
@@ -57,11 +57,11 @@ a {
 
 ## Focus variables
 
-<small class="d-inline-flex px-2 py-1 font-monospace text-muted border rounded-3">Added in v5.3.0</small>
+{{< added-in "5.3.0" >}}
 
 Bootstrap provides custom `:focus` styles using a combination of Sass and CSS variables that can be optionally added to specific components and elements. We do not yet globally override all `:focus ` styles.
 
-In our Sass, we set default values that can be customized pre-compiling.
+In our Sass, we set default values that can be customized before compiling.
 
 {{< scss-docs name="focus-ring-variables" file="scss/_variables.scss" >}}
 
diff --git a/site/content/docs/5.2/helpers/focus-ring.md b/site/content/docs/5.2/helpers/focus-ring.md
new file mode 100644
index 0000000000..361eafd374
--- /dev/null
+++ b/site/content/docs/5.2/helpers/focus-ring.md
@@ -0,0 +1,49 @@
+---
+layout: docs
+title: Focus ring
+description: Utility classes that allows you to add and modify custom focus ring styles to elements and components.
+group: helpers
+toc: true
+---
+
+The `.focus-ring` helper removes the default `outline` on `:focus`, replacing it with a `box-shadow` that can be more broadly customized. The new shadow is made up of a series of CSS variables, inherited from the `:root` level, that can be modified for any element or component.
+
+## Example
+
+Click into the example below and press <kbd>Tab</kbd> to see the focus ring in action.
+
+{{< example >}}
+<a href="#" class="d-inline-flex focus-ring py-1 px-2 text-decoration-none border rounded-2">
+  Custom focus ring
+</a>
+{{< /example >}}
+
+## Customize
+
+Modify the styling of a focus ring with our CSS variables, Sass variables, utilities, or custom styles.
+
+### CSS variables
+
+Modify the `--bs-focus-ring-*` CSS variables as needed to change the default appearance.
+
+{{< example >}}
+<a href="#" class="d-inline-flex focus-ring py-1 px-2 text-decoration-none border rounded-2" style="--bs-focus-ring-color: rgba(var(--bs-success-rgb), .25)">
+  Green focus ring
+</a>
+{{< /example >}}
+
+### Sass
+
+Customize the Sass variables to modify all usage of the focus ring styles across your Bootstrap-powered project.
+
+{{< scss-docs name="focus-ring-variables" file="scss/_variables.scss" >}}
+
+### Utilities
+
+In addition to `.focus-ring`, we have several `.focus-ring-*` utilities to modify the helper class defaults. Modify the color with any of our theme colors.
+
+{{< example >}}
+<a href="#" class="d-inline-flex focus-ring focus-ring-danger py-1 px-2 text-decoration-none border rounded-2">
+  Danger focus ring
+</a>
+{{< /example >}}
diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
index 51c60ba62d..8d1fbb33be 100644
--- a/site/data/sidebar.yml
+++ b/site/data/sidebar.yml
@@ -122,6 +122,7 @@
     - title: Display
     - title: Flex
     - title: Float
+    - title: Focus ring
     - title: Interactions
     - title: Object fit
     - title: Opacity