语义化CSS变量命名是保障视觉一致性的核心——用--text-primary而非--color-blue-500明确用途，统一采用--{domain}-{role}结构，分离基础色值与用途，借助HSL实现主题动态适配，并通过前缀收口、集中定义与自动化校验确保可维护性。
直接写 #3498db 或 rgb(52, 152, 219) 是最危险的起点——它不带任何上下文，改一次要全局搜、漏一处就崩视觉一致性。
用语义化变量名替代色值本身
颜色变量不是记颜色，是记“谁在什么场景下用它”。--text-primary 比 --color-blue-500 更可靠，因为前者明确回答了“这是主文本色”，后者只告诉你“这大概是个蓝”，但蓝在哪用？按钮？标题？禁用态？全靠猜。
- 命名结构统一用
--{domain}-{role}，例如--button-primary-bg、--card-border-hover，不加-color后缀（bg和border已隐含类型） - 禁用纯抽象名：
--main、--dark、--accent在深色模式或主题切换时必然失效，没人知道它该变亮还是变暗 - 设计稿中标注 “Text / Primary”，前端变量就必须叫
--text-primary，斜杠转短横线、全小写，不缩写、不意译
把基础色值和用途分离，用 HSL 动态生成
硬编码 #007bff 会导致所有衍生色（hover、disabled、dark mode）变成手动维护的噩梦。HSL 能解耦色相、饱和度、明度，让调整有逻辑可循。
- 在
:root中定义原子级变量：--color-brand-hue: 205、--color-brand-saturation: 85%、--color-brand-lightness-base: 55% - 再组合出用途变量：
--color-brand-primary: hsl(var(--color-brand-hue), var(--color-brand-saturation), var(--color-brand-lightness-base)) - 深色模式只需改明度：
@media (prefers-color-scheme: dark) { :root { --color-brand-lightness-base: 25%; } }，所有依赖它的变量自动变暗
避免 CSS 变量作用域和覆写失效的典型坑
var(--text-primary) 不是“实时求值”，它在样式计算阶段只取一次值。很多深色模式失效，根源不在媒体查询写错，而在变量没被正确重定义或作用域错位。
立即学习“前端免费学习笔记（深入）”；
- 别只靠
:root+@media覆写：组件内已计算的color: var(--text-primary)不会因:root变更而重算；加一层[data-theme="dark"]属性选择器更稳 - hover/focus 等交互态颜色必须单独定义变量，如
--button-primary-bg-hover，不能指望button:hover { color: var(--text-primary); }自动响应主题变化 - 禁止在
box-shadow或background-image中直接套用无透明度的语义变量，var(--text-primary)是纯色，而阴影常需 alpha，应提前定义--shadow-primary
大型项目必须收口变量定义与校验
当多个团队共用一套 CSS 变量时，--primary 这种名字等于没命名——它可能被 A 组当成背景色、B 组当成文字色、C 组当成边框色，冲突不可避免。
- 所有颜色变量必须带项目前缀，如
--myapp-text-primary，避免与第三方库（如 Ant Design 的--primary-color）冲突 - 变量定义必须集中收口（一个 JSON 文件或 TS module），禁止散落在多个 CSS 文件中；构建时用 PostCSS 插件校验值格式（如是否匹配
^#[0-9a-fA-F]{3,6}$） - 设计师给的 Token 名
color-brand-primary-600必须与前端变量名--color-brand-primary-600全路径可逆映射，中间不能跳步、不能意译
真正难的不是写出第一个 var(--text-primary)，而是确保第 200 个变量仍能被新成员一眼看懂、被自动化工具准确识别、被深色模式无缝接管——这取决于命名那一刻有没有把“谁、在哪、为什么”刻进名字里。
