color-contrast() 不生效是因为它仅在 Sass 编译期生成静态颜色值，无法响应运行时 CSS 变量变化；若仅修改 --bs-body-bg 而未同步更新 --bs-body-color 等语义变量，.text-* 类将失去对比度适配能力。
为什么 color-contrast() 生成的文本色有时不生效
Bootstrap 的 color-contrast() Sass 函数本身没问题，但它只在编译时起作用——生成的是固定颜色值（如 #fff 或 #212529），不会随背景色实时变化。如果你用 CSS 变量动态改了 --bs-body-bg，但文本类仍写死 .text-white，那对比度就完全脱钩了。
常见错误是以为加了 text-white 就“自动适配深色背景”，其实它只是强制白色，不管背景是不是纯黑；而 text-body 又依赖 --bs-body-color，这个变量若没在深色模式下重定义，就会沿用浅色值，导致灰字配深灰背景、几乎不可读。
- 必须确保深色模式下也同步更新
--bs-body-color、--bs-emphasis-color等语义变量，不能只改背景 -
color-contrast($color)只能用于 Sass 编译期，比如定义$primary-text: color-contrast($primary)，不能塞进 CSS 自定义属性里当运行时函数用 - 如果项目用 JS 动态换主题，得手动算好前景色再 setProperty，例如：
document.documentElement.style.setProperty('--bs-body-color', isDark ? '#f8f9fa' : '#212529')
如何让 .text-* 类真正响应背景明暗变化
Bootstrap 5.3+ 的 .text-body、.text-muted 等类靠的是 color: var(--bs-body-color) 这类声明，所以它们“自动切换”的前提是：CSS 变量本身已被正确更新。一旦你只改了 --bs-body-bg 却漏掉 --bs-body-color，这些类就失效。
最稳妥的做法是成对定义：
:root {
--bs-body-bg: #ffffff;
--bs-body-color: #212529;
}
[data-bs-theme="dark"] {
--bs-body-bg: #212529;
--bs-body-color: #f8f9fa;
}
- 别只覆盖
--bs-body-bg，所有与可读性强相关的变量都要配对：包括--bs-emphasis-color（强调文字）、--bs-secondary-color（次要文字）、--bs-border-color（边框） - 如果用了自定义主题色（如
--bs-brand），也要手动定义其对应的文字对比色，color-contrast()不会帮你注入到 CSS 变量中 - 检查浏览器开发者工具的“计算样式”，确认
color最终取值是否来自你期望的变量，而不是被更高优先级的类（如.text-white）覆盖
data-bs-theme 切换后，为什么部分文字还是看不清
根本原因在于 Bootstrap 的深色模式变量覆盖是“选择性”的——它只管自己定义的那套 --bs-* 变量，不会动你手写的 .bg-custom 或第三方组件里的颜色。如果你给某个卡片加了 class="bg-dark text-light"，那它确实变黑底白字；但如果你用 style="background-color: var(--my-custom-bg)"，而 --my-custom-bg 没在 [data-bs-theme="dark"] 下重定义，文字色就可能和背景撞色。
- 所有自定义背景色变量（如
--my-card-bg）都必须在[data-bs-theme="dark"]块内显式重设，不能指望它“自动变暗” - 避免混用
data-bs-theme和手写bg-dark/text-white类，二者逻辑不同源：前者驱动变量，后者是固定 class，容易优先级打架 - 用
getComputedStyle(document.documentElement).getPropertyValue('--bs-body-color')在控制台实时验证变量值，比肉眼判断更可靠
无障碍对比度检测该查哪几个值
WCAG AA 级要求文本与背景对比度 ≥ 4.5:1（普通文字）或 ≥ 3:1（大号文字）。Bootstrap 默认值基本达标，但自定义后极易跌破——尤其当你把 --bs-primary 设为浅蓝（如 #6a9cff）又配白色背景时，.text-primary 就只有 2.1:1。
- 重点检测三组组合：
--bs-body-colorvs--bs-body-bg、--bs-emphasis-colorvs--bs-body-bg、--bs-primaryvs--bs-body-bg - 推荐用浏览器插件（如 axe DevTools 或 Color Contrast Analyzer）直接选中元素测，比手动查值快得多
- Sass 层面可用
contrast-ratio()函数做构建时校验，但注意它只接受颜色字面量，不能传变量名
实际应用中，最易被忽略的是：深色模式下不仅要重定义背景变量，还得同步更新所有语义化文本变量，并且每个自定义色都要单独做对比度验证。变量名对上了，不等于可读性就过关。
