设计工作
用 AI 写设计系统文档
用 AI 写设计系统文档指南覆盖组件用途、禁止场景、变体、状态、内容、无障碍、代码映射、版本与迁移，让文档成为设计和开发共同事实源。
用 AI 写设计系统文档，适合从组件代码、设计库、测试和使用实例中整理结构、检查不一致与生成示例草案。文档不能只展示漂亮截图；必须说明何时使用、何时不用、行为、状态、内容、无障碍和迁移规则。
| 项目 | 说明 |
|---|---|
| 阅读时间 | 约 8 分钟 |
| 适合人群 | 设计系统团队、产品设计师、前端开发者、内容设计师、测试和技术写作者 |
| 核心产出 | 组件目的、API 与设计属性映射、状态、内容规则、无障碍、示例和版本记录 |
| 使用前提 | 有可定位的设计与代码源、负责人、版本和真实消费者 |
| 不适合 | 让 AI 根据组件名补写能力，或让文档与生产实现长期分离 |
设计文件说明视觉意图，代码说明真实 API 和语义，页面实例说明实际内容与组合。三者冲突时，AI 只能报告差异，不能擅自选择真相。公共组件变更要经过评审、版本与迁移流程。
| 文档章节 | 必须回答 | 常见遗漏 |
|---|---|---|
| 目的 | 组件解决什么任务 | 只有组件名称 |
| 使用边界 | 何时用、何时不用 | 缺少替代组件 |
| 属性与状态 | 变体、默认值、组合限制 | 只列默认截图 |
| 内容 | 标签、长度、术语和错误 | 用 Lorem ipsum 演示 |
| 无障碍 | 语义、键盘、焦点和状态通知 | 只写“符合标准” |
| 版本 | 变更、弃用与迁移 | 直接删除旧用法 |
七步文档流程
Section titled “七步文档流程”- 确认事实源：记录设计节点、代码包、故事或测试、版本和负责人。
- 写任务与边界：说明组件的用户目的、适用场景、替代方案和禁止组合。
- 映射设计与代码：把变体、属性、插槽、事件和令牌对应起来，冲突单独列出。
- 覆盖完整状态：默认、交互、加载、错误、禁用、空内容、长文本和响应式行为。
- 补内容与无障碍：提供真实长度示例、语义、键盘、焦点和动态通知要求。
- 用可运行示例验证：让示例来自当前实现，避免手写片段随版本漂移。
- 建立版本治理：定义提案、评审、发布、弃用、迁移和反馈入口。
假设示例：InlineAlert 组件文档
Section titled “假设示例：InlineAlert 组件文档”以下组件与 API 为教学假设，不代表当前仓库或 OfApp.cn 已公开能力。
用途：在页面上下文中说明需要注意、失败或成功的信息。代码属性：tone=info|warning|critical|success；title 可选；action 最多一个。已知规则：critical 不等于系统错误；关闭能力尚未实现。设计库：有图标与背景变体，但缺少长文本和读屏说明。| 文档项 | 草案 |
|---|---|
| 何时使用 | 信息与当前页面任务相关，用户需要理解或采取一个明确动作时 |
| 何时不用 | 全局临时反馈用状态通知；阻断流程的决定用对话框；字段错误放在字段附近 |
| 内容 | 标题说明问题或状态，正文说明影响和下一步；一个动作使用结果明确的动词 |
| tone | 按信息含义选择，不因想要更醒目而使用 critical |
| 状态 | 需验证长文本、无标题、带动作、窄容器与重复提示组合 |
| 无障碍 | 语义和播报策略取决于动态出现方式；不能只靠颜色和图标传达 tone |
| 未决项 | 关闭能力、焦点策略、动态播报级别由设计与前端确认 |
合适：无法保存草稿。请检查网络后重试。 [重新保存]不合适：出错了！ [确定]
原因：合适示例说明对象、影响和下一步；反例没有可执行信息。决策与复核表
Section titled “决策与复核表”| 检查项 | 复核问题 | 合格信号 |
|---|---|---|
| 真源 | 文档与哪个版本对应？ | 设计、代码和示例可定位 |
| 边界 | 何时不使用组件？ | 有替代模式和反例 |
| 状态 | 是否覆盖真实内容与组合？ | 不只展示理想变体 |
| 无障碍 | 要求能否由实现和测试验证？ | 不使用空泛合规声明 |
| 版本 | 变更怎样通知和迁移？ | 有弃用期与消费者清单 |
- 从组件名和截图推断功能，写出代码中不存在的属性。
- 示例全部使用短占位文本，没有错误、翻译和窄屏情况。
- 设计与代码各写一份文档，冲突无人负责。
- 用“请合理使用”代替明确边界与反例。
- 公共属性改变后只更新文档，没有迁移与回归计划。
AI 能从代码自动生成设计系统文档吗？
Section titled “AI 能从代码自动生成设计系统文档吗？”可以提取 API 和示例候选，但代码不包含全部设计意图、使用边界和内容规则，需要跨角色补充并验证。
文档应该放在设计工具还是代码站？
Section titled “文档应该放在设计工具还是代码站？”可以有多个入口，但应共享版本和事实源，避免设计与开发各维护相互冲突的说明。
每个组件都需要长文档吗？
Section titled “每个组件都需要长文档吗？”按复杂度决定。至少说明目的、边界、状态、内容、无障碍和代码对应；简单组件可以保持精炼。
怎样防止文档过期？
Section titled “怎样防止文档过期？”把文档更新纳入组件变更流程，使用可运行示例与版本检查，并明确负责人和弃用机制。
设计系统文档应成为可验证的共同事实源。AI 能加速提取和整理，组件边界、语义、版本与迁移仍需设计和工程共同负责。