css变量是构建可切换主题的最轻量原生方案，需从token设计阶段约束命名与层级：按语义+用途分层（基础色、语义色、空间尺寸、动效时长），禁用组件绑定名；:root中仅设空壳变量，通过[data-theme]作用域注入实际值；组件只读语义变量（如--color-primary-500），颜色计算全在主题层完成；禁用!important，确保级联逻辑有效。
CSS变量（:root自定义属性）是构建可切换主题的最轻量、最原生方案，无需框架、不侵入组件结构，但必须从Token设计阶段就约束命名和层级。
如何定义一套可维护的CSS Token命名规范
Token不是随便起名的颜色别名，而是按语义+用途分层：基础色、语义色、空间尺寸、动效时长。命名混乱会导致主题切换时漏改、误改。
-
--color-primary-base：基础品牌色（如#2563eb），不直接用于组件，只供衍生色计算 -
--color-primary-500：主按钮默认色，由--color-primary-base通过color-mix()或预设比例生成 -
--space-md：中等间距（如12px），避免用--padding-sm这类绑定具体用途的名，因为同一数值可能用于 margin/padding/gap - 禁止出现
--btn-bg-hover这种强组件绑定名——它应由--color-primary-600+--state-hover组合推导
为什么:root里不能直接写主题色值
把深色模式色值硬写进:root会阻断后续覆盖。正确做法是用空壳变量占位，再通过选择器作用域注入实际值。
:root {
--color-bg: ; /* 留空，不赋值 */
--color-text: ;
}
<p>[data-theme="light"] {
--color-bg: #ffffff;
--color-text: #1e293b;
}</p><p>[data-theme="dark"] {
--color-bg: #0f172a;
--color-text: #f1f5f9;
}</p><p>.card {
background: var(--color-bg);
color: var(--color-text);
}</p>
这样切换data-theme属性即可批量生效，且支持嵌套主题（如[data-theme="dark"] [data-theme="light"]局部还原）。
如何让组件自动响应主题变更而不重写CSS
关键在「隔离变量使用层级」：组件CSS只读var(--color-primary-500)，不读var(--color-primary-base)；颜色计算全放在主题层完成。
- 用
color-mix(in srgb, var(--color-primary-base), black 20%)生成--color-primary-600，比手写十六进制更可控 - 禁用
!important覆盖主题变量，否则破坏级联逻辑 - 对需要动态计算的值（如阴影模糊度适配深色模式），用
@media (prefers-color-scheme: dark)兜底，但仅限无法通过变量推导的边缘 case
提取Token到独立CSS文件后如何热更新调试
把所有:root变量抽成tokens.css后，浏览器不会自动监听文件变化。开发时需手动触发重载或借助构建工具注入。
- Vite 用户可在
import "./tokens.css"后加/* @vite-ignore */注释，配合插件监听变更 - 纯静态环境建议用
<link rel="stylesheet" href="tokens.css?ts=1712345678">加时间戳强制刷新 - 检查是否生效：打开开发者工具，在
Computed面板看background等属性是否显示为var(--color-bg)而非具体色值——如果已展开成色值，说明变量未被正确继承或被覆盖
真正难的不是写几个var()，而是让设计师、前端、主题配置方对同一套Token命名达成共识，并接受“不直接写死颜色”的约束。一旦松动，主题系统就会退化成一堆class="btn--dark"的手动开关。
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
