纯HTML组件不能直接用import引入，因为浏览器原生ES模块系统仅支持JS、TS、JSON等可执行模块，HTML文件无导出接口且不被解析为模块；必须封装为自定义元素（Custom Element）并通过customElements.define()注册，才能实现跨框架复用、Shadow DOM隔离与生命周期控制。
纯HTML组件为什么不能直接用 import 引入？
因为浏览器原生不支持 ES 模块语法加载纯 HTML 文件——import './button.html' 会报 Failed to resolve module specifier。你写的 HTML 片段不是 JS 模块，没有导出接口，也不能被打包工具自动识别为资源。
常见错误现象：在 Vue/React 项目里直接 import HTML 文件，控制台报错，组件空白，甚至整个页面白屏。
- 真正能被
import的只有 JS、TS、JSON，或经插件（如vite-plugin-html）显式声明处理的文件类型 - 纯 HTML 组件交付必须走“模板字符串 + 宿主注入”或“自定义元素注册”两条路径，不能依赖模块系统直读
- 如果用 Webpack，需配合
html-loader+raw-loader，但产出仍是字符串，不是可挂载节点
customElements.define() 是最稳妥的交付方式
把 HTML 片段封装成自定义元素（Custom Element），才能跨框架复用、支持 SSR、具备生命周期控制。它不依赖 React/Vue 运行时，浏览器原生支持（Chrome 67+/Firefox 63+/Safari 16.4+）。
使用场景：设计系统中按钮、卡片、表单控件等原子级 UI 单元；需要嵌入 CMS、邮件模板、微前端子应用的静态环境。
立即学习“前端免费学习笔记（深入）”；
将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。
- 必须用
class继承HTMLElement，且构造函数内不能访问this.shadowRoot（需在connectedCallback中创建） - 模板建议用
document.createElement('template')配合innerHTML，避免字符串拼接 XSS 风险 - 属性映射要用
static get observedAttributes()+attributeChangedCallback，不要靠dataset手动轮询
class DSButton extends HTMLElement {
constructor() {
super();
this.attachShadow({ mode: 'open' });
}
connectedCallback() {
this.shadowRoot.innerHTML = `
<style>:host { display: inline-block; } button { padding: 8px 16px; }</style><button><slot></slot></button>
`;
}
}
customElements.define('ds-button', DSButton);交付前必须验证三件事：语义、可访问性、CSS 隔离
设计系统组件不是视觉稿切图，HTML 结构决定语义层级和屏幕阅读器行为。一个没 role、没 aria-label、没 tabindex 的按钮，在无障碍测试中就是失败项。
容易踩的坑：用 div 模拟按钮却不加 role="button" 和键盘事件监听；Shadow DOM 内样式未用 :host 或 ::slotted 控制穿透；字体单位混用 px 和 rem 导致缩放失效。
- 所有交互元素必须有明确的
role、tabindex、aria-*属性，且通过 axe 或 WAVE 工具验证 - CSS 必须作用于
shadowRoot内部，外部样式无法穿透（除非显式用:host ::slotted(*)） - 字体大小统一用
rem，根字号由宿主页面控制，组件内禁止设html { font-size: 16px }
构建产物怎么组织才能被下游直接 script 引入？
交付物不是一堆 .html 文件，而是一个可执行的 ES 模块 bundle，入口是 customElements.define() 调用链。下游项目只需一行 <script type="module" src="https://cdn.example.com/ds/v1.2.0/index.js"></script> 即可注册全部组件。
性能影响：每个自定义元素注册都触发一次浏览器解析，10 个组件就 10 次注册开销。必须合并为单入口、按需注册（用 export 暴露工厂函数）、支持动态 import()。
- 构建输出至少含两个文件：
index.js（注册所有默认组件）和index.min.js（压缩版），无.html或.css单独文件 - 必须在
package.json中声明"type": "module"和"exports"字段，指向 ESM 入口 - CDN 地址应带版本号（如
/ds/v1.2.0/），避免缓存导致组件行为不一致
复杂点在于：HTML 模板里的内联样式、图片路径、字体引用，全得在构建时转为 base64 或相对 CDN 路径——这些细节漏一处，上线后就出现样式丢失或图标 404。
