imgui-ui-ux-engineering

Dear ImGui UI/UX エンジニアリング

目的と適用範囲

Dear ImGui を使ってプロフェッショナル向けツールのインターフェースを構築します。即時モードのモデルを中心に設計します。アプリケーションデータを唯一の信頼できる情報源とし、UI コードは現在のモデルを反映するとともに、ユーザーの意図をモデルに送り返します。Dear ImGui は、コンテンツ制作ツール、エディターやゲームのツール、デバッグパネル、運用画面、リアルタイムのビジュアライゼーションに特に適しています。一般消費者向け製品で完全なアクセシビリティ対応、RTL テキスト、または複雑なテキスト整形が必要な場合は、適合性を明示的に評価してください。[1] [2]

レビューを見た目だけの刷新として扱わないでください。機能の階層、操作コスト、エラーからの復旧、情報密度、技術的な正確さ、ビジュアルの一貫性をあわせて改善します。

リクエストを分類する

リクエストを、主なワークフローのいずれかに当てはめます。提供されたコード内に Dear ImGui の記載や根拠がない場合、使用フレームワークだと決めつけないでください。フレームワーク選定の評価は、明示的に依頼された場合にのみ提案します。情報不足が解決策を大きく左右しない場合は妥当な前提を置き、重大な曖昧さがある場合にのみ確認します。

リクエスト	主な成果物	最初に確認すること
新しいツールまたはエディター	情報アーキテクチャ、ワークスペースのシェル、プロダクション向け C++	ユーザーの役割、主要なタスク 3 つ、対象プラットフォーム
既存 UI の改善	監査、再設計の提案、対象を絞ったコード変更	スクリーンショットまたはコード、階層の問題、不足している状態
コンポーネント設計	振る舞いの仕様、状態マトリクス、ImGui の実装	データ、操作、空またはエラーの状態、キーボード操作
テーマまたはビジュアルアイデンティティ	デザイントークン、パレット、タイポグラフィ、テーマコード	タスク密度、ブランド上の制約、コントラスト要件
コードレビュー	優先順位を付けた指摘と安全な修正	ID、スタックの整合性、状態の所有権、入力、クリッピング、DPI、パフォーマンス

必須のワークフロー

1. コンテキストを把握します。 ユーザー、主なタスク、データ規模、画面サイズ、入力デバイス、密度の好み、破壊的な操作を特定します。
2. 階層を作成します。 主要な操作を常に見える状態にし、対象のタスクの近くに配置します。コンテキストに応じた操作は選択中のオブジェクトやインスペクターの近くに置き、使用頻度の低い設定はメニューや開閉コントロールに移します。各ビューについて、選択済み、空、読み込み中、エラー、未認証、完了の状態を定義します。
3. ワークスペースのシェルを選択します。 適切な場合は、コマンドバー、左側のナビゲーションまたはアセットペイン、中央の作業領域、右側のインスペクター、下部のログ／進捗領域、ステータスバーを使用します。パーソナライズによって実質的な価値が得られる場合にのみ、ドッキングとウィンドウのレイアウトを永続化します。選択した Dear ImGui のブランチ／バージョンが、使用するドッキング API に対応していることを確認してください。[2]
4. デザインシステムを構築します。 余白、角丸、境界線、タイポグラフィ、サーフェスのレイヤー、セマンティックカラーを一元管理します。まず templates/imgui_design_system.h.in を使用し、製品と密度の要件に合わせて調整します。
5. タスクを中心にコンポーネントを構築します。 組み込みウィジェット、テーブル API、標準的な操作を優先します。独自の描画リストコードは、独自の振る舞いやビジュアル表現が本当に必要な場合にのみ使用します。通常、ホバー中、操作中、選択中、フォーカス中、無効、読み込み中、エラーの各状態を設計します。
6. 操作方法を設計します。 キーボード操作、および該当する場合はゲームパッド操作、フォーカス、ショートカット、キャンセル、取り消しを検証します。生の入力は常に Dear ImGui に転送し、io.WantCaptureMouse、io.WantCaptureKeyboard、io.WantTextInput を使って、基盤となるアプリケーションにも入力を渡すかどうかを判断します。[2]
7. 技術的な監査を実施します。 ID の衝突、Push／Pop および Begin／End の対応、フレーム単位の割り当て、大規模リストのクリッピング、DPI の処理、コントラスト、バージョン固有の API を確認します。
8. ピクセルだけでなくタスクを検証します。 幅の狭いパネルと広いパネル、長いテキスト、データなし、数百件のレコード、処理の失敗、キーボードのみの操作をテストします。配置、操作へのフィードバック、復旧手順を確認します。

