直接操作 document.documentElement.style.setProperty() 即可读写 :root CSS 变量；需注意前缀 --、命名准确、IE 不支持；核心联动变量仅 4–6 个；HSL 推导须校验范围与单位；确保 CSS 规则实际使用 var(--xxx) 才生效。
怎么用 JS 读取并修改 :root 里的 CSS 变量
直接操作 document.documentElement.style 就行，不用查元素、不用写 getComputedStyle 再解析——那只是读值时才需要。修改变量本质就是往根元素的内联 style 上设属性，浏览器会自动触发重绘。
常见错误是写成 style.setProperty('--primary', '#ff6b6b') 却忘了加 -- 前缀，或者把变量名拼错（比如 --praimary），结果静默失败，控制台也不报错。
-
document.documentElement.style.setProperty('--color-bg', '#f8f9fa')是正确写法 - 如果变量原本在 CSS 文件里定义（如
:root { --color-bg: #fff; }），JS 修改后会覆盖它 - 不支持 IE，
setProperty在 IE 中完全不可用
生成配色方案时，哪些颜色必须联动改，哪些可以不动
别一上来就全量替换所有 --* 变量。真正影响视觉一致性的核心变量通常只有 4–6 个：主色、辅色、文字、背景、边框、状态色（success / error）。其余像 --shadow-sm 或 --radius-md 和颜色无关，强行改反而破坏设计系统。
典型联动关系：
立即学习“前端免费学习笔记（深入）”；
- 改
--color-primary→ 一般要同步更新--color-primary-hover、--color-primary-pressed（按比例调暗 10%–20%） - 改
--color-text→ 必须检查--color-text-secondary和--color-text-disabled的对比度是否仍合规（至少 4.5:1） -
--color-bg和--color-bg-alt要保持足够明度差，否则卡片/面板会“糊在一起”
用 HSL 动态推导衍生色时，hsl() 字符串拼接容易出什么错
很多人直接 `hsl(${h}, ${s}%, ${l}%)`，但漏掉单位或小数精度问题会导致浏览器拒绝解析——比如 l 算出来是 99.99999999999999，四舍五入到 100 才安全；s 和 l 后面的 % 缺一不可，少写就会变成无效值。
更稳的做法是封装一个校验函数：
function safeHSL(h, s, l) {
return `hsl(${Math.round(h)}, ${Math.round(s)}%, ${Math.round(l)}%)`;
}
另外注意：HSL 的 h 是 0–360，但有些算法（比如色相旋转）会算出负数或超 360 的值，得先 h % 360 再处理，否则 Chrome 会静默忽略整条声明。
切换主题后，CSS 变量没实时生效，可能卡在哪
最常踩的坑是：JS 改了变量，但对应元素的样式规则里压根没引用这个变量。比如你设了 --color-card，但 CSS 里写的是 background: #fff，而不是 background: var(--color-card) —— 这种改了等于白改。
另一个隐蔽问题是变量作用域。如果你在某个组件内部用了 .my-comp :root 这种写法（错误！），实际根本不会生效。:root 永远只指文档根元素，局部作用域只能靠类名 + 属性选择器模拟，比如：
- 正确：
.theme-dark { --color-bg: #121212; }，然后给 body 加 class - 错误：
.theme-dark :root { ... }（无效） - 调试技巧：在 DevTools 的 Elements 面板里点 HTML 根节点，右侧 Styles 标签页下拉到底，看
element.style区域有没有你设的变量
配色逻辑本身不难，难的是变量命名是否收敛、CSS 规则是否真正依赖变量、以及 HSL 推导时边界值是否兜得住——这三处漏一个，脚本就看起来“动了但没完全动”。
