最稳妥做法是在 :root 中声明全局 CSS 变量，确保所有基础色有默认值，再通过媒体查询或 class 覆盖；JS 动态换肤应批量注入主题对象，var() 必须带字面量 fallback，构建时用 style-dictionary 等工具统一管理设计 Token。
用 :root 声明全局 CSS 变量最稳妥
浏览器对 :root 的支持从 IE11 开始就稳定了，它等价于 html 元素，但语义更清晰、优先级更高，不会被局部选择器意外覆盖。别在某个 class 里写 --primary: #007bff，那样变量只在该作用域生效，根本达不到“全站统一”的目的。
常见错误是把变量塞进 .theme-dark 这类切换类里，结果默认主题没定义，页面一加载就是空白色或继承色。正确做法是：所有基础色必须在 :root 中声明默认值，再用媒体查询或 class 切换覆盖。
-
:root里定义所有主色、中性色、状态色，例如：--color-primary: #007bff、--color-text: #333、--color-bg: #fff - 深色模式用
@media (prefers-color-scheme: dark)或html.dark覆盖，不是重写整套变量，只改差异项 - 避免用
!important覆盖变量——它会破坏 CSS 变量的级联逻辑，导致后续无法被 JS 动态修改
JS 动态换肤时，别直接操作 style 属性
通过 document.documentElement.style.setProperty('--color-primary', '#ff6b35') 是可行的，但一旦页面有多个皮肤（比如用户选“蓝调”“墨绿”“暖灰”），硬编码 setProperty 容易漏项、难维护。更可靠的是把整套色值存成对象，一次性注入。
容易踩的坑是：JS 修改后，某些旧版 Safari 会丢失 CSS 变量缓存，导致闪屏；或者变量名拼错（比如 --primary-color 和 --color-primary 混用），浏览器静默忽略，不报错也不生效。
立即学习“前端免费学习笔记（深入）”；
- 用一个配置对象集中管理各主题色值，例如：
const themes = { light: { '--color-primary': '#007bff', ... }, dark: { ... } } - 批量设置用
Object.entries(theme).forEach(([k, v]) => doc.documentElement.style.setProperty(k, v)) - 确保变量名在 JS 和 CSS 中完全一致，建议用 ESLint 插件
stylelint-config-standard+stylelint-custom-property-no-outside-root检查
组件库里引用 CSS 变量，得防 fallback 失效
写 color: var(--color-text); 看似简单，但如果 --color-text 根本没定义，Chrome 会回退到 inherit，Firefox 可能直接透明——这不是 bug，是规范行为。尤其在微前端或多团队协作场景，某个子应用没加载主题 CSS，父容器又没兜底，文字就消失了。
所以每个 var() 都得带 fallback，而且 fallback 不能是另一个变量（var(--color-text, var(--color-default)) 不合法），只能是具体值或关键字。
- 写法必须是：
color: var(--color-text, #333);，第二个参数只能是字面量，不能嵌套var() - 中性色（如文本、边框、背景）的 fallback 建议用系统默认值：
var(--color-border, #ddd)、var(--color-bg, #fff) - 不要依赖浏览器默认颜色做 fallback，比如
var(--color-text, initial)在不同 UA 下表现不一致
构建时提取 CSS 变量生成设计 Token JSON
设计师给的 Sketch 文件里有颜色命名，前端开发却要手动抄进 :root，稍不注意就错位。更麻烦的是，当 UI 出新版色板，全站搜 --color-success 替换，可能误伤注释或字符串。真正可持续的做法，是让构建工具读取一份源数据，自动生成 CSS 和 JS 可用的 token。
目前没有通用方案能完美解析任意 CSS 文件里的变量，所以源头必须可控：要么用 JSON/YAML 维护色板，要么用 PostCSS 插件扫描带特定注释的 CSS 变量声明（如 /* @token primary */ --color-primary: #007bff;）。
- 推荐用
style-dictionary工具，输入 YAML 定义色值和层级，输出 CSS 变量、SCSS 变量、JS 对象、JSON Schema - 如果项目已用 Vite，可用
vite-plugin-css-vars在构建时解析:root并生成 TS 类型声明，避免手写declare module '*.css' {...} - 别把变量名写死在组件里（如
background: var(--bg-card);），先确认这个--bg-card是否在设计系统文档中有明确定义和用途说明
变量名要不要加前缀（--sys- 还是 --ui-）、深色模式是否该用 HSL 动态计算、第三方组件如何接入这套系统——这些都不是配置问题，而是团队对“谁负责维护变量含义”的约定问题。没对齐这点，再规范的 CSS 也会变成一堆没人敢动的魔法数字。
