Drop color(), theme-color() & gray() functions

scss/_alert.scss

@@ -46,6 +46,6 @@
 
 @each $color, $value in $theme-colors {
   .alert-#{$color} {
-    @include alert-variant(theme-color-level($color, $alert-bg-level), theme-color-level($color, $alert-border-level), theme-color-level($color, $alert-color-level));
+    @include alert-variant(color-level($value, $alert-bg-level), color-level($value, $alert-border-level), color-level($value, $alert-color-level));
   }
 }

scss/_functions.scss

@@ -93,22 +93,8 @@
   @return if($yiq >= $yiq-contrasted-threshold, $dark, $light);
 }
 
-// Retrieve color Sass maps
-@function color($key: "blue") {
-  @return map-get($colors, $key);
-}
-
-@function theme-color($key: "primary") {
-  @return map-get($theme-colors, $key);
-}
-
-@function gray($key: "100") {
-  @return map-get($grays, $key);
-}
-
-// Request a theme color level
-@function theme-color-level($color-name: "primary", $level: 0) {
-  $color: theme-color($color-name);
+// Request a color level
+@function color-level($color: $primary, $level: 0) {
   $color-base: if($level > 0, $black, $white);
   $level: abs($level);
 

scss/_list-group.scss

@@ -155,5 +155,5 @@
 // Organizationally, this must come after the `:hover` states.
 
 @each $color, $value in $theme-colors {
-  @include list-group-item-variant($color, theme-color-level($color, -9), theme-color-level($color, 6));
+  @include list-group-item-variant($color, color-level($value, -9), color-level($value, 6));
 }

scss/_tables.scss

@@ -106,7 +106,7 @@
 // inheritance to nested tables.
 
 @each $color, $value in $theme-colors {
-  @include table-row-variant($color, theme-color-level($color, $table-bg-level), theme-color-level($color, $table-border-level));
+  @include table-row-variant($color, color-level($value, $table-bg-level), color-level($value, $table-border-level));
 }
 
 @include table-row-variant(active, $table-active-bg);

scss/_variables.scss

@@ -161,7 +161,7 @@ $body-text-align:           null !default;
 //
 // Style anchor elements.
 
-$link-color:                              theme-color("primary") !default;
+$link-color:                              $primary !default;
 $link-decoration:                         none !default;
 $link-hover-color:                        darken($link-color, 15%) !default;
 $link-hover-decoration:                   underline !default;
@@ -244,7 +244,7 @@ $box-shadow-lg:               0 1rem 3rem rgba($black, .175) !default;
 $box-shadow-inset:            inset 0 1px 2px rgba($black, .075) !default;
 
 $component-active-color:      $white !default;
-$component-active-bg:         theme-color("primary") !default;
+$component-active-bg:         $primary !default;
 
 $caret-width:                 .3em !default;
 $caret-vertical-align:        $caret-width * .85 !default;
@@ -661,8 +661,8 @@ $form-file-button-bg:             $input-group-addon-bg !default;
 
 $form-feedback-margin-top:          $form-text-margin-top !default;
 $form-feedback-font-size:           $small-font-size !default;
-$form-feedback-valid-color:         theme-color("success") !default;
-$form-feedback-invalid-color:       theme-color("danger") !default;
+$form-feedback-valid-color:         $success !default;
+$form-feedback-invalid-color:       $danger !default;
 
 $form-feedback-icon-valid-color:    $form-feedback-valid-color !default;
 $form-feedback-icon-valid:          url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 8 8'><path fill='#{$form-feedback-icon-valid-color}' d='M2.3 6.73L.6 4.53c-.4-1.04.46-1.4 1.1-.8l1.1 1.4 3.4-3.8c.6-.63 1.6-.27 1.2.7l-4 4.6c-.43.5-.8.4-1.1.1z'/></svg>") !default;
@@ -985,7 +985,7 @@ $progress-bg:                       $gray-200 !default;
 $progress-border-radius:            $border-radius !default;
 $progress-box-shadow:               $box-shadow-inset !default;
 $progress-bar-color:                $white !default;
-$progress-bar-bg:                   theme-color("primary") !default;
+$progress-bar-bg:                   $primary !default;
 $progress-bar-animation-timing:     1s linear infinite !default;
 $progress-bar-transition:           width .6s ease !default;
 

site/content/docs/4.3/getting-started/theming.md

@@ -100,12 +100,19 @@ Some of our Sass maps are merged into empty ones by default. This is done to all
 
 #### Modify map
 
-To modify an existing color in our `$theme-colors` map, add the following to your custom Sass file:
+All variables in the `$theme-colors` map are defined as standalone variables. To modify an existing color in our `$theme-colors` map, add the following to your custom Sass file:
+
+{{< highlight scss >}}
+$primary: #0074d9;
+$danger: #ff4136;
+{{< /highlight >}}
+
+Later on, theses variables are set in Bootstrap's `$theme-colors` map:
 
 {{< highlight scss >}}
 $theme-colors: (
-  "primary": #0074d9,
-  "danger": #ff4136
+  "primary": $primary,
+  "danger": $danger
 );
 {{< /highlight >}}
 
@@ -146,36 +153,19 @@ For example, we use the `primary`, `success`, and `danger` keys from `$theme-col
 
 ### Functions
 
-Bootstrap utilizes several Sass functions, but only a subset are applicable to general theming. We've included three functions for getting values from the color maps:
-
-{{< highlight scss >}}
-@function color($key: "blue") {
-  @return map-get($colors, $key);
-}
-
-@function theme-color($key: "primary") {
-  @return map-get($theme-colors, $key);
-}
-
-@function gray($key: "100") {
-  @return map-get($grays, $key);
-}
-{{< /highlight >}}
-
-These allow you to pick one color from a Sass map much like how you'd use a color variable from v3.
+In Bootstrap 5, we've dropped the `color()`, `theme-color()` and `gray()` functions because the values are also available as standalone variables. So instead of using `theme-color("primary")`, you can now just use the `$primary` variable.
 
 {{< highlight scss >}}
 .custom-element {
-  color: gray("100");
-  background-color: theme-color("dark");
+  color: $gray-100;
+  background-color: $dark;
 }
 {{< /highlight >}}
 
-We also have another function for getting a particular _level_ of color from the `$theme-colors` map. Negative level values will lighten the color, while higher levels will darken.
+We also have a function for getting a particular _level_ of color. Negative level values will lighten the color, while higher levels will darken.
 
 {{< highlight scss >}}
-@function theme-color-level($color-name: "primary", $level: 0) {
-  $color: theme-color($color-name);
+@function color-level($color: $primary, $level: 0) {
   $color-base: if($level > 0, #000, #fff);
   $level: abs($level);
 
@@ -187,12 +177,10 @@ In practice, you'd call the function and pass in two parameters: the name of the
 
 {{< highlight scss >}}
 .custom-element {
-  color: theme-color-level(primary, -10);
+  color: color-level($primary, -10);
 }
 {{< /highlight >}}
 
-Additional functions could be added in the future or your own custom Sass to create level functions for additional Sass maps, or even a generic one if you wanted to be more verbose.
-
 ### Color contrast
 
 An additional function we include in Bootstrap is the color contrast function, `color-yiq`. It utilizes the [YIQ color space](https://en.wikipedia.org/wiki/YIQ) to automatically return a light (`#fff`) or dark (`#111`) contrast color based on the specified base color. This function is especially useful for mixins or loops where you're generating multiple classes.
@@ -219,7 +207,7 @@ You can also specify a base color with our color map functions:
 
 {{< highlight scss >}}
 .custom-element {
-  color: color-yiq(theme-color("dark")); // returns `color: #fff`
+  color: color-yiq($dark); // returns `color: #fff`
 }
 {{< /highlight >}}
 
@@ -272,11 +260,7 @@ All colors available in Bootstrap 4, are available as Sass variables and a Sass
 Here's how you can use these in your Sass:
 
 {{< highlight scss >}}
-// With variable
 .alpha { color: $purple; }
-
-// From the Sass map with our `color()` function
-.beta { color: color("purple"); }
 {{< /highlight >}}
 
 [Color utility classes]({{< docsref "/utilities/colors" >}}) are also available for setting `color` and `background-color`.
@@ -349,7 +333,7 @@ Here are two examples of how we loop over the `$theme-colors` map to generate mo
 // Generate alert modifier classes
 @each $color, $value in $theme-colors {
   .alert-#{$color} {
-    @include alert-variant(theme-color-level($color, -10), theme-color-level($color, -9), theme-color-level($color, 6));
+    @include alert-variant(color-level($color, -10), color-level($color, -9), color-level($color, 6));
   }
 }
 

site/content/docs/4.3/migration.md

@@ -33,6 +33,8 @@ Changes to our source Sass files and compiled CSS.
 - **Todo:** Rearrange forms source files (under `scss/forms/`)
 - **Todo:** Rearrange grid source files (under `scss/grid/`)
 - Removed print styles and `$enable-print-styles` variable. Print display classes, however, have remained intact. [See #28339](https://github.com/twbs/bootstrap/pull/28339).
+- Dropped `color()`, `theme-color()` & `gray()` functions in favor of variables. [See #29083](https://github.com/twbs/bootstrap/pull/29083)
+- The `theme-color-level()` function is renamed to `color-level()` and now accepts any color you want instead of only `$theme-color` colors. [See #29083](https://github.com/twbs/bootstrap/pull/29083)
 
 ## JavaScript