CSS变量在Shadow DOM中不继承，必须由:host显式声明才能被子元素读取；否则var(--x)只能fallback，因变量根本未传入。
不能靠“穿透”去改 Shadow DOM 里的 CSS 变量——变量根本不是被“挡住”，而是压根没传进去。真正要做的，是让宿主元素 :host 主动声明并承接变量，否则子元素读 var(--x) 就只能 fallback 到初始值。
为什么 document.documentElement.style.setProperty() 失效
你在 :root 改了 --primary-color，但 <my-button></my-button> 内部还是蓝色，不是因为样式被“隔离”了，而是它压根没继承这个变量。Shadow DOM 不继承自定义属性，getComputedStyle(host) 返回空字符串就是铁证。第三方组件（比如基于 Lit 的按钮）通常在自己的 :host 规则里直接赋值：:host { --primary-color: #1890ff; }，这行 CSS 加载顺序靠后、权重更高，就覆盖了你写的 :root 声明。
- 别碰
:root改主题，优先用组件文档里写的 theme API（如createTheme()或theme属性） - 检查 DevTools 的 Computed 面板，搜
--primary-color，如果显示 inherited from <html>，说明:host没接住 - 动态换肤时，仅改
document.documentElement.style不触发 Shadow DOM 重计算，必须同步调用host.style.setProperty('--primary-color', '...')
:host 必须显式声明变量名
这是最容易被忽略的一步：不声明，就不存；不存，就读不到。哪怕只写 :host { --primary-color: inherit; }，也比在子选择器里反复定义强得多。Web Components 不会自动把父级变量“透传”进来，必须由 :host 显式读取、可选重定义。
- 错误写法：
:host .btn { --primary-color: red; }—— 这只影响.btn自身，对同级.icon或父级:host都无效 - 正确写法：
:host { --primary-color: var(--primary-color, #1890ff); }，既承接外部值，又提供 fallback - 暗色模式下条件覆盖：
:host-context([data-theme="dark"]) { --primary-color: #1890ff; }，比 JS 监听 class 更及时
JS 动态修改必须操作宿主元素，而非 document
用 document.documentElement.style.setProperty() 是全局污染，所有同名组件一起变；而真正可控的方式，是拿到具体组件实例，直接设它的内联样式。注意不要用 cssText，它会清掉所有已有内联样式（包括 width、margin 等非变量属性）。
立即学习“前端免费学习笔记（深入）”；
- 安全写法：
buttonEl.style.setProperty('--primary-color', '#ff4d4f'); - 批量设置更高效：
Object.assign(buttonEl.style, { '--primary-color': '#ff4d4f', '--border-radius': '6px' }); - 绝对避免：
buttonEl.style.cssText = '--primary-color: #ff4d4f';—— 清空风险极高 - 若组件支持
adoptedStyleSheets，可复用同一份CSSStyleSheet，但变量仍需由:host显式承接
回退值必须是静态颜色，且命名带前缀
var(--x, var(--fallback)) 在 Safari 15.6 以下直接失效；--bg 这类无前缀名迟早冲突——.sidebar 和 .notification-badge 都定义它，换肤时就会互相干扰。
- 回退值只能是静态值：
color: var(--text-color, #333);安全，嵌套var()不行 - 命名必须带语义前缀：
--button-primary-bg，而不是--bg或--color-1 - Shadow DOM 中若变量未在
:host声明，var(--x, #fff)仍会 fallback，但前提是该变量名已被:host“注册”过（哪怕值为unset）
最核心的一点：CSS 变量是否生效，和 DOM 嵌套多深无关，只取决于有没有一个选择器（通常是 :host）在它自己身上声明了那个变量名——声明即存在，不声明即不存在。
