组织你的 Storybook

信息越多，就越难找到你想要的东西。起初，你的 Storybook 只有少量组件，很容易跟踪。但随着组件数量的增长，组织复杂度也随之增加。

你最终会遇到这样的问题：“我们把那个组件放哪儿去了？”以及“这个状态有没有对应的故事？”这会导致混乱，甚至更糟，重复工作。

Storybook 被奥迪、IBM、Monday.com、Wix 等全球公司使用。我想了解大型团队如何组织组件，所以我调查了 60 个生产环境中的 Storybook。本文将分享我的发现。

• 📑 在组件层面组织故事的技巧
• 🔍 分组和排序组件的策略
• ✍️ 使用文档页面展示设计代币和其他使用指南

Storybook 里有什么？

在深入探讨组织策略之前，我们先了解一些基础知识。Storybook 主要包含两样东西：

• 故事 (Stories)：用于隔离和捕获组件的使用场景。你可以通过 prop 或模拟的上下文和 API 调用，指定重现特定状态所需的输入。
• 文档页面 (Documentation pages)：使用 MDX 构建的自由格式页面。

1. 介绍你的 Storybook

在顶部，使用文档页面向人们介绍你的 Storybook，并指导他们如何开始。MDX 让你完全控制内容。你可以撰写散文，穿插 JSX 组件，并使用 MDX Embed 嵌入各种资源。

我们来看看每个 Storybook 都需要的一些顶级页面。

介绍页

首先，对你的 Storybook 进行高层介绍——包含哪些内容、谁负责维护以及如何报告问题。

入门页

“入门”部分分享了如何使用 Storybook 的组件。这可能包括安装说明、加载 CSS 或配置主题。 奥迪设计系统 为开发人员和设计师提供了入门指南。联合国世界粮食计划署 提供了详细的使用指南，解释了架构选择。

贡献页

记录如何贡献新功能或修复 Bug。贡献页面应包含环境设置说明、如何提交代码以及运行测试。这对于依赖社区支持的库和设计系统尤其重要。

设计代币 (Design Tokens)

组件通过设计代币获取视觉样式，例如颜色、排版、尺寸和图标。文档化这些代币便于开发人员查看代币对应的值。使用 Storybook 自带的 Doc Blocks 来可视化颜色调色板、排版和图标。或者通过将自定义组件导入 MDX 文件来创建自己的块。

更新日志 (Changelog)

健康的 UI 库和设计系统会持续更新。这意味着从你的库中添加或删除组件，或者更改它们的 API。更新日志页面将所有这些更新集中在一个地方。它也是分享你的版本控制策略和项目路线图的绝佳位置。

2. 分组和排序组件

接下来从介绍页转向组件的排列方式。组件的故事会自动分组。Storybook 还允许你将多个组件分组到一个类别中，并在侧边栏中调整它们的顺序。这使得浏览和发现 UI 元素变得更加容易。

你可以通过在 title 属性中添加前缀来创建分组。每个分组级别用 / 分隔。欲了解更多，请参阅：命名组件和层级结构。

// Checkbox.stories.js
import { Checkbox } from './Checkbox';
 
export default {
 title: 'Design System/Atoms/Checkbox',
 component: Checkbox,
};

你的层级选择取决于你的团队如何工作。虽然没有正确或错误的答案，但我将分享一些流行的组织技术。

原子设计方法论 (Atomic Design methodology)

由 Brad Frost 首创，原子设计是一种常见的 UI 层级系统。它将组件分为五个级别：原子、分子、组织、模板和页面。

像 Codecademy 这样的团队遵循原子层级的所有级别。而像 The Guardian 和 联合国世界粮食计划署 这样的团队只使用其中一部分。请参阅 Brad 关于 原子设计和 Storybook 的文章，了解他如何使用 Storybook。

按功能分组

另一种流行的方法是根据组件的功能类型或在应用程序中的角色进行分组。例如，表单控件、按钮、布局工具、卡片或导航元素。

按组件状态分组

有些团队根据组件的状态进行分组。也就是说，一个 UI 组件是可以使用、仍在实验中还是已被弃用。

这种策略对于像 IBM Carbon 和 Workday Canvas 这样的设计系统团队尤其适用。

3. 编写故事以展示你的组件功能

故事是一种灵活的结构，使你能够以多种模式展示 UI。故事有很多类型。有些故事帮助开发人员、设计师和项目经理检查 UI 是否正确。而其他故事则用于在浏览器中进行原型设计，无需触碰代码。

每个组件的故事将取决于其用例。例如，像 Accordion 这样的原子组件可能需要进行 API 分解，而连接组件或页面则可能不需要。

话虽如此，对于每种类型的组件，保持故事排序的一致性会使导航更具可预测性。Intuit 团队甚至写了一篇文章，介绍了一致性如何改进了他们的 UI 文档体验。让我们来了解不同的故事类型。

概览故事 (Overview story)

从文档页面开始，解释组件的作用以及何时使用它。这也是包含设计规范、视觉指南、响应行为以及可访问性注意事项的绝佳位置。

Playground 故事

接下来是 Playground 故事，其中所有组件 prop 都与 Storybook 控件关联。这对于演示组件 API 和在浏览器中进行原型设计非常有效。

功能故事 (Feature stories)

功能故事是一系列涵盖组件所有状态和变体的故事。对于 JavaScript 函数，你经常编写涵盖所有用例的测试用例。功能故事对于你的 UI 起着完全相同的作用。

更重要的是，你甚至可以将它们作为夹具在 Chromatic、Jest 或 Axe 等测试工具中重复使用。要了解更多，请查阅 UI 测试手册。

当你发布 Storybook 时，这些故事会使用渲染后的代码来展示组件功能，用户可以与代码互动，而不是静态图像。

配方故事 (Recipe stories)

配方故事演示了如何在实际场景中将一个组件与其他组件组合使用。类似于集成测试，它们展示了组件如何协同工作。例如，将 Input、Label 和 Buttons 组合以创建一个表单。或者展示如何使用 ProductCard 构建不同的布局。

向同行学习

应用程序的目录结构对开发人员的工作效率有重大影响。缺乏层级结构会让你很难找到文件并降低速度。

组织组件和故事也是如此。本文分享了我从 60 个 Storybook 中观察到的最佳实践。希望它能成为你编写自己的 Storybook 的起点。更多灵感，请查阅我们文档中 精选的 Storybook 列表。

即将推出的 组件百科全书 提供了一个更全面的展示，你可以浏览、参考和学习。在下方注册 Storybook 邮件列表，获取组件百科全书的更新和抢先体验。或者在此提交你自己的 Storybook URL。