Use WCAG contrast algo (#30168)

2 files changed, 15 insertions, 6 deletions

diff --git a/site/content/docs/4.3/getting-started/theming.md b/site/content/docs/4.3/getting-started/theming.md
index dcaa593f1..e6ed6c198 100644
--- a/site/content/docs/4.3/getting-started/theming.md
+++ b/site/content/docs/4.3/getting-started/theming.md
@@ -191,14 +191,14 @@ In practice, you'd call the function and pass in two parameters: the name of the
 
 #### 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.
+An additional function we include in Bootstrap is the color contrast function, `color-contrast`. It utilizes the [WCAG 2.0 algorithm](https://www.w3.org/TR/WCAG20-TECHS/G17.html#G17-tests) for calculating contrast thresholds based on [relative luminance](https://www.w3.org/WAI/GL/wiki/Relative_luminance) in a `sRGB` colorspace 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.
 
 For example, to generate color swatches from our `$theme-colors` map:
 
 {{< highlight scss >}}
 @each $color, $value in $theme-colors {
   .swatch-#{$color} {
-    color: color-yiq($value);
+    color: color-contrast($value);
   }
 }
 {{< /highlight >}}
@@ -207,7 +207,7 @@ It can also be used for one-off contrast needs:
 
 {{< highlight scss >}}
 .custom-element {
-  color: color-yiq(#000); // returns `color: #fff`
+  color: color-contrast(#000); // returns `color: #fff`
 }
 {{< /highlight >}}
 
@@ -215,10 +215,16 @@ You can also specify a base color with our color map functions:
 
 {{< highlight scss >}}
 .custom-element {
-  color: color-yiq($dark); // returns `color: #fff`
+  color: color-contrast($dark); // returns `color: #fff`
 }
 {{< /highlight >}}
 
+{{< callout info >}}
+##### Accessibility
+
+In order to meet [WCAG 2.0 accessibility standards for color contrast](https://www.w3.org/TR/UNDERSTANDING-WCAG20/visual-audio-contrast-contrast.html), authors **must** provide [a contrast ratio of at least 4.5:1](https://www.w3.org/WAI/WCAG20/quickref/20160105/Overview.php#visual-audio-contrast-contrast), with very few exceptions.
+{{< /callout >}}
+
 #### Escape SVG
 
 We use the `escape-svg` function to escape the `<`, `>` and `#` characters for SVG background images.
diff --git a/site/content/docs/4.3/migration.md b/site/content/docs/4.3/migration.md
index be953eca3..e3d2e1b3b 100644
--- a/site/content/docs/4.3/migration.md
+++ b/site/content/docs/4.3/migration.md
@@ -39,9 +39,12 @@ Changes to our source Sass files and compiled CSS.
 - 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)
 - `$enable-grid-classes` doesn't disable the generation of container classes anymore [See #29146](https://github.com/twbs/bootstrap/pull/29146)
 - 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)
-- The `button-variant()` mixin now accepts 3 optional color parameters, for each button state, to override the color provided by `color-yiq()`. By default, these parameters will find which color provides more contrast against the button state's background color with `color-yiq()`.
-- The `button-outline-variant()` mixin now accepts an additional argument, `$active-color`, for setting the button's active state text color. By default, this parameter will find which color provides more contrast against the button's active background color with `color-yiq()`.
+- The `button-variant()` mixin now accepts 3 optional color parameters, for each button state, to override the color provided by `color-contrast()`. By default, these parameters will find which color provides more contrast against the button state's background color with `color-contrast()`.
+- The `button-outline-variant()` mixin now accepts an additional argument, `$active-color`, for setting the button's active state text color. By default, this parameter will find which color provides more contrast against the button's active background color with `color-contrast()`.
 - Ditch the Sass map merges, which makes it easier to remove redundant values. Keep in mind you now have to define all values in the Sass maps like `$theme-colors`. Check out how to deal with Sass maps on the [theming documentation]({{< docsref "/getting-started/theming#maps-and-loops" >}}).
+- `color-yiq()` function is renamed to `color-contrast()` since it's not related to YIQ colorspace anymore — [See #30168](https://github.com/twbs/bootstrap/pull/30168/) — and related variables are renamed alongside:
+  - `$yiq-contrasted-threshold` is renamed `$min-contrast-ratio`,
+  - `$yiq-text-dark` and `$yiq-text-light` are respectively renamed `$color-contrast-dark` and `$color-contrast-light`.
 
 ## JavaScript