diff --git a/scss/_functions.scss b/scss/_functions.scss
index 59d431a15b93..a73d31be50f8 100644
--- a/scss/_functions.scss
+++ b/scss/_functions.scss
@@ -145,11 +145,31 @@
 
 // Color contrast
 // See https://github.com/twbs/bootstrap/pull/30168
+//
+// These functions implement WCAG 2.2 color contrast requirements.
+// Reference: https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html
+//
+// The minimum contrast ratio ($min-contrast-ratio) defaults to 4.5:1, which meets
+// WCAG Level AA requirements for normal text. For large text (18pt+ or 14pt+ bold),
+// a ratio of 3:1 is acceptable.
+//
+// WCAG Contrast Levels:
+// - Level AA (minimum): 4.5:1 for normal text, 3:1 for large text
+// - Level AAA (enhanced): 7:1 for normal text, 4.5:1 for large text
 
 // A list of pre-calculated numbers of pow(divide((divide($value, 255) + .055), 1.055), 2.4). (from 0 to 255)
 // stylelint-disable-next-line scss/dollar-variable-default, scss/dollar-variable-pattern
 $_luminance-list: .0008 .001 .0011 .0013 .0015 .0017 .002 .0022 .0025 .0027 .003 .0033 .0037 .004 .0044 .0048 .0052 .0056 .006 .0065 .007 .0075 .008 .0086 .0091 .0097 .0103 .011 .0116 .0123 .013 .0137 .0144 .0152 .016 .0168 .0176 .0185 .0194 .0203 .0212 .0222 .0232 .0242 .0252 .0262 .0273 .0284 .0296 .0307 .0319 .0331 .0343 .0356 .0369 .0382 .0395 .0409 .0423 .0437 .0452 .0467 .0482 .0497 .0513 .0529 .0545 .0561 .0578 .0595 .0612 .063 .0648 .0666 .0685 .0704 .0723 .0742 .0762 .0782 .0802 .0823 .0844 .0865 .0887 .0908 .0931 .0953 .0976 .0999 .1022 .1046 .107 .1095 .1119 .1144 .117 .1195 .1221 .1248 .1274 .1301 .1329 .1356 .1384 .1413 .1441 .147 .15 .1529 .1559 .159 .162 .1651 .1683 .1714 .1746 .1779 .1812 .1845 .1878 .1912 .1946 .1981 .2016 .2051 .2086 .2122 .2159 .2195 .2232 .227 .2307 .2346 .2384 .2423 .2462 .2502 .2542 .2582 .2623 .2664 .2705 .2747 .2789 .2831 .2874 .2918 .2961 .3005 .305 .3095 .314 .3185 .3231 .3278 .3325 .3372 .3419 .3467 .3515 .3564 .3613 .3663 .3712 .3763 .3813 .3864 .3916 .3968 .402 .4072 .4125 .4179 .4233 .4287 .4342 .4397 .4452 .4508 .4564 .4621 .4678 .4735 .4793 .4851 .491 .4969 .5029 .5089 .5149 .521 .5271 .5333 .5395 .5457 .552 .5583 .5647 .5711 .5776 .5841 .5906 .5972 .6038 .6105 .6172 .624 .6308 .6376 .6445 .6514 .6584 .6654 .6724 .6795 .6867 .6939 .7011 .7084 .7157 .7231 .7305 .7379 .7454 .7529 .7605 .7682 .7758 .7835 .7913 .7991 .807 .8148 .8228 .8308 .8388 .8469 .855 .8632 .8714 .8796 .8879 .8963 .9047 .9131 .9216 .9301 .9387 .9473 .956 .9647 .9734 .9823 .9911 1;
 
+// Returns an accessible foreground color (light or dark) for the given background.
+// The function tests multiple foreground options and returns the first one that
+// meets the minimum contrast ratio, or warns if none do.
+//
+// @param {Color} $background - The background color to check against
+// @param {Color} $color-contrast-dark - Dark foreground option (default: $color-contrast-dark)
+// @param {Color} $color-contrast-light - Light foreground option (default: $color-contrast-light)
+// @param {Number} $min-contrast-ratio - Minimum required contrast ratio (default: 4.5)
+// @return {Color} - The most accessible foreground color
 @function color-contrast($background, $color-contrast-dark: $color-contrast-dark, $color-contrast-light: $color-contrast-light, $min-contrast-ratio: $min-contrast-ratio) {
   $foregrounds: $color-contrast-light, $color-contrast-dark, $white, $black;
   $max-ratio: 0;