CSS变量不生效主因是定义位置错误，组件仅继承直接父容器变量，:root声明对Web Components无效；应将变量定义在组件外层DOM节点或:host中，并用语义化命名与静态fallback确保兼容性。
变量定义位置错了，组件根本读不到
绝大多数“CSS变量不生效”问题，根源不是语法写错，而是变量没挂到组件能继承到的地方。浏览器按 CSS 加载顺序解析，后定义的同名变量才生效；更重要的是，组件库（比如 antd、Lucid 或自研 Web Components）通常不读 :root，而是监听其**直接父容器**上的变量。
常见错误现象：:root { --primary-color: red; } 写了但按钮颜色不变；暗色模式切换后部分组件无响应；第三方组件完全无视你定义的变量。
- 真正起效的位置是组件外层 DOM 节点，例如
.dashboard-page { --primary-color: #52c418; }，只要按钮被这个元素包裹，且内部用var(--primary-color)，立刻生效 - Web Components 必须在
:host里显式承接：:host { --primary-color: inherit; }—— 缺少inherit就等于关死了门 - 普通 HTML 组件（如
<div class="card"><slot></slot></div>）需在.card上声明变量，并给<slot>外层加style="all: inherit"
组件内部重复声明变量，等于自废武功
在组件样式里写 .button { --primary-color: #1890ff; } 看似方便，实则切断了外部控制能力。这不是“设默认值”，而是硬编码覆盖——主题切换、运行时换肤、父级定制全部失效。
所有基础 Token（颜色、圆角、阴影、断点、间距）必须统一定义在 :root，且命名带语义前缀，例如 --color-primary-base、--space-md、--radius-lg。
立即学习“前端免费学习笔记（深入）”；
- 组件内部只做引用：
background-color: var(--color-primary-500);，不声明新变量 - 需要局部覆盖时，用属性选择器或自定义属性传入，例如
button[data-variant="ghost"] { --color-bg-surface: transparent; } - 禁止用 SCSS/Less 的
@mixin包裹变量赋值——那会把运行时可变性编译成静态 CSS，动态优势归零
回退值写错，Safari 15.6 以下直接崩溃
var(--text-color, var(--fallback)) 这种嵌套回退写法在 Safari 15.6 及更早版本中会被整个忽略，导致文本无色不可见。这不是兼容性警告，是真实挂掉。
安全写法只有一个：回退值必须是静态常量。
- ✅ 正确：
color: var(--text-color, #333); - ❌ 危险：
color: var(--text-color, var(--fallback));或color: var(--text-color, #fff + #000); - 如果真要多级 fallback，得靠 JS 注入或预设多个独立变量，不能依赖 CSS 层叠计算
Token 命名没分层，后期维护就是灾难
命名混乱不是小事。比如 --btn-bg-hover 这种强绑定名，会让暗色模式时不得不全局搜索替换；--padding-sm 这类用途绑定名，一旦某处要用它当 margin，就只能复制一份或改名，违背复用初衷。
Token 必须按语义 + 用途分层，且每一层职责清晰：
- 基础色：
--color-primary-base（如#2563eb），不直接用于组件，只供衍生色计算 - 语义色：
--color-primary-500（主按钮默认色），由 base 色通过color-mix()或预设比例生成 - 空间尺寸：
--space-md（如12px），避免--padding-sm这类用途限定名——同一数值可能用于margin/padding/gap - 字号系统分两级：
--font-size-100（绝对值），--text-body-font-size（角色名，引用前者）
最易被忽略的一点：所有基础 Token 必须定义在 :root，且外部项目引入时，要确保 tokens.css 在组件库 CSS 之前加载，否则压缩工具（如 PurgeCSS）可能误删“未使用”的变量声明。