ワークスペースの構成

以下は、固定的なピクセル単位のテンプレートではなく、柔軟に適用できる構成システムとして使用してください。

領域	目的	実装ガイダンス
コマンドバー	頻繁に使うグローバルアクション、検索、ワークスペースの切り替え	アクション数を抑え、補助的なコマンドはメニューまたはコマンドパレットに移動してください。
ナビゲーションまたはアセットペイン	階層、コレクション、シーン、ファイル、フィルター	検索、折りたたみ可能なグループ、選択状態の可視化、小さな件数表示を用意してください。
中央の作業領域	キャンバス、テーブル、タイムライン、チャート、またはメインエディター	ここに最大の面積とコントラストを割り当て、不要な装飾を取り除いてください。
インスペクター	選択したオブジェクトのプロパティとコンテキストに応じたアクション	項目をメンタルモデルに沿ってグループ化し、ライブプレビューと安全なリセット操作を用意してください。
補助領域	ログ、パフォーマンス、ジョブキュー、課題一覧	不要なときに閉じたり折りたたんだりできるようにしてください。
ステータスバー	接続、選択、プロセス、座標、またはパフォーマンスの状態	簡潔で、リアルタイムに更新され、操作可能な内容にしてください。

密度と階層

タスクの頻度とデータの規模から密度を選び、サーフェスの高さ、タイポグラフィ、余白、色、配置によって優先度を表現してください。色だけを意味の伝達手段にしないでください。密度に関する詳細なガイダンスとコンポーネントの仕様については、references/design-playbook.md を参照してください。 [5]

適切なコンポーネントを選ぶ

コンポーネント	用途	使用を避ける場面
テーブルまたはアセットブラウザー	並べ替え、フィルタリング、複数列に対応したデータ	数千件のレコードをカードとして表示する
インスペクター	選択したオブジェクトの編集可能なプロパティ	無関係なグローバル設定
メトリックカード	少数の重要な KPI と傾向	画面上のすべての数値
コマンドパレット	多数のコマンドと熟練者向けのキーボード操作ワークフロー	中核となるアクションをメイン UI から隠す
モーダル	確認や、短時間で完了する焦点を絞った判断	長期間使用するエディターや包括的なフォーム
トースト	簡潔な成功フィードバックと取り消し操作	重大なエラーを伝える唯一の手段
空状態	初回利用時や、フィルター結果が空の場合	理由が分からない空のパネルにユーザーを置き去りにする

詳細なレイアウトパターン、コンポーネントの仕様、状態表示の文言、またはレビュー基準が必要な場合は、references/design-playbook.md を参照してください。具体的な出力モデルによって一貫性を高められる場合は、レビューまたは変更前後の提案を作成する前に references/worked-example.md を参照してください。

Dear ImGui の実装ルール

状態、識別子、構造

アプリケーションモデルを唯一の信頼できる情報源として維持してください。開いているペイン、一時的なフィルターテキスト、ドラッグプレビューなど、表示に固有の状態のみを UI 状態として保存してください。ポインターを使う表示フィールドについては、モデルが null 以外であることを不変条件として強制し文書化するか、UI からのすべての読み取りを null 安全な表示アダプター経由にしてください。暗黙的な nullable 文字列の慣習に依存してはいけません。

