玩转 Storybook: Day 28 Design System for Developers - Document

通过 Storybook Docs 推动 Design System 的采用

Design System为整个组织的利益相关者服务，因此我们需要教其他人如何从经过良好测试的UI元件中获得最大收益。建立文件可以加速Design System的采用。

利用Storybook Docs，可以用较少的工作来创建完整的说明文件。

写说明耗时费力

说明文件对於协作UI开发非常重要。它可以帮助团队学习如何以及何时使用常见的UI元件。但是一边开发一边写文件耗时又麻烦。

另外，大多数说明文件在做完後就过时了。过时的文件破坏了对Design System 元件的信任，这导致开发人员选择直接建立元件，而不是重用现有元件。

Requirements

如果我们想克服说明文件固有的问题，以下几点是需要注意的

文件的内容需保持与最後的上线版本程序码同步
使用 Markdown 这类的简单写作工具使得写作更加容易
减少维护时间，使团队可以专注於写作
提供样板，使开发人员不必重写常见的模式
针对复杂的使用案例和元件提供客制化

对於Storybook使用者来说，拥有相当大的优势，因为元件的变异都会被记录在Stories，每个Story会展示出在不同的Input(传入参数)下，元件会如何呈现。

Stories易於编写，且它是直接同步使用目前的元件，它也易於做持续不断的测试。

撰写故事，生成文件

借助 Storybook Docs Addon，我们可以从现有Stories中生成丰富的说明文件，以减少撰写文件的时间。可以集中精力编写更易於被采纳使用的元件说明。

每次打开Storybook时，会看到两个页签：

Canvas 呈现元件的样子
Docs 元件的使用说明

每个元件都会对应该Docs，我们可以透过 Docs 快速的知道要如何使用元件。

扩展文件，提供更多使用资讯

让我们使用范例专案的Badge.stories.js为范例，Badge用来提供标识使用。

Subtitle

让我们加上parameters.componentSubtitle，补充元件的副标说明。

// src/Badage.stories.js

export default {
  title: 'Design System/Badge',
  component: Badge,
  parameters: {
    componentSubtitle: 'Displays meaningful label',
  },  
};

Description

当我们在Badage元件export function加上JSDOC的注解时，它也会成为Storybook Docs 的 Description

ArgsTable

在 propTypes 加上的注解也会自动生成呈现在 ArgsTable 中

storyDescription

为 Story 加上 Description

使用加强版的文件说明 - MDX

每个元件的复杂程度都不相同，对於说明文件的要求也不同。
Markdown是一种用於编写文件的简单格式。MDX允许您在Markdown内部使用JSX。Storybook Docs使用MDX，可让开发人员可以自己控制及安排说明文件的呈现方式。

如果Storybook要可以吃MDX的写法，.storybook/main.js 应该看起来像这样：

// .storybook/main.js

module.exports = {
  stories: [
    '../src/**/*.stories.mdx',        
    '../src/**/*.stories.@(js|jsx|ts|tsx)'
  ],
  addons: [
    '@storybook/addon-links',
    '@storybook/addon-essentials',
    '@storybook/preset-create-react-app',
    '@storybook/addon-a11y',
  ],
};

改写xx.stories.js 使用 MDX

试看看把 Badage.stories.js 改写为 Badage.stories.mdx

先把空白的DOC产生出来

至少要指定 Title、Component

加上第一个Story

列出常用的Stories

加上可以让使用者自行实验呈现的 Playground Story

MDX

在 Doc 分页

在 Canvas 分页

加上 Preview 及 ArgsTable

MDX

在 Doc 分页

使用复合元件的写法 With Icon

MDX

在 Doc 分页

透过这样的写法，就会发现使用 MDX 的设定方式，可以加上更多的说明，可以任意的编排文件的呈现，非常适用於当元件较为复杂时使用。

程序码范例：https://git.io/JTvMk

自定义页面

每个Design System都有一个封面。Storybook Doc可以使用MDX创建一个单独自定义页面。

// src/components/Intro.stories.mdx

import { Meta } from '@storybook/addon-docs/blocks';

<Meta title="Design System/Introduction" />

# Introduction to the Learn Storybook design system

The Learn Storybook design system is a subset of the full [Storybook design system](https://github.com/storybookjs/design-system/), created as a learning resource for those interested in learning how to write and publish a design system using best practice techniques.

Learn more at [Learn Storybook](https://learnstorybook.com).

为了使其出现在第一个，我们必须在.storybook/main.js设定一下顺序

// .storybook/main.js

module.exports = {
  stories: [
    // 第一个显示 Intro.stories.mdx
    '../src/components/Intro.stories.mdx',
    '../src/**/*.stories.mdx',
    '../src/**/*.stories.@(js|jsx|ts|tsx)',
  ],
  ...
};

这样 Intro.stories.mdx 就会显示在Storybook侧边栏第一个