组件文档页面应手写HTML+原生JS，禁用框架；API表格须用语义化table固定四列；示例代码需最小可运行HTML片段；模板须纯结构、语义清晰、路径可配置。
组件文档页面该不该用模板引擎
手写 HTML + 原生 JS 就够了，别上 React/Vue 或 art-template。你只是展示 API 和用法，不是跑应用——框架会引入构建依赖、跨域限制、模块解析失败，连双击打开 index.html 都可能白屏。本地可运行、零构建、无运行时依赖，才是文档页的底线。
API 表格怎么用 HTML 原生结构写清楚
表格必须固定四列：Name、Type、Default、Description。别用 div 模拟表格，语义丢失、屏幕阅读器读不出结构、复制粘贴错行。
-
Type写string、boolean | undefined，不写“字符串类型”或“可为空” -
Name末尾加?表示可选，如size?，别靠文字说明 -
Default填具体值：false、''、null，不填“无”或“默认关闭” - ID 必须全小写、无空格和特殊字符，否则锚点跳转失效；配合
scroll-margin-top适配固定 header
示例代码区块怎么嵌入才真正可用
每个示例必须是「最小可运行片段」：含 <!DOCTYPE html>、<html lang="zh-CN">、必要 <meta charset="UTF-8">、引入样式与脚本的相对路径，以及组件标签本身。
- HTML 示例用
<pre><code class="html">包裹，JS 示例第一行加// 在组件定义之后执行，避免用户误当入口 - 绝对不用
document.write()或同步fetch加载 demo，阻塞渲染且无法离线查看 - 图片、图标等资源用相对路径，不写死
https://cdn.example.com/，否则本地双击就 404
模板复用时最容易被忽略的语义断层
把 <div class="button"> 抽成模板没问题，但若它内部硬编码了 <svg> 或内联 style，就丧失复用前提——模板必须是纯结构钩子，样式和行为由外部控制。
立即学习“前端免费学习笔记（深入）”；
- 所有模板应以语义化标签为边界：
<button>模板里不能塞<h3>，标题属于父级上下文 - 混内联 JS 的片段（如
onclick="doSomething()"）必须先剥离逻辑，改用事件委托或data-*属性驱动 - 硬编码路径（如
src="assets/logo.png"）要替换为占位符或通过 JS 注入，否则换项目就挂
真正难的不是拆模板，而是让每个模板在脱离上下文时仍保有明确职责——它得知道自己是按钮、是表单域、还是错误提示，而不是一堆 class 堆出来的 div。
