应按功能域前缀（如–btn-primary-bg）、设计系统层级（基础/语义/组件色）和类型后缀（如color-brand-primary-600）规范命名，禁用抽象名，收口定义并校验值格式，用属性选择器而非仅:root覆写深色模式，确保Token与变量全路径可逆映射，并在ci中自动diff验证。
css颜色变量命名冲突怎么避免
大型团队里，--primary-color 这种名字一写就撞车——A组改了它，B组组件突然变色，没人知道谁动的。本质不是命名不够“语义”，而是没分域。
- 按功能域前缀，比如
--btn-primary-bg、--card-border-color，不单独用--primary - 按设计系统层级切分：基础色（
--color-blue-500）、语义色（--color-accent）、组件色（--color-input-border-hover），三者不混用 - 禁用纯抽象名如
--main、--dark，它们在深色模式或主题切换时必然失效
postcss 或 CSS-in-js 中如何安全导出颜色变量
直接 :root { --color-brand: #007bff; } 导出，会导致构建时无法做主题替换或值校验。真正可维护的做法是把颜色定义收口到一处，再生成多目标输出。
- 用
postcss-custom-properties+ json 配置源，避免硬编码在 CSS 里 - 在构建流程中加一层校验：比如要求所有
--color-*变量值必须匹配^#[0-9a-fA-F]{3,6}$或已注册的 token 名（如blue-500） - CSS-in-JS（如 Emotion）里别用
css`color: var(--primary)`直引，改用封装函数theme.color.primary，便于后期替换成 HSL 动态计算
深色模式下 CSS 变量覆写失效的典型原因
@media (prefers-color-scheme: dark) { :root { --color-text: #fff; } } 看似合理，但常被忽略的是：变量作用域和级联时机不对，导致组件内已计算的值不会重算。
- 不要只靠
:root覆写，对关键组件加[data-theme="dark"]属性选择器，确保样式优先级压得过默认值 - 避免在伪类里动态读取变量，比如
button:hover { color: var(--color-text); }—— hover 时不会重新解析var()，应提前定义好--color-text-hover - 检查是否用了
!important强制覆盖变量值，这会阻断后续所有主题层叠逻辑
设计 Token 和前端变量之间同步难在哪
设计师给的 figma Token 文件更新了 brand.blue.600，前端却还在用旧的 --color-blue-600，问题不在工具链多寡，而在映射关系缺乏约束。
立即学习“前端免费学习笔记（深入）”；
- Token 命名必须带明确类型后缀，如
color-brand-primary-600，不能只叫primary-600，否则导出时无法区分是 color 还是 spacing - 前端变量名必须与 Token 全路径可逆映射，例如
color-brand-primary-600 → --color-brand-primary-600，禁止做“智能缩写” - CI 流程里加一步 diff 检查：比对设计系统 JSON 和生成的 CSS 变量文件，发现缺失或多余项立刻报错，不靠人工核对
颜色变量不是写一次就完的事，真正卡点在于「谁有权改」「改了影响谁」「怎么验证没改坏」——这些都得靠命名规则和流程卡点来兜底，光靠注释或文档留不住人。