Shadow DOM 样式隔离导致外部 CSS 自定义属性 --my-color 无法穿透生效，需通过 :host { --my-color: var(--my-color); } 显式继承，或使用 ::part() 暴露子元素样式接口。
为什么直接在 Shadow DOM 外写 --my-color 不生效
因为 Shadow DOM 天然隔离样式，外部定义的 CSS 自定义属性（如 :root { --my-color: blue; }）默认无法穿透到 shadowRoot 内部。组件内部若用 var(--my-color)，但没在 shadowRoot 的作用域里声明或继承该变量，就会回退到 initial 值或 fallback（比如 var(--my-color, black) 中的 black）。这不是 bug，是封装机制的必然结果。
在自定义元素中显式继承外部变量的 2 种写法
必须让 shadowRoot “知道”外部传入的变量。最常用且可靠的方式是在组件根节点（即 this.shadowRoot.host 对应的自定义标签）上声明继承规则：
- 在组件内部
<style>中加一句：:host { --my-color: var(--my-color); }—— 这会把外部:root或父容器定义的--my-color拷贝进 shadow scope - 更稳妥的做法是带 fallback：
:host { --my-color: var(--my-color, #0062ff); }，避免变量未定义时样式断裂 - 如果组件支持多层嵌套（比如
<my-card><my-button></my-button></my-card>），子组件也要各自做一次:host继承，不能依赖“链式传递”
::part() 是暴露内部子元素样式的唯一标准方式
当你要允许外部控制组件内某个具体子元素（比如按钮里的图标、输入框的边框）时，::part() 是 Web Components 规范指定的方案。它不破坏封装，也不需要 JS 操作 shadowRoot：
- 组件作者必须在内部元素上显式添加
part="icon"、part="input-border"等属性 - 使用者才能写：
my-input::part(input-border) { border-color: red; } - 注意：浏览器兼容性需检查 —— Chrome 73+、Firefox 94+、Safari 17.4+ 支持；旧版 Safari 需加
-webkit-前缀 - 不能用
::part(icon:hover)这类伪类组合，::part()只接受单个 part 名称
别踩坑：CSS 变量名设计与主题切换的实际约束
暴露变量不是越多越好。真正要暴露的，是语义化、可组合、有明确用途的 token，比如 --my-input-border-color、--my-primary-bg，而不是 --my-icon-margin-left 这类细节值：
立即学习“前端免费学习笔记（深入）”；
- 变量命名建议统一前缀（如
--my-），避免和全局或第三方库冲突 - 不要在
:host上直接覆盖原生属性（如:host { color: var(--my-color); }），这会干扰用户对color的预期继承行为 - 主题切换时，靠 JS 切换
:root变量值是可行的，但要注意：shadowRoot 不会自动响应变量变化，除非你用了var(--x)且该变量在:host层已继承 —— 否则得手动触发requestUpdate()或重设 style
真正难的不是写几行 var()，而是判断哪些变量该暴露、哪些该锁死在 shadow 内部。一旦开放了 --my-padding，就得接受用户把它设成 100px 导致布局崩坏 —— 封装性和可定制性永远在博弈。
