应在 :root 中一次性声明所有设计系统颜色变量，如 :root { --color-primary: #0066cc; --color-error: #d32f2f; }，命名需语义化；暗色模式通过 :root[data-theme="dark"] 覆盖值；使用 data-theme 切换主题并配合合法 fallback 值（如 background: var(--color-primary, #0066cc)）确保兼容性；颜色源统一维护在 tokens/colors.json 等独立文件中，通过脚本生成 CSS 并纳入 CI 校验。
怎么用 :root 定义全局 CSS 变量
所有设计系统颜色必须在 :root 里一次性声明，这是唯一可靠的方式。浏览器会把 :root 当作全局作用域，子元素通过 var(--color-primary) 就能继承，不用重复写选择器。
常见错误是分散定义：在 .button 里写一次 --color-primary，又在 .header 里覆盖一次——这样根本没法统一，改个主色要翻十来个文件。
- 只在
:root中声明，例如：:root { --color-primary: #0066cc; --color-error: #d32f2f; } - 变量名用语义化命名（
--color-primary），别用--blue-500这类视觉绑定名，否则设计换色系时全得重命名 - 避免在媒体查询里重复定义同一变量，应该用
@media (prefers-color-scheme: dark)覆盖值，而不是新建一套
如何让 CSS 变量响应主题切换
靠 JS 切换 data-theme 属性比切换 class 更干净，因为 CSS 变量可以基于属性做条件覆盖，不需要重复写整套规则。
很多人直接用 document.body.className = 'theme-dark'，结果发现变量没更新——问题出在没在 :root[data-theme="dark"] 下重新赋值，CSS 变量不会自动“深响应”。
立即学习“前端免费学习笔记（深入）”；
- 基础色定义在
:root，暗色模式覆盖写在:root[data-theme="dark"]里 - JS 切换只需
document.documentElement.setAttribute('data-theme', 'dark') - 别忘了加
transition: background-color 0.2s这类属性过渡，否则变色突兀（CSS 变量本身不触发过渡，但依赖它的属性可以）
为什么 var(--color-primary) 在 background 里有时失效
最常踩的坑是 fallback 值写错或漏写。CSS 变量不是 JS 变量，它不报错、不提示，值无效就直接退回到浏览器默认（比如 background 退成透明）。
典型错误：写成 background: var(--color-primary);，但变量未定义，整个声明被忽略；或者写了 var(--color-primary, #000)，却把 fallback 写成无效值如 #ggg，导致 fallback 也失效。
- 永远带 fallback：
background: var(--color-primary, #0066cc); - fallback 必须是合法 CSS 值，不能是另一个未定义变量
- 在 DevTools 里检查 computed 样式，看
background是否显示为var(--color-primary, ...)—— 如果还显示这个字符串，说明变量名拼错了或作用域不对
怎样和设计工具（Figma/Sketch）保持颜色同步
没有自动同步这回事。所谓“同步”，其实是靠人维护一份 JSON 或 YAML 颜色表，开发读它生成 :root，设计师导出时也按同一份源文件校验。
很多团队试过插件自动生成 CSS，结果设计师调了个新灰度，插件没跑，代码里还是旧值——问题不在技术，而在流程断点。
- 把颜色定义抽成独立文件，例如
tokens/colors.json，含{"primary": "#0066cc", "surface": "#ffffff"} - 用简单脚本（Node 或 Python）读它，输出
:root块，避免手写遗漏 - 在 PR 检查中加一条：修改
colors.json必须同时更新 CSS 输出，CI 可跑 diff 校验
变量本身不解决协作问题，它只是把“颜色散落在各处”的混乱，收敛到一个可追踪、可比对、可版本控制的位置。剩下的，得靠人盯住那个 JSON 文件。
