Colors rewrite (#30622)

5 files changed, 24 insertions, 11 deletions

diff --git a/site/assets/scss/_buttons.scss b/site/assets/scss/_buttons.scss
index 6a2d703e63..b266d3e88e 100644
--- a/site/assets/scss/_buttons.scss
+++ b/site/assets/scss/_buttons.scss
@@ -11,8 +11,8 @@
   &:hover,
   &:active {
     color: $white;
-    background-color: darken($bd-purple-bright, 10%);
-    border-color: darken($bd-purple-bright, 10%);
+    background-color: shade-color($bd-purple-bright, 20%);
+    border-color: shade-color($bd-purple-bright, 20%);
   }
 
   &:focus {
diff --git a/site/assets/scss/_masthead.scss b/site/assets/scss/_masthead.scss
index a8ea52c869..2e742e76d1 100644
--- a/site/assets/scss/_masthead.scss
+++ b/site/assets/scss/_masthead.scss
@@ -1,6 +1,6 @@
 .bd-masthead {
   padding: 3rem 0;
-  background: linear-gradient(165deg, lighten($bd-purple-light, 16%) 50%, $white 50%);
+  background: linear-gradient(165deg, tint-color($bd-purple-light, 85%) 50%, $white 50%);
 
   h1 {
     @include font-size(4rem);
diff --git a/site/assets/scss/_variables.scss b/site/assets/scss/_variables.scss
index 4ebe2be710..110600260c 100644
--- a/site/assets/scss/_variables.scss
+++ b/site/assets/scss/_variables.scss
@@ -2,8 +2,8 @@
 
 // Local docs variables
 $bd-purple:        #563d7c;
-$bd-purple-bright: lighten(saturate($bd-purple, 5%), 15%);
-$bd-purple-light:  lighten(saturate($bd-purple, 5%), 45%);
+$bd-purple-bright: lighten(saturate($bd-purple, 5%), 15%); // stylelint-disable-line function-disallowed-list
+$bd-purple-light:  lighten(saturate($bd-purple, 5%), 45%); // stylelint-disable-line function-disallowed-list
 $bd-dark:          #2a2730;
 $bd-download:      #ffe484;
 $bd-info:          #5bc0de;
diff --git a/site/content/docs/5.0/customize/sass.md b/site/content/docs/5.0/customize/sass.md
index 7a7b7fb1eb..209ad2152a 100644
--- a/site/content/docs/5.0/customize/sass.md
+++ b/site/content/docs/5.0/customize/sass.md
@@ -152,7 +152,7 @@ For example, we use the `primary`, `success`, and `danger` keys from `$theme-col
 
 ### Colors
 
-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.
+Next to the [Sass maps]({{< docsref "/customize/color#color-sass-maps" >}}) we have, theme colors can also be used as standalone variables, like `$primary`.
 
 {{< highlight scss >}}
 .custom-element {
@@ -161,15 +161,19 @@ In Bootstrap 5, we've dropped the `color()`, `theme-color()` and `gray()` functi
 }
 {{< /highlight >}}
 
-We also have a function for getting a particular _level_ of color. Negative level values will lighten the color, while higher levels will darken.
+You can lighten or darken colors with Bootstrap's `tint-color()` and `shade-color()` functions. These functions will mix colors with black or white, unlike Sass' native `lighten()` and `darken()` functions which will change the lightness by a fixed amount, which often doesn't lead to the desired effect.
 
-{{< scss-docs name="color-level" file="scss/_functions.scss" >}}
+{{< scss-docs name="color-functions" file="scss/_functions.scss" >}}
 
-In practice, you'd call the function and pass in two parameters: the name of the color from `$theme-colors` (e.g., primary or danger) and a numeric level.
+In practice, you'd call the function and pass in the color and weight parameters.
 
 {{< highlight scss >}}
 .custom-element {
-  color: color-level($primary, -10);
+  color: tint-color($primary, 10%);
+}
+
+.custom-element-2 {
+  color: shade-color($danger, 30%);
 }
 {{< /highlight >}}
 
diff --git a/site/content/docs/5.0/migration.md b/site/content/docs/5.0/migration.md
index 8773394495..1b179f2e71 100644
--- a/site/content/docs/5.0/migration.md
+++ b/site/content/docs/5.0/migration.md
@@ -7,6 +7,15 @@ aliases: "/migration/"
 toc: true
 ---
 
+## v5.0.0-alpha3
+
+### Colors
+
+- The color system which worked with `color-level()` and `$theme-color-interval` was removed in favor of a new color system.
+- All `lighten()` and `darken()` functions in our codebase are replaced by `tint-color()` and `shade-color()`. These functions will mix the color with either white or black instead of changing its lightness by a fixed amount.
+- The `scale-color()` will either tint or shade a color depending on whether its weight parameter is positive or negative.
+- See [this PR](https://github.com/twbs/bootstrap/pull/30622) for more details.
+
 ## v5.0.0-alpha2
 
 ### Sass
@@ -152,7 +161,7 @@ Changes to our source Sass files and compiled CSS.
 - Rearranged forms source files under `scss/forms/`. [See Forms section for more details.](#forms)
 - 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)
+- 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) **Watch out:** `color-level()` was later on dropped in `v5.0.0-alpha3`.
 - `$enable-grid-classes` doesn't disable the generation of container classes anymore [See #29146](https://github.com/twbs/bootstrap/pull/29146)
 - Renamed `$enable-prefers-reduced-motion-media-query` and `$enable-pointer-cursor-for-buttons` to `$enable-reduced-motion` and `$enable-button-pointers` for brevity.
 - Line heights are dropped from several components to simplify our codebase. The `button-size()` and `pagination-size()` do not accept line height parameters anymore. [See #29271](https://github.com/twbs/bootstrap/pull/29271)