Add new text-bg-color utilities

4 files changed, 64 insertions, 0 deletions

diff --git a/scss/_helpers.scss b/scss/_helpers.scss
index 4a989f5a5c..644b693fbc 100644
--- a/scss/_helpers.scss
+++ b/scss/_helpers.scss
@@ -1,4 +1,5 @@
 @import "helpers/clearfix";
+@import "helpers/color-bg";
 @import "helpers/colored-links";
 @import "helpers/ratio";
 @import "helpers/position";
diff --git a/scss/helpers/_color-bg.scss b/scss/helpers/_color-bg.scss
new file mode 100644
index 0000000000..80ba863034
--- /dev/null
+++ b/scss/helpers/_color-bg.scss
@@ -0,0 +1,10 @@
+// stylelint-disable declaration-no-important, function-name-case
+
+// All-caps `RGBA()` function used because of this Sass bug: https://github.com/sass/node-sass/issues/2251
+@each $color, $value in $theme-colors {
+  $color-rgb: to-rgb($value);
+  .text-bg-#{$color} {
+    color: color-contrast($value) !important;
+    background-color: RGBA($color-rgb, var(--#{$prefix}bg-opacity, 1)) !important;
+  }
+}
diff --git a/site/content/docs/5.1/helpers/color-background.md b/site/content/docs/5.1/helpers/color-background.md
new file mode 100644
index 0000000000..c4174845c6
--- /dev/null
+++ b/site/content/docs/5.1/helpers/color-background.md
@@ -0,0 +1,52 @@
+---
+layout: docs
+title: Color & background
+description: Set a background color with contrasting foreground color.
+group: helpers
+toc: true
+added: "5.2"
+---
+
+## Overview
+
+{{< added-in "5.2.0" >}}
+
+Color and background helpers combine the power of our [`.text-*` utilities]({{< docsref "/utilities/colors" >}}) and [`.bg-*` utilities]({{< docsref "/utilities/background" >}}) in one class. Using our Sass `color-contrast()` function, we automatically determine a contrasting `color` for a particular `background-color`.
+
+{{< callout warning >}}
+**Heads up!** There's currently no support for a CSS-native `color-contrast` function, so we use our own via Sass. This means that customizing our theme colors via CSS variables may cause color contrast issues with these utilities.
+{{< /callout >}}
+
+{{< example >}}
+{{< text-bg.inline >}}
+{{- range (index $.Site.Data "theme-colors") }}
+<div class="text-bg-{{ .name }} p-3">{{ .name | title }} with contrasting color</div>
+{{- end -}}
+{{< /text-bg.inline >}}
+{{< /example >}}
+
+## With components
+
+Use them in place of combined `.text-*` and `.bg-*` classes, like on [badges]({{< docsref "/components/badge#background-colors" >}}):
+
+{{< example >}}
+<span class="badge text-bg-primary">Primary</span>
+<span class="badge text-bg-info">Info</span>
+{{< /example >}}
+
+Or on [cards]({{< docsref "/components/card#background-and-color" >}}):
+
+{{< example >}}
+<div class="card text-bg-primary mb-3" style="max-width: 18rem;">
+  <div class="card-header">Header</div>
+  <div class="card-body">
+    <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
+  </div>
+</div>
+<div class="card text-bg-info mb-3" style="max-width: 18rem;">
+  <div class="card-header">Header</div>
+  <div class="card-body">
+    <p class="card-text">Some quick example text to build on the card title and make up the bulk of the card's content.</p>
+  </div>
+</div>
+{{< /example >}}
diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
index eb03285c5f..cdf0b04d8b 100644
--- a/site/data/sidebar.yml
+++ b/site/data/sidebar.yml
@@ -100,6 +100,7 @@
   icon_color: orange
   pages:
     - title: Clearfix
+    - title: Color & background
     - title: Colored links
     - title: Ratio
     - title: Position