组件文档页面不应使用React/Vue框架，因其本地双击打开会因跨域、模块加载失败等问题报错；本质是静态说明材料，应手写HTML+原生JS实现折叠、标签切换与状态持久化，并确保示例完整可运行。
为什么不能用 React/Vue 渲染组件文档页面
本地双击打开 index.html 就报跨域或模块错误，是框架引入的第一道坎。文档本质是静态说明材料，不是交互应用——你只需要让人看清 props 怎么传、slots 往哪插、events 何时触发。加一层框架，反而要配构建、处理路由、模拟状态，连最基础的复制粘贴示例都可能跑不起来。
真实踩坑点：document.querySelector('my-button') 在未注册自定义元素时返回 null；React 的 useEffect 在纯 HTML 环境里根本不存在；VitePress 默认注入的全局 CSS 可能覆盖你组件的真实样式。
- 手写 HTML + 原生 JS 足够：折叠代码块用
details/summary，切换标签页用dataset+addEventListener - 状态持久化只用
localStorage记住展开项，不用 Redux 或 Pinia - 所有示例区块必须带完整结构：含
<!DOCTYPE html>、<html lang="zh-CN">、必要<link rel="stylesheet">和最小初始化脚本
API 表格怎么避免“看着全、用不对”
新手常把 size 的 Type 写成 “大小”，Default 写成 “默认中等”，结果用户传 "medium" 报错才发现其实是 number 类型。表格不是装饰，是契约。
-
Type列必须写运行时可验证类型：string、boolean、string | number，禁用 “字符串”“布尔值” 等中文描述 -
Name列末尾加?表示可选，如disabled?，别靠文字说明“非必填” -
Default列写具体值：false、''、null，不写 “无” 或 “空” - 每行只描述一个 API 成员，
v-model和modelValue不合并在一行
示例代码怎么嵌入才不误导用户
直接贴 <my-input v-model="value"></my-input> 是危险的——没引入组件、没注册、没样式、没 value 初始化，用户复制后白屏还找不到原因。
立即学习“前端免费学习笔记（深入）”；
- 每个示例用
<pre><code class="html">包裹，且必须包含完整可运行结构 - HTML 示例第一行是
<!DOCTYPE html>，结尾有<script>const value = '';</script>这类最小初始化 - JS 示例第一行加注释
// 在组件定义之后执行，防止用户误以为这是入口逻辑 - 路径全部用相对路径：
./dist/my-component.js，不写https://unpkg.com/...（CDN 地址随时失效）
锚点跳转和固定 header 怎么不偏移
点击 #props 后标题被吸顶导航栏盖住，是文档页最常见却最容易被忽略的体验断点。这不是 CSS 小问题，而是语义和布局协同失效的表现。
- ID 必须全小写、无特殊字符、全局唯一：
props可以，Props-API不行 - 用
scroll-margin-top而不是 JS 修正滚动位置：h3[id] { scroll-margin-top: 80px; } - 固定 header 高度必须与
scroll-margin-top严格一致，差 1px 都会偏移 - 不要依赖
document.getElementById().scrollIntoView()手动滚动——它绕过 CSS 滚动行为，破坏原生平滑和可访问性
