17370845950

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，这会动态降低对比度，必须用独立变量控制，而不是靠透明度“省事”。