storyboard

ストーリーボード

ストーリーボードとは、作業範囲に含まれるすべての UX 画面をひとつのビューにまとめた、レビュー可能な単一の HTML ページです。既存のモックが信頼でき、安全に読み込める場合に限り、サンドボックス化された <iframe> 要素として埋め込みます。それ以外の場合は、ラベル付きの静止画像を使用します。ページ上部には、ユーザーが各画面をどのように移動するかを示すフロー図を配置します。ギャップカードは、まだ作成が必要なモックを示します。モックごとの監査チェックリストにより、レビュー担当者は具体的な修正を承認したり、指摘したりできます。

目的： 「タブをいくつも開いて、頭の中でフローをつなぎ合わせる」デザイン監査を、「ページをひとつ開いてスクロールする」形に変えます。プラン文書、監査メモ、PR の説明など、記録しているテキスト形式の意思決定記録と組み合わせてレビューできる成果物を提供します。

作成するタイミング

• 関連する画面や状態が十分にあり、個別にレビューすると遷移、不整合、ギャップが見えにくくなる場合。 例：サインアップ → 認証 → オンボーディング、または破壊的な操作と復旧状態を含む設定フロー。
• 計画中の作業単位に対して、まとめてレビューする価値が維持コストを上回る場合に限り、作業前に作成します。 画面数だけを理由に、別の成果物を作成する必要はありません。
• 単一機能の監査： ひとつの機能が複数の状態にまたがる場合（3 つ以上のステップにわたる、読み込み中／空／データあり／エラー状態を含むフロー）。
• ユーザーから明示的に依頼された場合： 「すべてをひとつの場所にまとめて」「フロー全体を見せて」「モックを監査して」「これらをまとめて確認したい」など。
• 新しいモックを作成する前。 まず既存のモックをストーリーボードにまとめることで、ギャップが視覚的に明らかになり、作成に取りかかる前にギャップごとのブレインストーミングを促せます。

作成しないタイミング

• モックがひとつだけの作業（設定ページの文言を単発で修正する場合など）。モックを開き、impeccable パイプラインを実行すれば完了です。
• UX 画面を伴わない、API／データ移行／運用だけの作業。モックがなければ、ストーリーボードにまとめるものもありません。
• 作業範囲が確定する前の、探索的な作業や使い捨ての作業。ストーリーボードはレビュー用の成果物なので、まずレビューする価値のあるものが必要です。
• すでに完全に実装済みの機能。ストーリーボードは実装前に作成するものです。事後に視覚的なレビューが必要な場合は、代わりにライブ画面に対して critique スキル（impeccable ファミリーの外部スキル。インストールされていない場合は省略）を実行します。

スキルが収集する入力情報

HTML の作成に取りかかる前に、次の情報を集めます。

1. 作業範囲コードとタイトル。 例：Onboarding v2 — reset regression、Settings page — profile + notifications、M3 · address book。ページタイトルとパンくずリストに使用します。
2. 作業範囲内の既存モック。 プロジェクトの design-mocks フォルダー（または同等の場所）を確認し、この作業範囲に関連するパスを集めます。既存のモックはそれぞれ、埋め込みパネルになります。
3. ユーザーフロー。 ユーザーがたどる状態と遷移の順序。<pre> ブロック内に ASCII で描画します。ギャップは目立つ色やグリフで示します。
4. ギャップ。 作業範囲で必要だが、まだ用意されていない新しいモック。ギャップごとに、作成前にユーザーが回答すべきブレインストーミングの質問を含むカードを用意します。質問のないギャップは設けません。
5. 上流／隣接する画面。 作業範囲には含まれないものの、コンテキストを提供する画面（例：このフローの後にユーザーが移動する画面）。iframe の高さを低めにして埋め込みます。
6. 関連ドキュメントへのリンク。 プラン項目、デザインブリーフ、関連する ADR、親インデックスページ。

出力先

