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

diff --git a/scss/_maps.scss b/scss/_maps.scss
index c8b9fa7e538ab3add2cafab984a0952aa8bc5f29..2770a67615c7445dbdb1008deeffb2ae64d25096 100644 (file)
--- 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 2927c343ff23e1e125af058d822aff7747b37948..ab0584e68a35949f81f8e2024448ca4cf1122048 100644 (file)
--- 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 4d65bb88b52298debfe209be16b3b77356dbef1f..7fc732acf665fab9bf87cf07a6812b8ca59274c5 100644 (file)
--- 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 e871b4233671123ba99fad213556598fddadf66a..b2c6683d7de923f7e088f25417d4e036e7b6c69c 100644 (file)
--- 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);

diff --git a/site/content/docs/5.1/utilities/api.md b/site/content/docs/5.1/utilities/api.md
index f961a5da9b6a4b0ddf58e15975b433102fb85031..16270ad5112c3d49f5be4337d857ffc79bb4ba28 100644 (file)
--- 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 6ba1174c9d517845e8f076bb970c85dd07437f95..e76c461a3ac269b046b0d96fc8d6960344589772 100644 (file)
--- 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.