使用 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. 在设计系统管理器（Zeroheight、Zeplin、InVision）中连接 stories

为什么要为你的设计系统编写文档？

文档对于设计系统的采用至关重要。它整合了使用指南，以帮助开发人员、设计师、产品经理和其他利益相关者交付可预测的 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 Design System 是两个很好的例子。

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

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

在工作区中嵌入 stories

Notion 和 Confluence 是通用的文档工具，具有 WYSIWYG 编辑界面。这有助于你让非技术贡献者参与进来，并在散文旁边嵌入资源。Notion 甚至提供了一个 设计系统入门模板。

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

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

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

DSM 仅支持 Sketch，而 Supernova 是为 Figma 制作的。Zeroheight 与大多数设计工具兼容，使其成为 Intuit、Instacart 和 Guardian 等团队的流行选择。

结论

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

当你开发期间编写 stories 时，你也在创建基本文档。Storybook Docs 插件生成一个静态站点，其中包含实时代码示例、API 文档和使用指南。你可以使用它作为起点来定制工作流程以适应你的需求。在文档工具或自定义站点中嵌入 stories。