文章目录 / 点击展开
设计系统文档不是组件截图合集，而是设计、开发和内容团队共同使用的契约。AI 可以把分散信息整理成统一结构、发现缺失状态和生成初稿，但组件真实行为必须以已发布设计与代码为准。
先确定唯一事实来源
团队需要明确颜色、间距和字体以设计变量还是代码 token 为准，组件行为以设计稿还是线上实现为准，文案规则由谁维护。若多个来源互相冲突，AI 只能展示差异，不能自行选一个作为正确答案。
建立组件清单时记录设计链接、代码路径、负责人、当前版本和使用状态。废弃组件也要标记迁移目标与截止时间，避免旧页面继续复制。
第一步：定义文档模板
每个组件使用同一结构：用途、不适用场景、组成、属性、尺寸、状态、交互、内容规则、无障碍、代码映射、示例和变更记录。固定模板有助于发现空白，也方便团队搜索。
根据以下设计说明和组件接口整理文档草稿。
只使用提供的事实；无法确认的属性标记“待确认”。
按用途、组成、属性、状态、交互、内容、无障碍、代码映射和测试清单输出。不要把 AI 生成的属性名直接写入正式规范，先与组件 API 和设计变量核对。
第二步：补齐状态和边界
按钮不仅有默认和悬停，还可能有聚焦、按下、禁用、加载和错误；输入框需要空值、已填、聚焦、校验失败、只读和禁用；数据组件还要考虑空数据、加载、部分失败和超长内容。
让 AI 对照模板列出缺失状态，再由设计师和开发确认是否真实支持。重点检查键盘操作、焦点顺序、文本缩放、颜色对比和屏幕阅读器名称，不能只评审视觉截图。
第三步：记录内容与本地化规则
组件文案需要说明语气、长度、标点和动态变量。例如按钮使用动作词，错误消息说明发生了什么和如何恢复，空状态提供下一步。为中文、英文和长文本保留可测试示例。
AI 可批量检查同类文案是否一致，但不得自动改动法律、支付、安全和隐私相关文本。高风险文案需要业务与合规负责人确认。
第四步：建立设计到代码映射
文档中同时列出设计组件名称、变体属性、代码组件名称、参数和示例。颜色、间距和字号尽量引用 token，而不是复制具体值。若设计和代码存在差异，记录差异、影响页面和修复计划。
新页面设计前可参考 Figma + AI 线框到高保真流程，但交付时必须回到已批准的组件和 token。
第五步：用真实场景编写示例
示例应覆盖推荐用法、错误用法、边界内容和组合场景。不要只使用“标题”“示例文本”等占位符，因为真实文案长度、权限和错误状态往往会暴露问题。
为高频组合建立页面模式，例如筛选列表、设置表单和确认流程。模式说明组件顺序、响应式变化、加载与失败处理，但不把临时页面布局过早固化为系统规则。
第六步：发布、变更与废弃
每次发布记录新增、修改、修复、破坏性变化和迁移方式。重大变化需要版本号、负责人和影响范围。文档更新应与代码和设计发布同步，而不是上线数周后补写。
定期统计组件使用量、重复组件、过期页面和常见问题。AI 可以整理变更摘要和影响清单，但实际引用关系应由代码搜索、设计库分析和页面检查验证。
文档验收清单
- 是否明确设计变量、代码和文档的事实来源。
- 是否说明组件用途与不适用场景。
- 是否覆盖加载、错误、空状态和超长内容。
- 是否包含键盘、焦点、对比度和可访问名称要求。
- 设计属性是否能映射到代码参数和 token。
- 示例是否使用真实内容和边界场景。
- 变更是否包含影响范围和迁移方法。
常见问题
可以让 AI 从截图直接生成设计规范吗
只能作为初步观察。截图无法说明交互、语义、代码接口和全部状态，不能成为唯一事实来源。
文档应该由设计师还是开发维护
最好共同负责：设计维护视觉与使用原则，开发维护接口和运行行为，内容或无障碍负责人补充相应规则。
组件很多时从哪里开始
先处理使用最广、问题最多的基础组件和表单组件，再整理页面模式。不要一开始追求一次性覆盖全部历史组件。
正式发布前，可用 AI 辅助界面评审清单 检查可读性、响应式和无障碍状态。