Colors rewrite (#30622)

15 files changed, 157 insertions, 146 deletions

diff --git a/.stylelintrc b/.stylelintrc
index 15e5765ea1..1c9ee18116 100644
--- a/.stylelintrc
+++ b/.stylelintrc
@@ -4,7 +4,9 @@
   ],
   "rules": {
     "function-disallowed-list": [
-      "calc"
+      "calc",
+      "lighten",
+      "darken"
     ],
     "property-disallowed-list": [
       "border-radius",
diff --git a/scss/_alert.scss b/scss/_alert.scss
index dd08a55c6b..f67dcc6a1d 100644
--- a/scss/_alert.scss
+++ b/scss/_alert.scss
@@ -45,7 +45,7 @@
 
 @each $color, $value in $theme-colors {
   .alert-#{$color} {
-    @include alert-variant(color-level($value, $alert-bg-level), color-level($value, $alert-border-level), color-level($value, $alert-color-level));
+    @include alert-variant(scale-color($value, $alert-bg-scale), scale-color($value, $alert-border-scale), scale-color($value, $alert-color-scale));
   }
 }
 // scss-docs-end alert-modifiers
diff --git a/scss/_functions.scss b/scss/_functions.scss
index fd72c98bfd..b95fbf94e2 100644
--- a/scss/_functions.scss
+++ b/scss/_functions.scss
@@ -150,23 +150,23 @@ $_luminance-list: .0008 .001 .0011 .0013 .0015 .0017 .002 .0022 .0025 .0027 .003
   @return mix(rgba($foreground, 1), $background, opacity($foreground) * 100);
 }
 
