ChromaticをFigmaとGitHubと連携させてUI実装の品質向上

Chromaticとは？

Storybookのメンテナーが作成したパブリッシングツールです。

Chromaticを利用するメリット

その１：Storybookをホスティングしてチームで見ることができる

• フロントエンドエンジニアだけでなくデザイナーやプロダクトオーナーも見やすくなる
• Figmaと連携することでFigmaのデザインとStorybookを相互参照できる

その２：Storiesを追加するとドキュメンテーションとビジュアルリグレッションテストができて1粒で2度美味しい！

• PR作るとmainブランチとスナップショットの差分があると教えてくれる
• CSS変更時のデグレや、コンポーネントにpropsで渡すデータや構造などに変化があったときのデグレ等、デグレしやすい部分で察知しやすくなる
• Storiesをメンテする動機ができるので、形骸化しにくい　→　積極的にStorybookを参照されるようになる（はず）

その３：UIの品質を向上することができる

• UIの実装をデザイナーや他のフロントエンドエンジニア、プロダクトオーナーなどに鬼レビューしてもらえる
• ChromaticでApproveされないとプルリクエストをマージできないようにできる
• ビジュアルリグレッションテストでこけているとプルリクエストをマージできないようにできる
• Storybook上にFigmaのデザインを表示できるので、意図通りの実装か比較できる

プロジェクトの作成

まずGitHubのリポジトリと連携させます。

そして npm install --save-dev chromatic でchromaticをインストールします。

※まだStorybookを導入していない人は npx storybook@latest init してください。

Chromaticプロジェクトに反映

コンポーネントとstoriesを追加した後、 npx chromatic --project-token=***** でChromaticプロジェクトに反映します。（*****の部分はChromaticに記載されているトークンを入力ください）

Chromaticに反映されました。これでStorybookをオンラインで見ることができます。

FigmaのデザインにChromatic(Storybook)を連携する

メニューから「Library」に移動し、コンポーネントを選択してリンクをコピーします。

Figma上でコンポーネントを選択して、プラグイン「Storybook Connect」に先ほどコピーしたリンクを貼り付けて「Link Story」をクリックします。

するとFigmaのコンポーネントとChromaticで公開しているStorybookのStoryがリンクされ、実際の実装と見比べることができるようになりました。

Chromaticへの反映を自動化する

メニューから「Reviews」に移動するとこのような画面が表示されます。

まず、GitHub Appをインストールします。

これだけではプルリクエストを作ってもChromaticへ反映されないので、GitHub Actionsを使ってChromaticへの反映を自動化します。

package.jsonのscriptsにchromaticがない場合は追加してください。

package.json

"scripts": {
  ...
  "chromatic": "chromatic --exit-zero-on-changes"
}

そして、ChromaticのプロジェクトトークンをGitHubのSecretsに登録します。

下記のように git pushすると先ほど登録したSecrets（トークン）を元にChromaticへ反映するworkflowを追加します。

※全てこのworkflowを通すと大変なことになるので、ブランチの命名規則 or 特定のラベル or 特定のタグが付いた時に実行されるようにしてもいいと思います。

.github/workflows/chromatic.yml

# Workflow name
name: 'Chromatic'

# Event for the workflow
on: push

# List of jobs
jobs:
  chromatic-deployment:
    # Operating System
    runs-on: ubuntu-latest
    # Job steps
    steps:
      - uses: actions/checkout@v1
      - name: Install dependencies
        # <img draggable="false" data-mce-resize="false" data-mce-placeholder="1" data-wp-emoji="1" class="emoji" alt="?" src="https://s.w.org/images/core/emoji/14.0.0/svg/1f447.svg"> Install dependencies with the same package manager used in the project (replace it as needed), e.g. yarn, npm, pnpm
        run: npm ci
        # <img draggable="false" data-mce-resize="false" data-mce-placeholder="1" data-wp-emoji="1" class="emoji" alt="?" src="https://s.w.org/images/core/emoji/14.0.0/svg/1f447.svg"> Adds Chromatic as a step in the workflow
      - name: Publish to Chromatic
        uses: chromaui/action@v1
        # Chromatic GitHub Action options
        with:
          # <img draggable="false" data-mce-resize="false" data-mce-placeholder="1" data-wp-emoji="1" class="emoji" alt="?" src="https://s.w.org/images/core/emoji/14.0.0/svg/1f447.svg"> Chromatic projectToken, refer to the manage page to obtain it.
          projectToken: ${{ secrets.CHROMATIC_PROJECT_TOKEN }}

するとGitHubのプルリクエストページに先ほど追加したworkflowに加えて3つくらいworkflowが追加されるようになりました。

ChromaticのReviewsを活用する

ドロップシャドウの追加を忘れていたので、早速プルリクエストを作ってみます。

するとReviewsページにプルリクエストの内容が追加されました。

GitHubのプルリクエストページを見ると何やらUI ReviewとUI Testsが通らないとマージできないようです。

UIテスト

mainブランチとの見た目の差分があるとそれが意図した変更かどうか（デグレてないか）各コンポーネントの各Story毎にチェックすることができます。

もし、意図した変更の場合はAcceptしましょう。

ちなみに一度Acceptした後、再度修正してpushしても見た目に差分がなければAcceptedになったままになります。

レビュー

実装したプルリクエストをOKとみなすかジャッジすることができます。

変更があったコンポーネントの実装前と実装後のスナップショットを差分で見たり、ここで実装に対してディスカッションしたりできます。

ぜひデザイナーの人に鬼レビューしてもらいましょう！

レビューをApproveする

変更に問題がいないのでApproveしました。

するとプルリクエストをマージできるようになりました。

Chromatic(Storybook)にFigmaのデザインを連携する

storybook-addon-designsの追加

まずはstorybook-addon-designsをインストールします。

npm install --save-dev storybook-addon-designs

※Storybook v7を使っている場合はnpm install --save-dev storybook-addon-designs@beta でインストールする必要があります（2023/7/3現在）

.storybook/main.tsのaddonにstorybook-addon-designsを追加します。

.storybook/main.ts

const config: StorybookConfig = {
  // ...
  addons: [
    // ↓追加
    'storybook-addon-designs',
  ],
}
export default config

Figmaのデザインのリンクをコピーする

Storyに追加するコンポーネントを選択し、右クリックでリンクをコピーを選択します。

コピーしたFigmaのデザインのURLを指定

Storyにparametersを追加します。

Button.stories.tsx

import type { Meta, StoryObj } from '@storybook/react'

import { Button } from './Button'

// More on how to set up stories at: https://storybook.js.org/docs/react/writing-stories/introduction
const meta: Meta<typeof Button> = {
  title: 'Button',
  component: Button,
  tags: ['autodocs'],
}

export default meta
type Story = StoryObj<typeof Button>

// More on writing stories with args: https://storybook.js.org/docs/react/writing-stories/args
export const Primary: Story = {
  args: {
    children: 'ラベル',
  },
  // ↓下記を追加
  parameters: {
    design: {
      type: 'figma',
      url: 'https://www.figma.com/file/...',
    },
  },
}

するとStorybook上にFigmaが表示されるようになりました。

参考資料

Chromatic https://www.chromatic.com/

Figmaデザイン（デモ） https://www.figma.com/file/i371U9UcMoOVAWAopGOXL4/chromatic-sample

リポジトリ（デモ） https://github.com/r-kataoka11/chromatic-test