直接复制粘贴HTML文件会导致样式失控，因缺乏统一控制机制，无法同步设计变更、易引发CSS污染、主题失效及维护断层；应改用构建时预处理或Web Components等可注入、可继承、可隔离的方案实现真正响应式统一。
为什么直接复用 HTML 文件会导致样式失控
统一设计系统下，把 header.html 复制到每个页面目录里，看似省事，实则埋雷。一旦设计规范更新（比如导航栏高度从 64px 改为 72px），你得手动改几十个文件，漏一个就出现视觉断层。
更麻烦的是：不同页面可能引入了不同版本的 CSS 变量、字体加载策略或 JS 初始化逻辑，data-theme="dark" 在 A 页面生效，在 B 页面却没触发 —— 因为 B 页面的 initTheme() 函数压根没执行。
- 硬编码内容（如
<h1>关于我们</h1>）无法被设计系统动态接管 - 内联样式或
style属性会覆盖 CSS 自定义属性，导致主题切换失效 - 没有 Shadow DOM 隔离时，第三方组件的 CSS 可能意外污染全局
.button类
如何让 HTML 模板真正“响应”设计系统变更
关键不是“写死结构”，而是“声明意图”。HTML 模板只保留语义骨架和可插拔的钩子，所有样式、行为、文案都由设计系统运行时注入。
例如页脚版权年份，不写死 <p>© 2025 公司名称</p>
<p><span>立即学习</span>“<a href="https://pan.quark.cn/s/cb6835dc7db1" style="text-decoration: underline !important; color: blue; font-weight: bolder;" rel="nofollow" target="_blank">前端免费学习笔记（深入）</a>”；</p>，而用：
<footer data-component="ds-footer"> <p data-bind="copyright"></p> </footer>
再配合设计系统提供的 renderDSComponent() 函数自动填充当前年份（截至 2026 年 5 月 1 日）和品牌名。
把任意文章或文档内容转换成精美的全屏翻页 HTML 演示文件（幻灯片风格）。当用户发来一篇文章、文档链接、Markdown 内容、或粘贴的文本，并且希望生成演示用的 HTML 时触发。支持任意内容来源：iWiki 链接、KM 链接、本地文件路径、直接粘贴的文本。生成的 HTML 文件保存到本地工作区，并通过企微直接发送给用户。触发词示例：帮我把这篇文章做成PPT、转成演示文档、生成HTML幻灯片、做个演示、转成可以演示的格式、article to deck、make a slide。
- 所有可配置项必须通过
data-属性暴露，如data-variant="compact"、data-icon="mail" - 禁止在模板中写具体颜色值（如
#3b82f6），只允许使用 CSS 自定义属性（var(--color-primary)） - 图标、SVG 图形必须抽象为
<ds-icon name="search"></ds-icon>这类自定义元素，由 Web Components 统一渲染
构建时预处理 vs 运行时 JS 注入，怎么选
答案取决于你的部署链路是否可控。如果你用 Vite 或 Hugo，无条件选构建时预处理；如果必须支持纯静态托管（如 GitHub Pages + CDN），才退回到 JS 注入方案。
Vite 用户用 vite-plugin-html 插件，在 index.html 里写：
<!-- @include ./design-system/components/header.html -->
Webpack 用户配合 html-loader 和 html-webpack-plugin，通过 require('./ds/footer.html') 导入。
- 构建时方案：输出即完整 HTML，SEO 友好，无 FOUC（闪白），CDN 缓存命中率高
- JS 注入方案：必须等
DOMContentLoaded后才能操作template.content，且得用document.importNode()，否则表单控件状态丢失 - 千万别用 SSI（
<!--#include file="header.html" -->）——本地开发无法预览，也无法传参
最容易被忽略的兼容性陷阱
设计系统不是“加一套 CSS 就完事”。很多团队卡在细节上：CSS 自定义属性未降级、Web Components 在旧版 Safari 不可用、JSON 配置字段名大小写混用导致解析失败。
比如你在设计系统里定义了 --ds-spacing-xs: 0.25rem，但忘了在 :root 下 fallback 到 0.25rem，IE11 和 iOS 13.3 以下就直接失效。
- 所有 CSS 自定义属性必须带降级值：
padding: 0.25rem; padding: var(--ds-spacing-xs, 0.25rem); - Web Components 必须注册前检查
'customElements' in window，不支持时回退到普通div+ class 方案 - JSON 配置字段统一用小写下划线（
primary_color），避免 JS 中primaryColor和后端返回的primary-color对不上
真正难的不是把页头塞进每个页面，而是当设计改了字体大小、导航加了新菜单项、页脚要动态显示版权年——这些变化能否在 5 分钟内全站同步生效，且不引发任何回归问题。
