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 没更新。
立即学习“前端免费学习笔记（深入）”；
系统介绍：YIXUNCMS中专专版是易迅软件工作室在中秋节来临之即推出的专题模板建站系统，使用增强版后台管控系统，板板设计符合节日特点。易迅软件工作室恭祝全国人民中秋快乐。特别提示：由于网站页面的不同设计，部分后台功能未在前端进行体现。系统特点：1、采用目前流行的PHP语言编写，底层采用超轻量级框架作为系统支撑；2、页面布局使用DIV+CSS技术，遵循WEB标准，及大提高页面的浏览速度；3、使用应
别用 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，这会动态降低对比度，必须用独立变量控制，而不是靠透明度“省事”。
