根本原因是：:root定义的CSS变量无法被Shadow DOM自动继承，必须通过:host显式声明--primary-color: inherit;才能透传；且变量须挂载在宿主元素或其直接父容器（如.dashboard-page）上，而非全局:root。
为什么直接在 :root 里改 --primary-color 总是失效
根本原因就两个：你的 :root 块加载顺序在组件库 CSS 之前——浏览器按顺序解析，后加载的同名变量才会生效；组件库没读 :root，它把变量挂到了自己的根容器上，比如 .ant-btn 或 my-button 元素本身。
真正起效的位置，是组件实例的直接父容器，例如：.dashboard-page { --primary-color: #52c418; }。只要这个元素包裹了按钮，且组件内部用 var(--primary-color) 读取，颜色立刻变。
常见错误现象：
- 写了
:root { --primary-color: red; }，但按钮还是蓝色 - 暗色模式切换后，部分组件颜色没响应
- 第三方组件（如
codexUI或Lucid）完全无视你定义的变量
组件内如何安全读取外层传入的 CSS 变量
别指望变量自动透入 Shadow DOM 或深层嵌套结构。必须显式承接：
立即学习“前端免费学习笔记（深入）”；
- 对于 Web Components：
:host { --primary-color: inherit; }——缺少inherit就等于关上了门 - 对于普通 HTML 组件（如
<div class="card"><slot></slot></div>）：.card { --card-bg: #fff; }，再给slot外层加style="all: inherit" - 绝对不要在组件内部重复声明同名变量，比如
.button { --primary-color: #1890ff; }——这会屏蔽外部传入值，变成硬编码 - 回退值必须是静态色：
color: var(--text-color, #333)安全；color: var(--text-color, var(--fallback))在 Safari 15.6 以下直接失效
如何设计一套可维护的 CSS Token 命名与分层体系
Token 不是随便起名的颜色别名，而是按语义 + 用途分层：基础色、语义色、空间尺寸、动效时长。命名混乱会导致主题切换时漏改、误改。
-
--color-primary-base：基础品牌色（如#2563eb），不直接用于组件，只供衍生色计算 -
--color-primary-500：主按钮默认色，由--color-primary-base通过color-mix()或预设比例生成 -
--space-md：中等间距（如12px），避免用--padding-sm这类绑定具体用途的名，因为同一数值可能用于margin/padding/gap - 禁止出现
--btn-bg-hover这种强组件绑定名——它应由--color-primary-600+--state-hover组合推导
所有基础 Token（颜色、圆角、阴影、断点）只定义在 :root，且命名带语义前缀；组件内部不声明新变量，只用 var(--color-bg-surface) 引用。
Web Components 中 :host 为何无法直接读取 CSS 变量
因为 :host 本身不继承父级样式，而 CSS 变量（--my-color）默认不具备跨 Shadow DOM 透传能力。除非显式在 :host 或 :host-context() 中声明，否则组件内部 var(--my-color) 会 fallback 到初始值或 undefined。
实操建议：
- 在自定义元素的
:host选择器中，用inherit或initial显式承接外部变量，例如：:host { --primary-color: inherit; } - 若需响应外部主题切换，优先用
:host-context([data-theme="dark"])而非依赖 JS 监听，避免重绘延迟 - 避免在
:host内部重复定义同名变量（如--primary-color: #007bff），否则会屏蔽外部传入值
最易被忽略的一点：JS 动态修改变量后，Shadow DOM 内部样式不会立即重排，尤其当变量被多个 var() 引用且涉及 calc() 时，可能出现短暂错位——此时应优先用 CSS.registerProperty 显式声明变量为可动画属性。
