应在:root中定义带语义的CSS变量（如--color-btn-primary-bg），用HSL值便于计算，所有var()调用必须含fallback，变量不可嵌套在媒体查询或class内，JS通过document.documentElement.style.setProperty动态修改。
如何在:root里定义可被JS动态读写的主题变量
直接写 :root 是最简路径，但必须确保变量名带语义、值可计算、有合理默认。别用 --blue-500 这类设计系统残留命名，它不告诉你这个色用在哪；改用 --color-btn-primary-bg 或 --color-surface-card，一眼知道作用域。
变量值推荐用 HSL 而非 HEX：比如 --primary-hue: 210; 配合 hsl(var(--primary-hue), 70%, 60%)，后续换蓝→紫只需改一个数字，饱和度/明度不变。HEX 值无法参与 calc 或渐变插值，硬切容易失衡。
务必加后备值：所有 var() 调用都应带 fallback，例如 color: var(--color-text, #333);。IE 和部分旧 WebView 不支持 CSS 变量，没 fallback 就是白屏或黑字叠黑底。
-
:root必须是顶层声明，不能嵌套在媒体查询或 class 内（否则 JS 无法通过document.documentElement.style.setProperty修改） - 避免在
@media (prefers-color-scheme: dark)里重定义:root变量——它会覆盖 JS 设置，导致手动切换失效 - 深色模式兜底建议用
@media (prefers-color-scheme: dark) { :root:not([data-theme]) { ... } }，保留用户主动选择的优先级
为什么移动端适配要拆分「基础色」和「响应式色阶」
PC 端按钮 hover 色可以压暗 15%，但手机触控反馈需要更明显对比，直接复用同一套 var(--color-primary-hover) 容易导致点击态不可见。正确做法是把色阶逻辑交给 CSS 变量本身：
立即学习“前端免费学习笔记（深入）”；
:root { --color-primary-base: hsl(210, 70%, 60%); --color-primary-hover: hsl(210, 70%, 48%); }
然后在媒体查询中覆盖 hover 值：@media (hover: none) and (pointer: coarse) { :root { --color-primary-hover: hsl(210, 70%, 40%); } }。这样既不用写两套 class，也不用 JS 判断设备类型。
- 「hover: none」表示无悬停能力（多数移动浏览器），「pointer: coarse」代表粗粒度指针（手指触摸），两者交集即真·移动端
- 不要用
max-width媒体查询做主题判断——平板横屏时宽度超 1024px，但仍是触控设备 - SVG 图标内联时，
fill必须显式写fill: var(--color-icon, currentColor);，否则不会响应变量变更
第三方 UI 库的颜色变量怎么透传过去
Element Plus、Ant Design 等库若未开启 CSS 变量支持，默认样式不会读取你的 --color-primary。强行覆盖它们的 class 是下策，容易随版本升级断裂。
优先查文档看是否支持变量注入：比如 Ant Design v5+ 提供 theme 配置项，可传入 { primaryColor: '#3b82f6' }，它会自动编译为对应变量；Element Plus 则需启用 cssVar: true 并配合 el-config-provider。
- 没官方支持？用
:where(.el-button) { background-color: var(--color-primary) !important; }强制接管，但只限关键组件，避免全局!important污染 - Shadow DOM 组件（如某些 Web Component 封装的日期选择器）无法穿透，必须在组件内部样式中定义变量，或通过
part属性暴露 slot 样式钩子 - 图标字体（Font Awesome）需额外加规则：
.fa { color: var(--color-icon); }，它的color不继承父级fill
切换主题时颜色闪动的根本原因和解法
闪动不是变量更新慢，而是新旧颜色在重绘帧之间并存。常见于三类场景：内联 style 写死颜色、JS 直接操作 element.style.color、第三方库插入的 style 标签未监听变量变更。
解法很直接：所有颜色控制权收归 CSS 变量，删掉所有 style="color: #333" 和 el.style.backgroundColor = '#3b82f6'。哪怕临时状态也走 class 控制，例如用 .is-loading { opacity: 0.6; } 而非直接改 opacity。
- 给
body加transition: background-color 0.2s, color 0.2s;，但仅限于简单背景/文字色，复杂渐变或阴影需用will-change提前提示渲染引擎 - 暗色模式初始化阶段，先同步设置
data-theme="dark"再挂载 Vue/React 应用，避免首屏渲染用错主题 - SSR 场景下，服务端需根据请求头
Sec-CH-Prefers-Color-Scheme或 cookie 注入初始data-theme，否则客户端 hydration 会闪一次
真正麻烦的从来不是改几个变量，而是让所有颜色引用点都意识到自己该用变量——包括伪元素、SVG、disabled 状态、focus outline，甚至 console.log 里打印的调试色块。漏掉任意一处，主题切换就变成拼图游戏。
