Rename theme text tokens to fg, update utilities (#42295)

With this refactor, our .fg-* and .bg-* and .border-* utilities can be modified by custom CSS, like in our blue theme example.

This also standardizes some nomenclature by using fg instead of text in the token names for theme values, better matching bg. Classes already use this, as do root fg tokens, so this is just a consistency update.

Author: mdo

scss/_accordion.scss

@@ -106,7 +106,7 @@ $accordion-tokens: defaults(
       border-color: var(--theme-border, var(--accordion-border-color));
 
       > .accordion-header {
-        color: var(--theme-text, var(--accordion-active-color));
+        color: var(--theme-fg, var(--accordion-active-color));
         background-color: var(--theme-bg-subtle, var(--accordion-active-bg));
         box-shadow: inset 0 calc(-1 * var(--accordion-border-width)) 0 var(--theme-border, var(--accordion-border-color));
 

scss/_alert.scss

@@ -13,7 +13,7 @@ $alert-tokens: defaults(
     --alert-bg: var(--theme-bg-subtle, var(--bg-1)),
     --alert-padding-x: #{$spacer},
     --alert-padding-y: #{$spacer},
-    --alert-color: var(--theme-text, inherit),
+    --alert-color: var(--theme-fg, inherit),
     --alert-border-color: var(--theme-border, var(--border-color)),
     --alert-border: var(--border-width) solid var(--alert-border-color),
     --alert-border-radius: var(--border-radius),

scss/_avatar.scss

@@ -75,7 +75,7 @@ $avatar-sizes: defaults(
   }
 
   .avatar-subtle {
-    color: var(--theme-text, var(--avatar-color));
+    color: var(--theme-fg, var(--avatar-color));
     background-color: var(--theme-bg-subtle, var(--avatar-bg));
   }
 

scss/_card.scss

@@ -140,13 +140,13 @@ $card-tokens: defaults(
     border-color: var(--theme-border, var(--card-border-color));
 
     .card-header {
-      color: var(--theme-text-emphasis, currentcolor);
+      color: var(--theme-fg-emphasis, currentcolor);
       background-color: var(--theme-bg-subtle, var(--card-cap-bg));
       border-color: var(--theme-border, var(--card-border-color));
     }
 
     .card-footer {
-      color: var(--theme-text-emphasis, currentcolor);
+      color: var(--theme-fg-emphasis, currentcolor);
       background-color: var(--theme-bg-subtle, var(--card-cap-bg));
       border-color: var(--theme-border, var(--card-border-color));
     }

scss/_chip.scss

@@ -19,7 +19,7 @@ $chip-tokens: defaults(
     --chip-dismiss-size: 1rem,
     --chip-dismiss-opacity: .65,
     --chip-dismiss-hover-opacity: 1,
-    --chip-color: var(--theme-text, var(--fg-body)),
+    --chip-color: var(--theme-fg, var(--fg-body)),
     --chip-bg: var(--theme-bg-subtle, var(--bg-2)),
     --chip-border-color: transparent,
     --chip-selected-color: var(--theme-contrast, var(--primary-contrast)),

scss/_list-group.scss

@@ -65,7 +65,7 @@ $list-group-tokens: defaults(
     position: relative;
     display: block;
     padding: var(--list-group-item-padding-y) var(--list-group-item-padding-x);
-    color: var(--theme-text, var(--list-group-color));
+    color: var(--theme-fg, var(--list-group-color));
     // stylelint-disable-next-line scss/at-function-named-arguments
     text-decoration: if(sass($link-decoration == none): null);
     background-color: var(--theme-bg-subtle, var(--list-group-bg));
@@ -112,7 +112,7 @@ $list-group-tokens: defaults(
 
   .list-group-item-action {
     width: 100%; // For `<button>`s (anchors become 100% by default though)
-    color: var(--theme-text, var(--list-group-action-color));
+    color: var(--theme-fg, var(--list-group-action-color));
     text-align: inherit; // For `<button>`s (anchors inherit)
     text-decoration: none;
 
@@ -121,13 +121,13 @@ $list-group-tokens: defaults(
       &:hover,
       &:focus {
         z-index: 1; // Place hover/focus items above their siblings for proper border styling
-        color: var(--theme-text-emphasis, var(--list-group-action-hover-color));
+        color: var(--theme-fg-emphasis, var(--list-group-action-hover-color));
         text-decoration: none;
         background-color: var(--theme-bg-muted, var(--list-group-action-hover-bg));
       }
 
       &:active {
-        color: var(--theme-text-emphasis, var(--list-group-action-active-color));
+        color: var(--theme-fg-emphasis, var(--list-group-action-active-color));
         background-color: var(--theme-bg-muted, var(--list-group-action-active-bg));
       }
     }

scss/_menu.scss

@@ -152,7 +152,7 @@ $menu-tokens: defaults(
     width: 100%;
     padding: var(--menu-item-padding-y) var(--menu-item-padding-x);
     font-weight: var(--menu-item-font-weight, var(--font-weight-normal));
-    color: var(--theme-text, var(--menu-item-color));
+    color: var(--theme-fg, var(--menu-item-color));
     text-align: inherit;
     text-decoration: none;
     white-space: nowrap;
@@ -164,7 +164,7 @@ $menu-tokens: defaults(
 
     &:hover,
     &:focus {
-      color: var(--theme-text-emphasis, var(--menu-item-hover-color));
+      color: var(--theme-fg-emphasis, var(--menu-item-hover-color));
       background-color: var(--theme-bg-subtle, var(--menu-item-hover-bg));
       // @include gradient-bg(var(--theme-bg-subtle, var(--menu-item-hover-bg)));
     }

scss/_root.scss

@@ -41,7 +41,7 @@ $root-tokens: defaults(
 
     --hr-border-color: var(--border-color),
 
-    --link-color: light-dark(var(--primary-base), var(--primary-text)),
+    --link-color: light-dark(var(--primary-base), var(--primary-fg)),
     --link-decoration: #{$link-decoration},
     --link-hover-color: color-mix(in oklch, var(--link-color) 90%, #000),
 

scss/_theme.scss

@@ -12,6 +12,39 @@
   @return $result;
 }
 
+// Themes map sub-keys
+//
+// Return var() references to root tokens instead of raw values.
+// Ex: theme-color-refs("bg") => (primary: var(--primary-bg), accent: var(--accent-bg), ...)
+@function theme-color-refs($key) {
+  $result: ();
+
+  @each $color-name, $color-map in $theme-colors {
+    @if map.has-key($color-map, $key) {
+      $result: map.merge($result, ($color-name: var(--#{$color-name}-#{$key})));
+    }
+  }
+
+  @return $result;
+}
+
+// Theme token to root tokens
+//
+// Returns the global :root token reference for a given a given token map, prefix, and key.
+// Ex: theme-token-refs($theme-bgs, "bg") => (body: var(--bg-body), 1: var(--bg-1), ...)
+// Skips `inherit` since it's a CSS-wide keyword that can't be stored in a custom property.
+@function theme-token-refs($map, $prefix) {
+  $result: ();
+
+  @each $key, $value in $map {
+    @if $value != inherit {
+      $result: map.merge($result, ($key: var(--#{$prefix}-#{$key})));
+    }
+  }
+
+  @return $result;
+}
+
 // Generate opacity values using color-mix()
 @function theme-opacity-values($color-var, $opacities: $util-opacity) {
   $result: ();
@@ -45,8 +78,8 @@
 $theme-colors: (
   "primary": (
     "base": var(--blue-500),
-    "text": light-dark(var(--blue-600), var(--blue-400)),
-    "text-emphasis": light-dark(var(--blue-800), var(--blue-200)),
+    "fg": light-dark(var(--blue-600), var(--blue-400)),
+    "fg-emphasis": light-dark(var(--blue-800), var(--blue-200)),
     "bg": var(--blue-500),
     "bg-subtle": light-dark(var(--blue-100), var(--blue-900)),
     "bg-muted": light-dark(var(--blue-200), var(--blue-800)),
@@ -56,8 +89,8 @@ $theme-colors: (
   ),
   "accent": (
     "base": var(--indigo-500),
-    "text": light-dark(var(--indigo-600), color-mix(in oklch, var(--indigo-400), var(--indigo-300))),
-    "text-emphasis": light-dark(var(--indigo-800), var(--indigo-300)),
+    "fg": light-dark(var(--indigo-600), color-mix(in oklch, var(--indigo-400), var(--indigo-300))),
+    "fg-emphasis": light-dark(var(--indigo-800), var(--indigo-300)),
     "bg": var(--indigo-500),
     "bg-subtle": light-dark(var(--indigo-100), var(--indigo-900)),
     "bg-muted": light-dark(var(--indigo-200), var(--indigo-800)),
@@ -67,8 +100,8 @@ $theme-colors: (
   ),
   "success": (
     "base": var(--green-500),
-    "text": light-dark(var(--green-600), var(--green-400)),
-    "text-emphasis": light-dark(var(--green-800), var(--green-300)),
+    "fg": light-dark(var(--green-600), var(--green-400)),
+    "fg-emphasis": light-dark(var(--green-800), var(--green-300)),
     "bg": var(--green-500),
     "bg-subtle": light-dark(var(--green-100), var(--green-900)),
     "bg-muted": light-dark(var(--green-200), var(--green-800)),
@@ -78,8 +111,8 @@ $theme-colors: (
   ),
   "danger": (
     "base": var(--red-500),
-    "text": light-dark(var(--red-600), var(--red-400)),
-    "text-emphasis": light-dark(var(--red-800), var(--red-300)),
+    "fg": light-dark(var(--red-600), var(--red-400)),
+    "fg-emphasis": light-dark(var(--red-800), var(--red-300)),
     "bg": var(--red-500),
     "bg-subtle": light-dark(var(--red-100), var(--red-900)),
     "bg-muted": light-dark(var(--red-200), var(--red-800)),
@@ -89,8 +122,8 @@ $theme-colors: (
   ),
   "warning": (
     "base": var(--yellow-500),
-    "text": light-dark(var(--yellow-700), var(--yellow-400)),
-    "text-emphasis": light-dark(var(--yellow-800), var(--yellow-300)),
+    "fg": light-dark(var(--yellow-700), var(--yellow-400)),
+    "fg-emphasis": light-dark(var(--yellow-800), var(--yellow-300)),
     "bg": var(--yellow-500),
     "bg-subtle": light-dark(var(--yellow-100), var(--yellow-900)),
     "bg-muted": light-dark(var(--yellow-200), var(--yellow-800)),
@@ -100,8 +133,8 @@ $theme-colors: (
   ),
   "info": (
     "base": var(--cyan-500),
-    "text": light-dark(var(--cyan-600), var(--cyan-400)),
-    "text-emphasis": light-dark(var(--cyan-800), var(--cyan-300)),
+    "fg": light-dark(var(--cyan-600), var(--cyan-400)),
+    "fg-emphasis": light-dark(var(--cyan-800), var(--cyan-300)),
     "bg": var(--cyan-500),
     "bg-subtle": light-dark(var(--cyan-100), var(--cyan-900)),
     "bg-muted": light-dark(var(--cyan-200), var(--cyan-800)),
@@ -111,8 +144,8 @@ $theme-colors: (
   ),
   "inverse": (
     "base": var(--gray-900),
-    "text": light-dark(var(--gray-900), var(--gray-200)),
-    "text-emphasis": light-dark(var(--gray-975), var(--white)),
+    "fg": light-dark(var(--gray-900), var(--gray-200)),
+    "fg-emphasis": light-dark(var(--gray-975), var(--white)),
     "bg": light-dark(var(--gray-900), var(--gray-025)),
     "bg-subtle": light-dark(var(--gray-100), var(--gray-900)),
     "bg-muted": light-dark(var(--gray-200), var(--gray-300)),
@@ -122,8 +155,8 @@ $theme-colors: (
   ),
   "secondary": (
     "base": var(--gray-200),
-    "text": light-dark(var(--gray-600), var(--gray-400)),
-    "text-emphasis": light-dark(var(--gray-800), var(--gray-200)),
+    "fg": light-dark(var(--gray-600), var(--gray-400)),
+    "fg-emphasis": light-dark(var(--gray-800), var(--gray-200)),
     "bg": light-dark(var(--gray-100), var(--gray-600)),
     "bg-subtle": light-dark(var(--gray-050), var(--gray-800)),
     "bg-muted": light-dark(var(--gray-100), var(--gray-700)),

scss/_toasts.scss

@@ -76,7 +76,7 @@ $toast-tokens: defaults(
     display: flex;
     align-items: center;
     padding: var(--toast-padding-y) var(--toast-padding-x);
-    color: var(--theme-text-emphasis, var(--toast-header-color));
+    color: var(--theme-fg-emphasis, var(--toast-header-color));
     background-color: var(--theme-bg-subtle, var(--toast-header-bg));
     // background-clip: padding-box;
     border-block-end: var(--toast-border-width, var(--border-width)) solid var(--theme-border, var(--toast-header-border-color, var(--border-color-translucent)));