Colors rewrite (#30622)

2 files changed, 19 insertions, 6 deletions

diff --git a/site/content/docs/5.0/customize/sass.md b/site/content/docs/5.0/customize/sass.md
index 7a7b7fb1e..209ad2152 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 877339449..1b179f2e7 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)