Iterate on border utilities (#36239)

* Remove `--bs-border-opacity: 1` from `.border-*` utilities

We set `--bs-border-opacity: 1` globally at the `:root` level, so redeclaring it on every `.border-*` utility doesn't make much sense. I think we can drop this.

* Remove global border-opacity var, restore on .border-color classes, move .border-color utils down the list to fix some specificity issues

* Add some demos of border utils to the docs

3 files changed, 33 insertions, 19 deletions

diff --git a/scss/_root.scss b/scss/_root.scss
index 36f9849ef8..e16d2a3f69 100644
--- a/scss/_root.scss
+++ b/scss/_root.scss
@@ -57,7 +57,6 @@
   --#{$prefix}border-style: #{$border-style};
   --#{$prefix}border-color: #{$border-color};
   --#{$prefix}border-color-translucent: #{$border-color-translucent};
-  --#{$prefix}border-opacity: 1;
 
   --#{$prefix}border-radius: #{$border-radius};
   --#{$prefix}border-radius-sm: #{$border-radius-sm};
diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 9e60529098..1e0d141acc 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -98,25 +98,11 @@ $utilities: map-merge(
     // scss-docs-start utils-borders
     "border": (
       property: border,
-      local-vars: (
-        "border-opacity": 1
-      ),
       values: (
         null: var(--#{$prefix}border-width) var(--#{$prefix}border-style) var(--#{$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: (
@@ -150,6 +136,9 @@ $utilities: map-merge(
     "border-color": (
       property: border-color,
       class: border,
+      local-vars: (
+        "border-opacity": 1
+      ),
       values: $utilities-border-colors
     ),
     "border-width": (
@@ -158,6 +147,17 @@ $utilities: map-merge(
       class: border,
       values: $border-widths
     ),
+    "border-opacity": (
+      css-var: true,
+      class: border-opacity,
+      values: (
+        10: .1,
+        25: .25,
+        50: .5,
+        75: .75,
+        100: 1
+      )
+    ),
     // scss-docs-end utils-borders
     // Sizing utilities
     // scss-docs-start utils-sizing
diff --git a/site/content/docs/5.1/utilities/borders.md b/site/content/docs/5.1/utilities/borders.md
index bba34358eb..1df69f3725 100644
--- a/site/content/docs/5.1/utilities/borders.md
+++ b/site/content/docs/5.1/utilities/borders.md
@@ -12,6 +12,8 @@ Use border utilities to add or remove an element's borders. Choose from all bord
 
 ### Additive
 
+Add borders to custom elements:
+
 {{< example class="bd-example-border-utils" >}}
 <span class="border"></span>
 <span class="border-top"></span>
@@ -22,6 +24,8 @@ Use border utilities to add or remove an element's borders. Choose from all bord
 
 ### Subtractive
 
+Or remove borders:
+
 {{< example class="bd-example-border-utils bd-example-border-utils-0" >}}
 <span class="border-0"></span>
 <span class="border-top-0"></span>
@@ -43,11 +47,22 @@ Change the border color using utilities built on our theme colors.
 <span class="border border-white"></span>
 {{< /example >}}
 
-{{< callout >}}
-Unlike text and background color utilities, border color utilities redeclare the `border-color` property **without** an additional `--bs-border-opacity`, as opposed to resetting only `--bs-border-color`. This ensures the backward compatibility of border color utilities applying to other components while providing additional functionality through CSS variables.
+Or modify the default `border-color` of a component:
 
-This will be revisited in a future major release.
-{{< /callout >}}
+{{< example >}}
+<div class="mb-4">
+  <label for="exampleFormControlInput1" class="form-label">Email address</label>
+  <input type="email" class="form-control border-success" id="exampleFormControlInput1" placeholder="name@example.com">
+</div>
+
+<div class="h4 pb-2 mb-4 text-danger border-bottom border-danger">
+  Dangerous heading
+</div>
+
+<div class="p-3 bg-info bg-opacity-10 border border-info border-start-0 rounded-end">
+  Changing border color and width
+</div>
+{{< /example >}}
 
 ## Opacity