From 9e27c231a7ae8fb8859dacef22017087c3e2e7a7 Mon Sep 17 00:00:00 2001
From: Mark Otto <markdotto@gmail.com>
Date: Thu, 25 Nov 2021 14:24:22 -1000
Subject: Add CSS variables for global focus styling, document it

---
 scss/_root.scss                         | 11 +++++++++++
 site/content/docs/5.2/content/reboot.md | 10 ++++++++++
 2 files changed, 21 insertions(+)

diff --git a/scss/_root.scss b/scss/_root.scss
index d9355b38ef..6eff503cee 100644
--- a/scss/_root.scss
+++ b/scss/_root.scss
@@ -74,4 +74,15 @@
   @each $name, $value in $grid-breakpoints {
     --#{$prefix}breakpoint-#{$name}: #{$value};
   }
+
+  // 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);
+  // scss-docs-end root-focus-variables
+  // stylelint-enable custom-property-empty-line-before
 }
diff --git a/site/content/docs/5.2/content/reboot.md b/site/content/docs/5.2/content/reboot.md
index 55f7f66331..2504a950ca 100644
--- a/site/content/docs/5.2/content/reboot.md
+++ b/site/content/docs/5.2/content/reboot.md
@@ -374,6 +374,16 @@ Reboot includes an enhancement for `role="button"` to change the default cursor
 <span role="button" tabindex="0">Non-button element button</span>
 {{< /example >}}
 
+## Focus state
+
+<small class="d-inline-flex px-2 py-1 font-monospace text-muted border rounded-3">Added in v5.3.0</small>
+
+Bootstrap globally updates the styling for `:focus` styles using a combination of Sass and CSS variables. In our Sass, we set default values that can be customized pre-compiling. 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="focus-ring-variables" file="scss/_variables.scss" >}}
+
+{{< scss-docs name="root-focus-variables" file="scss/_root.scss" >}}
+
 ## Misc elements
 
 ### Address
-- 
cgit v1.2.3