こんにちは。CADDi Quoteのプロダクトデザイナー山崎文菜 (@ayana_yamazaki) です。
去年までは、Figmaでデザインファイルを完成させて、エンジニアに渡す。それが当たり前だと思っていました。
実装に入ってからエンジニアに「ここのデフォルトの並び順、昇順にしてますけど大丈夫ですか？」と聞かれ、Figmaを見返す。あっ決めてなかった…！ デザインファイルではUIが完成していたのに、実はUXの意思決定が終わっていなかった…
この記事は、コードが書けないデザイナーが、エンジニアの伴走を受けながらClaude CodeでStorybookを書き、プロダクトマネージャーとのウォークスルーで130件以上の仕様課題を実装前に発見・解決した実践録です。 Figma→実装のハンドオフで手戻りに苦しむデザイナーやエンジニアに向けて、何をやり、なぜ仕様の抜け漏れを実装前に潰せたのかをお伝えします。
- 1. Figmaは画面を完成させるが、意思決定を完了させない
- 2. やったこと: コードで画面仕様を定義し、PdMとUX検証した
- 3. なぜ効いたか①: コードは曖昧さを許さない
- 4. なぜ効いたか②: 触れるものを囲んで多職種で検証できる
- 5. 結果
- 6. 導入に何が必要か
- 終わりに: これはデザイナーの仕事なのか？
1. Figmaは画面を完成させるが、意思決定を完了させない
静的デザインファイル→実装のハンドオフには、2つの問題があります。
1. 静的デザインファイルでは「決めていないこと」が見えない
エラーのバリデーションタイミング、Empty State、長い文字列が入った場合の表現…これらを決めなくても画面は完成します。未決定の項目が埋もれたまま先に進む。
2.Figmaはプロダクトの現実と繋がっていない
Figma Prototypeは決められた遷移を辿れますし、Figma Makeならインタラクティブなプロトタイプも生成できます。しかしそれらは本番のコードやデータから切り離された世界です。既存実装に埋もれた仕様も、実データを流し込んだときの壊れ方も映りません。プロダクトの現実に触れなければ出てこない問いがあります。
2. やったこと: コードで画面仕様を定義し、PdMとUX検証した
最初にClaude CodeでHTMLプロトタイプを作り、画面構成や情報の優先度をPdMと検証しました。大枠の方向が固まった段階で、React + 社内デザインシステムでStorybookに移行。本プロジェクトではFigmaは全く使っていません。
- 画面仕様書 (.mdx) : カラム定義、ステータス定義、フィルター仕様、スクロール挙動、ページネーション仕様、i18nラベル定義
- 画面 (.story): 状態パターン網羅（Default、EmptyState、Loading、全ステータス表示など）
- UIコンポーネント (.tsx): インタラクティブに操作できる画面やUIコンポーネント
私はコーディングスキルがなく、すべてClaude Codeで指示を出して書いています。このプロセスを成立させた条件はセクション6で詳しく述べます。
3. なぜ効いたか①: コードは曖昧さを許さない
コードで書き、UXを体験し、本番コードを参照する。この3つが重なったことで、ハンドオフまでに定義しきれなかった仕様が、プロセスの力で構造的に炙り出されました。
例1: エラー表示の定義から、エラー防止の設計へ
ユーザーを追加するモーダルに、表示名とメールアドレスの2フィールドがあります。FEに「エラー状態」の赤い静止画を1枚描けば補完してもらえますが、UXデザイナーとして品質にこだわりたいところです。コードで書くと、「エラー表示」でもフィールドごとにonChange・onBlur・onSubmitと発火タイミングが分岐します。 これらを定義し、実際にキーボードで操作して挙動を触り比べる過程で、「エラーをどう表示するか」ではなく、「そもそもエラーを起こさない体験」を追求していきました。 onBlurで空白が入力されたらトリム、全角英数字は自動で半角に変換するなど、フロントのみで実装できるエラー防止のUXの詰め。操作しなければ浮かびづらい発想でした。
例2: 本番コードを起点にしたUX改善
新画面にメモ編集機能を設計する際、本番の類似コンポーネントのコードを読み込みました。既存の実装と挙動を把握した上で、長文が入ったときの表示の切り方やアフォーダンスの改善など、元のUIにはなかった設計判断をStorybookで試しながら加えていきました。 コードを起点にしたからこそ、既存UIの設計意図を理解し、それを超える改善の起点が得られました。
その他にも、コードで定義する過程で露出した仕様
| 露出した仕様 | なぜコードで定義すると露出するか |
|---|---|
| グローバル対応の名前の字数（タイ人名の場合30文字を超えることも） | ダミーデータを自分で定義するため、「どんなデータでテストすべきか」という問いが発生。PdM調査で名前に関する左記の実態が判明し、あらかじめ崩れ防止や視認性を担保できた |
| Empty State・Loadingなどの状態 | 状態パターンをStoryとして網羅するため、未定義の状態が残らない |
静的なデザインファイルでは、これらを「決めなくても画面は完成する」ため見過ごされることがありますが、コードでは「定義しないと画面が動かない」ため、未決定の項目が残りようがありません。
4. なぜ効いたか②: 触れるものを囲んで多職種で検証できる
CADDiは製造業AIプラットフォームであり、製造業では品質を後工程の検査で担保するのではなく、前工程に検査を組み込む「フロントローディング」という考え方があります。
例3: PdMとのUX検証で表現を磨き込む
Storybook上で実際にアイテムの追加・フィルター・ソートなどの画面操作を試せたからこそ気づけた問題がありました。 業務を再現しながらPdMとレビューを繰り返し、ステータスカラムの表現を改善した例を紹介します。
1回目: ステータス4種、期限切れはテキスト表現 → PdMとStorybook上でフィルターやソートを操作。ITリテラシーが高くないユーザーになりきると、期限切れアイテムを探す時にdateで絞り込む発想が難しいことに気づく
2回目: ステータスに「期限切れ」を追加 → 期限切れかつ未対応/対応中なのかがわからなくなるが、期限切れの時点でユーザーにやれることは少ないため未対応/対応中の区別は不要と判断。
3回目: ステータス5種 → システム的には違和感があるが、デジタルツールに不慣れなユーザーの直感性を優先
ユーザーの実務を再現しながら操作することで、実装前に1-3日サイクルで6回の検証・改善を回せました。
例4: デザインフェーズでテスト観点を先回り
伴走したエンジニアが「この仕様だとテストで何が壊れるか」という後工程の視点で私のアウトプットをレビューしました。例えば「複数タブで別テナントのセッションを開いたとき、メモの書き込み先が混在しないこと」といった観点です。
デザインファイル・画面仕様書がコードと同じリポジトリにあるので、テスト観点がデザインのフェーズで組み込まれました。通常なら実装後のテストで初めて見つかり、仕様修正と再実装の手戻りが発生する問題を、前工程で潰せる構造です。
デザイナーとエンジニア、PdM。この多職種の組み合わせが、UIデザインにおけるフロントローディングとして機能しました。
5. 結果
約1.5ヶ月で以下を達成しました。
- PdMとのウォークスルーを6回実施
- アウトプット: 31画面、49のStory、39件のMDX (画面仕様書) を作成
- 131件の仕様の抜け漏れ・UX改善施策を発見し、すべて実装前に解決
131件の内訳:
| 種別 | 件数 | なぜ今回の方法で見つかったか |
|---|---|---|
| 仕様の検討もれ（未定義・矛盾） | 60件 | 定義しないと画面が動かないため、未決定の項目が構造的に露出した |
| UX改善 | 45件 | 実際に操作できる画面でPdMと業務を再現し、静止画では気づけない違和感を検出した |
| 実装誤り・既存との不整合 | 26件 | 本番コードを参照しながら作業したことで、既存実装との意図しない乖離に気づけた |
今までは実装フェーズまで持ち越されていた問題が、修正コストの低い前工程で出てきました。 副次的に、コードベースを理解したことで「この実装ならこのUXが実現できる/できない」をエンジニアと議論できるようになり、デザイナーとしての意思決定の質が変わったと感じています。
今後の検証
- フロントエンドへの繋ぎ込み:
- StorybookはFigmaと同じく中間成果物であり、FEの代替ではありません
- 担当FEからは「デザイナーの考えた最強のUI持ってこい」と言われており、仕様とUXの意思決定はデザイナーが、実装はFEが引き受けます
- Storybookのコードがどの程度そのまま流用されるかは現在検証中
- 再現性: 別のプロダクト・別のデザイナーへのプロセス展開を開始
6. 導入に何が必要か
このプロセスの成立に必要な条件と、飛び込んでみてわかった正直なところを書きます。
必要だったもの
私の試行錯誤を受け止めてもらえる環境がなければ、このプロセスは成立しませんでした。
- Claude Codeへのアクセス
- デザイナーだけでなく、エンジニア1名の伴走
- 最初から完璧を求めず、Sandbox環境での挑戦を許容するマインドセット
- 一定のデザインシステム（コンポーネントや状態パターンが構造化されたもの）が整備されていること
コードが書けないデザイナーが飛び込むと何が起きたか
恥ずかしながら正直に書きます。 私は入社3ヶ月半、Gitもまともに使ったことがない状態でStorybookでの画面仕様実装を始めました。プロトタイプ制作でOpusのトークンをメチャクチャに溶かし、Sandboxのディレクトリをぐちゃぐちゃにし、リンターエラーが出ているのにAIに聞いて無理やりpushしていました…
エンジニアの環境構築のおかげで、2ヶ月で251コミット・177ファイルを書けるようになりました。 詳しくはエンジニアの記事で説明されていますので、ぜひご覧ください！
Storybookでデザイナーが仕様を書く——自走を支えたエンジニアの伴走記録
得られたもの
- 手戻り工数の削減: Figma→実装の翻訳コストや差し戻しを削減
- 実装前の検証の質: 実務を再現した操作検証でエッジケースや状態定義の漏れを前倒しで潰せる
- デザインの意思決定の明確化: 「デザイン側が定義しきれずエンジニアが埋めたUI」をゼロにし、根拠のある実装を届けられる
終わりに: これはデザイナーの仕事なのか？
デザイナーがAIでコードを書き、エンジニアがUXを底上げし、PdMがプロトタイプを作る。職種の境界はどんどん溶けていて、「デザイナーとは何か」がわからなくなりつつあります。
Storybookを書くことがデザイナーの本質的な仕事かと聞かれたら、違うかもしれません。ただ、コードの側に踏み出して初めて見えたことがあります。 エラーをいつ出すか、データがないとき何を表示するか、デフォルトの並び順はどうするか… Figmaでは表現しきれなかったこれらを、今まで誰かが暗黙に決めていました。
境界を越えてみて初めて、自分が決めるべきだったことの輪郭が見えました。 手段がFigmaかStorybookかは本質ではなく、「ユーザーが触れるものに対して、曖昧にしない」ことが自分の責任だと思っています。 境界を越えると、居心地のいい場所は失います。その先に、もっと強い武器があります。一緒に踏み越えましょう！
