Revamp focus ring helper and docs (#42350)

* Revamp focus ring helper and docs

* remove util

Author: mdo

scss/_utilities.scss

@@ -114,14 +114,6 @@ $utilities: map.merge(
       )
     ),
     // scss-docs-end utils-shadow
-    // scss-docs-start utils-focus-ring
-    "focus-ring": (
-      // css-var: true,
-      property: --focus-ring-color,
-      class: focus-ring,
-      values: theme-color-values("focus-ring"),
-    ),
-    // scss-docs-end utils-focus-ring
     // scss-docs-start utils-position
     "position": (
       property: position,

scss/helpers/_focus-ring.scss

@@ -1,5 +1,6 @@
 @layer helpers {
   .focus-ring:focus-visible {
-    outline: var(--focus-ring);
+    // outline: var(--focus-ring);
+    outline: var(--focus-ring-width) solid var(--theme-focus-ring, var(--focus-ring-color));
   }
 }

site/src/content/docs/helpers/focus-ring.mdx

@@ -6,50 +6,26 @@ toc: true
 
 import { getData } from '@libs/data'
 
-The `.focus-ring` helper modifies the default `outline` for focus states with one that can be more easily customized. The new focus ring is made up of a series of CSS variables, inherited from the `:root` level, that can be modified for any element or component.
+The `.focus-ring` helper modifies the default `outline` for focus states with one that can be more easily customized. Focus ring 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 directly on the link below to see the focus ring in action, or into the example below and then press <kbd>Tab</kbd>.
+Tab into the example below to see the focus ring in action, or into the example below and then press <kbd>Tab</kbd>.
 
 <Example code={`<a href="#" class="d-inline-flex focus-ring py-1 px-2 text-decoration-none border rounded-2">
     Custom focus ring
   </a>`} />
 
-## Customize
+## Variants
 
-Modify the styling of a focus ring with our CSS variables, Sass variables, utilities, or custom styles.
+Change the color of the focus ring with the [theme color]([[docsref:/customize/theme#theme-colors]]) utility classes. The helper class pulls in the `--bs-theme-focus-ring` CSS variable for the given theme color.
 
-### CSS variables
+<Example class="vstack gap-2 align-items-start" code={getData('theme-colors').map((themeColor) => `<a href="#" class="d-inline-flex focus-ring theme-${themeColor.name} py-1 px-2 text-decoration-none border rounded-2">${themeColor.title} focus</a>`)} />
 
-Modify the `--bs-focus-ring-*` CSS variables as needed to change the default appearance.
+## Custom colors
 
-<Example code={`<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>`} />
-
-`.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.
-
-<ScssDocs name="root-focus-variables" file="scss/_root.scss" />
+Modify the `--bs-focus-ring-color` CSS variable as needed to change the default appearance. Use existing theme variables or your own colors. When using your own colors, we recommend using `light-dark()` for color mode support and `color-mix()` to ensure colors deviate slightly for more contrast on different backgrounds.
 
-By default, there is no `--bs-focus-ring-x`, `--bs-focus-ring-y`, or `--bs-focus-ring-blur`, but we provide CSS variables with fallbacks to initial `0` values. Modify them to change the default appearance.
-
-<Example code={`<a href="#" class="d-inline-flex focus-ring py-1 px-2 text-decoration-none border rounded-2" style="--bs-focus-ring-x: 10px; --bs-focus-ring-y: 10px; --bs-focus-ring-blur: 4px">
-    Blurry offset focus ring
+<Example code={`<a href="#" class="d-inline-flex focus-ring py-1 px-2 text-decoration-none border rounded-2" style="--bs-focus-ring-color: var(--bs-success-focus-ring)">
+    Green focus ring
   </a>`} />
-
-### Sass variables
-
-Customize the focus ring Sass variables to modify all usage of the focus ring styles across your Bootstrap-powered project.
-
-{/* <ScssDocs name="focus-ring-variables" file="scss/_config.scss" /> */}
-
-### Sass utilities API
-
-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 code={getData('theme-colors').map((themeColor) => `<p><a href="#" class="d-inline-flex focus-ring focus-ring-${themeColor.name} py-1 px-2 text-decoration-none border rounded-2">${themeColor.title} focus</a></p>`)} />
-
-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]])
-
-<ScssDocs name="utils-focus-ring" file="scss/_utilities.scss" />