Update color and background-color utilities

- Adds new functions to generate additional Sass maps
- Adds new root variables for rgb() versions of our theme colors, plus a few extras
- Adds ability to change the alpha transparency of text color and background color utilities with new utilities, inline styles, or local CSS var
- Updates documentation for color and background-color utilities pages
- Deprecates .text-black-50 and .text-white-50 since those (and additional transparency levels) can be generated on the fly

Change approach slightly to prevent cascade

5 files changed, 127 insertions, 14 deletions

diff --git a/scss/_functions.scss b/scss/_functions.scss
index 1f3263175e..e00395505f 100644
--- a/scss/_functions.scss
+++ b/scss/_functions.scss
@@ -32,6 +32,41 @@
   }
 }
 
+// Colors
+@function to-rgb($value) {
+  @return red($value), green($value), blue($value);
+}
+
+@function rgba-css-var($identifier, $target) {
+  @return rgba(var(--#{$variable-prefix}#{$identifier}-rgb), var(--#{$variable-prefix}#{$target}-opacity));
+}
+
+// stylelint-disable scss/dollar-variable-pattern
+@function map-loop($map, $func, $args...) {
+  $_map: ();
+
+  @each $key, $value in $map {
+    // allow to pass the $key and $value of the map as an function argument
+    $_args: ();
+    @each $arg in $args {
+      $_args: append($_args, if($arg == "$key", $key, if($arg == "$value", $value, $arg)));
+    }
+
+    $_map: map-merge($_map, ($key: call(get-function($func), $_args...)));
+  }
+
+  @return $_map;
+}
+// stylelint-enable scss/dollar-variable-pattern
+
+@function varify($list) {
+  $result: null;
+  @each $entry in $list {
+    $result: append($result, var(--#{$variable-prefix}#{$entry}), space);
+  }
+  @return $result;
+}
+
 // Internal Bootstrap function to turn maps into its negative variant.
 // It prefixes the keys with `n` and makes the value negative.
 @function negativify-map($map) {
diff --git a/scss/_root.scss b/scss/_root.scss
index 768d6343f8..95c7739011 100644
--- a/scss/_root.scss
+++ b/scss/_root.scss
@@ -8,6 +8,14 @@
     --#{$variable-prefix}#{$color}: #{$value};
   }
 
+  @each $color, $value in $theme-colors-rgb {
+    --#{$variable-prefix}#{$color}-rgb: #{$value};
+  }
+
+  --#{$variable-prefix}white-rgb: #{to-rgb($white)};
+  --#{$variable-prefix}black-rgb: #{to-rgb($black)};
+  --#{$variable-prefix}body-rgb: #{to-rgb($body-color)};
+
   // Use `inspect` for lists so that quoted items keep the quotes.
   // See https://github.com/sass/sass/issues/2383#issuecomment-336349172
   --#{$variable-prefix}font-sans-serif: #{inspect($font-family-sans-serif)};
diff --git a/scss/_utilities.scss b/scss/_utilities.scss
index 74f8a3a01c..960d6f1adf 100644
--- a/scss/_utilities.scss
+++ b/scss/_utilities.scss
@@ -514,32 +514,55 @@ $utilities: map-merge(
     "color": (
       property: color,
       class: text,
+      local-vars: (
+        "text-opacity": 1
+      ),
       values: map-merge(
-        $theme-colors,
+        $utilities-text-colors,
         (
-          "white": $white,
-          "body": $body-color,
           "muted": $text-muted,
-          "black-50": rgba($black, .5),
-          "white-50": rgba($white, .5),
+          "black-50": rgba($black, .5), // deprecated
+          "white-50": rgba($white, .5), // deprecated
           "reset": inherit,
         )
       )
     ),
+    "text-opacity": (
+      css-var: true,
+      class: text-opacity,
+      values: (
+        25: .25,
+        50: .5,
+        75: .75,
+        100: 1
+      )
+    ),
     // scss-docs-end utils-color
     // scss-docs-start utils-bg-color
     "background-color": (
       property: background-color,
       class: bg,
+      local-vars: (
+        "bg-opacity": 1
+      ),
       values: map-merge(
-        $theme-colors,
+        $utilities-bg-colors,
         (
-          "body": $body-bg,
-          "white": $white,
           "transparent": transparent
         )
       )
     ),
+    "bg-opacity": (
+      css-var: true,
+      class: bg-opacity,
+      values: (
+        10: .1,
+        25: .25,
+        50: .5,
+        75: .75,
+        100: 1
+      )
+    ),
     // scss-docs-end utils-bg-color
     "gradient": (
       property: background-image,
diff --git a/scss/_variables.scss b/scss/_variables.scss
index 9e921c07ef..3750fa2c23 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -90,6 +90,10 @@ $theme-colors: (
 ) !default;
 // scss-docs-end theme-colors-map
 
+// scss-docs-start theme-colors-rgb
+$theme-colors-rgb: map-loop($theme-colors, to-rgb, "$value") !default;
+// scss-docs-end theme-colors-rgb
+
 // The contrast ratio to reach against white, to determine if color changes from "light" to "dark". Acceptable values for WCAG 2.0 are 3, 4.5 and 7.
 // See https://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast
 $min-contrast-ratio:   4.5 !default;
@@ -401,6 +405,28 @@ $body-bg:                   $white !default;
 $body-color:                $gray-900 !default;
 $body-text-align:           null !default;
 
+// Utilities maps
+//
+// Extends the default `$theme-colors` maps to help create our utilities.
+
+// scss-docs-start utilities-colors
+$utilities-colors: map-merge(
+  $theme-colors-rgb,
+  (
+    "black": to-rgb($black),
+    "white": to-rgb($white),
+    "body":  to-rgb($body-color)
+  )
+) !default;
+// scss-docs-end utilities-colors
+
+// scss-docs-start utilities-text-colors
+$utilities-text-colors: map-loop($utilities-colors, rgba-css-var, "$key", "text") !default;
+// scss-docs-end utilities-text-colors
+
+// scss-docs-start utilities-bg-colors
+$utilities-bg-colors: map-loop($utilities-colors, rgba-css-var, "$key", "bg") !default;
+// scss-docs-end utilities-bg-colors
 
 // Links
 //
diff --git a/scss/mixins/_utilities.scss b/scss/mixins/_utilities.scss
index 4d2370a0bf..e871b42336 100644
--- a/scss/mixins/_utilities.scss
+++ b/scss/mixins/_utilities.scss
@@ -41,25 +41,46 @@
       }
     }
 
+    $is-css-var: map-get($utility, css-var);
+    $is-local-vars: map-get($utility, local-vars);
     $is-rtl: map-get($utility, rtl);
 
     @if $value != null {
       @if $is-rtl == false {
         /* rtl:begin:remove */
       }
-      .#{$property-class + $infix + $property-class-modifier} {
-        @each $property in $properties {
-          #{$property}: $value if($enable-important-utilities, !important, null);
+
+      @if $is-css-var {
+        .#{$property-class + $infix + $property-class-modifier} {
+          --#{$variable-prefix}#{$property-class}: #{$value};
         }
-      }
 
-      @each $pseudo in $state {
-        .#{$property-class + $infix + $property-class-modifier}-#{$pseudo}:#{$pseudo} {
+        @each $pseudo in $state {
+          .#{$property-class + $infix + $property-class-modifier}-#{$pseudo}:#{$pseudo} {
+            --#{$variable-prefix}#{$property-class}: #{$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};
+              }
+            }
             #{$property}: $value if($enable-important-utilities, !important, null);
           }
         }
+
+        @each $pseudo in $state {
+          .#{$property-class + $infix + $property-class-modifier}-#{$pseudo}:#{$pseudo} {
+            @each $property in $properties {
+              #{$property}: $value if($enable-important-utilities, !important, null);
+            }
+          }
+        }
       }
+
       @if $is-rtl == false {
         /* rtl:end:remove */
       }