Focus ring helper and utilities (#33125)

* Add global variables for box-shadow focus rings

* Update instances of -btn-focus-box-shadow to use -ring-box-shadow, unless it's for buttons or inputs

* fix variable name

* Add CSS variables for global focus styling, document it

* Move to CSS vars section

* Update scss/_nav.scss

Co-authored-by: Gaël Poupard <[email protected]>

* Helper and utils

* Fix bundlewatch

* Change 'Focus ring' in sidebar so that the page can be visible

* Minor typo fix

* fix merge

* Revamp some more, improve docs

Co-authored-by: Gaël Poupard <[email protected]>
Co-authored-by: Julien Déramond <[email protected]>
Co-authored-by: Patrick H. Lauke <[email protected]>

4 files changed, 80 insertions, 0 deletions

diff --git a/site/assets/scss/_component-examples.scss b/site/assets/scss/_component-examples.scss
index 11800a638..99bc460c1 100644
--- a/site/assets/scss/_component-examples.scss
+++ b/site/assets/scss/_component-examples.scss
@@ -397,3 +397,8 @@
     margin-right: 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.3/customize/css-variables.md b/site/content/docs/5.3/customize/css-variables.md
index 838a1abf7..ffb40c0c4 100644
--- a/site/content/docs/5.3/customize/css-variables.md
+++ b/site/content/docs/5.3/customize/css-variables.md
@@ -74,6 +74,20 @@ a {
 }
 ```
 
+## Focus variables
+
+{{< 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 before compiling.
+
+{{< scss-docs name="focus-ring-variables" file="scss/_variables.scss" >}}
+
+Those variables are then reassigned to `:root` level CSS variables that can be customized in real-time, including with options for `x` and `y` offsets (which default to their fallback value of `0`).
+
+{{< scss-docs name="root-focus-variables" file="scss/_root.scss" >}}
+
 ## Grid breakpoints
 
 While we include our grid breakpoints as CSS variables (except for `xs`), be aware that **CSS variables do not work in media queries**. This is by design in the CSS spec for variables, but may change in coming years with support for `env()` variables. Check out [this Stack Overflow answer](https://stackoverflow.com/a/47212942) for some helpful links. In the meantime, you can use these variables in other CSS situations, as well as in your JavaScript.
diff --git a/site/content/docs/5.3/helpers/focus-ring.md b/site/content/docs/5.3/helpers/focus-ring.md
new file mode 100644
index 000000000..5819bf1c6
--- /dev/null
+++ b/site/content/docs/5.3/helpers/focus-ring.md
@@ -0,0 +1,60 @@
+---
+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
+added: "5.3"
+---
+
+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 >}}
+
+`.focus-ring` sets styles via global CSS variables that can be overridden on any parent element, as shown above. These variables are generated from their Sass variable counterparts.
+
+{{< scss-docs name="root-focus-variables" file="scss/_root.scss" >}}
+
+### Sass
+
+Customize the focus ring 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]({{< docsref "/customize/color#theme-colors" >}}). Note that the light and dark variants may not be visible on all background colors given current color mode support.
+
+{{< example >}}
+{{< focus-ring.inline >}}
+{{- range (index $.Site.Data "theme-colors") }}
+<p><a href="#" class="d-inline-flex focus-ring focus-ring-{{ .name }} py-1 px-2 text-decoration-none border rounded-2">{{ title .name }} focus</a></p>
+{{- end -}}
+{{< /focus-ring.inline >}}
+{{< /example >}}
+
+Focus ring utilities are declared in our utilities API in `scss/_utilities.scss`. [Learn how to use the utilities API.]({{< docsref "/utilities/api#using-the-api" >}})
+
+{{< scss-docs name="utils-focus-ring" file="scss/_utilities.scss" >}}
diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
index 4199fa535..b1d567e99 100644
--- a/site/data/sidebar.yml
+++ b/site/data/sidebar.yml
@@ -104,6 +104,7 @@
     - title: Clearfix
     - title: Color & background
     - title: Colored links
+    - title: Focus ring
     - title: Position
     - title: Ratio
     - title: Stacks