-// Request a color level
-// scss-docs-start color-level
-@function color-level($color: $primary, $level: 0) {
-  $color-base: if($level > 0, $black, $white);
-  $level: abs($level);
-
-  @return mix($color-base, $color, $level * $theme-color-interval);
+// scss-docs-start color-functions
+// Tint a color: mix a color with white
+@function tint-color($color, $weight) {
+  @return mix(white, $color, $weight);
 }
-// scss-docs-end color-level
 
-@function tint-color($color, $level) {
-  @return mix(white, $color, $level * $theme-color-interval);
+// Shade a color: mix a color with black
+@function shade-color($color, $weight) {
+  @return mix(black, $color, $weight);
 }
 
-@function shade-color($color, $level) {
-  @return mix(black, $color, $level * $theme-color-interval);
+// Scale a color:
+// Shade the color if the weight is positive, else tint it
+@function scale-color($color, $weight) {
+  @return if($weight > 0, shade-color($color, $weight), tint-color($color, -$weight));
 }
+// scss-docs-end color-functions
 
 // Return valid calc
 @function add($value1, $value2, $return-calc: true) {
diff --git a/scss/_list-group.scss b/scss/_list-group.scss
index b1937909b2..84fbb1b0ee 100644
--- a/scss/_list-group.scss
+++ b/scss/_list-group.scss
@@ -152,6 +152,6 @@
 // Organizationally, this must come after the `:hover` states.
 
 @each $color, $value in $theme-colors {
-  @include list-group-item-variant($color, color-level($value, $list-group-item-bg-level), color-level($value, $list-group-item-color-level));
+  @include list-group-item-variant($color, scale-color($value, $list-group-item-bg-scale), scale-color($value, $list-group-item-color-scale));
 }
 // scss-docs-end list-group-modifiers
diff --git a/scss/_popover.scss b/scss/_popover.scss
index 6ebb2c3de8..55bfe1f9ab 100644
--- a/scss/_popover.scss
+++ b/scss/_popover.scss
@@ -156,7 +156,7 @@
   @include font-size($font-size-base);
   color: $popover-header-color;
   background-color: $popover-header-bg;
-  border-bottom: $popover-border-width solid darken($popover-header-bg, 5%);
+  border-bottom: $popover-border-width solid shade-color($popover-header-bg, 10%);
   @include border-top-radius($popover-inner-border-radius);
 
   &:empty {
diff --git a/scss/_variables.scss b/scss/_variables.scss
index 3941bab0fb..59850a592d 100644
--- a/scss/_variables.scss
+++ b/scss/_variables.scss
@@ -82,9 +82,6 @@ $theme-colors: (
 ) !default;
 // scss-docs-end theme-colors-map
 
-// Set a specific jump point for requesting color jumps
-$theme-color-interval: 8% !default;
-
 // The contrast ratio to reach against white, to determine if color changes from "light" to "dark". Acceptable values for WCAG 2.0 are 3, 4.5 and 7.
 // See https://www.w3.org/TR/WCAG20/#visual-audio-contrast-contrast
 $min-contrast-ratio:   4.5 !default;
@@ -94,105 +91,105 @@ $color-contrast-dark:      $black !default;
 $color-contrast-light:     $white !default;
 
 // fusv-disable
-$blue-100: tint-color($blue, 8) !default;
-$blue-200: tint-color($blue, 6) !default;
-$blue-300: tint-color($blue, 4) !default;
-$blue-400: tint-color($blue, 2) !default;
+$blue-100: tint-color($blue, 80%) !default;
+$blue-200: tint-color($blue, 60%) !default;
+$blue-300: tint-color($blue, 40%) !default;
+$blue-400: tint-color($blue, 20%) !default;
 $blue-500: $blue !default;
-$blue-600: shade-color($blue, 2) !default;
-$blue-700: shade-color($blue, 4) !default;
-$blue-800: shade-color($blue, 6) !default;
-$blue-900: shade-color($blue, 8) !default;
-
-$indigo-100: tint-color($indigo, 8) !default;
-$indigo-200: tint-color($indigo, 6) !default;
-$indigo-300: tint-color($indigo, 4) !default;
-$indigo-400: tint-color($indigo, 2) !default;
+$blue-600: shade-color($blue, 20%) !default;
+$blue-700: shade-color($blue, 40%) !default;
+$blue-800: shade-color($blue, 60%) !default;
+$blue-900: shade-color($blue, 80%) !default;
+
+$indigo-100: tint-color($indigo, 80%) !default;
+$indigo-200: tint-color($indigo, 60%) !default;
+$indigo-300: tint-color($indigo, 40%) !default;
+$indigo-400: tint-color($indigo, 20%) !default;
 $indigo-500: $indigo !default;
-$indigo-600: shade-color($indigo, 2) !default;
-$indigo-700: shade-color($indigo, 4) !default;
-$indigo-800: shade-color($indigo, 6) !default;
-$indigo-900: shade-color($indigo, 8) !default;
-
-$purple-100: tint-color($purple, 8) !default;
-$purple-200: tint-color($purple, 6) !default;
-$purple-300: tint-color($purple, 4) !default;
-$purple-400: tint-color($purple, 2) !default;
+$indigo-600: shade-color($indigo, 20%) !default;
+$indigo-700: shade-color($indigo, 40%) !default;
+$indigo-800: shade-color($indigo, 60%) !default;
+$indigo-900: shade-color($indigo, 80%) !default;
+
+$purple-100: tint-color($purple, 80%) !default;
+$purple-200: tint-color($purple, 60%) !default;
+$purple-300: tint-color($purple, 40%) !default;
+$purple-400: tint-color($purple, 20%) !default;
 $purple-500: $purple !default;
-$purple-600: shade-color($purple, 2) !default;
-$purple-700: shade-color($purple, 4) !default;
-$purple-800: shade-color($purple, 6) !default;
-$purple-900: shade-color($purple, 8) !default;
-
-$pink-100: tint-color($pink, 8) !default;
-$pink-200: tint-color($pink, 6) !default;
-$pink-300: tint-color($pink, 4) !default;
-$pink-400: tint-color($pink, 2) !default;
+$purple-600: shade-color($purple, 20%) !default;
+$purple-700: shade-color($purple, 40%) !default;
+$purple-800: shade-color($purple, 60%) !default;
+$purple-900: shade-color($purple, 80%) !default;
+
+$pink-100: tint-color($pink, 80%) !default;
+$pink-200: tint-color($pink, 60%) !default;
+$pink-300: tint-color($pink, 40%) !default;
+$pink-400: tint-color($pink, 20%) !default;
 $pink-500: $pink !default;
-$pink-600: shade-color($pink, 2) !default;
-$pink-700: shade-color($pink, 4) !default;
-$pink-800: shade-color($pink, 6) !default;
-$pink-900: shade-color($pink, 8) !default;
-
-$red-100: tint-color($red, 8) !default;
-$red-200: tint-color($red, 6) !default;
-$red-300: tint-color($red, 4) !default;
-$red-400: tint-color($red, 2) !default;
+$pink-600: shade-color($pink, 20%) !default;
+$pink-700: shade-color($pink, 40%) !default;
+$pink-800: shade-color($pink, 60%) !default;
+$pink-900: shade-color($pink, 80%) !default;
+
+$red-100: tint-color($red, 80%) !default;
+$red-200: tint-color($red, 60%) !default;
+$red-300: tint-color($red, 40%) !default;
+$red-400: tint-color($red, 20%) !default;
 $red-500: $red !default;
-$red-600: shade-color($red, 2) !default;
-$red-700: shade-color($red, 4) !default;
-$red-800: shade-color($red, 6) !default;
-$red-900: shade-color($red, 8) !default;
-
-$orange-100: tint-color($orange, 8) !default;
-$orange-200: tint-color($orange, 6) !default;
-$orange-300: tint-color($orange, 4) !default;
-$orange-400: tint-color($orange, 2) !default;
+$red-600: shade-color($red, 20%) !default;
+$red-700: shade-color($red, 40%) !default;
+$red-800: shade-color($red, 60%) !default;
+$red-900: shade-color($red, 80%) !default;
+
+$orange-100: tint-color($orange, 80%) !default;
+$orange-200: tint-color($orange, 60%) !default;
+$orange-300: tint-color($orange, 40%) !default;
+$orange-400: tint-color($orange, 20%) !default;
 $orange-500: $orange !default;
-$orange-600: shade-color($orange, 2) !default;
-$orange-700: shade-color($orange, 4) !default;
-$orange-800: shade-color($orange, 6) !default;
-$orange-900: shade-color($orange, 8) !default;
-
-$yellow-100: tint-color($yellow, 8) !default;
-$yellow-200: tint-color($yellow, 6) !default;
-$yellow-300: tint-color($yellow, 4) !default;
-$yellow-400: tint-color($yellow, 2) !default;
+$orange-600: shade-color($orange, 20%) !default;
+$orange-700: shade-color($orange, 40%) !default;
+$orange-800: shade-color($orange, 60%) !default;
+$orange-900: shade-color($orange, 80%) !default;
+
+$yellow-100: tint-color($yellow, 80%) !default;
+$yellow-200: tint-color($yellow, 60%) !default;
+$yellow-300: tint-color($yellow, 40%) !default;
+$yellow-400: tint-color($yellow, 20%) !default;
 $yellow-500: $yellow !default;
-$yellow-600: shade-color($yellow, 2) !default;
-$yellow-700: shade-color($yellow, 4) !default;
-$yellow-800: shade-color($yellow, 6) !default;
-$yellow-900: shade-color($yellow, 8) !default;
-
-$green-100: tint-color($green, 8) !default;
-$green-200: tint-color($green, 6) !default;
-$green-300: tint-color($green, 4) !default;
-$green-400: tint-color($green, 2) !default;
+$yellow-600: shade-color($yellow, 20%) !default;
+$yellow-700: shade-color($yellow, 40%) !default;
+$yellow-800: shade-color($yellow, 60%) !default;
+$yellow-900: shade-color($yellow, 80%) !default;
+
+$green-100: tint-color($green, 80%) !default;
+$green-200: tint-color($green, 60%) !default;
+$green-300: tint-color($green, 40%) !default;
+$green-400: tint-color($green, 20%) !default;
 $green-500: $green !default;
-$green-600: shade-color($green, 2) !default;
-$green-700: shade-color($green, 4) !default;
-$green-800: shade-color($green, 6) !default;
-$green-900: shade-color($green, 8) !default;
-
-$teal-100: tint-color($teal, 8) !default;
-$teal-200: tint-color($teal, 6) !default;
-$teal-300: tint-color($teal, 4) !default;
-$teal-400: tint-color($teal, 2) !default;
+$green-600: shade-color($green, 20%) !default;
+$green-700: shade-color($green, 40%) !default;
+$green-800: shade-color($green, 60%) !default;
+$green-900: shade-color($green, 80%) !default;
+
+$teal-100: tint-color($teal, 80%) !default;
+$teal-200: tint-color($teal, 60%) !default;
+$teal-300: tint-color($teal, 40%) !default;
+$teal-400: tint-color($teal, 20%) !default;
 $teal-500: $teal !default;
-$teal-600: shade-color($teal, 2) !default;
-$teal-700: shade-color($teal, 4) !default;
-$teal-800: shade-color($teal, 6) !default;
-$teal-900: shade-color($teal, 8) !default;
-
-$cyan-100: tint-color($cyan, 8) !default;
-$cyan-200: tint-color($cyan, 6) !default;
-$cyan-300: tint-color($cyan, 4) !default;
-$cyan-400: tint-color($cyan, 2) !default;
+$teal-600: shade-color($teal, 20%) !default;
+$teal-700: shade-color($teal, 40%) !default;
+$teal-800: shade-color($teal, 60%) !default;
+$teal-900: shade-color($teal, 80%) !default;
+
+$cyan-100: tint-color($cyan, 80%) !default;
+$cyan-200: tint-color($cyan, 60%) !default;
+$cyan-300: tint-color($cyan, 40%) !default;
+$cyan-400: tint-color($cyan, 20%) !default;
 $cyan-500: $cyan !default;
-$cyan-600: shade-color($cyan, 2) !default;
-$cyan-700: shade-color($cyan, 4) !default;
-$cyan-800: shade-color($cyan, 6) !default;
-$cyan-900: shade-color($cyan, 8) !default;
+$cyan-600: shade-color($cyan, 20%) !default;
+$cyan-700: shade-color($cyan, 40%) !default;
+$cyan-800: shade-color($cyan, 60%) !default;
+$cyan-900: shade-color($cyan, 80%) !default;
 // fusv-enable
 
 // Characters which are escaped by the escape-svg function
@@ -276,10 +273,9 @@ $body-text-align:           null !default;
 
 $link-color:                              $primary !default;
 $link-decoration:                         underline !default;
-$link-hover-color:                        darken($link-color, 15%) !default;
+$link-shade-percentage:                   20% !default;
+$link-hover-color:                        scale-color($link-color, $link-shade-percentage) !default;
 $link-hover-decoration:                   null !default;
-// Darken percentage for links with `.text-*` class (e.g. `.text-success`)
-$emphasized-link-hover-darken-percentage: 15% !default;
 
 $stretched-link-pseudo-element:           after !default;
 $stretched-link-z-index:                  1 !default;
@@ -524,15 +520,15 @@ $table-group-separator-color: currentColor !default;
 
 $table-caption-color:         $text-muted !default;
 
-$table-bg-level:              -9 !default;
+$table-bg-scale:              -80% !default;
 
 $table-variants: (
-  "primary":    color-level($primary, $table-bg-level),
-  "secondary":  color-level($secondary, $table-bg-level),
-  "success":    color-level($success, $table-bg-level),
-  "info":       color-level($info, $table-bg-level),
-  "warning":    color-level($warning, $table-bg-level),
-  "danger":     color-level($danger, $table-bg-level),
+  "primary":    scale-color($primary, $table-bg-scale),
+  "secondary":  scale-color($secondary, $table-bg-scale),
+  "success":    scale-color($success, $table-bg-scale),
+  "info":       scale-color($info, $table-bg-scale),
+  "warning":    scale-color($warning, $table-bg-scale),
+  "danger":     scale-color($danger, $table-bg-scale),
   "light":      $light,
   "dark":       $dark,
 ) !default;
@@ -650,7 +646,7 @@ $input-border-radius-sm:                $border-radius-sm !default;
 $input-border-radius-lg:                $border-radius-lg !default;
 
 $input-focus-bg:                        $input-bg !default;
-$input-focus-border-color:              lighten($component-active-bg, 25%) !default;
+$input-focus-border-color:              tint-color($component-active-bg, 50%) !default;
 $input-focus-color:                     $input-color !default;
 $input-focus-width:                     $input-btn-focus-width !default;
 $input-focus-box-shadow:                $input-btn-focus-box-shadow !default;
@@ -782,7 +778,7 @@ $form-range-thumb-border-radius:           1rem !default;
 $form-range-thumb-box-shadow:              0 .1rem .25rem rgba($black, .1) !default;
 $form-range-thumb-focus-box-shadow:        0 0 0 1px $body-bg, $input-focus-box-shadow !default;
 $form-range-thumb-focus-box-shadow-width:  $input-focus-width !default; // For focus box shadow issue in Edge
-$form-range-thumb-active-bg:               lighten($component-active-bg, 35%) !default;
+$form-range-thumb-active-bg:               tint-color($component-active-bg, 70%) !default;
 $form-range-thumb-disabled-bg:             $gray-500 !default;
 $form-range-thumb-transition:              background-color .15s ease-in-out, border-color .15s ease-in-out, box-shadow .15s ease-in-out !default;
 
@@ -944,7 +940,7 @@ $dropdown-divider-margin-y:         $spacer / 2 !default;
 $dropdown-box-shadow:               $box-shadow !default;
 
 $dropdown-link-color:               $gray-900 !default;
-$dropdown-link-hover-color:         darken($gray-900, 5%) !default;
+$dropdown-link-hover-color:         shade-color($gray-900, 10%) !default;
 $dropdown-link-hover-bg:            $gray-100 !default;
 
 $dropdown-link-active-color:        $component-active-color !default;
@@ -1065,7 +1061,7 @@ $popover-border-radius:             $border-radius-lg !default;
 $popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width) !default;
 $popover-box-shadow:                $box-shadow !default;
 
-$popover-header-bg:                 darken($popover-bg, 3%) !default;
+$popover-header-bg:                 shade-color($popover-bg, 6%) !default;
 $popover-header-color:              $headings-color !default;
 $popover-header-padding-y:          .5rem !default;
 $popover-header-padding-x:          $spacer !default;
@@ -1163,9 +1159,9 @@ $alert-border-radius:               $border-radius !default;
 $alert-link-font-weight:            $font-weight-bold !default;
 $alert-border-width:                $border-width !default;
 
-$alert-bg-level:                    -10 !default;
-$alert-border-level:                -9 !default;
-$alert-color-level:                 6 !default;
+$alert-bg-scale:                    -80% !default;
+$alert-border-scale:                -70% !default;
+$alert-color-scale:                 50% !default;
 
 $alert-dismissible-padding-r:       $alert-padding-x * 3 !default; // 3x covers width of x plus default padding on either side
 
@@ -1193,8 +1189,8 @@ $list-group-border-radius:          $border-radius !default;
 
 $list-group-item-padding-y:         $spacer / 2 !default;
 $list-group-item-padding-x:         $spacer !default;
-$list-group-item-bg-level:          -9 !default;
-$list-group-item-color-level:       6 !default;
+$list-group-item-bg-scale:          -80% !default;
+$list-group-item-color-scale:       50% !default;
 
 $list-group-hover-bg:               $gray-100 !default;
 $list-group-active-color:           $component-active-color !default;
diff --git a/scss/helpers/_colored-links.scss b/scss/helpers/_colored-links.scss
index d135194d17..8c167dedf5 100644
--- a/scss/helpers/_colored-links.scss
+++ b/scss/helpers/_colored-links.scss
@@ -2,10 +2,10 @@
   .link-#{$color} {
     color: $value;
 
-    @if $emphasized-link-hover-darken-percentage != 0 {
+    @if $link-shade-percentage != 0 {
       &:hover,
       &:focus {
-        color: if(color-contrast($value) == $color-contrast-light, darken($value, $emphasized-link-hover-darken-percentage), lighten($value, $emphasized-link-hover-darken-percentage));
+        color: if(color-contrast($value) == $color-contrast-light, shade-color($value, $link-shade-percentage), tint-color($value, $link-shade-percentage));
       }
     }
   }
diff --git a/scss/mixins/_alert.scss b/scss/mixins/_alert.scss
index 20da83a27c..99ebbc3055 100644
--- a/scss/mixins/_alert.scss
+++ b/scss/mixins/_alert.scss
@@ -4,6 +4,6 @@
   border-color: $border;
 
   .alert-link {
-    color: darken($color, 10%);
+    color: shade-color($color, 20%);
   }
 }
diff --git a/scss/mixins/_buttons.scss b/scss/mixins/_buttons.scss
index eeade6a32e..3aabd896c6 100644
--- a/scss/mixins/_buttons.scss
+++ b/scss/mixins/_buttons.scss
@@ -7,11 +7,11 @@
   $background,
   $border,
   $color: color-contrast($background),
-  $hover-background: if($color == $color-contrast-light, darken($background, 7.5%), lighten($background, 7.5%)),
-  $hover-border: if($color == $color-contrast-light, darken($border, 10%), lighten($border, 5%)),
+  $hover-background: if($color == $color-contrast-light, shade-color($background, 15%), tint-color($background, 15%)),
+  $hover-border: if($color == $color-contrast-light, shade-color($border, 20%), tint-color($border, 10%)),
   $hover-color: color-contrast($hover-background),
-  $active-background: if($color == $color-contrast-light, darken($background, 10%), lighten($background, 10%)),
-  $active-border: if($color == $color-contrast-light, darken($border, 12.5%), lighten($border, 5%)),
+  $active-background: if($color == $color-contrast-light, shade-color($background, 20%), tint-color($background, 20%)),
+  $active-border: if($color == $color-contrast-light, shade-color($border, 25%), tint-color($border, 10%)),
   $active-color: color-contrast($active-background),
   $disabled-background: $background,
   $disabled-border: $border,
diff --git a/scss/mixins/_list-group.scss b/scss/mixins/_list-group.scss
index 965fc4bd87..351e9109ec 100644
--- a/scss/mixins/_list-group.scss
+++ b/scss/mixins/_list-group.scss
@@ -9,7 +9,7 @@
       &:hover,
       &:focus {
         color: $color;
-        background-color: darken($background, 5%);
+        background-color: shade-color($background, 10%);
       }
 
       &.active {
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)