iT邦幫忙

第 12 屆 iT 邦幫忙鐵人賽

DAY 28
1
Modern Web

玩轉 Storybook系列 第 28

玩轉 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側邊欄第一個

Next

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

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

Reference

Design System for Developers - Document


上一篇
玩轉 Storybook: Day 27 Design System for Developers - Review、Test
下一篇
玩轉 Storybook: Day 29 Design System for Developers - Distribute
系列文
玩轉 Storybook30

尚未有邦友留言

立即登入留言