.sr-only & .sr-only-focusable tweaks (#28720)

* Prevent .sr-only-focusable overriding properties when being focused

* Typo

scss/mixins/_screen-reader.scss

@@ -1,34 +1,28 @@
+// stylelint-disable declaration-no-important
+
 // Only display content to screen readers
 //
 // See: https://a11yproject.com/posts/how-to-hide-content/
 // See: https://hugogiraudel.com/2016/10/13/css-hide-and-seek/
 
 @mixin sr-only {
-  position: absolute;
-  width: 1px;
-  height: 1px;
-  padding: 0;
-  margin: -1px; // Fix for https://github.com/twbs/bootstrap/issues/25686
-  overflow: hidden;
-  clip: rect(0, 0, 0, 0);
-  white-space: nowrap;
-  border: 0;
+  position: absolute !important;
+  width: 1px !important;
+  height: 1px !important;
+  padding: 0 !important;
+  margin: -1px !important; // Fix for https://github.com/twbs/bootstrap/issues/25686
+  overflow: hidden !important;
+  clip: rect(0, 0, 0, 0) !important;
+  white-space: nowrap !important;
+  border: 0 !important;
 }
 
-// Use in conjunction with .sr-only to only display content when it's focused.
+// Use to only display content when it's focused.
 //
 // Useful for "Skip to main content" links; see https://www.w3.org/TR/2013/NOTE-WCAG20-TECHS-20130905/G1
-//
-// Credit: HTML5 Boilerplate
 
 @mixin sr-only-focusable {
-  &:active,
-  &:focus {
-    position: static;
-    width: auto;
-    height: auto;
-    overflow: visible;
-    clip: auto;
-    white-space: normal;
+  &:not(:focus) {
+    @include sr-only();
   }
 }

scss/utilities/_screenreaders.scss

@@ -2,10 +2,7 @@
 // Screenreaders
 //
 
-.sr-only {
+.sr-only,
+.sr-only-focusable:not(:focus) {
   @include sr-only();
 }
-
-.sr-only-focusable {
-  @include sr-only-focusable();
-}

site/content/docs/4.3/getting-started/accessibility.md

@@ -37,10 +37,10 @@ Content which should be visually hidden, but remain accessible to assistive tech
 </p>
 {{< /highlight >}}
 
-For visually hidden interactive controls, such as traditional "skip" links, `.sr-only` can be combined with the `.sr-only-focusable` class. This will ensure that the control becomes visible once focused (for sighted keyboard users).
+For visually hidden interactive controls, such as traditional "skip" links, use the `.sr-only-focusable` class. This will ensure that the control becomes visible once focused (for sighted keyboard users). **Watch out, since Bootstrap 5 the `.sr-only-focusable` class may not be used in combination with the `.sr-only` class.**
 
 {{< highlight html >}}
-<a class="sr-only sr-only-focusable" href="#content">Skip to main content</a>
+<a class="sr-only-focusable" href="#content">Skip to main content</a>
 {{< /highlight >}}
 
 ### Reduced motion

site/content/docs/4.3/migration.md

@@ -85,6 +85,10 @@ Badges were overhauled to better differentiate themselves from buttons and to be
 
 - Renamed `.arrow` to `.tooltip-arrow`
 
+## Accessibility
+
+- `.sr-only-focusable` does not require `.sr-only` anymore. [See #28720](https://github.com/twbs/bootstrap/pull/28720).
+
 ## Utilities
 
 - **Todo:** Drop `.text-hide` as it's an antiquated method for hiding text that shouldn't be used anymore

site/content/docs/4.3/utilities/screen-readers.md

@@ -5,16 +5,21 @@ description: Use screen reader utilities to hide elements on all devices except
 group: utilities
 ---
 
-Hide an element to all devices **except screen readers** with `.sr-only`. Combine `.sr-only` with `.sr-only-focusable` to show the element again when it's focused (e.g. by a keyboard-only user). Can also be used as mixins.
+Hide an element to all devices **except screen readers** with `.sr-only`. Use `.sr-only-focusable` to show the element only when it's focused (e.g. by a keyboard-only user). Can also be used as mixins.
 
 {{< example >}}
-<a class="sr-only sr-only-focusable" href="#content">Skip to main content</a>
+<h2 class="sr-only">Title for screen readers</h2>
+<a class="sr-only-focusable" href="#content">Skip to main content</a>
 {{< /example >}}
 
 {{< highlight scss >}}
 // Usage as a mixin
-.skip-navigation {
+
+.sr-only-title {
   @include sr-only;
+}
+
+.skip-navigation {
   @include sr-only-focusable;
 }
 {{< /highlight >}}

site/layouts/partials/skippy.html

@@ -1,3 +1,3 @@
-<a class="skippy sr-only sr-only-focusable" href="#content">
+<a class="skippy sr-only-focusable" href="#content">
   <span class="skippy-text">Skip to main content</span>
 </a>