css变量未生效主因是作用域错位或拼写错误：变量名严格区分大小写、连字符数量及顺序，--color-primary与--colorprimary互不识别；var()仅在声明该变量的元素及其后代中有效，且受all: unset等重置属性中断继承链。
直接在 :root 里定义颜色变量、所有地方用 var() 引用并带 fallback，是唯一靠谱的全局颜色管理方式。硬写 #3498db 或 blue 到组件里，等于主动放弃维护权。
为什么 var(--color-primary) 不生效，页面变透明或继承父色
这不是浏览器 bug，而是 CSS 规范行为：var() 在变量未定义或值为空时，不会报错，而是回退到该 CSS 属性的初始值或继承值。比如 color: var(--text-color) 中 --text-color 根本没声明，Chrome 会取 inherit，Firefox 可能渲染为 transparent —— 文字就消失了。
-
var()必须带 fallback，且 fallback 必须是合法 CSS 值：color: var(--text-color, #333)✅，color: var(--text-color, unset)❌ - fallback 不是“变量不存在才用”，而是“变量值无效时兜底”；即使变量存在但语法错误（如
--x: 10px 20px），也会触发 fallback - 微前端或多团队协作时，某个子应用漏载主题 CSS，父级又没设 fallback，UI 就会突然失真
:root 里定义变量时常见的命名和值陷阱
变量名必须以 -- 开头，且必须放在 :root（不是 html 或 .theme），否则无法全局继承。命名混乱或值写法不当，会导致后续所有引用都不可靠。
- 禁止用绑定组件的命名：
--header-bg、--btn-primary-color—— 换个组件名，变量就废了 - 推荐分层语义化命名：
--color-primary-500（基础值）、--color-text-primary（用途映射） - HSL 分量变量要拆开写且不带引号：
--primary-h: 210✅，--primary-s: "65%"❌（旧版 Safari 会解析失败） - 避免在
:root中嵌套var()：--color-text: var(--color-primary)在部分 Safari 版本中不生效
var() 在哪些地方不能直接用，或容易出错
var() 不是万能占位符，它只在支持该属性值类型的上下文中起作用，且有明确的解析边界。
- 不能用于
content属性：content: var(--label)无效，只能用字符串字面量 - 不能在内联
style中使用：<div style="color: var(--text-color)"> → 浏览器完全忽略 <code>var() - 在
background复合属性中要注意顺序：background: var(--bg-color) no-repeat✅，background: no-repeat var(--bg-color)❌（解析失败） - @keyframes 中引用变量需谨慎：部分浏览器不支持跨作用域引用未声明变量，动画可能卡住或跳变
- 不要为深色模式新建一套变量名（如
--color-primary-dark），而是在媒体查询或.dark类中重设同一组变量：.dark { --brand-l-base: 30%; } - 所有状态色统一用
hsl(var(--brand-h), var(--brand-s), calc(...))动态生成，例如：button:disabled { background: hsl(var(--brand-h), var(--brand-s), 20%) } - JS 主题切换时，务必用
document.documentElement.style.setProperty('--color-primary', '#0d6efd')，而不是操作 class 后再手动改样式表 —— 后者无法触发 CSS 变量重计算
深色模式切换时，为什么颜色跳变或闪屏
单纯替换 --color-primary 的 HEX 值，无法保证按钮 hover、disabled、border、SVG fill 等所有衍生状态同步变化，视觉就会断裂。真正稳定的方案是控制 HSL 的明度（l）分量。
最易被忽略的一点：CSS 变量本身不校验类型，也不提供运行时错误提示。一个拼错的变量名（如 --primray-color）会静默失效，直到你在某个按钮上看到文字突然变黑或背景消失 —— 那时候再查，已经跨了三个文件和两个 Git 分支。