繰り返し表示されるウィジェットには、一意の ID を保証してください。## を使用して非表示のサフィックスを追加し、ループや動的なコレクションでは安定したオブジェクトキーとともに PushID()／PopID() を使用し、表示ラベルが変わっても ID を安定させるには ### を使用してください。同じスコープでラベルを繰り返すと、衝突が発生します。 [2]

すべての Push* と対応する Pop*、すべての Begin* と対応する End* の呼び出しを必ず対応させてください。各 API の仕様に従ってください。たとえば、ウィンドウが現在折りたたまれているという理由だけで、必須の End() を省略してはいけません。

レイアウトと大規模データ

固定ピクセル座標の使用は、最後の手段にしてください。BeginTable、子領域、利用可能な幅、柔軟な列、スペーシングトークンを使ってレイアウトを構成してください。インスペクターのラベルと入力欄は2列に揃え、サポートする最小幅のパネルでテストしてください。

大規模なコレクションでは、フィルター済みの安定した ID のビューを構築し、ImGuiListClipper を使用して表示中の行を描画してください。並べ替え可能な列を公開する場合は、ImGuiTableSortSpecs を処理してください。実際のモデルの並べ替えを伴わない Sortable フラグは、不完全な操作です。並べ替え方向、適用中のフィルターの概要、選択状態の可視化、意味のある空の結果を提供してください。

テーマ、タイポグラフィ、DPI

測定値を一元管理します。パディング、間隔、角丸は小さなスケールから導出します。任意の色調を各パネルに割り当てるのではなく、WindowBg、ChildBg、PopupBg、境界線を使ってレイヤーを分けます。

通常のテキストでは4.5:1以上、大きなテキストでは3:1以上のコントラスト比を目標にします。[4] デフォルトのフォントがツールの想定サイズで読みづらい場合は、適切なフォントを選択します。FontScaleDpi の管理元は必ず1つにします。テンプレートのホスト管理ポリシーを使ってホストがスケールを提供するか、ドッキングブランチの io.ConfigDpiScaleFonts がモニターの DPI 変更に応じて自動更新する場合は、Dear ImGui 管理ポリシーを選択します。コンテンツスケールが変わる場合は、引き続きスタイルをリセットし、サイズ／パディングのスケーリングに ScaleAllSizes() を適用します。新しい API に依存する前に、対象バージョンとバックエンドの機能を確認します。[3]

キーボード、ゲームパッド、アクセシビリティ

ImGuiConfigFlags_NavEnableKeyboard を有効にし、必要に応じて ImGuiConfigFlags_NavEnableGamepad も有効にします。Tab／Shift+Tab による移動、フォーカスの可視性、Escape によるキャンセル、Enter による確定、重要なアプリケーションのショートカットをテストします。キーボードフォーカスの初期位置を変更するのは、明示的なナビゲーション要求またはプログラムによる選択要求がある場合に限ります。選択中の行に毎フレームフォーカスを再設定しないでください。テーマの変更を完全な解決策として提示するのではなく、Dear ImGui に組み込まれたアクセシビリティ機能と、国際化に関する制限を明確に伝えます。[1]

フォーカス、ホバー、選択状態は視覚的に区別します。曖昧なアイコンや略語を補足するためにツールチップを使います。必須タスクの説明をツールチップに委ねないでください。コントロールが無効な場合は、その理由を簡潔に示します。

カスタム描画とコンポーネントの契約

カスタム描画リストのコードを書く前に、組み込みウィジェット、テーブル、選択可能項目、ツリー、ポップアップ、子領域を組み合わせれば要件を満たせるか確認します。カスタムコントロールごとに、次の項目を定義します。

1. 表示境界とヒット領域を同じ座標モデルで定義します。
2. 一意の ID を生成し、通常、ホバー、アクティブ、選択中、フォーカス中、無効、読み込み中、エラーの各状態での動作を指定します。
3. クリック、ドラッグ、キャンセル、データなしの場合の動作を文書化します。
4. クリッピングを守り、大量のデータでは表示範囲内のジオメトリのみを生成し、フレーム間で保持する割り当てを最小限に抑えます。
5. 色、間隔、フォントには一元管理されたトークンを使います。コンポーネントに任意の視覚的定数を埋め込まないでください。
6. 狭い／広いパネル、低／高 DPI、すべての操作状態で視覚的に確認します。

