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]>

1 files changed, 14 insertions, 0 deletions

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.