为什么CSS主题色变量建议分语义层和基础层

语义层和基础层必须分离：基础层（如--color-blue-500）只存原始色值，语义层（如--color-primary）通过var()引用基础层，组件仅使用语义变量；换主题只需修改语义层映射，避免grep误伤和fallback失效。

语义层和基础层不分开，换主题时就得全局搜替换

直接在 :root 里写 --primary-color: #3b82f6; 看似省事，但一旦品牌色从蓝色换成紫色，所有含 primary 的变量名本身没问题，可你得确认它没被误用于“主标题文字”或“禁用态边框”——而这些本不该和主操作色绑定。更麻烦的是，如果项目里还散落着 --blue-500、--indigo-600 这类基础色变量，它们和语义变量混在一起，grep 替换会连带改掉注释、SVG fill 值甚至 JS 字符串。

基础层只存原始值，语义层才决定“谁用什么色”

分层不是为了多写几行代码，而是把“设计决策”和“技术实现”切开：

1. 基础层（如 --color-blue-500、--color-gray-900）只出现在一个地方：:root 顶部，且只赋具体十六进制值
2. 语义层（如 --color-primary、--color-text-primary）必须用 var(--color-blue-500) 显式引用基础层，不能硬写色值
3. 组件内只允许使用语义层变量，禁止出现 var(--color-blue-500) 或直接写 #3b82f6

这样改品牌主色，只需动基础层一行；调深色模式对比度，只改语义层的 calc() 表达式；第三方组件漏了主题适配？查它用了哪一层变量，就能快速定位是语义映射缺失，还是基础色没覆盖全。

不按层组织，var() 的 fallback 就会失效

var(--color-primary, #1a1a1a) 的第二个参数只在 --color-primary 未定义或值为 unset 时生效。但如果基础层和语义层混写，比如某处漏声明 --color-primary，而另一处又在组件里写了 --color-primary: #6b7280; 覆盖了全局值，那 fallback 根本不会触发——浏览器看到的是“已定义但值不对”，而不是“未定义”。分层后，基础层确保所有原始值存在，语义层统一做映射，fallback 才真正起到兜底作用。

最常被忽略的一点：媒体查询里的重定义必须基于语义层

很多人在 @media (prefers-color-scheme: dark) 里直接重设 --color-blue-500，结果发现按钮变紫了、文字却还是黑的。因为组件读的是 --color-primary，而它的值仍指向旧的 --color-blue-500。正确做法是：只在媒体查询里重定义语义变量，例如：

:root {--color-primary: var(--color-blue-500);}@media (prefers-color-scheme: dark) {:root {--color-primary: var(--color-indigo-400); /* 不动基础层 */}}

基础层保持稳定，语义层响应变化——这才是 CSS 变量能支撑复杂主题系统的底层逻辑。否则所谓“一键切换”，最后都变成手动修 37 个文件。