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

4 files changed, 47 insertions, 12 deletions

diff --git a/scss/_maps.scss b/scss/_maps.scss
index c8b9fa7e53..2770a67615 100644
--- a/scss/_maps.scss
+++ b/scss/_maps.scss
@@ -39,6 +39,16 @@ $utilities-bg: map-merge(
 $utilities-bg-colors: map-loop($utilities-bg, rgba-css-var, "$key", "bg") !default;
 // scss-docs-end utilities-bg-colors
 
+// scss-docs-start utilities-border-colors
+$utilities-border: map-merge(
+  $utilities-colors,
+  (
+    "white": to-rgb($white)
+  )
+) !default;
+$utilities-border-colors: map-loop($utilities-border, rgba-css-var, "$key", "border") !default;
+// scss-docs-end utilities-border-colors
+
 $negative-spacers: if($enable-negative-margins, negativify-map($spacers), null) !default;
 
 $gutters: $spacers !default;
diff --git a/scss/_root.scss b/scss/_root.scss
index 2927c343ff..ab0584e68a 100644
--- a/scss/_root.scss
+++ b/scss/_root.scss
@@ -50,5 +50,12 @@
   }
   --#{$variable-prefix}body-bg: #{$body-bg};
   // scss-docs-end root-body-variables
+
+  // scss-docs-start root-border-var
+  --#{$variable-prefix}border-width: #{$border-width};
+  --#{$variable-prefix}border-style: solid;
+  --#{$variable-prefix}border-color: #{$border-color};
+  --#{$variable-prefix}border-radius: #{$border-radius};
+  // scss-docs-end root-border-var
   // stylelint-enable custom-property-empty-line-before
 }
diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 4d65bb88b5..7fc732acf6 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -98,15 +98,29 @@ $utilities: map-merge(
     // scss-docs-start utils-borders
     "border": (
       property: border,
+      local-vars: (
+        "border-opacity": 1
+      ),
       values: (
-        null: $border-width solid $border-color,
+        null: var(--#{$variable-prefix}border-width) var(--#{$variable-prefix}border-style) var(--#{$variable-prefix}border-color),
         0: 0,
       )
     ),
+    "border-opacity": (
+      css-var: true,
+      class: border-opacity,
+      values: (
+        10: .1,
+        25: .25,
+        50: .5,
+        75: .75,
+        100: 1
+      )
+    ),
     "border-top": (
       property: border-top,
       values: (
-        null: $border-width solid $border-color,
+        null: var(--#{$variable-prefix}border-width) var(--#{$variable-prefix}border-style) var(--#{$variable-prefix}border-color),
         0: 0,
       )
     ),
@@ -114,14 +128,14 @@ $utilities: map-merge(
       property: border-right,
       class: border-end,
       values: (
-        null: $border-width solid $border-color,
+        null: var(--#{$variable-prefix}border-width) var(--#{$variable-prefix}border-style) var(--#{$variable-prefix}border-color),
         0: 0,
       )
     ),
     "border-bottom": (
       property: border-bottom,
       values: (
-        null: $border-width solid $border-color,
+        null: var(--#{$variable-prefix}border-width) var(--#{$variable-prefix}border-style) var(--#{$variable-prefix}border-color),
         0: 0,
       )
     ),
@@ -129,17 +143,18 @@ $utilities: map-merge(
       property: border-left,
       class: border-start,
       values: (
-        null: $border-width solid $border-color,
+        null: var(--#{$variable-prefix}border-width) var(--#{$variable-prefix}border-style) var(--#{$variable-prefix}border-color),
         0: 0,
       )
     ),
     "border-color": (
-      property: border-color,
+      css-var: true,
+      css-variable-name: border-color,
       class: border,
-      values: map-merge($theme-colors, ("white": $white))
+      values: $utilities-border-colors
     ),
     "border-width": (
-      property: border-width,
+      css-var: true,
       class: border,
       values: $border-widths
     ),
diff --git a/scss/mixins/_utilities.scss b/scss/mixins/_utilities.scss
index e871b42336..b2c6683d7d 100644
--- a/scss/mixins/_utilities.scss
+++ b/scss/mixins/_utilities.scss
@@ -20,6 +20,9 @@
     $property-class: if(map-has-key($utility, class), map-get($utility, class), nth($properties, 1));
     $property-class: if($property-class == null, "", $property-class);
 
+    // Use custom CSS variable name if present, otherwise default to `class`
+    $css-variable-name: if(map-has-key($utility, css-variable-name), map-get($utility, css-variable-name), map-get($utility, class));
+
     // State params to generate pseudo-classes
     $state: if(map-has-key($utility, state), map-get($utility, state), ());
 
@@ -52,20 +55,20 @@
 
       @if $is-css-var {
         .#{$property-class + $infix + $property-class-modifier} {
-          --#{$variable-prefix}#{$property-class}: #{$value};
+          --#{$variable-prefix}#{$css-variable-name}: #{$value};
         }
 
         @each $pseudo in $state {
           .#{$property-class + $infix + $property-class-modifier}-#{$pseudo}:#{$pseudo} {
-            --#{$variable-prefix}#{$property-class}: #{$value};
+            --#{$variable-prefix}#{$css-variable-name}: #{$value};
           }
         }
       } @else {
         .#{$property-class + $infix + $property-class-modifier} {
           @each $property in $properties {
             @if $is-local-vars {
-              @each $local-var, $value in $is-local-vars {
-                --#{$variable-prefix}#{$local-var}: #{$value};
+              @each $local-var, $variable in $is-local-vars {
+                --#{$variable-prefix}#{$local-var}: #{$variable};
               }
             }
             #{$property}: $value if($enable-important-utilities, !important, null);