直接在:root中声明--primary-color即可全局生效；必须用双短横线前缀，值需手动替换到所有color、background等属性及伪元素、SVG、表单状态中，第三方库需确认支持CSS变量。
直接在 :root 里声明 --primary-color 就行
不用套 class、不用写 html:root，就一行 :root { --primary-color: #3b82f6; }。浏览器把 :root 当作 html 元素处理，变量天然全局可访问。漏掉双短横线（比如写成 primary-color）或写在 .theme-wrapper 里，变量就只在局部生效，后代取不到。
所有用颜色的地方都得手动替换成 var()
浏览器不会自动扫描旧样式去替换 #3b82f6。你得逐个检查并改写：
-
background-color、color、border-color、box-shadow、outline-color中的硬编码值 -
::before和::after里的background和color—— 图标类装饰最容易漏 -
svg标签内的fill和stroke，必须显式写成fill: var(--primary-color) - 表单状态：如
input:focus、button:active、select:disabled - 第三方库（Ant Design、Element Plus）内部 class 若未开启 CSS 变量支持，它们的颜色不会响应你的
--primary-color
JS 切换主题色时 setProperty 没反应？别只改 style
调用 document.documentElement.style.setProperty('--primary-color', '#e63946') 后没变化，常见原因是：
- 变量名拼错（大小写敏感，
--Brand-Color≠--brand-color） - 加载顺序不对：你的
:root块必须放在框架 CSS（如 Bootstrap、Tailwind）之后，否则被覆盖 - 用了
!important：整行会被忽略 - 想靠它触发
[data-theme="dark"] :root重定义逻辑——但setProperty只改内联 style，不触发动态选择器匹配；正确做法是document.documentElement.setAttribute('data-theme', 'dark')
伪元素和简写属性里 var() 容易失效
var(--primary-color) 在 background 简写里常静默失败，因为浏览器会尝试解析整个字符串为图像、位置等组合值。例如 --bg-main: #f8f9fa 看似能用，但换成 linear-gradient() 就崩。
立即学习“前端免费学习笔记（深入）”；
安全写法只有两种：
- 拆开写：
background-color: var(--primary-color); - 确保变量值本身是完整合法的背景声明，比如
--bg-main: linear-gradient(135deg, #f5f7fa, #c3cfe2);，再用background: var(--bg-main);
调试时看开发者工具“计算样式”，如果还显示 var(--x) 没展开，基本就是变量未定义或拼写错误。