ストーリーボード HTML は、プロジェクト内の既存のモックまたはリリース計画用フォルダーに、モックと同じ場所へ配置します。相対 iframe パスが正しく機能する場所を選んでください。一般的な配置先は次のとおりです。

• apps/<app>/design-mocks/<scope>-audit.html
• design-mocks/<scope>-storyboard.html

ストーリーボードは永続的な記録ではなく、レビュー中に使用する成果物として扱います。使用中はリポジトリの成果物配置ルールに従い、レビュー結果がリリースされたとき、または前提が更新されたときに削除してください。ただし、現在の課題のために担当者が継続して保守する場合は除きます。アーカイブには Git の履歴を使用します。

リポジトリ内の他の成果物の命名規則に合わせます。モックのマニフェストやインデックスページがある場合は、ストーリーボードへの目立つリンクを追加し、見つけやすくします。

必須の構成（この順序）

ストーリーボードはパターンであり、テンプレートではありません。すべてのストーリーボードに、以下のセクションをこの順序で設けます。各セクションの内容は対象範囲によって異なります。

1. パンくずリスト

親インデックス（モックのマニフェスト、計画インデックスなど）への戻りリンクです。

2. ヘッダー

• 対象範囲コード（例：Onboarding v2、またはプロジェクトで使用しているもの）を大文字のトラッキングスタイルで表示する小さなピル。
• 対象範囲を表すセリフ体のディスプレイタイトル。
• このページの目的を示す、1文の短いサブ見出し。
• 対象範囲の説明と、項目の README、デザインブリーフ、関連する ADR へのリンクをまとめた段落。

3. フロー図

• ASCII 図には必ず <pre> を使い、<div class="whitespace-pre"> は使わないでください。 Prettier は後者を再フォーマットしてレイアウトを壊しますが、<pre> なら影響を受けません。これは厳守してください。違反すると、ページが壊れた状態でリリースされます。
• 対象範囲におけるユーザーの流れを、ASCII のボックスと矢印で示します。
• インラインで色分けします。既存のモックがあるノードには1色、ギャップには別の色（ユーザーの目を引くよう、できればプロジェクトの「アクション」カラー）、関連するコンテキスト画面には控えめな色を使います。
• 🆕 GAP のようなインライン記号を使ってギャップを示し、すばやく見つけられるようにします。

4. 既存のモック（横並び）

• ステータスバッジ（「✓ … に含まれる」）付きの見出し。
• レスポンシブなグリッド（通常はデスクトップで3列、モバイルでは1列に折り返し）。モックごとに1セルを配置します。
• 各セルには以下を含めます。
  • 小さなバッジとファイル名のヘッダー。
  • プロジェクトの見出し用タイポグラフィを使ったモック名。
  • 短い説明（1～2文）。
  • 高さを固定したサンドボックス化された <iframe>（主要なモックでは780px、関連画面では640pxが適しています。プロジェクトに合わせて調整してください）、またはドキュメントに記載された静的な代替手段。
  • rel="noopener noreferrer" を指定した「新しいタブで開く ↗」リンク。
  • 監査チェックリストカード — モックに関連する、Impeccable の各専門領域について確認する項目：/critique、/clarify、/audit、/polish、/adapt、/impeccable harden、/distill。さらに、対象範囲固有の質問（「編集操作の見つけやすさは十分か？」「ローディング状態はモック化されているか？」など）。

5. 遷移／状態のギャップ

モック化すべきものの、明確でない要素（アクション後のトーストや成功確認など）がある場合は、「? 不明」というセクションを設け、ブレインストーミング用の質問を箇条書きにします。曖昧さを残さず表面化させるほうが、見落としを防げます。

6. 埋めるべきギャップ

