CSS变量必须统一在:root下声明以确保全局生效，推荐通过design-tokens.css集中管理语义化变量，配合calc()构建弹性间距系统，并在初始:root中预设所有可能变量以支持可靠的主题切换。
如何用:root集中声明设计系统基础变量
所有CSS变量必须挂载在:root伪类下才能全局生效，这是设计系统可维护性的起点。别在组件里零散定义--color-primary，否则后期替换颜色要翻遍整个项目。
实际做法是建一个design-tokens.css文件，只放变量声明：
:root {
--space-xs: 4px;
--space-s: 8px;
--space-m: 16px;
--space-l: 24px;
--space-xl: 32px;
--color-primary: #007bff;
--color-success: #28a745;
--color-text: #333;
--color-text-secondary: #6c757d;
}然后在主CSS入口用@import引入。注意：变量名要语义化，避免--blue-500这类纯描述色值的命名，它无法表达用途，换主题时会失去上下文。
为什么var(--color-primary)比直接写#007bff更可靠
直接写死颜色值看似简单，但一旦设计规范更新——比如主色从蓝色改成紫色，就得全局搜索替换，还容易漏掉某些background或border里的隐藏引用。
立即学习“前端免费学习笔记（深入）”；
用var()能保证一处修改、全链响应。更重要的是，它支持fallback机制：
.btn {
background-color: var(--color-primary, #007bff);
}这个#007bff不是“默认值”，而是当--color-primary未定义或被覆盖时的兜底。常见误用是把它当成设计稿色值参考，结果变量没生效时页面直接变样，却查不出原因。
- 变量未定义时，
var()返回无效值，属性会被浏览器忽略（不是取fallback） - 只有变量存在但值非法（比如
--color-primary: none），才会启用fallback - 嵌套
var(var(--x))不合法，CSS不支持变量展开链
间距系统怎么避免margin: var(--space-m) 0变成魔法数字
单纯把像素值存成变量还不够。真正高效的设计系统间距，要配合语义化工具类或CSS函数封装。
例如，定义一套基于--space-m的相对缩放：
:root {
--space-2xs: calc(var(--space-xs) / 2); /* 2px */
--space-xxs: calc(var(--space-xs) * 0.75); /* 3px */
--space-xxl: calc(var(--space-xl) * 1.5); /* 48px */
}这样padding: var(--space-xxs)比写3px更能传达设计意图。但注意：calc()里不能混用单位，var(--space-xs) + 1px合法，var(--space-xs) + 1em会失效。
- 不要为每个间距值单独设变量（如
--space-1到--space-24），维护成本爆炸 - 移动端需重设
:root变量时，用@media包裹整个:root块，而不是单条声明 -
rem和em单位与CSS变量无直接关系，别指望var(--space-m)自动适配根字体大小
主题切换时document.documentElement.style.setProperty的坑
运行时切换深色模式，最常用方式是用JS动态改:root变量：
document.documentElement.style.setProperty('--color-primary', '#6f42c1');这行代码确实生效，但问题在于：它只覆盖:root上已存在的变量，如果深色主题需要新增--color-bg-surface，而原始CSS里没声明，JS设置后依然无效。
正确做法是——所有可能用到的变量，都在初始:root中声明（哪怕先给个占位值），再用JS更新。否则会出现部分组件颜色变了、部分没变的割裂感。
- 批量设置多个变量时，别循环调用
setProperty，改用cssText一次性注入，性能更好 - SSR场景下，服务端渲染的HTML不含JS执行结果，首屏仍显示默认主题，需配合
prefers-color-scheme媒体查询做双重保障 - 变量名含大写字母（如
--ColorPrimary）在部分旧版Safari中不被识别，一律用短横线小写
变量不是越多越好，真正关键的是哪些值会跨组件复用、是否会被主题或状态影响。颜色和间距只是入口，字体层级、圆角、阴影强度这些同样得进:root——但前提是它们真的在设计系统里被当作原子单位使用过。
