调色板变量必须定义在 :root 中并带 fallback，因浏览器仅将 :root 视为文档级作用域锚点，局部声明或嵌套 fallback 会导致引用失效、维护困难；命名须语义化分层，深色模式应通过 class 切换而非媒体查询直接覆盖变量。
必须在 :root 中定义调色板变量，且所有颜色引用必须带 fallback；局部声明、嵌套 fallback、无单位数值或媒体查询直接改 :root 变量，都会让调色逻辑失控，后期维护成本翻倍。
为什么调色板变量必须写在 :root 而不是 html 或组件里
浏览器只把 :root 视为文档级作用域锚点，html { --color-primary: #007bff; } 在旧版 Safari 中可能完全不生效。写在 .button 或 .card 里，其他组件根本读不到——var(--color-primary) 在 .header 中会退化为空值，导致背景/文字消失，而控制台不报错。
常见错误现象：
-
.header文字突然变透明，Computed 面板显示color: var(--text-primary)原样未替换 - 深色模式切换后，只有按钮变色，卡片背景仍白——因为
--bg只定义在.btn下
正确做法：
立即学习“前端免费学习笔记（深入）”；
- 全部调色变量统一收口到
:root，例如：:root { --color-primary: #2196F3; --color-secondary: #6c757d; --color-surface: #ffffff; --color-on-surface: #333333; } - 组件内只用
var(--color-primary)，不重复声明
var() 的 fallback 写法错一个字符就失效
CSS 解析器对 var() 的 fallback 是单层文本替换，不递归求值。写成 color: var(--text-primary, var(--text-fallback))，浏览器会把第二个 var() 当作纯字符串，最终渲染出字面量 "var(--text-fallback)"，文字直接消失。
容易踩的坑：
- fallback 里嵌套函数（
var(--c, rgb(var(--r), 0, 0))）→ 解析失败 - fallback 写成未声明变量名（
var(--c, --fallback)，缺var()包裹）→ 当作字面量字符串 - 依赖链断裂：若
--text-primary: var(--text-default)，但--text-default没在:root中定义 → 整个var()失效
实操建议：
- 关键属性（如
color、background-color）永远配字面量 fallback：color: #333; color: var(--text-primary, #333); - 需要多级 fallback 时，用 CSS 层叠而非嵌套：
.text { color: #333; color: var(--text-default, #333); color: var(--text-primary, var(--text-default, #333)); }
调色板命名必须结构化，避免 --blue-500 这类“设计系统快照”式命名
--blue-500 看似直观，但一旦设计规范调整（比如主蓝从 #2196F3 改成 #1976D2），你得全局搜索替换所有 --blue-500，还可能误伤 --indigo-500。这不是复用，是硬编码换了个马甲。
真正可维护的调色板应按语义+角色分层：
-
--color-primary：主操作色（按钮、链接、强调边框） -
--color-success：正向状态（成功提示、通过图标） -
--color-surface：容器背景（卡片、模态框、页面主体） -
--color-on-surface：表面之上的文字/图标（与 surface 形成对比） -
--color-outline：边框/分割线（比 surface 浅，比 on-surface 淡）
这样换主题时只需改 :root 里这 5 行，所有组件自动适配，无需 grep、无需担心漏掉某个 --blue-600。
深色模式切换别用 @media (prefers-color-scheme: dark) 直接覆盖变量
在媒体查询里写 @media (prefers-color-scheme: dark) { :root { --color-surface: #1e1e1e; } }，浏览器会同步重绘所有引用该变量的元素。如果 --color-surface 用在 50 个卡片、30 个按钮上，肉眼可见闪烁，尤其低端设备。
更稳的做法是用 class 切换：
- HTML 根节点加
class="theme-light"或class="theme-dark" - 变量定义在对应 class 下：
:root.theme-dark { --color-surface: #1e1e1e; --color-on-surface: #eeeeee; } :root.theme-light { --color-surface: #ffffff; --color-on-surface: #333333; } - 配合
transition: background-color 0.2s，仅触发动画属性，不触发变量重算
注意：CSS 变量本身不可动画，transition 必须作用于实际可过渡的属性（如 background-color、color），而不是变量名。
最易被忽略的一点：调色板变量必须和单位、透明度、语义绑定。比如 --color-primary 应始终是不带 alpha 的纯色，需要半透时用 color-mix(in srgb, var(--color-primary) 70%, transparent) 或预定义 --color-primary-alpha-70 —— 把透明度混进变量值里，等于把“状态”耦合进“角色”，后期想单独调亮暗或改不透明度，就得拆解所有已混入的值。
