Convert border utilities to CSS variables

- Updates the utilities mixin to check for specific CSS variable names via `css-variable`
- Bonus fix: we now prevent local variables for `0` value utilities (e.g., `.border-top-0` no longer sets `--bs-border-opacity: 1`
- Adds new `.border-opacity-*` classes
- Adds new root variables: `--bs-border-color`, `--bs-border-style`, `--bs-border-width`
- Documents the new variable changes

2 files changed, 50 insertions, 8 deletions

diff --git a/site/content/docs/5.1/utilities/api.md b/site/content/docs/5.1/utilities/api.md
index f961a5da9..16270ad51 100644
--- a/site/content/docs/5.1/utilities/api.md
+++ b/site/content/docs/5.1/utilities/api.md
@@ -18,6 +18,7 @@ The `$utilities` map contains all our utilities and is later merged with your cu
 | [`values`](#values) | **Required** | – | List of values, or a map if you don't want the class name to be the same as the value. If `null` is used as map key, `class` is not prepended to the class name. |
 | [`class`](#class) | Optional | null | Name of the generated class. If not provided and `property` is an array of strings, `class` will default to the first element of the `property` array. If not provided and `property` is a string, the `values` keys are used for the `class` names. |
 | [`css-var`](#css-variable-utilities) | Optional | `false` | Boolean to generate CSS variables instead of CSS rules. |
+| [`css-variable-name`](#css-variable-utilities) | Optional | null | Custom un-prefixed name for the CSS variable inside the ruleset. |
 | [`local-vars`](#local-css-variables) | Optional | null | Map of local CSS variables to generate in addition to the CSS rules. |
 | [`state`](#states) | Optional | null | List of pseudo-class variants (e.g., `:hover` or `:focus`) to generate. |
 | [`responsive`](#responsive) | Optional | `false` | Boolean indicating if responsive classes should be generated. |
@@ -158,12 +159,15 @@ Output:
 
 ### CSS variable utilities
 
-Set the `css-var` boolean option to `true` and the API will generate local CSS variables for the given selector instead of the usual `property: value` rules. Consider our `.text-opacity-*` utilities:
+Set the `css-var` boolean option to `true` and the API will generate local CSS variables for the given selector instead of the usual `property: value` rules. Add an optional `css-variable-name` to set a different CSS variable name than the class name.
+
+Consider our `.text-opacity-*` utilities. If we add the `css-variable-name` option, we'll get a custom output.
 
 ```scss
 $utilities: (
   "text-opacity": (
     css-var: true,
+    css-variable-name: text-alpha,
     class: text-opacity,
     values: (
       25: .25,
@@ -178,10 +182,10 @@ $utilities: (
 Output:
 
 ```css
-.text-opacity-25 { --bs-text-opacity: .25; }
-.text-opacity-50 { --bs-text-opacity: .5; }
-.text-opacity-75 { --bs-text-opacity: .75; }
-.text-opacity-100 { --bs-text-opacity: 1; }
+.text-opacity-25 { --bs-text-alpha: .25; }
+.text-opacity-50 { --bs-text-alpha: .5; }
+.text-opacity-75 { --bs-text-alpha: .75; }
+.text-opacity-100 { --bs-text-alpha: 1; }
 ```
 
 ### Local CSS variables
diff --git a/site/content/docs/5.1/utilities/borders.md b/site/content/docs/5.1/utilities/borders.md
index 6ba1174c9..e76c461a3 100644
--- a/site/content/docs/5.1/utilities/borders.md
+++ b/site/content/docs/5.1/utilities/borders.md
@@ -30,7 +30,7 @@ Use border utilities to add or remove an element's borders. Choose from all bord
 <span class="border-start-0"></span>
 {{< /example >}}
 
-## Border color
+## Color
 
 Change the border color using utilities built on our theme colors.
 
@@ -43,7 +43,45 @@ Change the border color using utilities built on our theme colors.
 <span class="border border-white"></span>
 {{< /example >}}
 
-## Border-width
+## Opacity
+
+<small class="d-inline-flex px-2 py-1 font-monospace text-muted border rounded-3">Added in v5.2.0</small>
+
+Bootstrap `border-{color}` utilities are generated with Sass using CSS variables. This allows for real-time color changes without compilation and dynamic alpha transparency changes.
+
+### How it works
+
+Consider our default `.border-success` utility.
+
+```css
+.border-success {
+  --bs-border-opacity: 1;
+  border-color: rgba(var(--bs-success-rgb), var(--bs-border-opacity)) !important;
+}
+```
+
+We use an RGB version of our `--bs-success` (with the value of `25, 135, 84`) CSS variable and attached a second CSS variable, `--bs-border-opacity`, for the alpha transparency (with a default value `1` thanks to a local CSS variable). That means anytime you use `.border-success` now, your computed `color` value is `rgba(25, 135, 84, 1)`. The local CSS variable inside each `.border-*` class avoids inheritance issues so nested instances of the utilities don't automatically have a modified alpha transparency.
+
+### Example
+
+To change that opacity, override `--bs-border-opacity` via custom styles or inline styles.
+
+{{< example >}}
+<div class="border border-success p-2 mb-2">This is default success border</div>
+<div class="border border-success p-2" style="--bs-border-opacity: .5;">This is 50% opacity success border</div>
+{{< /example >}}
+
+Or, choose from any of the `.border-opacity` utilities:
+
+{{< example >}}
+<div class="border border-success p-2 mb-2">This is default success border</div>
+<div class="border border-success p-2 mb-2 border-opacity-75">This is 75% opacity success border</div>
+<div class="border border-success p-2 mb-2 border-opacity-50">This is 50% opacity success border</div>
+<div class="border border-success p-2 mb-2 border-opacity-25">This is 25% opacity success border</div>
+<div class="border border-success p-2 border-opacity-10">This is 10% opacity success border</div>
+{{< /example >}}
+
+## Width
 
 {{< example class="bd-example-border-utils" >}}
 <span class="border border-1"></span>
@@ -53,7 +91,7 @@ Change the border color using utilities built on our theme colors.
 <span class="border border-5"></span>
 {{< /example >}}
 
-## Border-radius
+## Radius
 
 Add classes to an element to easily round its corners.