CSS变量必须在:root中显式声明全部字段，每套皮肤覆盖同一组变量名；切换主题须用document.documentElement.dataset.theme并在HTML解析前设置；组件内禁止重复声明同名变量。
皮肤变量必须在 :root 中显式声明全部字段
漏定义某个变量，比如只写了 --color-primary 却忘了 --border-color，所有用 var(--border-color) 的地方就会 fallback 到初始值（通常是 currentColor 或透明），导致边框消失、分割线不可见。这不是“没生效”，是 CSS 变量的 fallback 机制在起作用。
每套皮肤都应覆盖同一组变量名，哪怕值和 light 模式相同也要写出来。结构保持一致，方便后续用 JS 批量读取或 JSON 驱动生成主题配置。
- 基础色：
--color-primary-base、--color-neutral-100、--color-neutral-900 - 语义色：
--color-success-500、--color-error-500、--color-warning-500 - 空间与动效：
--space-sm、--radius-md、--duration-fast - 禁用强绑定名，如
--btn-bg-hover或--card-border-dark——它们无法复用，也无法被其他组件继承
切换必须操作 document.documentElement.dataset.theme
用 className 切换（比如 html.dark）看似简单，但选择器权重只有 10，很容易被 .header .nav-item.active 这类业务样式覆盖，导致变量不生效。而 [data-theme="dark"] 权重是 110，稳定可靠，且无命名冲突风险。
更关键的是：必须在 HTML 解析前设置 dataset.theme，否则必现 FOUC（白屏闪动）。不能等 DOMContentLoaded，也不能包在函数里延迟执行。
立即学习“前端免费学习笔记（深入）”；
- 在
<head>内放同步内联 script：<script>document.documentElement.dataset.theme = localStorage.getItem('ui-theme') || 'light';</script> - 服务端能判断就优先服务端注入（比如根据 Cookie 或 UA），比客户端更稳
- 切换时只改
dataset.theme，别碰style.setProperty()—— 后者适合单变量微调，不适合整套皮肤切换
Tailwind 用户请用 theme.extend 桥接 CSS 变量
Tailwind 本身不解析 CSS 变量，但你可以通过 theme.extend 把 var(--color-primary) 显式映射进去，再配合 darkMode: 'class' 或自定义 data-theme 触发器使用。
千万别装第三方主题插件（如 tailwindcss-theming）。它们会劫持 theme.colors 解析逻辑，导致 DevTools 里看不到最终变量来源，升级 Tailwind 4 后大概率直接失效。
- 配置示例：
module.exports = { darkMode: 'class', theme: { extend: { colors: { primary: { DEFAULT: 'var(--color-primary-500)', 50: 'var(--color-primary-50)', }, }, }, },} - 对应 CSS 中必须有：
[data-theme="dark"] :root { --color-primary-500: #3b82f6; } - 确保所有主题变量都在
:root下定义，且顺序上位于默认值之后，否则会被覆盖
组件内禁止重复声明同名 CSS 变量
比如在 .card 里写 --bg-base: #f0f0f0，会污染继承链：子元素读取 var(--bg-base) 时拿到的是卡片局部值，而不是你预设的皮肤变量。这会让皮肤切换逻辑失控，且难以调试。
CSS 变量的优势在于“穿透性”——它能覆盖内联样式（只要没加 !important），也能被 calc()、rgba() 直接调用。一旦在组件层重定义，就等于切断了全局控制流。
- 组件样式中只允许使用
var(--xxx)引用，不允许--xxx: xxx声明 - 如果某组件需要特殊背景，应通过新增语义变量实现，例如
--card-bg-emphasis，并在各皮肤中统一提供值 - 第三方 UI 库（如 Element Plus）若支持 CSS 变量，直接按其文档覆盖对应变量名即可，无需 hack class