• 「🆕 次に作成」バッジ付きの見出し。
• レスポンシブなグリッド。ギャップごとに1セルを配置します。
• 視覚的に区別できる背景／境界線（プロジェクトの「アクション」カラーの淡色を使用）。
• 各セルには以下を含めます。
  • 作成するモックのバッジとファイル名。
  • プロジェクトの見出し用タイポグラフィを使った表示名。
  • モックで表現する内容の説明。
  • ブレインストーミング用の質問 — 順不同のリスト。各項目で、モックの作成前に決めるべきことを1つ明示します。入口、形状（シート／ダイアログ／ページ）、フィールド一覧、エッジケース／エラー状態、既存パターンとの統合、破壊的なアクションの意味、キャンセル時の動作を網羅します。

7. 上流／関連画面（コンテキスト用）

• 小さめの iframe。
• 3列のグリッド。
• それぞれに「この対象範囲には含まれません。コンテキストとして掲載しています」と表示します。
• この対象範囲からユーザーが移動する画面（後続で内容が表示される詳細ページ）や、この対象範囲に至る上流のフローを示します。

8. 提案する手順

このストーリーボードからコード実装に至るまでの手順を、順序付きリストで説明します。

1. ユーザーがこのページを確認し、既存のモックを承認するか、具体的な修正点を指摘します。
2. 各ギャップカードのブレインストーミング用の質問に回答します。
3. /impeccable craft を使ってギャップを埋めるモックを作成し、デザインパイプライン（/shape → /critique → /layout → /clarify → /polish、さらにレスポンシブ対応には /adapt、エッジケースには /impeccable harden）を通して確認します。
4. 監査で指摘された既存のモックを修正します。
5. リポジトリで承認されている提出ワークフローを通じて、レビュー済みのモックと監査メモを保存します。実装を開始します。

9. フッター

メタ情報の行：対象範囲コード · 最終更新日 · 相互レビュー用リンク。

スタイルの規約

プロジェクトで既に使われているデザイントークンとレイアウトツールを使用してください。新しいものを独自に作らないでください。プロジェクトで Tailwind を使っている場合は、設定済みのユーティリティを再利用してください。コンパイルされないプロジェクトに Tailwind クラスを出力しないでください。ローカルの規約がない場合は、フレームワークに依存しない、最小限のインライン CSS による代替手段を使ってください。具体的には、次のとおりです。

• 色： アクション、テキスト、背景、存在、間隔、不確実性の各ロールを、ローカルのセマンティックトークンに対応させてください。代替手段では、ページに必要な最小限のアクセシブルな色だけを定義できます。
• フォント： ローカルの本文用および見出し用フォントスタックを再利用してください。ストーリーボードだけのために、セリフ体やフォント依存関係を追加しないでください。
• バッジ： プロジェクトのセマンティックなステータスカラーを使い、色だけが情報の手がかりにならないよう、テキストまたはグリフのラベルを付けてください。
• Iframe のフレーム： 高さを固定し、枠線、角丸、薄い影を付けてください。グリッド全体で視覚的な重みを揃えてください。
• コンテナー： ローカルのページシェル／コンテナーパターンを使ってください。フレームワークに依存しない代替手段では、max-width、margin-inline: auto、レスポンシブなパディングを使えます。

ローカルのコードベースで既に使われているモックまたはインデックスページのスタイルに合わせてください。新たに考案するのではなく、同階層のモックから <style> ブロックをコピーしてください。

埋め込みの安全性

モックや URL がリポジトリ内にある場合も含め、すべて信頼できないコンテンツとして扱ってください。相対パスで、レビュー済みのリポジトリが所有するリンク先を優先してください。認証情報を含む URL や、非公開のサードパーティーページは絶対に埋め込まないでください。各 iframe に sandbox 属性を指定し、そのモックで必要だと明確に確認できる機能だけを許可してください。静的モックにトークンは不要です。インタラクティブなモックでは一般に allow-scripts が必要ですが、信頼できない同一オリジンのコンテンツには allow-scripts と allow-same-origin の両方を付与しないでください。その組み合わせが本当に必要な場合は、分離されたオリジンから配信するか、静的な代替手段を使ってください。

