data-theme属性必须挂载在document.documentElement上，否则高对比度主题切换失效；需同步设置整套变量、提供回退值、适配forced-colors媒体查询并预写HTML模板。
data-theme 属性必须挂载在 document.documentElement 上
高对比度主题切换失败，90% 是因为把 data-theme="high-contrast" 错误地加到了 或某个容器上。CSS 变量的层叠作用域依赖于选择器匹配，:root[data-theme="high-contrast"] 这个规则只对 元素生效 —— 也就是 document.documentElement。用 document.body.setAttribute() 不会触发变量重计算，样式完全不动。
正确写法：
function setTheme(theme) {
document.documentElement.setAttribute('data-theme', theme);
localStorage.setItem('ui-theme', theme);
}
setTheme('high-contrast');
高对比度主题不能只改文字和背景色
只覆盖 --color-text 和 --color-bg，会导致表单控件边框消失、按钮悬停无反馈、SVG 图标不可见、甚至滚动条“隐身”。WCAG 2.1 要求所有交互元素的对比度 ≥ 4.5:1（普通文本）或 ≥ 3:1（大号文本/UI 组件），这需要系统性重设整套变量。
必须同步更新的变量包括：
立即学习“前端免费学习笔记（深入）”；
-
--color-border：输入框、卡片边框需用高饱和度色（如#0000FF或#FF0000） -
--color-focus：聚焦轮廓线必须足够粗且对比强烈（推荐3px solid #0000FF） -
--color-icon：SVGfill和图标字体颜色需显式声明 -
--color-disabled：禁用态控件不能变灰，而应保留可辨识的强对比色（如黑底黄字） -
scrollbar-color：用@media (forced-colors: active)配合forced-color-adjust: none控制
避免 FOUC（闪白/文字消失）的关键时机
页面首次加载时出现短暂白屏或文字消失，根本原因是 CSS 变量回退值缺失 + JS 执行滞后。浏览器先渲染默认样式（:root 中的浅色变量），再等 JS 加载、读取 localStorage、设置 data-theme，中间存在毫秒级空白。
解决办法只有两个，缺一不可：
- HTML 模板中预先写死
（服务端渲染或构建时注入） - CSS 中为每个变量提供强回退值：
color: var(--color-text, #000000);，而不是color: var(--color-text);
注意：仅靠 matchMedia('(prefers-contrast: high)') 监听是不够的——它只响应系统级设置，无法覆盖用户手动开启高对比度主题的场景。
如何兼容 Windows 强制颜色模式（Windows High Contrast Mode）
原生高对比度主题在 Windows 系统中会触发 forced-colors: active 媒体查询，此时浏览器会强制覆盖大部分 CSS 颜色，但 CSS 变量默认不受影响。必须主动适配：
在 CSS 中加入：
@media (forced-colors: active) {
:root {
--color-text: CanvasText;
--color-bg: Canvas;
--color-border: ButtonBorder;
}
* {
forced-color-adjust: none;
}
button, input, select, textarea {
border: 2px solid;
}
}
关键点：CanvasText 和 ButtonBorder 是系统语义色，不是具体值；forced-color-adjust: none 允许你保留部分自定义样式（如圆角、阴影），但边框、文字、背景必须使用系统色，否则会被强制重置。
别忘了测试：Edge 浏览器按 Alt+Shift+P 可快速启用 Windows 高对比度模式，这是唯一真实还原用户环境的方式。
