AI 辅助设计系统文档自动生成组件说明不能只靠人工补一、组件库最容易欠文档债组件库刚开始时大家都愿意写文档按钮怎么用、表单怎么校验、主题怎么配置。等业务需求一多文档就开始落后。Props 变了没人更新示例代码跑不通设计说明停留在旧版本。最后组件库明明还在更新使用者却不敢用因为不知道哪个说明是真的。AI 可以帮助生成和维护组件文档但它不能替代真实源码。更好的方式是从 TypeScript 类型、Storybook 示例、设计 Token 和变更记录中抽取事实再让 AI 生成更自然的说明。文档自动化的核心是事实来源可信。二、生成链路源码事实先行AI 负责表达flowchart TD A[组件源码] -- B[Props 类型抽取] C[Story 示例] -- D[使用场景抽取] E[设计 Token] -- F[视觉规则] B -- G[文档生成上下文] D -- G F -- G G -- H[AI 生成说明] H -- I[人工审核发布]文档生成要区分事实和解释。事实包括 Props 名称、类型、默认值、事件回调、可访问属性和示例代码。解释包括使用建议、常见错误、设计原则和迁移提示。AI 可以写解释但事实必须从代码或配置中来。否则它可能编出不存在的参数。Storybook 是很好的文档来源。每个 story 代表一个使用场景默认态、加载态、禁用态、错误态、复杂组合。AI 可以根据 story 名称和代码生成说明帮助使用者理解什么时候用哪种状态。前提是 story 本身要维护好。在实践层面我们遇到过这样的坑一个 Button 组件新增了varianttertiary类型但没有人更新文档。一周后设计团队在 Figma 里看到了这个变体以为它是正式规范于是所有新页面都开始用。但开发者并不知道tertiary的 hover 色和 focus 环还没有完整实现。最后导致一批页面的交互状态不一致。这件事让我们痛下决心做文档自动化。具体做法是先写一个脚本通过 TypeScript 编译器 API 提取组件 Propsimport ts from typescript; function extractProps(filePath: string): PropMeta[] { const program ts.createProgram([filePath], {}); const source program.getSourceFile(filePath)!; const props: PropMeta[] []; function visit(node: ts.Node) { if (ts.isInterfaceDeclaration(node) node.name.text.endsWith(Props)) { for (const member of node.members) { if (ts.isPropertySignature(member)) { props.push({ name: member.name.getText(), type: member.type?.getText() ?? unknown, optional: !!member.questionToken, }); } } } ts.forEachChild(node, visit); } visit(source); return props; }这段脚本从组件的 Props 接口中提取字段名、类型和是否可选生成结构化的元数据。AI 拿到这份元数据后生成的文档就不会出现不存在的参数名。Storybook 的示例提取也可以用类似的思路。读取每个 story 文件解析 exported 的 story 对象名和对应的组件用法。比如export const Loading () Button loading保存/Button可以被解析为loading 状态下的按钮示例。AI 拿到 story 名称和源码片段后可以生成一段自然语言说明当 loading 为 true 时按钮显示加载动画且不可点击常用于表单提交等待状态。三、元数据示例给文档生成器稳定输入下面是一份简化的组件元数据可以由脚本从源码抽取也可以先人工维护。{ name: PrimaryButton, props: [ { name: loading, type: boolean, default: false }, { name: disabled, type: boolean, default: false }, { name: onClick, type: () void, required: false } ], stories: [default, loading, danger], accessibility: [button has accessible name, focus visible] }有了结构化元数据AI 生成文档时可以被约束。Prompt 中明确要求不得新增元数据中不存在的 Props能减少幻觉。生成后再跑一次校验检查文档里的参数名是否都存在于源码类型中。我们实际使用的校验脚本大约二十行核心逻辑是把文档中出现的 Props 名称和元数据对比function validateDocProps(docContent: string, meta: PropMeta[]): string[] { const validNames new Set(meta.map(p p.name)); const docPropPattern /\*\*(\\w)\*\*/g; const issues: string[] []; let match: RegExpExecArray | null; while ((match docPropPattern.exec(docContent)) ! null) { if (!validNames.has(match[1])) { issues.push(文档引用了不存在的 prop: ${match[1]}); } } return issues; }这个检查可以放到 CI 中文档生成后自动运行。如果发现不存在的参数直接阻断合并。比起事后人工审核自动化校验可靠得多。示例代码也要可运行。文档最怕复制出来报错。可以把示例作为测试的一部分至少通过 TypeScript 检查。AI 生成的示例如果没有被编译验证只能算草稿。四、发布流程文档变更也要走 Review自动生成不等于自动发布。组件文档影响开发者体验也可能传递错误用法。建议在组件 PR 中同时生成文档 diff由组件维护者 review。文档变化太大时要确认是源码真的变了还是生成提示词漂了。还要保留人工编辑区域。比如设计理念、最佳实践和迁移说明可能需要维护者写得更有上下文。自动生成区域和人工区域可以分开避免每次生成覆盖人工心血。工具要帮人省事不是抢编辑权。我们的做法是在文档模板中用注释标记自动生成区和人工编辑区!-- AUTO_GENERATED_START -- ## Props | 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | loading | boolean | false | 是否显示加载状态 | | disabled | boolean | false | 是否禁用按钮 | !-- AUTO_GENERATED_END -- !-- MANUAL_EDIT_START -- ## 使用建议 PrimaryButton 是产品中最常用的按钮变体。每个页面最多应出现一个 PrimaryButton... !-- MANUAL_EDIT_END --自动生成脚本只更新AUTO_GENERATED区域的内容手工编写的部分完全不受影响。这解决了怕生成器覆盖人工心血的核心顾虑。最后文档质量可以监控。统计文档缺失组件、示例编译失败、Props 说明为空、用户搜索无结果等指标。组件库文档不是装饰它决定团队能不能放心复用。五、总结设计系统文档自动生成要以源码、类型、Story 和 Token 为事实来源AI 负责组织语言和补充解释。结构化元数据、幻觉校验、示例编译和人工 Review能让文档自动化真正减轻维护负担而不是制造新的不可信内容。