组件文档不是组件截图加一段介绍，而是一份跨角色契约：它要让设计师知道什么时候使用，让研发知道结构和属性如何实现，让测试知道哪些状态必须覆盖，也让维护者知道谁能修改、如何升级。一份可执行的组件文档至少包含用途与边界、结构、属性、状态、设计变量、设计—代码映射、无障碍要求、负责人和变更记录。
本文聚焦“一个组件的说明页怎么写”。组件名称和层级语法可先查看组件命名规范；版本、废弃与迁移属于组件库治理，不在文档页里重复堆叠全部流程。
先明确组件文档要回答谁的问题
同一份文档会被不同角色以不同方式使用。产品经理判断组件能否承载业务任务；设计师选择正确变体并保持体验一致；研发确认接口、样式和依赖；测试覆盖状态、边界与异常；维护者判断修改会影响哪些产品。文档如果只服务于设计展示，交付时仍会回到口头确认。
- 选用问题：什么场景该用，什么场景不该用？
- 配置问题：有哪些属性、取值和组合限制？
- 行为问题：不同状态下如何反馈，键盘与焦点如何工作？
- 实现问题：设计对象对应哪个代码组件和参数？
- 维护问题：谁负责，当前状态是什么，升级后如何迁移？
组件文档的九个必备字段
推荐使用固定字段顺序，让读者不必每次重新寻找信息。最小模板包括：名称与摘要、用途、禁用场景、结构、属性、状态、变量、设计—代码映射、负责人和变更记录。无障碍要求可以放在行为规则中，也可以独立成章。
名称保持稳定，摘要用一句话说明组件解决什么任务。用途与禁用场景必须成对出现，例如“单选用于互斥选项，多个项目可同时选择时改用复选框”。只有“适用于表单”这类宽泛描述，无法帮助成员做选择。
结构章节要写角色，不只标尺寸
结构图应标出容器、标签、图标、辅助文字、错误提示等语义角色，并说明哪些区域必选、哪些可选。不要只列宽高和间距，因为尺寸会随文案、设备和主题变化；稳定的结构关系才是实现与测试的依据。
结构名称应与画布图层和代码槽位保持可追踪关系。比如设计中的 LeadingIcon 对应代码的 prefix 插槽，文档要记录这种映射，而不是要求两边强行使用完全相同的字符串。
属性章节要给默认值、限制和组合规则
属性表至少写属性名、用途、允许值、默认值、是否必选和限制条件。尺寸、用途、状态、图标开关等应分开，避免把所有组合做成独立组件。若两个属性不能同时出现，也要把冲突规则写出来。
| 属性 | 允许值 | 默认值 | 规则 |
|---|---|---|---|
| Type | Primary / Secondary / Text | Primary | 同一区域只保留一个主操作 |
| Size | Small / Medium / Large | Medium | 同一任务区不混用高度 |
| State | Default / Hover / Focus / Disabled / Loading | Default | Loading 时阻止重复提交 |
| Icon | None / Leading / Trailing | None | 图标不能代替不熟悉的文字 |
状态章节要描述触发、表现和恢复
状态不是一排效果图。每个状态需要说明由什么触发、用户看到什么、能否继续操作、如何离开。默认、悬停、聚焦、按下、禁用、加载、错误和成功并非每个组件都全部需要，应按交互责任选择；具体取舍可以用组件状态与变体清单逐项核对。
错误状态尤其要写清恢复路径。输入框变红只是表现，真正的规则还包括何时校验、错误文字放在哪里、修正后何时消失，以及屏幕阅读器如何获知错误。
设计—代码映射要成为文档主表
映射表至少关联设计组件、设计属性、代码组件、代码参数、设计变量、实现状态和负责人。它的作用不是追求命名完全一致，而是让一次变更能够定位影响范围。设计侧增加 State=Loading 时，团队能立即确认代码是否已有 loading 参数、测试是否覆盖重复点击。
颜色、字号和间距不要在组件页复制一套孤立数值。文档应引用稳定的语义变量或组件级变量；变量分层与主题切换可由Design Token 指南承接。
一段合格的按钮组件说明长什么样
Button / Primary：用于当前页面或任务区的唯一主操作。默认使用 Medium；提交需要等待结果时进入 Loading 并阻止重复点击；不可用时必须给出原因，不能仅降低透明度。不要在同一区域并列两个 Primary，也不要用它承载纯导航。
这段说明同时包含用途、边界、默认值、行为和反例，读者可以据此做选择。再配上结构图、属性表、状态演示和代码映射，就能形成可实现、可测试的组件条目。
在墨刀里把组件说明放进真实协作流程
团队可以在墨刀设计中整理主组件、变量和重复界面元素，再将用途、属性、状态和负责人写进组件说明或相邻规范页。先选按钮、输入框等高频组件建立模板，让设计和研发共同核对映射，再推广到复杂业务组件。
- 组件进入团队库前，文档至少完成用途、属性、状态和负责人四项。
- 设计评审检查选用与行为，研发评审检查参数、变量和实现边界。
- 交付链接指向固定版本，变更后同步更新示例与映射，不让说明脱离组件。
文档评审：用任务验证，不只检查格式
让一名未参与编写的设计师根据文档完成组件选用，让研发根据属性表解释接口，让测试列出状态用例。三方都能独立完成任务，说明文档具备可执行性；如果仍需作者口头补充，就把追问内容回写到字段或示例中。
- 设计任务：给出一个真实页面，判断该用哪个组件和变体。
- 研发任务：从映射表找到对象、参数、变量和不允许的组合。
- 测试任务：根据触发、表现与恢复条件生成状态用例。
- 维护任务：模拟一次属性废弃，确认负责人、替代项和迁移说明。
维护文档：跟随组件版本，而不是定期重写
文档应和组件变更处在同一评审入口。新增属性、改变默认值、调整状态或替换变量时，同步更新文档并留下变更原因；只改文字和示例可作为补丁，破坏兼容性的调整则要提供版本与迁移路径。没有负责人和发布日期的文档，很快会变成无法判断真假的历史说明。
可直接复制的组件文档模板
- 名称与一句话摘要：组件解决什么任务。
- 用途 / 禁用场景：什么时候用，什么时候换其他组件。
- 结构：必选与可选区域，以及语义角色。
- 属性：允许值、默认值、必选性和组合限制。
- 状态与行为：触发、表现、可操作性和恢复路径。
- 变量引用：颜色、字号、间距和主题来源。
- 设计—代码映射：对象、属性、参数与实现状态。
- 无障碍：键盘、焦点、标签、对比度和错误提示。
- 维护信息：负责人、版本、更新时间、替代项和变更记录。
组件文档发布前检查清单
- 用途和禁用场景是否能帮助成员做选择？
- 结构角色是否对应画布图层与代码槽位？
- 属性是否包含允许值、默认值和冲突规则？
- 状态是否写清触发、表现、操作和恢复？
- 设计对象、代码组件、变量和负责人是否可追踪？
- 示例是否使用真实内容，并包含至少一个反例？
- 变更是否与组件版本同步，并提供迁移说明？
常见问题
每个组件都要写同样长的文档吗？
不需要。简单分隔线可以只写用途、结构和变量；输入框、日期选择、上传等交互复杂组件需要完整属性、状态、验证、无障碍和代码映射。字段顺序保持一致，深度按风险增加。
组件文档由设计还是研发维护？
设计负责人维护用途、结构与体验规则，研发负责人维护代码映射和实现状态，测试补充验收条件。仍需指定一位最终维护人，避免共同负责变成无人更新。
文档和组件不一致时以哪个为准？
应立即停止继续复制，并由维护人确认当前有效版本。短期记录差异和影响范围，长期把文档更新纳入组件变更检查，避免再次出现两个事实来源。
总结
组件文档的价值不在于字段齐全，而在于不同角色能据此完成选用、实现、测试和维护。用固定模板写清用途边界、结构、属性、状态、变量、设计—代码映射和责任人，再用真实任务评审一次，组件说明才会从展示页变成团队共同执行的契约。
信息核验日期：2026-09-28。墨刀产品能力依据当前官方墨刀设计页面核验；具体入口和界面以实际账号版本为准。
