画面詳細
各画面のUI要素、動作仕様、エラー処理を定義します。
Tiptapエディタと自由項目で、プロジェクトに合った形式で記述できます。
なぜ画面詳細が必要か
よくある失敗パターン
- • 「ログイン画面」と書いてあるが、パスワードリセット導線がない
- • エラー時の表示が決まっておらず、エンジニアが即興で作る
- • デザイナーとエンジニアで「ボタンの位置」の認識が違う
- • 入力バリデーションのルールが曖昧で、終盤に仕様追加
画面詳細を事前に定義することで、「書いてあること」と「書いてないこと」の境界が明確になります。 実装前にレビューすることで、終盤の「これも必要だった」を防げます。
入力する項目
対象画面
画面遷移で定義した画面を選択します。
UI要素一覧
画面に含まれるUI要素（ボタン、入力欄、リストなど）を列挙します。
記入例：検索結果ページ
- • 検索バー: 上部固定、キーワード入力、クリアボタン付き
- • 絞り込みフィルター: カテゴリ、価格帯、在庫有無
- • ソート: 人気順、価格順、新着順
- • 商品カード: 画像、商品名、価格、評価
- • ページネーション: 1ページ20件、無限スクロール
動作仕様
ユーザーの操作に対する動作を記述します。
記入例
- 検索実行時:
- • 入力後0.5秒でサジェスト表示
- • Enterキーまたは検索ボタンで検索実行
- • 検索中はスケルトンローダーを表示
- • 結果表示は1秒以内（目標）
- 商品カードタップ時:
- • 商品詳細ページへ遷移
- • 遷移アニメーション: 0.3秒のスライド
エラー・例外処理
エラー時やエッジケースの動作を記述します。
記入例
- 検索結果0件の場合:
- • 「該当する商品が見つかりませんでした」メッセージ表示
- • 「キーワードを変えて検索」「人気の商品を見る」リンク表示
- 通信エラーの場合:
- • トースト通知「通信に失敗しました」
- • 「再試行」ボタン表示
- • 3回失敗でサポートへの問い合わせ導線
自由項目（Tiptap + カスタムフィールド）
プロジェクト固有の項目を自由に追加できます。
追加できる項目例
- • ワイヤーフレーム画像
- • アクセシビリティ要件（WCAG準拠レベル）
- • パフォーマンス要件（LCP、FID）
- • 多言語対応の注意点
- • A/Bテスト対象フラグ
Claude Code での操作例
あなた
「toishiに検索結果ページの画面詳細を追加して。 検索バー、フィルター、商品カードが必要。 検索結果が0件の場合のエラー表示も入れて」
AI
検索結果ページの画面詳細を作成しました。
【UI要素】
- 検索バー（上部固定）
- 絞り込みフィルター
- 商品カード一覧
【エラー処理】
- 0件時: 「該当する商品が見つかりませんでした」表示
動作仕様（検索の挙動、ページネーションなど）も追加しますか？
承認のポイント
承認者はここをチェック
- ✓ UI要素が網羅されているか（抜け漏れがないか）
- ✓ 動作仕様が具体的で、実装可能か
- ✓ エラーケースが考慮されているか
- ✓ ユーザー体験として自然か（ステップ数、操作性）
- ✓ 既存画面との一貫性があるか
ベストプラクティス
「書いてないこと」を明確にする
「今回は対応しない」項目も明記します。 例：「多言語対応は Phase 2 で対応」「ダークモードは対象外」
数値で定義する
「速く」ではなく「1秒以内」、「少なく」ではなく「3件まで」。 曖昧さをなくすことで、実装とテストが明確になります。
エンジニアと一緒にレビューする
仕様を書いた段階でエンジニアにレビューしてもらうと、 「これは技術的に難しい」「こうした方が簡単」というフィードバックが得られます。
なぜこの設計なのか
画面名、種別、紐付くユーザーニーズを明記 — 「この画面は何のためにあるか」を常に追跡可能
画面が増えると「この画面は何のため？」が分からなくなります。 各画面にユーザーニーズを紐付けることで、 「このニーズを満たすための画面」が明確になり、目的のない画面が生まれません。
紐付かない画面 = 不要な画面の可能性が高い
「なんとなく必要そう」で作った画面は、リリース後に誰も使いません。 全ての画面がユーザーニーズに紐付いていることを確認することで、 無駄な開発工数を削減できます。
UIコンポーネントレベルの仕様まで書く — 曖昧だとデザイナー/エンジニア間で認識ズレ
「検索フォームがある」だけでは、デザイナーとエンジニアで「検索フォーム」のイメージが違います。 「検索バー（上部固定、キーワード入力、クリアボタン付き）」まで書くことで、 実装前にレビューでき、終盤の「イメージと違う」を防げます。