设计系统中纯HTML组件规范与交付流程实战-html教程-PHP中文网

纯html组件不能直接用import引入，因为浏览器原生es模块系统仅支持js、ts、json等可执行模块，html文件无导出接口且不被解析为模块；必须封装为自定义元素（custom element）并通过customelements.define()注册，才能实现跨框架复用、shadow dom隔离与生命周期控制。

设计系统中纯html组件规范与交付流程实战

纯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、邮件模板、微前端子应用的静态环境。

必须用 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 的按钮，在无障碍测试中就是失败项。

anything-to-html

将调研报告、方案对比、数据分析、需求梳理、会议纪要、设计说明、代码评审、学习笔记等任务产物输出为可在浏览器直接打开的单文件 HTML，替代 Markdown 作为最终交付物。Markdown 在信息密度、视觉清晰度和可分享性上已跟不上 AI 产物的丰富度，HTML 能同时承载排版、表格、SVG 等。

下载

容易踩的坑：用 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()。