CSS变量命名需加语义前缀如--ui-color-primary，禁用裸名、色值绑定名和位置状态耦合名，统一用hsl()实现主题动态切换，所有var()必须带中性色fallback。
直接在 :root 里写一堆 --primary、--text 就算规范了？不是。这类命名会在半年后让所有人翻遍 DevTools 才敢改一个色值——因为没人知道它到底用在哪、谁覆盖过、换主题时要不要动它。
为什么 --primary 这种名字一上线就失控
CSS 变量是全局的，没有模块作用域。A 组在 button.css 里设了 --primary: #007bff，B 组在 card.css 里又写了 --primary: #6b21a8，最终生效的是后者，但你在 DevTools 的 Computed 面板里根本看不出来源。更糟的是，设计稿里“Primary”可能指按钮背景，也可能指标题文字，语义模糊导致复用困难。
-
--primary这类裸名必须加前缀，如--ui-color-primary或--app-color-brand - 二级关键词统一用
color，不是brand或main，IDE 补全才可靠（--ui-color-*能批量提示，--ui-brand-*不行） - 禁用
--blue-500这类绑定具体色值的命名，换主色时所有引用和文档全得重来
--color-text-primary 比 --text-primary-color 更好使
顺序决定可读性与工具支持。把维度（color）放前面，语义（text-primary）放后面，既符合 CSS 变量命名惯例，也对齐 Figma 图层命名（如 “Text / Primary” → --color-text-primary）。
- VS Code 搜索
--color-能一次性列出所有颜色变量，搜索--text-则混入字体、间距等无关项 - 设计系统交付时，前端变量名和设计师标注必须严格对齐，斜杠转连字符、全小写、不缩写（
--surface-card-bg✅，--surf-card-bg❌） - 避免
--header-bg-active这种“位置+状态”耦合命名，换成--color-bg-surface+.header--active类控制状态更灵活
深色模式下别写两套变量，只改几个数字
在 :root 里硬写 --color-text-primary: #333 和 [data-theme="dark"] { --color-text-primary: #f0f0f0 } 看似简单，但主题切换逻辑分散、无法动态计算（比如自动变暗 10%），后期维护爆炸。
立即学习“前端免费学习笔记（深入）”；
- 用
hsl()基于基础变量生成：定义--color-brand-h: 220、--color-brand-s: 80%、--color-brand-l: 50%，再用hsl(var(--color-brand-h), var(--color-brand-s), var(--color-brand-l)) - 深色模式只需改
--color-brand-l: 30%，所有衍生色自动响应，不用逐个替换 - 配合
@media (prefers-color-scheme: dark)做系统级 fallback，不依赖 JS 切换，避免闪屏
变量该不该带 fallback？什么时候必须写
var(--color-primary, #007bff) 的 fallback 不是为了兼容 IE，而是防住构建或注入失败的瞬间。如果变量没被正确注入（比如 CSS 文件加载失败、JS 初始化晚于样式计算），页面会直接用 fallback 值渲染，而不是退到 currentColor 或透明。
- 所有生产环境使用的
var()必须带 fallback，哪怕只是var(--color-primary, black) - fallback 值建议用中性色（
black、white、transparent）或设计系统里的基础色，别用临时色值 - 不要在组件内部重复定义同名变量（如
.card { --color-primary: red; }），这会让 fallback 失效且调试路径断裂
真正难的不是起名，而是守住边界：只在 :root 定义语义变量、禁止局部覆盖、所有颜色引用必须走 var()。一旦某处出现硬编码 #007bff，规范就从那个点开始瓦解。
