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、状态、无障碍和边界条件。
组件说明不能停在截图旁边。能指导选择、实现和测试的文档，才是设计系统真正的资产。
好的文档应该让新人少问一次“这里该用哪个组件”，也让评审少争一次“这个状态算不算合理”。这才是自动化生成文档真正节省的成本。