ストーリーボード自体に制限の厳しいコンテンツセキュリティポリシーを追加してください（通常は、セルフホストのフレーム、画像、スタイルのみとし、ローカルで必要性を説明できる例外だけを最小限加えます）。モックを動作させるだけのために、allow-top-navigation、ポップアップ、フォーム、ダウンロード、カメラ、マイク、クリップボードへのアクセスを追加しないでください。サンドボックス化や CSP によって忠実に表示できない場合は、その制限を明示し、レビュー用ページの保護を黙って弱めるのではなく、静的な情報源を使用してください。

Prettier の安全性

経験から学んだ 3 つのルール：

1. ASCII または複数行の整形済みコンテンツは、必ず <pre> で囲んでください。 Prettier は <div class="whitespace-pre"> 内の HTML を再整形し、レイアウトを崩します。<pre> はその影響を受けません。
2. Markdown テーブルの列幅にこだわらないでください。 テーブルを書いたら、Prettier に再調整させ、その状態でコミットしてください。
3. コミット前に、ストーリーボードファイルに対して prettier --write を実行してください。 プロジェクトに Prettier のコミット前フックがあれば、いずれにせよ検出されますが、事前に整形しておくほうが早く済みます。

規約への統合

ストーリーボードを作成したら、次の手順を行ってください。

1. プロジェクトのモック一覧またはインデックスページで、ストーリーボードへのリンクを追加してください。 現在有効な間は、「アクティブな監査」などのセクションに掲載します。
2. 進行中の意思決定資料（計画、監査メモ、PR の説明など）から、視覚的な補足資料として参照してください。
3. ストーリーボードを削除または置き換えたら、アクティブなリンクを削除してください。長期的に有効な設計上の制約は、継続して管理される製品ドキュメントまたはテストに反映してください。

必須事項

• ライブでレンダリングされたモックを優先してください。 信頼できるソースが埋め込み可能で、安全に読み込める場合は iframe を使用してください。信頼できるソースが静的なモックしかない場合は、画像を埋め込み、非インタラクティブであることを明記し、操作できない状態を記録してください。
• ギャップにはブレインストーミングの質問が必要です。 質問のないギャップカードは役に立ちません。各ギャップは、ドラフト作成前に意思決定を促すものです。
• ページは1つにし、ツリーにはしないでください。 リンクツリーを移動するより、1ページをスクロールするほうが効率的です。範囲が広すぎてページが読みにくくなる場合は、サブフローごとに分割しますが、分割後もそれぞれ1ページにしてください。
• チェックリストは実質を伴うものであり、飾りではありません。 監査チェックリストの各項目は、実際の設計上の取り組みに対応しています。レビュアーはチェックリストをレビューの指針として使い、エージェントはその後の作業の指針として使います。実際には実行されない /critique を記載しないでください。

アンチパターン

❌ 静的なモックをライブの根拠として提示する。 静的画像は、利用可能な信頼できるソースがそれしかない場合には有効ですが、非インタラクティブであることを明記する必要があり、スクロール、遷移、フォーカス、実行時の状態を証明することはできません。

❌ ギャップカードに「TODO: ブレインストーミングの質問を追加」と書く。 質問に回答していないギャップには、このスキルの価値がありません。今すぐブレインストーミングを行うか、カードを削除してください。

❌ ストーリーボード用に独自のデザイントークンを作る。 ストーリーボードはプロジェクトに馴染むものにしてください。元のモックと同じ Tailwind の色、フォント、シャドウを使用します。

❌ スクロール可能な1ページではなく、ナビゲーションツリーにする。 ストーリーボードの価値は「すべてが1か所にある」ことです。サブページのツリーでは、その価値が損なわれます。1ページが読めないほど長くなる場合に限って分割し、その理由を記録してください。

❌ ASCII 図に <div class="whitespace-pre"> を使う。 Prettier は内部の HTML を再フォーマットし、図を壊します。必ず <pre> を使用してください。

❌ ストーリーボードのレビュー前に新しいモックを作る。 ストーリーボードのブレインストーミング用の質問が意思決定を促します。先にモックを作ると、誤っているかもしれない答えに前もって固執することになります。

