CSS颜色变量应按语义角色命名（如--color-brand-primary-default）、分三层声明（色板/语义/上下文）、禁用HSL动态函数、预设明暗对比度变量并嵌入构建流程做自动化对比度检查。
颜色变量命名要反映语义，而不是物理值
直接用 --primary: #007bff 这类命名在设计系统中很快会失控。当品牌色调整、暗色模式接入、或组件状态变多时，--primary 到底指“主按钮默认色”还是“高亮文本色”？没人能立刻答出。应该按用途而非色值定义变量：
-
--color-brand-primary-default（品牌主色默认态） -
--color-interactive-hover（所有可交互元素悬停态） -
--color-surface-card（卡片背景） -
--color-text-secondary（次要文字，非“灰色#666”）
这样即使把 #007bff 换成 #0d6efd，也不影响下游组件逻辑——它们只认“谁该用什么角色”，不关心具体 RGB。
CSS 自定义属性必须分层声明，避免跨层覆盖
常见错误是把所有颜色变量一股脑写在 :root 里，结果暗色模式切换时只能靠 JS 强刷或重复定义整套变量。正确做法是分三层：
- 基础色板层（
color-palette.css）：仅含原始色值，如--palette-blue-50,--palette-blue-500，不带语义 - 语义映射层（
color-role.css）：将基础色映射为角色，例如--color-brand-primary-default: var(--palette-blue-500) - 上下文覆盖层（
dark-theme.css）：只重定义语义变量，如--color-surface-card: var(--palette-gray-800)
这样换主题只需加载不同上下文层，基础色板和语义定义完全复用，不会漏掉某个 --text-link 没更新。
立即学习“前端免费学习笔记（深入）”；
别用 HSL 调色函数做“动态生成”，它不等于设计系统中的颜色语义
看到 hsl(var(--hue), 70%, 60%) 就以为能自动适配主题？危险。HSL 偏移对饱和度/明度的感知是非线性的，lighten() 在深色背景下可能产出不可读的灰紫，且无法保证 WCAG 对比度。真实项目中更可靠的做法是：
- 每种语义色都预设明度阶梯（如
--color-text-primary-light/--color-text-primary-dark） - 用媒体查询或 class 控制哪组生效：
.theme-dark .text-primary { color: var(--color-text-primary-dark); } - 禁用
color-mix()或hwb()等实验性函数，它们在 Safari 16.4 之前不支持，且输出不可控
:root {
--color-text-primary-light: #1a1a1a;
--color-text-primary-dark: #e0e0e0;
}
.theme-dark {
--color-text-primary: var(--color-text-primary-dark);
}
.text-primary {
color: var(--color-text-primary);
}
对比度检查必须嵌入构建流程，不能靠设计师肉眼判断
即使所有变量命名规范、分层清晰，如果 --color-text-secondary 和 --color-surface-card 的组合在暗色模式下只有 2.1:1 对比度，就违反 WCAG AA。手动查每个组合不现实。推荐方案：
- 用 PostCSS 插件
postcss-accessibility在构建时扫描所有color/background-color组合 - CI 中跑
npx axe-cli --rules color-contrast验证 HTML 示例页 - 禁止提交对比度低于 4.5:1 的文字/背景对（正文）或 3:1（大号文字）
最容易被忽略的是：disabled 状态下的文字色常被设为 opacity: 0.5，这会动态降低对比度，必须用独立变量控制，而不是靠透明度“省事”。
