好的设计系统文档不是“组件长什么样”的图库，而是一套帮助设计师和开发者在没有核心团队陪同的情况下仍能做对决策的产品。本文拆解组件文档应包含的内容、设计与代码如何对齐，以及怎样避免文档上线后迅速过期。
很多团队说自己“已经有设计系统文档”，打开以后却只有组件截图、尺寸标注和一个 Figma 链接。设计师仍然会问：这个场景到底该用 Modal 还是 Drawer？开发仍然会问：这个状态有没有对应 API？产品经理仍然会问：为什么不能加一个新样式？如果文档不能减少这些重复沟通，它就只是展示页面，而不是系统的一部分。
01 一、设计系统文档的目标不是记录，而是支持决策
Atlassian 把文档、支持、工具和维护视为设计系统体验的一部分；Carbon 的组件页面则会同时提供使用、样式、代码和无障碍信息。共同点很明确：文档应该帮助不同角色完成工作，而不是只让维护者“把规范存下来”。因此文档最重要的衡量标准不是页数，而是使用者能否在没有人工解释的情况下回答“该不该用、怎么用、出了问题怎么办”。
02 二、一篇组件文档最少应该回答 10 个问题
- 它解决什么用户问题？先写用途，不要先写尺寸。
- 什么时候使用？给出最典型的场景。
- 什么时候不要使用？说明容易混淆的替代组件。
- 组件由哪些区域构成？明确 anatomy 和可选区域。
- 有哪些状态与变体？默认、Hover、Focus、Disabled、Loading、Error 等不能只藏在 Figma 里。
- 内容怎么写？按钮文案、标题长度、空状态、错误信息都属于组件行为的一部分。
- 响应式怎么变化？不能只展示 1440px 的理想状态。
- 无障碍要求是什么？键盘、焦点、语义、对比度、可访问名称等要具体。
- 开发如何使用？包名、API、示例、依赖和限制要可查。
- 当前版本和维护状态是什么？使用者必须知道它是 Stable、Beta 还是 Deprecated。
03 三、“When to use / When not to use”比视觉规格更重要
组件系统最常见的问题不是按钮颜色错了，而是选错了组件。例如同样用于展示额外信息，Tooltip、Toggletip、Popover、Modal 的交互成本完全不同。如果文档只写“Tooltip 的 padding 是多少”，设计师仍然可能把需要交互的复杂内容塞进 Tooltip。
因此每篇组件文档都应该主动写边界，并列出“如果你的需求是 X，请改用 Y”。这实际上是在把资深设计师的判断经验产品化。
04 四、设计文档和代码文档不能是两个世界
成熟的系统通常同时存在 Figma 和代码实现，但两套资产必须共享名称、变体和状态。设计稿里叫“Primary / Medium”，代码里却叫“appearance=brand / size=default”，长期一定会产生翻译成本。文档应该建立一张清晰映射：Figma 属性对应哪个代码 prop，设计 Token 对应哪个变量，哪些变体只存在于特定平台。
DTCG 在 2025.10 发布了第一版稳定的 Design Tokens 格式，目标正是提高不同工具和平台之间的互操作性。它并不会自动解决团队文档问题，但提醒了一个重要方向：设计系统信息应该尽可能成为结构化、可转换的数据，而不是散落在截图里。
05 五、无障碍文档不能只写一句“符合 WCAG”
“Accessible”不是一个标签。文档应该告诉使用者具体责任：组件本身已经处理了什么，业务使用者还必须提供什么。例如图标按钮组件可能已经处理 Focus 样式，但业务方仍需要提供可理解的 accessible name；表单组件提供错误样式，但页面仍需要给出与字段相关联的错误说明。
把责任边界写清楚非常重要，否则团队会误以为“用了系统组件就自动无障碍”。
06 六、示例要覆盖真实边界，而不是只展示最漂亮的 Happy Path
文档示例应该至少包含正常状态、内容很长、数据为空、错误、权限不足、Loading 和移动端等关键场景。对于国际化产品，还应测试更长的语言、RTL 或中英文混排。一个只用“John Smith”和短英文演示的组件，很容易在真实产品里崩掉。
07 七、文档结构建议：先帮助选择，再帮助实现
一篇组件页可以按这个顺序组织：Overview → When to use → When not to use → Anatomy → Behavior → Variants & states → Content → Accessibility → Responsive → Design → Code → Tokens → Changelog → Support。这个顺序符合使用者实际任务：先判断选不选，再理解行为，最后才进入具体实现。
08 八、不要把所有知识都塞进组件页
组件文档之外，还需要基础层和模式层。颜色、字体、间距、图标属于 Foundations；搜索、筛选、权限、Onboarding、表单流程属于 Patterns；组件页则聚焦单个可复用构件。否则“表格筛选怎么做”会被散落在 Button、Select、Data Table 三个组件页面里，没人知道该去哪找。
09 九、文档必须和发布流程绑定
最可靠的方法不是提醒大家“记得更新文档”，而是把文档纳入 Definition of Done：没有使用说明、无障碍说明和版本记录的组件不能进入 Stable；API 发生变化必须同步更新示例；组件弃用时文档顶部立即显示替代方案和迁移链接。Carbon 的贡献清单把网站文档、Storybook 和可访问性信息作为组件质量的一部分，这类机制比人工提醒有效得多。
10 十、如何判断你的文档是否真的有用？
观察使用者行为。哪些搜索没有结果？哪些组件页面打开后仍然大量提问？新人最常问哪些问题？哪些组件使用错误率最高？把这些问题反向补进文档。最好的设计系统文档不是一次性写出来的，而是在真实支持工作中不断发现缺口。
当文档成熟以后，核心团队的价值不会消失，而是从“每天解释同样的问题”转向处理真正复杂的新问题。这才是文档应该带来的杠杆。
常见问题
设计系统文档应该放在 Figma 还是独立网站？
Figma 适合贴近设计资产的说明，但独立文档站更适合跨设计、开发和内容角色协作。规模较小的团队可以先从统一入口开始，关键是不要让信息分散且互相冲突。
组件文档要不要写所有尺寸数值？
可以写关键规格，但更推荐通过 Token、Figma 属性和代码变量表达。文档的重点应放在使用规则和行为，而不是把 Inspect 面板能看到的数据重复一遍。
设计师和开发者应该共用一篇组件文档吗？
建议共用同一事实源，再为不同角色提供对应区域。完全拆成两套文档很容易出现名称、状态和版本不同步。
文档多久更新一次？
不应按固定周期集中更新，而应与组件发布同步。每次变更都应更新对应文档和变更记录。
怎样减少文档维护成本？
统一模板、结构化 Token、自动生成 API 文档、把文档检查加入发布流程，并删除重复信息。不要手工维护同一份事实的多个副本。
相关服务与进一步咨询
链接复制成功
