Storybookの存在は知っていたが、「ドキュメントツールでしょ」と軽く見ていた時期があった。
実際に導入してみると、コンポーネント開発のフローそのものが変わった。同時に、運用を継続する難しさも痛感した。テックリードとして導入を主導した立場から、メリットと現実を書いておく。
Storybookとは
コンポーネントを単体で開発・表示・管理するためのツール。各コンポーネントの「ストーリー」を書くことで、アプリケーション全体を起動しなくてもコンポーネントの動作を確認できる。
// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';
const meta: Meta<typeof Button> = {
component: Button,
};
export default meta;
type Story = StoryObj<typeof Button>;
export const Primary: Story = {
args: {
label: '送信する',
variant: 'primary',
},
};
export const Disabled: Story = {
args: {
label: '送信する',
disabled: true,
},
};これだけでブラウザ上でコンポーネントが一覧表示され、propsを変えて動作を確認できる。
導入してよかったこと
コンポーネントの「カタログ」ができる
一番の恩恵はUIの共通認識が生まれることだ。
「このボタンコンポーネント、どんなバリエーションがあるんだっけ」という確認をコードを読まなくてもできる。デザイナーとエンジニアの間で「このコンポーネントを使って」という会話が具体的になった。
Atomic Designと組み合わせると特に効果的で、Atoms・Molecules・Organismsごとにカタログが整理される。
propsの設計が良くなる
ストーリーを書く過程で、コンポーネントの設計上の問題に気づきやすくなる。
「このコンポーネント、ストーリーを書こうとしたらpropsが複雑すぎる」という状況が起きたら、それはコンポーネント自体の問題だ。Storybookはコンポーネント設計の品質指標として機能する。
ローカルでUIを確認できる
バックエンドの準備が整っていない段階でも、フロントエンドの開発を進められる。APIのレスポンスをモックしてストーリーを書けば、実際のデータがなくても画面を確認できる。
正直に言う：難しかったこと
ストーリーのメンテナンスコストが高い
導入から数ヶ月経つと、コンポーネントは更新されているのにストーリーが古いまま、という状況が発生した。
ストーリーがあることで安心するが、古いストーリーは実際の動作と乖離している。「Storybookが正しい」と思って確認したら、実装が変わっていた、という事故も起きた。
対策として取った方針
- コンポーネントを変更したらストーリーも必ず更新するをコードレビューのチェック項目にした
- CIでストーリーのビルドが通ることを確認するようにした
チームへの浸透に時間がかかった
「ストーリーを書かないといけないの？」という抵抗感が最初はある。
特に「動けばいい」と考えているメンバーには、ストーリーを書くコストに見合うメリットが伝わりにくい。私はコードレビューで「このコンポーネントのストーリーは？」と必ず聞くことを続け、習慣として定着させた。
継続して使うための運用方針
試行錯誤の結果、以下の方針が機能した。
書く範囲を絞る 全コンポーネントのストーリーを書こうとすると破綻する。AtomsとMoleculesは必須、Organismsは複雑なものだけ、とルールを決めた。
ストーリーをテストとして使う
Storybookには @storybook/test と組み合わせてインタラクションテストを書ける機能がある。単なるドキュメントではなく、テストとして機能させることでメンテナンスの動機づけになる。
デザイナーを巻き込む Storybookをエンジニアだけのツールにしない。デザイナーが実装の確認に使えるようになると、チーム全体のツールとして定着する。
まとめ
Storybookは「入れるだけで良くなる」ツールではなく、継続的な運用ルールがないと形骸化する。
ただ、正しく運用できれば、コンポーネント設計の品質向上とチームの共通認識づくりに確実に貢献する。特にAtomic Designと組み合わせる場合は相性がいいので、セットで導入することをおすすめしたい。
