--text-primary比--blue-500更可靠，因其语义明确指向主文本色，遵循--{domain}-{role}命名规范，避免主题切换时全局搜索替换和语义分散导致的视觉不一致。
直接用#3498db或rgb(52, 152, 219)写颜色，等于给项目埋雷——改一次要全局搜，漏一处就崩视觉一致性。
为什么--text-primary比--blue-500更可靠
前者明确回答“这是主文本色”，后者只说“这大概是个蓝”，但蓝用在哪？按钮？标题？禁用态？全靠猜。设计稿标的是“Text / Primary”，变量就必须叫--text-primary，斜杠转短横线、全小写、不缩写。
常见错误现象：团队里有人写--main-text，有人写--primary-text，有人写--text-main，结果同一语义分散在三处，主题切换时漏改一个就出错。
- 命名结构统一用
--{domain}-{role}，例如--button-primary-bg、--card-border-hover - 禁用纯抽象名：
--main、--dark、--accent在深色模式下必然失效 - 不加
-color后缀：bg和border已隐含类型，--button-primary-bg比--button-primary-color更精准
如何避免CSS变量作用域混乱导致覆写失效
var(--text-primary)不是实时求值，它在样式计算阶段只取一次值。很多深色模式失效，根源不在媒体查询写错，而在变量没被正确重定义或作用域错位。
立即学习“前端免费学习笔记（深入）”；
典型坑：只靠:root + @media覆写，但组件内已计算的color: var(--text-primary)不会因:root变更而重算。
- 加一层
[data-theme="dark"]属性选择器更稳，比单纯依赖@media (prefers-color-scheme: dark)兼容性更强 - hover/focus等交互态必须单独定义变量，如
--button-primary-bg-hover，不能指望button:hover { color: var(--text-primary); }自动响应主题变化 - 禁止在
box-shadow或background-image中直接套用无透明度的语义变量；var(--text-primary)是纯色，阴影常需 alpha，应提前定义--shadow-primary
怎样用HSL解耦基础色值与用途，支撑主题动态适配
硬编码#007bff会导致所有衍生色（hover、disabled、dark mode）变成手动维护的噩梦。HSL能解耦色相、饱和度、明度，让调整有逻辑可循。
示例结构：
: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));
}
@media (prefers-color-scheme: dark) {
:root {
--color-brand-lightness-base: 25%;
}
}
深色模式只需改明度，所有依赖它的变量自动变暗。大型项目必须收口变量定义与校验——基础色值抽成独立变量，用途变量只负责组合，不存具体色值。
最易被忽略的一点：CSS变量是全局的，没有模块隔离。不加前缀的--primary在引入第三方UI库时极易冲突，必须统一加项目或组件前缀，比如--myapp-color-text-primary。