呼び出し方法

ユーザーが /storyboard <scope> と入力するか、トリガーフレーズのいずれか（frontmatter の説明を参照）を依頼します。このスキルは次の処理を行います。

1. 関連する項目／機能のドキュメントと、既存のモックマニフェスト項目を読み込みます。
2. 既存のモック、フロー、ギャップ、隣接する画面を収集します。
3. 各ギャップについてブレインストーミングの質問を作成します（回答はせず、ユーザーに委ねます）。
4. HTML ファイルをプロジェクトの正式なパスに作成します。
5. モックマニフェスト／インデックスページが存在する場合、アクティブな監査へのリンクを追加します。
6. ユーザーがブラウザーで開けるよう、ファイルパスと簡潔な概要を報告します。

関連スキル

• impeccable ファミリー（/shape、/critique、/layout、/clarify、/audit、/polish、/adapt、/impeccable harden、/distill）— pbakaus/impeccable の外部スキルです。監査チェックリストはこれらを参照し、ギャップモックの作成手順ではこれらを実行します。harden は /impeccable のサブコマンドとしてのみ存在し、単独のスキルではない点に注意してください。インストールされていない場合は、実際に実行する分野のみを記載してください（「必須事項」の「チェックリストは実質を伴うものであり、飾りではありません」を参照）。
• story-splitting — ストーリーボードから、その機能の範囲が広すぎる、または実装前にフロー、役割、状態、インターフェース、データ、ルール、品質レベルごとに分割する必要があると分かった場合に使用します。
• planning — 範囲を実装可能な単位に分割した後、リポジトリが管理する計画成果物を補完するために使用します。ローカルの管理元がなく、ファイルの作成が許可されていない場合に限り、計画スキルの代替としてルートの plans/ を使用します。
• find-gaps — ストーリーボードの作成後に使用し、不足している状態、未回答のブレインストーミングの質問、不明確な遷移を、具体的な受け入れ基準またはモック状態の仕様に変換します。
• expectations — ストーリーボードの監査で長期的に活用できる学びが明らかになった後、その内容をリポジトリの最新のガイダンス、承認済みの決定事項、用語集、ソース、またはテストに反映します。

クイックリファレンス

/storyboard <scope>
│
├─► GATHER
│   ├─ Scope code + title
│   ├─ Existing mocks in scope
│   ├─ User flow (sequence of states + transitions)
│   ├─ Gaps (new mocks needed)
│   └─ Adjacent surfaces (upstream / downstream context)
│
├─► PRODUCE (<scope>-audit.html)
│   ├─ Breadcrumb
│   ├─ Header (scope code + title + link row)
│   ├─ Flow diagram (<pre>, colour-coded, glyphs for gaps)
│   ├─ Existing mocks (3-column grid, iframes + audit checklists)
│   ├─ State gaps ("? unclear" + brainstorm questions)
│   ├─ Gaps to fill (brainstorm-question cards per gap)
│   ├─ Upstream/adjacent (context iframes at smaller height)
│   ├─ Proposed sequence (ordered list)
│   └─ Footer (meta)
│
├─► WIRE UP
│   ├─ Link from mocks manifest / index page
│   ├─ Reference from plan / audit markdown
│   └─ Reference from feature README
│
└─► USER REVIEWS
    ├─ Answers brainstorm questions per gap
    ├─ Approves existing mocks (or flags fixes)
    └─ Skill produces gap mocks via /impeccable craft

経験則：

• 維持管理されている正式な情報源であり、安全に表示できる場合はライブ iframe を優先します。表示できない場合は、ドキュメントに記載された静的な正式情報源へのフォールバックを使用します。
• すべてのギャップには、アイデア出しのための質問があります。
• ツリーではなく、1 ページにします。
• ASCII には <pre> を使用します。<div class="whitespace-pre"> は使用しないでください。
• プロジェクト既存のデザイントークンを使用します。