组件文档必须提供可运行的最小代码片段，api 表格须严格按 name/type/default/description 四列组织：name 末尾加 ? 表示可选，type 写具体类型如 boolean 或 (value: string) => void，default 填真实值如 false 或 ["primary"]，表格用原生 ；每个示例含完整 html 结构、相对路径外链资源、明确加载说明，锚点 id 全小写无特殊字符，css 添加 scroll-margin-top 适配固定 header，禁用框架依赖，确保离线双击即运行。
直接说结论：组件文档不写成可运行的最小片段，就等于没写；API 表格不按 Name/Type/Default/Description 四列固化，用户根本没法快速查参数。
API 表格为什么必须用四列表格
新手常把 disabled、size、on-click 混在一段文字里描述，结果用户复制代码后报错——不知道 disabled 是布尔值还是字符串，也不知道 size 默认是 "md" 还是 null。
-
Name列末尾加?表示可选，如label?，别写“该参数可省略” -
Type必须写具体类型：string、boolean、(value: string) => void，禁用“字符串类型”“回调函数”这种模糊表述 -
Default写真实值：false、""、["primary"]，不写“无”“默认关闭” - 所有表格用原生
<table>，不套 UI 库——加载快、打印友好、离线可用 <h3>示例代码怎么嵌入才不白写</h3> <p>把 <code><c-button></c-button>往文档里一贴，用户双击打开index.html就报错：样式没加载、自定义元素没定义、customElements.define()没执行。- 每个示例区块必须是完整可运行片段：含
、<code>、（引入 CSS 和 JS）、和组件标签 - JS 示例第一行加注释
// 在组件定义之后执行，防止用户误以为这是初始化入口 - 所有路径用相对路径：
./dist/c-button.js，不用 CDN 或绝对 URL —— 离线查看时依然有效 - 禁用
style或script内联块，外链文件需注明用途，如“需提前加载c-button.css”
锚点跳转和本地预览怎么不出错
点击「API」跳到表格，结果页面卡在 header 下面；或者本地双击 HTML 文件，控制台报
Failed to load module script—— 这两个问题都源于细节失控。- 所有锚点 ID 全小写、无空格、无特殊字符，如
api-table、example-basic，确保唯一 - CSS 加一行
scroll-margin-top: 64px（数值匹配固定 header 高度），解决跳转后被遮挡 - 不依赖构建工具：手写 HTML + 原生 JS 即可完成折叠、标签页切换，用
localStorage记住展开状态 - 拒绝 React/Vue：文档不是应用，框架会引入跨域、模块解析、路由等无关错误，连本地双击都跑不起来
最容易被忽略的是：所有示例必须能在无服务器环境下运行。你写的不是 demo 页面，是别人复制粘贴就能验证行为的契约。路径写错一个点、漏引一个 CSS、ID 重复两次，用户信任就掉一块。
- 每个示例区块必须是完整可运行片段：含
前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
