Standardize focus styles using focus-ring mixin (#41950)

mdo · web-flow · commit cd7474164cf5 · 2025-12-18T13:13:09.000-08:00
* Standardize focus styles using focus-ring mixin Replace box-shadow focus styles with consistent focus-ring() mixin across components: - Accordion, nav, pagination now use @include focus-ring(true) - Forms (checkboxes, radios, switches, range, controls) use focus-ring mixin - Update focus-ring-offset default from -1px to 1px - Remove deprecated *-focus-box-shadow variables * Fix some focus styles * Remove unused CSS * Remove more box-shadow on buttons
diff --git a/scss/_accordion.scss b/scss/_accordion.scss
@@ -3,8 +3,9 @@
 @use "functions" as *;
 @use "mixins/border-radius" as *;
 @use "mixins/transition" as *;
-@use "mixins/box-shadow" as *;
+@use "mixins/focus-ring" as *;
 @use "mixins/color-mode" as *;
+@use "buttons/button-variables" as *; // mdo-do: remove?
 
 // scss-docs-start accordion-variables
 $accordion-padding-y:                     1rem !default;
@@ -27,8 +28,6 @@ $accordion-transition:                    $btn-transition, border-radius .15s ea
 $accordion-button-active-bg:              var(--#{$prefix}bg-2) !default;
 $accordion-button-active-color:           var(--#{$prefix}fg) !default;
 
-$accordion-button-focus-box-shadow:       $btn-focus-box-shadow !default;
-
 $accordion-icon-width:                    1.25rem !default;
 $accordion-icon-transition:               transform .2s ease-in-out !default;
 $accordion-icon-transform:                rotate(-180deg) !default;
@@ -53,7 +52,6 @@ $accordion-button-icon:         url("data:image/svg+xml,<svg xmlns='http://www.w
     --#{$prefix}accordion-btn-icon-width: #{$accordion-icon-width};
     --#{$prefix}accordion-btn-icon-transform: #{$accordion-icon-transform};
     --#{$prefix}accordion-btn-icon-transition: #{$accordion-icon-transition};
-    --#{$prefix}accordion-btn-focus-box-shadow: #{$accordion-button-focus-box-shadow};
     --#{$prefix}accordion-body-padding-x: #{$accordion-body-padding-x};
     --#{$prefix}accordion-body-padding-y: #{$accordion-body-padding-y};
     --#{$prefix}accordion-active-color: #{$accordion-button-active-color};
@@ -103,10 +101,9 @@ $accordion-button-icon:         url("data:image/svg+xml,<svg xmlns='http://www.w
       z-index: 2;
     }
 
-    &:focus {
+    &:focus-visible {
       z-index: 3;
-      outline: 0;
-      box-shadow: var(--#{$prefix}accordion-btn-focus-box-shadow);
+      @include focus-ring(true);
     }
   }
 
diff --git a/scss/_nav.scss b/scss/_nav.scss
@@ -1,8 +1,8 @@
 @use "config" as *;
 @use "variables" as *;
 @use "mixins/border-radius" as *;
-@use "mixins/gradients" as *;
 @use "mixins/focus-ring" as *;
+@use "mixins/gradients" as *;
 @use "mixins/transition" as *;
 
 // scss-docs-start nav-variables
diff --git a/scss/_navbar.scss b/scss/_navbar.scss
@@ -2,13 +2,13 @@
 @use "config" as *;
 @use "colors" as *;
 @use "variables" as *;
+@use "layout/breakpoints" as *;
 @use "mixins/border-radius" as *;
 @use "mixins/box-shadow" as *;
+@use "mixins/color-mode" as *;
+@use "mixins/focus-ring" as *;
 @use "mixins/gradients" as *;
 @use "mixins/transition" as *;
-@use "mixins/color-mode" as *;
-@use "mixins/deprecate" as *;
-@use "layout/breakpoints" as *;
 
 // scss-docs-start navbar-variables
 $navbar-padding-y:                  $spacer * .5 !default;
@@ -29,8 +29,7 @@ $navbar-brand-margin-end:           1rem !default;
 $navbar-toggler-padding-y:          .25rem !default;
 $navbar-toggler-padding-x:          .75rem !default;
 $navbar-toggler-font-size:          $font-size-lg !default;
-$navbar-toggler-border-radius:      $btn-border-radius !default;
-$navbar-toggler-focus-width:        $btn-focus-width !default;
+$navbar-toggler-border-radius:      var(--#{$prefix}border-radius) !default;
 $navbar-toggler-transition:         box-shadow .15s ease-in-out !default;
 
 $navbar-light-color:                var(--#{$prefix}fg-2) !default;
@@ -78,7 +77,6 @@ $navbar-dark-brand-hover-color:     $navbar-dark-active-color !default;
     --#{$prefix}navbar-toggler-icon-bg: #{escape-svg($navbar-light-toggler-icon-bg)};
     --#{$prefix}navbar-toggler-border-color: #{$navbar-light-toggler-border-color};
     --#{$prefix}navbar-toggler-border-radius: #{$navbar-toggler-border-radius};
-    --#{$prefix}navbar-toggler-focus-width: #{$navbar-toggler-focus-width};
     --#{$prefix}navbar-toggler-transition: #{$navbar-toggler-transition};
     // scss-docs-end navbar-css-vars
 
@@ -217,10 +215,9 @@ $navbar-dark-brand-hover-color:     $navbar-dark-active-color !default;
       text-decoration: none;
     }
 
-    &:focus {
+    &:focus-visible {
       text-decoration: none;
-      outline: 0;
-      box-shadow: 0 0 0 var(--#{$prefix}navbar-toggler-focus-width);
+      @include focus-ring(true);
     }
   }
 
@@ -318,10 +315,6 @@ $navbar-dark-brand-hover-color:     $navbar-dark-active-color !default;
   //
   // Styles for switching between navbars with light or dark background.
 
-  .navbar-light {
-    @include deprecate("`.navbar-light`", "v5.2.0", "v6.0.0", true);
-  }
-
   .navbar-dark,
   .navbar[data-bs-theme="dark"] {
     // scss-docs-start navbar-dark-css-vars
diff --git a/scss/_pagination.scss b/scss/_pagination.scss
@@ -2,8 +2,9 @@
 @use "variables" as *;
 @use "mixins/lists" as *;
 @use "mixins/border-radius" as *;
-@use "mixins/transition" as *;
+@use "mixins/focus-ring" as *;
 @use "mixins/gradients" as *;
+@use "mixins/transition" as *;
 
 // scss-docs-start pagination-variables
 $pagination-padding-y:              .375rem !default;
@@ -24,8 +25,6 @@ $pagination-border-color:           var(--#{$prefix}border-color) !default;
 
 $pagination-focus-color:            var(--#{$prefix}link-hover-color) !default;
 $pagination-focus-bg:               var(--#{$prefix}secondary-bg) !default;
-$pagination-focus-box-shadow:       $focus-ring-box-shadow !default;
-$pagination-focus-outline:          0 !default;
 
 $pagination-hover-color:            var(--#{$prefix}link-hover-color) !default;
 $pagination-hover-bg:               var(--#{$prefix}tertiary-bg) !default;
@@ -71,7 +70,6 @@ $pagination-border-radius-lg:       var(--#{$prefix}border-radius-lg) !default;
     --#{$prefix}pagination-hover-border-color: #{$pagination-hover-border-color};
     --#{$prefix}pagination-focus-color: #{$pagination-focus-color};
     --#{$prefix}pagination-focus-bg: #{$pagination-focus-bg};
-    --#{$prefix}pagination-focus-box-shadow: #{$pagination-focus-box-shadow};
     --#{$prefix}pagination-active-color: #{$pagination-active-color};
     --#{$prefix}pagination-active-bg: #{$pagination-active-bg};
     --#{$prefix}pagination-active-border-color: #{$pagination-active-border-color};
@@ -102,12 +100,11 @@ $pagination-border-radius-lg:       var(--#{$prefix}border-radius-lg) !default;
       border-color: var(--#{$prefix}pagination-hover-border-color);
     }
 
-    &:focus {
+    &:focus-visible {
       z-index: 3;
       color: var(--#{$prefix}pagination-focus-color);
       background-color: var(--#{$prefix}pagination-focus-bg);
-      outline: $pagination-focus-outline;
-      box-shadow: var(--#{$prefix}pagination-focus-box-shadow);
+      @include focus-ring(true);
     }
 
     &.active,
diff --git a/scss/_root.scss b/scss/_root.scss
@@ -133,7 +133,7 @@
   // Focus styles
   // scss-docs-start root-focus-variables
   --#{$prefix}focus-ring-width: 3px;
-  --#{$prefix}focus-ring-offset: -1px;
+  --#{$prefix}focus-ring-offset: 1px;
   --#{$prefix}focus-ring-color: var(--#{$prefix}primary-focus-ring);
   --#{$prefix}focus-ring: var(--#{$prefix}focus-ring-width) solid var(--#{$prefix}focus-ring-color);
   // scss-docs-end root-focus-variables
diff --git a/scss/_variables.scss b/scss/_variables.scss
@@ -354,12 +354,6 @@ $input-btn-font-family:       null !default;
 $input-btn-font-size:         $font-size-base !default;
 $input-btn-line-height:       $line-height-base !default;
 
-$input-btn-focus-width:         .25em !default;
-$input-btn-focus-color-opacity: $focus-ring-opacity !default;
-$input-btn-focus-color:         $focus-ring-color !default;
-$input-btn-focus-blur:          $focus-ring-blur !default;
-$input-btn-focus-box-shadow:    $focus-ring-box-shadow !default;
-
 $input-btn-padding-y-sm:      .25rem !default;
 $input-btn-padding-x-sm:      .5rem !default;
 $input-btn-font-size-sm:      $font-size-sm !default;
@@ -372,51 +366,6 @@ $input-btn-border-width:      var(--#{$prefix}border-width) !default;
 // scss-docs-end input-btn-variables
 
 
-// Buttons
-//
-// For each of Bootstrap's buttons, define text, background, and border color.
-
-// scss-docs-start btn-variables
-$btn-color:                   var(--#{$prefix}color-body) !default;
-$btn-padding-y:               $input-btn-padding-y !default;
-$btn-padding-x:               $input-btn-padding-x !default;
-$btn-font-family:             $input-btn-font-family !default;
-$btn-font-size:               $input-btn-font-size !default;
-$btn-line-height:             $input-btn-line-height !default;
-$btn-white-space:             null !default; // Set to `nowrap` to prevent text wrapping
-
-$btn-padding-y-sm:            $input-btn-padding-y-sm !default;
-$btn-padding-x-sm:            $input-btn-padding-x-sm !default;
-$btn-font-size-sm:            $input-btn-font-size-sm !default;
-
-$btn-padding-y-lg:            $input-btn-padding-y-lg !default;
-$btn-padding-x-lg:            $input-btn-padding-x-lg !default;
-$btn-font-size-lg:            $input-btn-font-size-lg !default;
-
-$btn-border-width:            $input-btn-border-width !default;
-
-$btn-font-weight:             $font-weight-normal !default;
-$btn-box-shadow:              inset 0 1px 0 rgba($white, .15), 0 1px 1px rgba($black, .075) !default;
-$btn-focus-width:             $input-btn-focus-width !default;
-$btn-focus-box-shadow:        $input-btn-focus-box-shadow !default;
-$btn-disabled-opacity:        .65 !default;
-$btn-active-box-shadow:       inset 0 3px 5px rgba($black, .125) !default;
-
-$btn-link-color:              var(--#{$prefix}link-color) !default;
-$btn-link-hover-color:        var(--#{$prefix}link-hover-color) !default;
-$btn-link-disabled-color:     var(--#{$prefix}gray-600) !default;
-// $btn-link-color-contrast:     color-contrast($link-color) !default;
-// $btn-link-focus-shadow-rgb:   to-rgb(color.mix($btn-link-color-contrast, $link-color, 15%)) !default;
-
-// Allows for customizing button radius independently from global border radius
-$btn-border-radius:           var(--#{$prefix}border-radius) !default;
-$btn-border-radius-sm:        var(--#{$prefix}border-radius-sm) !default;
-$btn-border-radius-lg:        var(--#{$prefix}border-radius-lg) !default;
-
-$btn-transition:              color .15s ease-in-out, background-color .15s ease-in-out, border-color .15s ease-in-out, box-shadow .15s ease-in-out !default;
-// scss-docs-end btn-variables
-
-
 // Z-index master list
 //
 // Warning: Avoid customizing these values. They're used for a bird's eye view
diff --git a/scss/buttons/_button-group.scss b/scss/buttons/_button-group.scss
@@ -97,19 +97,6 @@
     padding-inline: $btn-padding-x-lg * .75;
   }
 
-
-  // The clickable button for toggling the menu
-  // Set the same inset shadow as the :active state
-  .btn-group.show .dropdown-toggle {
-    @include box-shadow($btn-active-box-shadow);
-
-    // Show no shadow for `.btn-link` since it has no other button styles.
-    &.btn-link {
-      @include box-shadow(none);
-    }
-  }
-
-
   //
   // Vertical button groups
   //
diff --git a/scss/buttons/_button-variables.scss b/scss/buttons/_button-variables.scss
@@ -38,9 +38,7 @@ $btn-line-height-lg:          1.25rem !default;
 $btn-border-width:            $input-btn-border-width !default;
 
 $btn-font-weight:             $font-weight-normal !default;
-$btn-box-shadow:              inset 0 1px 0 rgba($white, .15), 0 1px 1px rgba($black, .075) !default;
 $btn-disabled-opacity:        .65 !default;
-$btn-active-box-shadow:       inset 0 3px 5px rgba($black, .125) !default;
 
 $btn-link-color:              var(--#{$prefix}link-color) !default;
 $btn-link-hover-color:        var(--#{$prefix}link-hover-color) !default;
diff --git a/scss/buttons/_button.scss b/scss/buttons/_button.scss
@@ -305,8 +305,6 @@ $btn-variant-selectors: () !default;
     --#{$prefix}btn-active-border-color: transparent;
     --#{$prefix}btn-disabled-color: #{$btn-link-disabled-color};
     --#{$prefix}btn-disabled-border-color: transparent;
-    --#{$prefix}btn-box-shadow: 0 0 0 #000; // Can't use `none` as keyword negates all values when used with multiple shadows
-    // --#{$prefix}btn-focus-shadow-rgb: #{$btn-link-focus-shadow-rgb};
 
     text-decoration: var(--#{$prefix}link-decoration);
 
diff --git a/scss/forms/_check.scss b/scss/forms/_check.scss
@@ -3,7 +3,6 @@
 @use "../variables" as *;
 @use "../functions" as *;
 @use "../mixins/border-radius" as *;
-@use "../mixins/box-shadow" as *;
 @use "../mixins/color-mode" as *;
 @use "../mixins/focus-ring" as *;
 @use "../mixins/transition" as *;
@@ -68,6 +67,10 @@ $check-disabled-opacity: .65 !default;
       border-color: var(--#{$prefix}theme-bg, var(--#{$prefix}check-checked-border-color));
     }
 
+    :where(input:focus-visible) {
+      @include focus-ring(true);
+    }
+
     &:has(input:checked) .checked,
     &:has(input:indeterminate) .indeterminate {
       display: block;
@@ -83,7 +86,6 @@ $check-disabled-opacity: .65 !default;
         cursor: default;
       }
     }
-
     &:has(input:disabled:checked) {
       opacity: var(--#{$prefix}check-disabled-opacity);
     }
diff --git a/scss/forms/_form-control.scss b/scss/forms/_form-control.scss
@@ -9,6 +9,7 @@
 @use "../mixins/gradients" as *;
 @use "../mixins/transition" as *;
 @use "form-variables" as *;
+@use "../buttons/button-variables" as *; // mdo-do: remove?
 
 @layer forms {
   .form-control {
@@ -56,6 +57,7 @@
       background-color: $input-focus-bg;
       border-color: $input-focus-border-color;
       @include focus-ring(true);
+      --#{$prefix}focus-ring-offset: -1px;
     }
 
     &::-webkit-date-and-time-value {
diff --git a/scss/forms/_form-range.scss b/scss/forms/_form-range.scss
@@ -3,6 +3,7 @@
 @use "../variables" as *;
 @use "../mixins/border-radius" as *;
 @use "../mixins/box-shadow" as *;
+@use "../mixins/focus-ring" as *;
 @use "../mixins/transition" as *;
 @use "../mixins/gradients" as *;
 @use "form-variables" as *;
@@ -21,8 +22,6 @@ $form-range-thumb-bg:                      $component-active-bg !default;
 $form-range-thumb-border:                  0 !default;
 $form-range-thumb-border-radius:           1rem !default;
 $form-range-thumb-box-shadow:              0 .1rem .25rem rgba($black, .1) !default;
-$form-range-thumb-focus-box-shadow:        0 0 0 1px $body-bg, $input-focus-box-shadow !default;
-$form-range-thumb-focus-box-shadow-width:  $input-focus-width !default; // For focus box shadow issue in Edge
 $form-range-thumb-active-bg:               tint-color($component-active-bg, 70%) !default;
 $form-range-thumb-disabled-bg:             var(--#{$prefix}secondary-color) !default;
 $form-range-thumb-transition:              background-color .15s ease-in-out, border-color .15s ease-in-out, box-shadow .15s ease-in-out !default;
@@ -31,18 +30,24 @@ $form-range-thumb-transition:              background-color .15s ease-in-out, bo
 @layer forms {
   .form-range {
     width: 100%;
-    height: add($form-range-thumb-height, $form-range-thumb-focus-box-shadow-width * 2);
+    height: calc(#{$form-range-thumb-height} + (var(--#{$prefix}focus-ring-width) * 2));
     padding: 0; // Need to reset padding
     appearance: none;
     background-color: transparent;
 
     &:focus {
       outline: 0;
 
+
       // Pseudo-elements must be split across multiple rulesets to have an effect.
-      // No box-shadow() mixin for focus accessibility.
-      &::-webkit-slider-thumb { box-shadow: $form-range-thumb-focus-box-shadow; }
-      &::-moz-range-thumb     { box-shadow: $form-range-thumb-focus-box-shadow; }
+      &::-webkit-slider-thumb {
+        @include focus-ring(true);
+        --#{$prefix}focus-ring-offset: 1px;
+      }
+      &::-moz-range-thumb     {
+        @include focus-ring(true);
+        --#{$prefix}focus-ring-offset: 1px;
+      }
     }
 
     &::-moz-focus-outer {
diff --git a/scss/forms/_form-variables.scss b/scss/forms/_form-variables.scss
@@ -93,8 +93,6 @@ $input-border-radius-lg:                var(--#{$prefix}border-radius-lg) !defau
 $input-focus-bg:                        $input-bg !default;
 $input-focus-border-color:              var(--#{$prefix}primary-border) !default;
 $input-focus-color:                     $input-color !default;
-$input-focus-width:                     $input-btn-focus-width !default;
-$input-focus-box-shadow:                $input-btn-focus-box-shadow !default;
 
 $input-placeholder-color:               var(--#{$prefix}secondary-color) !default;
 $input-plaintext-color:                 var(--#{$prefix}color-body) !default;
@@ -150,15 +148,15 @@ $form-validation-states: (
     "icon": $form-feedback-icon-valid,
     "tooltip-color": #fff,
     "tooltip-bg-color": var(--#{$prefix}success),
-    "focus-box-shadow": 0 0 $input-btn-focus-blur $input-focus-width rgba(var(--#{$prefix}success-rgb), $input-btn-focus-color-opacity),
+    // "focus-box-shadow": 0 0 $input-btn-focus-blur $input-focus-width rgba(var(--#{$prefix}success-rgb), $input-btn-focus-color-opacity),
     "border-color": var(--#{$prefix}form-valid-border-color),
   ),
   "invalid": (
     "color": var(--#{$prefix}form-invalid-color),
     "icon": $form-feedback-icon-invalid,
     "tooltip-color": #fff,
     "tooltip-bg-color": var(--#{$prefix}danger),
-    "focus-box-shadow": 0 0 $input-btn-focus-blur $input-focus-width rgba(var(--#{$prefix}danger-rgb), $input-btn-focus-color-opacity),
+    // "focus-box-shadow": 0 0 $input-btn-focus-blur $input-focus-width rgba(var(--#{$prefix}danger-rgb), $input-btn-focus-color-opacity),
     "border-color": var(--#{$prefix}form-invalid-border-color),
   )
 ) !default;
diff --git a/scss/forms/_radio.scss b/scss/forms/_radio.scss
diff --git a/scss/forms/_switch.scss b/scss/forms/_switch.scss
diff --git a/scss/forms/_validation.scss b/scss/forms/_validation.scss
diff --git a/site/src/scss/_buttons.scss b/site/src/scss/_buttons.scss
diff --git a/site/src/scss/docs.scss b/site/src/scss/docs.scss

Original file line number	Diff line number	Diff line change
`@@ -3,7 +3,6 @@`
`3`	`3`	`@use "../variables" as *;`
`4`	`4`	`@use "../functions" as *;`
`5`	`5`	`@use "../mixins/border-radius" as *;`
`6`		`-@use "../mixins/box-shadow" as *;`
`7`	`6`	`@use "../mixins/color-mode" as *;`
`8`	`7`	`@use "../mixins/focus-ring" as *;`
`9`	`8`	`@use "../mixins/transition" as *;`
`@@ -68,6 +67,10 @@ $check-disabled-opacity: .65 !default;`
`68`	`67`	`border-color: var(--#{$prefix}theme-bg, var(--#{$prefix}check-checked-border-color));`
`69`	`68`	`}`
`70`	`69`
	`70`	`+ :where(input:focus-visible) {`
	`71`	`+ @include focus-ring(true);`
	`72`	`+ }`
	`73`	`+`
`71`	`74`	`&:has(input:checked) .checked,`
`72`	`75`	`&:has(input:indeterminate) .indeterminate {`
`73`	`76`	`display: block;`
`@@ -83,7 +86,6 @@ $check-disabled-opacity: .65 !default;`
`83`	`86`	`cursor: default;`
`84`	`87`	`}`
`85`	`88`	`}`
`86`		`-`
`87`	`89`	`&:has(input:disabled:checked) {`
`88`	`90`	`opacity: var(--#{$prefix}check-disabled-opacity);`
`89`	`91`	`}`