通過 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側邊欄第一個

Next

到目前為止，我們都是在開發團隊內部運作。首先，創建UI元件，然後，對它們進行審查，測試和文件化。

接下來，我們將視野向外，讓不只是開發團隊而是擴大到專案的利害關係者如何使用Design System。利用npm及auto這二個工具，打包Design System並發佈以供其他App使用。

Reference

Design System for Developers - Document