shadow dom 的 css 变量是唯一规范支持的安全样式通信机制，需显式挂载于宿主元素，配合 var()、:host、exportparts/::part() 实现分层主题定制与细粒度控制。

Shadow DOM 的 CSS 变量不是“穿透”的捷径，而是唯一被规范支持的、安全可控的内外样式通信机制。它不破坏封装性，反而在严格隔离与灵活定制之间架起桥梁：变量必须显式声明在宿主元素上，由 shadow 内部通过 var(--name, fallback) 按需读取，既防全局污染，又支持运行时主题切换。

变量必须挂载在宿主元素本身

外部设置的 CSS 变量默认不会进入 Shadow DOM，除非该变量定义在组件标签自身或其直系祖先（非 :root 或 body）。这是最常见的失效原因。

• ✅ 正确：<my-button style="--primary-color: #28a745; --radius: 6px;"></my-button>
• ✅ 正确：my-button[theme="dark"] { --bg: #1e1e1e; }（配合 :host[theme="dark"] 使用）
• ❌ 错误：body { --primary-color: red; } → shadow 内无法继承
• ❌ 错误：.wrapper > my-button { --primary-color: blue; } → 变量未挂载到宿主节点，不生效

用 :host 配合变量控制宿主外观

仅靠变量只能影响 shadow 内部节点；若要让主题也作用于组件容器本身（如圆角、边框、尺寸），必须在 shadow 内的 <style></style> 中使用 :host 选择器绑定变量。

• :host { border-radius: var(--button-radius, 4px); }
• :host(:hover) { --shadow: 0 4px 12px rgba(0,0,0,0.15); }
• :host([size="large"]) { --font-size: 1.25rem; }
• ⚠️ 注意：:host 只能在 shadow 内部样式中使用，不能写在外部 CSS 文件里

分层设计主题变量体系

避免把所有变量都暴露出去。推荐按语义分三级管理：

• 基础原子变量（必须暴露）：如 --color-primary、--spacing-md、--radius-sm —— 组件内部直接消费，提供默认值
• 组件级变量（建议暴露）：如 --button-bg、--input-border —— 封装组合逻辑，便于批量定制同类组件
• 上下文变量（谨慎暴露）：如 --card-shadow、--modal-z-index —— 仅在明确需要跨组件协调时开放

所有变量名应统一前缀（如 --mylib-），避免冲突；每个 var() 调用都带 fallback，防止未定义时样式崩塌。

搭配 exportparts + ::part() 实现细粒度控制

当标准变量不足以覆盖子元素样式（比如图标颜色、 placeholder 文字、禁用态透明度），可启用 exportparts 属性和 ::part() 伪类。

• 组件内部标记：<svg part="icon"></svg>
• 宿主添加：<my-button exportparts="icon"></my-button>
• 外部控制：my-button::part(icon) { color: var(--icon-color); }
• ⚠️ 注意：::part() 不支持嵌套（如 ::part(icon)::before 无效），且需浏览器支持（Chrome 95+ / Safari 17.4+ / 微信小程序 2.28.0+）