Storybookを仕様書として使うSDD実践方法

仕様駆動開発 SDD Storybook フロントエンド テスト

Storybookは「UIカタログ」ではなく「実行可能な仕様」にできる

SDD（仕様駆動開発）をフロントエンドで実践しようとすると、
ほぼ確実に候補に挙がるツールがあります。Storybookです。

一般的には「コンポーネントカタログ」や「デザイン確認ツール」として使われます。
ボタン、フォーム、モーダルなどを一覧で表示し、デザイナーと確認する用途です。

ここで多くのチームが、惜しい使い方をします。

  • 見た目確認に使う
  • デザインレビューに使う
  • UIギャラリーとして公開する

もちろん有用ですが、それだけではSDDにはなりません。
しかし使い方を一段階変えると、Storybookは仕様書そのものとして機能します。

重要なのは「コンポーネントを並べる」ことではありません。
「振る舞いを固定する」ことです。

なぜStorybookがSDDと相性が良いのか

SDDの条件は、仕様が次の性質を持つことです。

  • 実行できる
  • 誰でも確認できる
  • 曖昧さがない

従来の仕様書（Excel・Wiki）は実行できません。
テストコードは実行できますが、非エンジニアが理解しにくいです。

Storybookはこの中間に位置します。

  • ブラウザで動く
  • 触って確認できる
  • コードと同期する

つまり「読めるテスト」になります。

ただし、そのためには書き方を変える必要があります。

間違った使い方

よくあるStorybookの構成：

  • Primary Button
  • Secondary Button
  • Disabled Button

これはUIサンプルです。
仕様ではありません。

なぜなら「いつ disabled になるのか」が書かれていないからです。

見た目だけでは仕様になりません。

正しい書き方 ― 状態をストーリーにする

SDDで使うStorybookは、見た目ではなく状態を表現します。

例：注文ボタン

次のようにストーリーを分けます。

  • 在庫あり状態
  • 在庫切れ状態
  • ログイン前状態
  • 決済中状態
  • エラー状態

これで初めて仕様になります。
UIコンポーネントが「どの条件でどう振る舞うか」を固定できます。

このとき重要なのは、propsをデザインのためではなく、状態のために使うことです。

つまり：

色を変える → ×
状態を変える → ○

テストとの連携

ここでSDDが成立します。
各ストーリーに対して振る舞いテストを書きます。

例：

  • ログイン前ではクリック不可
  • 在庫切れではメッセージ表示
  • 処理中は再クリック不可

これを自動テストとして実行します。
ストーリーが壊れたら仕様が壊れたと判断できます。

この瞬間、StorybookはUI確認ツールではなく、
実行可能な仕様書になります。

APIとの接続

さらに有効なのがモックAPIです。
Storybook内でレスポンスを固定します。

  • 成功レスポンス
  • バリデーションエラー
  • タイムアウト
  • 権限エラー

これにより、バックエンド未完成でも仕様検証が可能になります。

ここでのポイントは、モックを「仮実装」にしないことです。
契約として扱います。

バックエンドはこの挙動に合わせて実装します。
これがSDDです。

実務での運用手順

実践的な流れは次です。

1. ユースケースを定義
2. 状態を洗い出す
3. Storybookストーリー化
4. 振る舞いテストを書く
5. API契約を固定
6. サーバ実装

この順序にすると、UI先行でも仕様先行になります。

注意点 ― Storybookの落とし穴

最も多い失敗は「パターン爆発」です。

状態を増やし続けると、次が起きます。

  • 管理不能
  • 更新漏れ
  • 仕様の分裂

対策は明確です。
コンポーネントではなく「ユースケース単位」でストーリーを持ちます。

ボタン単体ではなく、
「注文できる状態」
をストーリーにします。

まとめ ― Storybookはデザインツールではなく契約ツール

StorybookはUIツールとして使うと便利な補助資料です。
しかしSDDとして使うと、開発の中心になります。

ポイントは1つです。

見た目を記述するのではなく、
振る舞いを固定すること。

Storybookに書かれた状態が、
そのままテストになり、
そのままAPI契約になります。

この形を作れたとき、仕様書・テスト・UIレビューが分離しなくなります。
そして「仕様がどこにあるのか分からない」という問題が消えます。

Storybookはカタログにもなります。
ただしSDDでは、それ以上の役割を持ちます。
チーム全員が触れる、最も理解しやすい仕様書になります。