customelements.define()前必须验证标签名合法性并检查重复注册，observedattributes与attributechangedcallback需成对使用，shadow dom需透传css变量，slot应通过::slotted()精确控制样式，且每个组件须配套轻量接口文档。
customElements.define() 调用前必须检查标签名合法性
不合法的标签名会让注册直接失败，且错误信息模糊——常见报错是 Failed to execute 'define' on 'CustomElementRegistry': The name "mybutton" is not a valid custom element name。浏览器只认带连字符的全小写字符串，比如 my-button、user-profile-card，而 MyButton、mybutton、123-panel 全部拒收。
实操建议：
- 命名严格用 kebab-case：组件类名
UserProfileCard→ 标签名必须是user-profile-card，不能靠大小写或下划线“模拟”语义 - 注册前先查重：
if (!customElements.get('user-profile-card')) { customElements.define('user-profile-card', UserProfileCard); }，避免重复定义报错 - CI/CD 中可加脚本校验：提取所有
customElements.define(后的第一个字符串参数，用正则/^[a-z][a-z0-9]*-[a-z0-9-]*[a-z0-9]$/扫描源码
observedAttributes 和 attributeChangedCallback 必须成对出现
很多团队写了 attributeChangedCallback 却没声明 static get observedAttributes()，结果属性变更完全不触发回调——HTML 里写 <my-input value="test"></my-input> 或 JS 调用 el.setAttribute('value', 'new') 都无效。
实操建议：
- 所有需响应的属性（如
disabled、size、theme）必须显式列在observedAttributes数组里，漏一个就收不到变更 - 首次渲染时的属性值不会进
attributeChangedCallback，得在constructor或connectedCallback里手动读：this.hasAttribute('disabled') && this.setAttribute('disabled', '') - 别在回调里直接重写
shadowRoot.innerHTML，否则会清空<slot></slot>内容；应只更新 class、style 或子元素文本
Shadow DOM 内部样式必须主动透传 CSS 变量
Shadow DOM 隔离了样式，但也隔绝了外部继承链——font-family、color、line-height 默认进不去。如果组件内文字全变成浏览器默认字体，不是 Shadow DOM 没起作用，而是你忘了透传。
实操建议：
- 在 shadowRoot 的
<style></style>开头加：:host { --text-color: var(--text-color, #333); --font-family: var(--font-family, system-ui); } - 组件内部用
color: var(--text-color)、font-family: var(--font-family)，而非硬编码值 - 对外暴露的变量名要收敛：每个组件最多预留 2–3 个高频变量（如
--button-bg、--input-border），并在 README 明确用途和默认值
slot 插槽内容样式失控？优先用 :slotted() 约束而非 wrapper div
把 <slot></slot> 包在一层 <div class="content-wrapper"> 里再写 CSS 控制，看似简单，实则把样式责任甩给使用者——别人传进来的 <code><h2></h2> 或第三方组件可能被意外重置。
实操建议：
- 在 shadowRoot 的
<style></style>中写：:host ::slotted(*) { all: initial; font-size: inherit; line-height: inherit; }（慎用all: initial，仅限需要强重置时） - 更推荐细粒度控制：
:host ::slotted(h2) { margin: 0.5em 0; }、:host ::slotted(p) { margin: 0 0 1em 0; } - 文档必须注明 slot 接受的内容类型，例如注释写
<!-- @slot default - 接收纯文本或 inline 元素，不支持嵌套 block 元素 -->
组件质量一致性最易被忽略的点，不在语法对错，而在「契约意识」：每个 customElements.define() 都该对应一份轻量接口文档——标签名、必选属性、可选属性类型、触发事件、插槽约定、CSS 变量列表。没有这份契约，封装得再严实，协作时照样各写各的。
