Storybook 使用手册——组织你的Storybook

在前面的文章中，通过个人博客的案例，展示了如何在现有项目中集成Storybook。但是，实际情况是，随着项目的迭代和组件数量的增加，组织的复杂性也在增加。

在日常工作中，针对Storybook的使用，曾思考过类似的问题：

这个组件的Story该放哪里？
是否需要展示组件的每一个State?
除了组件的文档，我该怎么组织页面文档？
…

希望能够找到组织和维护Story的最佳实践。我试图去体验各种不同的Storybook输出的文档，希望借此来探索出适合自己的管理方式。在Medium上发现了设计师 Varun Vachhar 的文章，作者在体验了60个个storybook项目之后，整理分享了一些心得：

📑 在组件层面组织 Story 的技巧
🔍 对组件进行分组和分类的策略
✍️使用文档页来展示设计标记和其他使用指南

看下来确实是一个不错的实践。

一个Storybook项目中包含了什么？

在深入探讨组织策略之前，让我们先介绍一些基本情况。Storybook主要包含两类：

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

介绍你的Storybook

在顶层，使用文档页面像用户介绍你的Storybook，并向他们展示如何开始。MDX的自由格式可以让我们完全控制内容，可以在JSX组件中写文档，也可以通过 MDX 嵌入各种文件。

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

介绍页

使用一个高层级的介绍页来开始你的Storybook。这个页面包含的内容可以有Storybook中包含了什么，谁负责维护以及如何报告问题等等。

开始页面

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

贡献页面

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

Design Tokens

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

ChangeLog

健康的UI库和设计系统会不断地更新。你会在组件库中添加或删除组件或改变它们的API。更新日志页面将所有这些更新记录在一个地方。它也是一个分享你的版本策略和项目路线图的绝佳地点。

Natura的Changlogs

Vibe的Changelogs

对组件进行分组和排序

组件的Story会自动组合在一起。 Storybook 还允许将多个组件分组到一个类别中，并在侧边栏中调整它们的顺序。这使得浏览和发现 UI 元素变得更加容易。

你可以通过给标题属性添加一个前缀来创建分组。每个分组级别都由一个/隔开。更多信息请参见：命名组件和层次结构。

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

层次结构的选择取决于团队情况，没有对错之分。下面是几种比较受欢迎的组织技巧

原子设计方法论

由 Brad Frost 开创的 Atomic Design 是一种常见的 UI 分层系统。它将组件分为五个级别：原子、分子、有机体、模板和页面。像 Codecademy 这样的团队遵循原子层次结构的所有级别。而其他人，如卫报和联合国世界粮食计划署，只使用一个子集。请参阅 Brad 的 Atomic Design and Storybook 文章，了解他如何使用 Storybook。