主题变量必须挂载在:root，否则Web Components、Vue和React组件无法读取；仅:root下的CSS变量能被Shadow DOM和框架透传，切换主题需用classList.toggle()和setProperty()，并为过渡属性添加transition。
主题变量必须挂载在 :root，否则组件读不到
Web Components、Vue 的 <my-button>、React 封装的 ThemeProvider 都依赖 CSS 变量透传机制——而只有 :root 是全局作用域。写成 .theme-dark { --primary: #1e40af; } 或 html.theme-dark { --primary: ... } 都无效：浏览器会把它们当两个独立选择器，--primary 根本不会进入级联链。真正能被 Shadow DOM 和框架组件读取的，只有这一种结构：
:root {
--theme-primary: #3b82f6;
--theme-bg: #ffffff;
}
.theme-dark {
--theme-primary: #60a5fa;
--theme-bg: #111827;
}
切换时只需给 <html> 元素 classList.toggle('theme-dark')，所有 var(--theme-primary) 引用点（包括 ::before、input:focus、SVG fill、Font Awesome 图标）都会响应更新。
var() 必须显式出现在每个用色位置，漏一个就断链
哪怕 99% 的样式都用了 var(--theme-primary)，只要有一个地方硬编码：.card:hover { background-color: #2563eb; }，悬停态颜色就永远卡死。容易被忽略的引用点包括：
-
::before和::after里的background、color、border-color - 表单控件：
input:focus、select:disabled、textarea::placeholder - SVG 图标：内联
fill或stroke必须写成fill: var(--theme-primary); - Font Awesome 这类字体图标：需在对应 class 上补
color: var(--theme-primary);
JS 切换主题必须用 setProperty()，别碰 cssText
常见错误是直接清空整个内联样式：
立即学习“前端免费学习笔记（深入）”；
document.documentElement.style.cssText = '--theme-primary: #1e40af; --theme-bg: #111827;';
这会抹掉其他 JS 注入的动态样式（比如按钮禁用态、动画状态、第三方库管理的 class），导致 UI 行为异常。正确做法是逐个设置：
document.documentElement.style.setProperty('--theme-primary', '#1e40af');
document.documentElement.style.setProperty('--theme-bg', '#111827');
另外注意：为需要过渡的属性（如 background-color）提前加 transition: background-color 0.2s;，否则重绘生硬。
组件化封装时，主题配置要和结构解耦
HTML 组件（如自定义 <my-card> 或纯语义化 <article class="cmp-card">）不能自己声明主题变量，必须依赖顶层 :root 提供。组件内部只做引用：
.cmp-card {
background-color: var(--theme-bg);
color: var(--theme-text);
border: 1px solid var(--theme-border);
}
如果组件需要额外主题变体（比如 data-variant="inverted"），也应通过 class 控制，而非重定义变量：
.cmp-card.inverted {
--theme-bg: var(--theme-accent);
--theme-text: var(--theme-on-accent);
}
真正复杂的地方在于：主题变量名必须加语义前缀（如 --theme-bg 而非 --bg），否则容易和 Ant Design、Bootstrap 等第三方库的 --ad-bg、--bs-primary 冲突；且所有组件的样式文件必须确保不覆盖或重置这些变量——否则切换就失效。
