全局CSS变量必须在:root中集中定义，如--color-primary: #3b82f6；主题切换需通过.theme-dark :root重定义变量，并确保html类名首屏即存在；禁止在非:root处声明颜色变量。
直接在 :root 定义全局变量，别搞“引入”那一套
CSS 变量不是靠 @import 或构建工具“引入”的，它是原生运行时机制。所有基础色必须集中声明在 :root 块里，比如：
:root {
--color-primary: #3b82f6;
--color-text-primary: #1f2937;
--color-bg-surface: #ffffff;
}
这不是“可选写法”，而是唯一可靠起点。写在其他选择器（如 .theme-dark 外部）或组件内部的同名变量，会因层叠顺序或作用域失效——你改了 :root 却没生效，八成是被后面加载的样式覆盖了。
-
:root等价于html，但语义更准、优先级更高，别用html替代 - 变量名强制用双短横前缀（
--color-primary），避免和未来 CSS 属性冲突 - 值必须是合法 CSS 值，支持嵌套引用：
--color-primary-light: hsl(from var(--color-primary) h s calc(l + 10%));
主题切换失效？检查 class 切换时机和变量重定义位置
闪屏、颜色没变、部分组件不响应——这些问题几乎都出在 HTML 标签类名和变量定义的配合上。
错误写法：.theme-dark { --color-bg-surface: #1e1e1e; }（没挂到 :root 上，浏览器直接忽略）
立即学习“前端免费学习笔记（深入）”；
正确写法必须绑定到 :root 伪类：
.theme-dark :root {
--color-bg-surface: #1e1e1e;
--color-text-primary: #f0f0f0;
}
同时，<html class="theme-dark"> 必须在首屏渲染前就存在（服务端注入或内联 script），不能等 JS 加载完再 document.documentElement.classList.add('theme-dark') —— 否则中间几十毫秒会回退到默认样式。
PigX UI Pro 前端开发指南 - Vue 3 + TypeScript + Element Plus。当用户提到 PigX UI、PigX 前端、lgb-mgui 项目、Vue 3 企业级后台开发、Element Plus 后台开发时使用此技能。
- 禁用过渡干扰：
html { transition: none !important; }，主题切换完成后再恢复 - 不要用
data-theme+[data-theme="dark"] :root，CSS 层叠权重不如类名稳定 - 深色模式检测可结合
@media (prefers-color-scheme: dark)，但仅作 fallback，别依赖它接管全部逻辑
var() 回退值不是兜底保险，而是解析失败时才触发
写 color: var(--color-text-primary, #333); 并不能防住“变量已定义但值为空”这种坑。回退值只在变量**未声明**或显式设为 unset 时生效。
常见翻车现场：
- 构建工具把变量值替换成空字符串（如 PostCSS 插件误处理），
--color-text-primary: ""→var()不触发 fallback - JS 动态设置时漏掉单位或格式：
el.style.setProperty('--color-bg', '')，变量存在但无效 - 大小写拼错：
var(--Color-Primary)和--color-primary是两个变量
调试建议：用 getComputedStyle(document.documentElement).getPropertyValue('--color-text-primary') 直接看真实值，确认是不是空字符串或 inherit。
组件内禁止硬编码重写变量，只允许引用
这是大型项目失控的起点。看到某个卡片背景要临时调深一点，下意识写 .card-special { --color-bg-surface: #f9fafb; } —— 这等于在局部污染整套变量体系。
正确做法只有两条路：
- 用已有变量组合：
background-color: color-mix(in srgb, var(--color-bg-surface), white 10%); - 加新语义变量（如
--color-bg-card），但必须在:root统一定义，且说明用途
团队规范里得写死：禁止在任何非 :root 选择器中声明 --color- 开头的变量。否则半年后你会在 DevTools 里看到十几个同名变量层层覆盖，根本分不清哪个在起作用。
最麻烦的不是定义，是清理旧值——上线前务必 grep 全项目，删掉所有散落在组件 CSS 中的 --color- 声明。
