通过 Storybook 记录设计系统的 4 种方式

Storybook 被用于构建网络上最流行的设计系统，包括 Shopify Polaris、IBM Carbon、Salesforce Lightning、Auth0 Cosmos 和 Github Primer。

世界各地的前端团队使用 Storybook 的 Docs 插件可以更快地交付成果，工作量更少。它能从你现有的 stories 中自动生成文档。但这仅仅是一个起点。通过将 Storybook 与更多工具集成来扩展你的文档工作流程。

本文分享了现实世界中的设计系统如何使用 Storybook 来增强其设计系统文档。你将了解四种成熟的工作流程：

1. 使用官方的 Docs 插件编写文档
2. 在自定义文档站点上嵌入 stories
3. 在 Confluence 或 Notion 等工作空间中嵌入 stories
4. 在设计系统管理器中连接 stories（Zeroheight、Zeplin、InVision）

为什么要记录你的设计系统？

文档对于设计系统的采用至关重要。它整合了使用指南，帮助开发者、设计师、产品经理及其他利益相关者交付可预测的 UI。

设计系统记录了从高层级指南到精细组件的一切。由于 Storybook 是一个组件驱动的工具，这也是本文将深入探讨的内容。Nathan Curtis（来自 EightShapes）将组件文档需求分解为四大类：

1. 组件的**描述**，其名称和功能。
2. **示例**，说明组件的变体、状态。用户更喜欢可以交互的渲染代码，而不是静态图片。
3. **设计参考**，包括视觉指南、响应行为、何时使用组件以及注意事项。
4. **代码参考**，详细说明组件 API——props、事件处理程序等。

有许多方法可以构建组件文档。团队采用各种方式，从现成工具到构建自己的自定义站点。让我们仔细看看这些选项及其权衡。

使用 Storybook Docs 插件

Storybook 的 Docs 插件提供了一种精益的 UI 组件文档记录选项。你可以专注于编写文档，而 Storybook 则管理所有工具链的复杂性，以生成带有实时代码示例的静态站点。

团队已经使用 Storybook 构建其设计系统的组件。他们编写 stories 来演示每个组件的使用方式。Docs 插件使用这些 stories 为每个组件自动生成文档。

你能得到什么

1. **组件示例**：stories 在浏览器中实时渲染，并显示其源代码。
2. **组件 API**：以 ArgsTable 形式呈现。它是交互式的，你可以修改 args 并查看组件如何更新。
3. **使用指南**：从 Markdown 生成。你可以向页面的任何部分添加文字描述并提供更多上下文。
4. **设计资产**：Storybook 的插件生态系统提供了与所有你喜爱的设计工具的集成。例如，在 stories 中嵌入Figma 文件或将它们连接到Zeplin。

更重要的是，这一切都由 MDX 提供支持。因此，你可以随心所欲地自定义和主题化。

将内容引入 Storybook 是一个选择。另一种选择是将 Storybook 带到内容所在的地方。每个 story 都在一个 iframe 中渲染，允许你将其嵌入用于各种文档的其他工具中。

在自定义文档站点上嵌入 stories

一些团队构建自定义文档站点，以根据用户的特定需求调整体验。Shopify 的 Polaris 和 IBM 的 Carbon 设计系统是两个很好的例子。

这些站点仍然通过渲染代码来显示组件用例。你可以为此构建自己的工具，或者通过利用 Storybook 来减少开销。Workday 的 Canvas 和 Rocket Mortgage 的 Spark 设计系统将 story iframe 直接嵌入到文档页面中。

自定义站点需要大量投资，并非所有公司都能承担。现成工具在定制和维护之间提供了良好的折衷方案。

在工作空间中嵌入 stories

Notion 和 Confluence 是通用的文档工具，具有所见即所得的编辑界面。这有助于你邀请非技术贡献者参与，并在文字描述旁边嵌入资产。Notion 甚至提供了一个设计系统入门模板。

你可以使用 Chromatic（一个由 Storybook 团队提供的免费在线发布 Storybook 服务）将 stories 嵌入支持 oEmbed 标准的任何工具中。嵌入就像粘贴 story URL 一样简单。

在设计系统管理器中连接 stories

InVision DSM、Zeroheight 和 Supernova 是专门用于记录设计系统的工具。它们允许你跟踪设计令牌并创建组件页面，你可以在其中添加代码片段、嵌入 stories 并与设计工具链接。

DSM 只支持 Sketch，而 Supernova 专为 Figma 构建。Zeroheight 与大多数设计工具兼容——这使得它成为 Intuit、Instacart 和 The Guardian 等团队的流行选择。

结论

采用是任何设计系统的最大挑战。良好的文档通过充当所有用户的集中真相来源来加速采用。它涵盖了关于如何使用设计系统的指南以及每个组件的详细文档。

在开发过程中编写 stories 时，你同时也创建了基本文档。Storybook Docs 插件会生成一个带有实时代码示例、API 文档和使用指南的静态站点。你可以以此为起点，根据你的需求定制工作流程。将 stories 嵌入文档工具或自定义站点中。