




直接用英文命名CSS颜色。CSS标准不支持中文标识符,自定义变量需符合标识符规则,推荐语义化英文组合如--brand-primary;统一使用rgb()或hsl()而非HEX或命名色;CSS变量按作用域+类型两级命名并集中声明于:root;需工具链检测覆盖与未使用问题。
直接用英文。CSS 标准不支持中文标识符,color: 红色; 会完全失效。所有自定义颜色变量名(如 --primary-red)必须符合 CSS 标识符规则:只能含字母、数字、连字符(-),且不能以数字开头。
常见错误是照搬设计稿里的“珊瑚橙”“雾霾蓝”这类描述性中文名,结果在代码里写成 --珊瑚橙 —— 浏览器直接忽略该变量声明,后续引用全挂。
--brand-primary、--state-error、--bg-surface-light
--red 或 --blue,它们无法体现用途,后期改色时极易误改--color-p123,但需配套文档说明对应视觉效果项目中统一用 rgb() 或 hsl(),禁用 #rrggbb 和命名色(如 tomato)。
#ff6b6b 这类 HEX 值无法直接看出明度/饱和度,调整深浅时得靠试错;tomato 是固定值(rgb(255, 99, 71)),但语义模糊、不可控、不支持 alpha。
rgb(255, 107, 107) 明确暴露通道值,微调亮度只需改一个数字hsl(0, 70%, 71%) 更适合设计师协作——色相(h)、饱和度(s)、明度(l)直观可调,比如“降低主色明度 10%”直接改 l 值即可rgba() 或 hsla(),不要用 opacity 覆盖整块元素按「作用域层级 + 类型」两级命名,全部声明在 :root,禁止在组件内部重复定义同名变量。
错误做法:每个组件自己写 --text-color: #333,结果 A 组件改了,B 组件没同步,文字颜色就分裂了。
: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));

--color-brand-primary-hover: hsl(var(--color-brand-hue), var(--color-brand-saturation), calc(var(--color-brand-lightness-base) - 8%));
--color-text-primary: hsl(0, 0%, 12%);
--color-bg-canvas: hsl(0, 0%, 98%);
}--color-brand-hue)只存抽象值,不参与渲染-primary、-hover、-disabled),而非状态(-light、-dark)--color-bg-canvas 和 --color-text-primary,其他依赖它们的变量自动响应靠人眼检查 CSS 文件基本无效。必须引入工具链验证。
常见漏检场景:Figma 插件导出的颜色变量名拼写错误(--primar-color)、PostCSS 插件编译后变量被删除、CI 阶段未校验 CSS 变量引用完整性。
stylelint 配合 stylelint-declaration-strict-value 规则,强制限定颜色只能来自指定变量列表window.getComputedStyle(document.body).getPropertyValue('--color-brand-primary') 手动调试,确认变量已注入且未被覆盖var(--color- 并比对 :root 中声明的变量名,缺失即报错最常被忽略的是「颜色语义漂移」:某个 --color-success 最初指绿色,半年后被改成蓝绿色,但所有用到它的按钮、图标、提示文字都没同步更新视觉含义——这时候变量名没变,颜色值变了,一致性反而更危险。