成果物の要件

成果物	必須項目
設計提案	ユーザー／タスク一覧、画面領域、優先順位、状態マトリクス、インタラクションに関する注記、実装順序
C++ 実装	テーマトークン、コンポーネント関数、ID 戦略、状態の所有権、空状態／エラー状態、バージョンの前提
再設計	変更前／変更後の問題点の表、提案する構成、測定可能な改善目標、対象を絞った変更
コードレビュー	Critical / High / Medium / Low の優先度、根拠、影響、修正、検証手順

ドック領域を中心としたワークスペースのシェルには templates/imgui_panel_skeleton.cpp.in を、トークンを一元管理するシステムには templates/imgui_design_system.h.in を使用してください。ベンダー版またはバージョンを固定した Dear ImGui プロジェクトに、バージョン依存のコードをコピーする前に references/version-notes.md を読んでください。C++ ソースをレビューまたは生成する際は、よくある直接的な Begin／End および Push／Pop の対応ミスを検出するため、scripts/check_imgui_cpp.py <source...> を実行してください。このスクリプトは対象を限定した静的チェックであり、コンパイルやランタイムテストの代替ではありません。自動化された構造、意味、コントラスト、静的チェッカー、およびコンパイルの回帰チェックを実行するには、python3 scripts/run_quality_suite.py を実行してください。通常の実行では毎回、一時的な公式 v1.92.0 および master ソースを取得し、両方に対してテンプレートをコンパイルします。同梱の意味参照応答は 30/30 点を獲得する必要があります。ターゲットモデルの出力を同じ契約に照らして評価するには、--semantic-responses RESPONSES.json を指定してください。製品フォークを検証する場合は、さらに --imgui-dir /path/to/vendored/imgui を指定してください。--skip-official-revisions は、明示的にオフラインで診断を行う場合にのみ使用してください。リリース判定には使用できません。このスキル自体を改訂または回帰テストする場合に限り、evals/quality-suite.md および evals/failure-mode-regressions.md を使用してください。後者では、一般的な出力品質ではなく、具体的な状態、スコープ、フォーカス、DPI に関する問題をテストします。

リリース品質ゲート

• 主要なタスクへの入口は、見つけやすく、視認でき、利用する場所の近くにありますか？
• 選択中、ホバー中、フォーカス中、無効、エラー、読み込み中、空の各状態を見分けられますか？
• 主要なアクションは、二次的なアクションや破壊的なアクションと明確に区別されていますか？
• ショートカット、フォーカスの移動、Escape／キャンセル、入力キャプチャは適切ですか？
• 大量のデータを扱うテーブル／リストで、フィルタリング、ソート、選択、検索結果なしの状態に対応できていますか？
• ウィジェット ID は一意で、Push／Pop および Begin／End の呼び出しは対応が取れていますか？
• NULL 許容のモデル値を安全に描画でき、デフォルトフォーカスの移動は明示的な要求があった場合にのみ行われますか？
• コントラスト、フォントの読みやすさ、DPI、狭いパネル、長いコンテンツをテストしましたか？
• クリッピング、回避可能なメモリ割り当て、プロファイリングを検討しましたか？
• scripts/run_quality_suite.py は、サポート対象のベンダー版 Dear ImGui ヘッダーの各リビジョンに対して合格しましたか？
• 該当する場合、アクセシビリティおよび国際化の制限を明記していますか？

参考資料

[1] Dear ImGui 公式リポジトリ

[2] Dear ImGui FAQ：パラダイム、ID、入力キャプチャ、ナビゲーション、ドッキング

[3] Dear ImGui：フォント、DPI スケーリング、アイコン

[4] W3C WCAG 2.2：コントラスト（最低限）の理解

[5] Nielsen Norman Group：ユーザビリティの 10 原則