AI 生成设计规范文档：别让组件说明停在截图旁边

AI 生成设计规范文档：别让组件说明停在截图旁边

很多组件库的问题不是没有组件，而是没有清楚的使用规范。设计稿里有截图，代码里有 props，但什么时候用 primary，什么时候用 secondary，错误态怎么写文案，空态是否需要动作，这些往往靠口头传递。AI 可以帮助生成规范文档，但前提是输入足够结构化。

组件规范不是截图旁边的说明文字，而是设计、前端、测试都能使用的契约。

一、规范文档要覆盖四类信息

flowchart TD A[Component Spec] --> B[Usage] A --> C[API] A --> D[States] A --> E[Accessibility] B --> F[Docs] C --> F D --> F E --> F

只写视觉样式不够。组件文档至少要说明使用场景、接口参数、状态组合和无障碍要求。

二、输入要来自真实组件定义

AI 生成文档时，最好从组件类型、props、Token 和示例中抽取信息，而不是让模型凭空写。

type ButtonProps = { variant?: 'primary' | 'secondary' | 'ghost' | 'danger'; size?: 'sm' | 'md' | 'lg'; loading?: boolean; disabled?: boolean; children: React.ReactNode; };

模型可以基于类型生成参数说明、组合示例和注意事项。这样文档更贴近代码，不容易漂。

三、使用建议要写边界

规范文档的价值在于告诉使用者“什么时候不要用”。比如 danger 按钮不能用于普通取消，loading 状态不能替代禁用态，ghost 按钮不适合主操作。

usage_rules: primary: use: "single main action in a section" avoid: "multiple primary buttons in the same toolbar" danger: use: "destructive irreversible action" require_confirm: true

AI 生成文档时，要强制输出 avoid 和 edge cases。只有正向描述，规范会变成宣传页。

四、文档要可测试

如果文档写“按钮必须有可访问名称”，测试就应该能验证。

expect(screen.getByRole('button', { name: /save/i })).toBeVisible();

文档、测试和代码互相对应，组件库才不会越用越散。AI 生成的文档也要进入 review，不应直接发布。

文档还要包含反例。比如两个 primary 按钮并排、危险操作没有确认、图标按钮没有 aria-label，这些都是组件误用的高频场景。

### Avoid - Do not place two primary buttons in one dialog footer. - Do not use danger style for normal cancel actions. - Do not use icon-only buttons without accessible labels.

反例能让规范从“建议”变成边界。AI 生成文档时，可以要求它基于组件风险输出常见误用清单。

五、总结

AI 可以提高设计规范文档生成效率，但输入要来自真实组件定义、Token 和使用规则。文档要覆盖使用场景、API、状态、无障碍和边界条件。

组件说明不能停在截图旁边。能指导选择、实现和测试的文档，才是设计系统真正的资产。

好的文档应该让新人少问一次“这里该用哪个组件”，也让评审少争一次“这个状态算不算合理”。这才是自动化生成文档真正节省的成本。