用 shadow dom 实现 ui 一致性本质是切断外部干扰路径，必须用 attachshadow({ mode: 'open' }) 并将所有样式内联注入 shadowroot，仅通过 :host 和 ::slotted 合规穿透，且初始化须在 connectedcallback 中执行。
用 Shadow DOM 实现 UI 一致性，本质不是“让样式看起来一样”，而是切断外部干扰路径——只要隔离到位，组件在任何页面里渲染结果就天然一致。
attachShadow({ mode: 'open' }) 是默认且最稳妥的选择
别被“closed 更安全”误导。mode: 'closed' 会把 shadowRoot 设为不可访问，但实际中：DevTools 看不到结构、测试脚本拿不到内部节点、协作时排查问题靠猜。而 mode: 'open' 下 element.shadowRoot 可读可查，调试和自动化测试都能正常进行。真正影响一致性的，从来不是 shadowRoot 是否暴露，而是样式是否注入正确、:host 是否覆盖关键容器属性。
所有样式必须内联进 shadowRoot，不能靠 中的 link
第三方 UI 框架（如 Foundation、Tailwind）的 <link rel="stylesheet"> 放在主文档 里，样式会全局生效，直接污染宿主页面，也根本不会进入 shadow tree。必须把 CSS 内容放进 shadowRoot：
- 用
shadowRoot.innerHTML = '<style>...</style>'最快，但动态更新时需重写整个 innerHTML，容易丢事件监听器 - 更健壮的做法是创建
CSSStyleSheet实例，再赋值给shadowRoot.adoptedStyleSheets；Chrome/Firefox 支持sheet.replace()动态更新，Safari 17.4+ 才稳定支持 - 如果用了
<link href="...">，必须把它放在 shadowRoot 内部，且带上crossorigin（尤其 CDN 资源），否则加载失败或 CORS 报错
:host 和 ::slotted 是唯一可控的穿透出口，别滥用
UI 一致性崩塌，往往发生在“以为能透、其实不能透”或“不该透、却强行透”的地方：
-
:host只匹配宿主元素自身（比如<my-card></my-card>标签），适合设display、margin、width、[disabled]状态样式——这是组件对外暴露的“容器接口” -
:host-context(.dark-theme)才能响应祖先链上的主题类；:host(.dark-theme)只查宿主自己有没有这个 class，基本没用 -
::slotted(*)只作用于传入<slot></slot>的顶层 light DOM 子节点，且只允许继承性属性（color、font-family、line-height），不能设margin或display—— 布局责任必须由使用者承担，组件不越界
模板初始化必须等 connectedCallback，不能在 constructor 里操作 shadowRoot
常见错误：在自定义元素 constructor() 里就调用 this.shadowRoot.appendChild(...)，结果报 Cannot read property 'appendChild' of null。因为此时 shadowRoot 还没创建——attachShadow() 通常在 connectedCallback() 里才执行（或至少要等元素挂载后）。正确时机是：
- 在
connectedCallback中检查this.shadowRoot是否存在，不存在则先attachShadow - 再把模板内容（HTML 字符串或
document.createElement('template')）克隆并 append 到 shadowRoot - 避免在
disconnectedCallback里清理 shadowRoot，它不会自动销毁，也不该手动删
真正决定 UI 是否一致的，不是写了多少 CSS，而是有没有守住三条线：shadow boundary 是否完整、样式是否全部落在 shadowRoot 内、穿透逻辑是否严格按规范使用 :host 和 ::slotted。一旦这三处出偏差，哪怕只漏一个全局 .btn 规则，整个组件的视觉表现就可能在不同页面里彻底失守。
