Storybook 的结构化

信息越多，就越难找到您要查找的内容。最初，您的 Storybook 只有少数组件，因此很容易跟踪事物。但是随着组件数量的增长，组织复杂性也随之增加。

您最终会遇到诸如“我们把那个组件放在哪里了？”和“这个状态有 story 吗？”之类的问题。这会导致混乱，甚至更糟，重复劳动。

全球公司如 Audi、IBM、Monday.com、Wix 等都在使用 Storybook。我想了解最大的团队是如何处理组件组织的，所以我调查了 60 个生产 Storybook。本文分享了我的发现。

• 📑 在组件级别组织 story 的技巧
• 🔍 分组和排序组件的策略
• ✍️ 使用文档页面展示设计令牌和其他使用指南

Storybook 内部是什么？

在深入研究组织策略之前，让我们先介绍一些基础知识。Storybook 主要包含两件事

• Stories： 用于隔离和捕获组件的用例。您可以指定重现特定状态所需的输入，作为 props 或通过模拟上下文和 API 调用。
• 文档页面：使用 MDX 构建的自由格式页面。

1. 介绍您的 Storybook

在顶部，使用文档页面向人们介绍您的 Storybook，并向他们展示如何开始使用。MDX 使您可以完全控制内容。您可以编写散文，其中穿插 JSX 组件，并使用 MDX Embed 嵌入各种类型的资源。

让我们看看每个 Storybook 都需要的不同顶级页面。

介绍页面

从对您的 Storybook 进行高级介绍开始——包括什么、谁维护它以及如何报告问题。

入门页面

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

贡献页面

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

设计令牌

组件通过设计令牌获取视觉样式，例如颜色、排版、尺寸和图标。记录这些内容使开发人员可以方便地查看令牌映射到的值。使用 Storybook 自己的 Doc Blocks 来可视化调色板、排版和图标。或者通过将自定义组件导入 MDX 文件来创建您自己的块。

变更日志

健康的 UI 库和设计系统会不断更新。这意味着从您的库中添加或删除组件或更改其 API。变更日志页面在一个地方捕获所有这些更新。这也是分享您的版本控制策略和项目路线图的绝佳地点。

2. 分组和排序组件

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

您可以通过在 title 属性中添加前缀来创建分组。每个分组级别用 / 分隔。有关更多信息，请参见：命名组件和层次结构。

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

您对层次结构的选择取决于您的团队的工作方式。虽然没有正确或错误的答案，但我将分享一些流行的组织技巧。

原子设计方法

由 Brad Frost 开创的原子设计是 UI 的常见分层系统。它将组件分为五个级别：原子、分子、生物体、模板和页面。

Codecademy 等团队坚持原子层次结构的所有级别。而其他团队，例如 The Guardian 和 联合国世界粮食计划署，仅使用一个子集。请参阅 Brad 的 原子设计和 Storybook 文章，了解他是如何使用 Storybook 的。

按功能

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

按组件状态

有些团队按状态对组件进行分组。也就是说，UI 组件是准备好使用、实验性的还是已弃用的。

这种策略对于 IBM Carbon 和 Workday Canvas 等设计系统团队尤其有效。

3. 编写 story 以展示组件的功能

Stories 是灵活的结构，使您能够以多种模式展示 UI。有很多类型的 story。有些 story 帮助开发人员、设计师和 PM 检查 UI 看起来是否正确。而另一些则用于在浏览器中进行原型设计，而无需接触代码。

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

也就是说，保持每个组件类型的 story 顺序一致，可以使导航更可预测。Intuit 团队甚至写了一篇文章，关于 一致性 如何改善他们的 UI 文档体验。让我们来看看不同的 story 类型。

概述 story

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

游乐场 story

接下来是游乐场 story，其中所有组件 props 都连接到 Storybook 控件。这非常适合演示组件 API 和在浏览器中进行原型设计。

功能 story

功能 story 是一组 story，涵盖组件的所有状态和变体。对于 JavaScript 函数，您通常编写测试用例来涵盖它们的所有用例。功能 story 对您的 UI 起着完全相同的作用。

更重要的是，您甚至可以将它们重用为测试工具（如 Chromatic、Jest 或 Axe）中的 fixtures。有关更多信息，请查看 UI 测试手册。

当您发布 Storybook 时，这些 story 使用户可以与之交互的渲染代码而不是静态图像来展示组件功能。

配方 story

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

向您的同行学习

应用程序的目录结构对您作为开发人员的生产力有重大影响。缺乏层次结构会使查找文件变得困难并减慢您的速度。

在组织组件和 story 时，情况也是如此。本文分享了我从 60 个 Storybook 中观察到的最佳实践。我希望它可以作为您编写自己的 Storybook 的起点。有关更多灵感，请查看我们文档中 精选列表 中的 Storybook。

即将推出的 组件百科全书 具有更详尽的展示，您可以浏览、参考和学习。在下面注册 Storybook 邮件列表以获取组件百科全书的更新和抢先体验。或者在此处提交您自己的 Storybook 的 URL here。