tui-design

TUI と CLI の設計

ターミナルソフトウェアは、落ち着きがあり、予測しやすく、高速で、媒体の特性に誠実なものとして設計してください。このファイルは、ワークフローと横断的な契約として扱います。詳細なガイダンスは、それを担当する唯一のリファレンスから読み込み、ここで再構成したり繰り返したりしないでください。

回答する前に参照先を決める

必要な内容	権威あるリファレンス
Go、Bubble Tea、Lipgloss、Bubbles、tview、gocui	references/ecosystem-go.md
Rust、Ratatui、crossterm、Cursive	references/ecosystem-rust.md
Python、Textual、Rich、prompt_toolkit、urwid	references/ecosystem-python.md
TypeScript/JavaScript、Ink、OpenTUI、Clack、Inquirer	references/ecosystem-typescript.md
単発コマンド、引数、ストリーム、終了コード、自動化	references/cli-basics.md
レイアウト、バッファー、境界線、階層、色、情報密度、レスポンシブ動作、テーブル、テーマ、アクセシビリティ（スクリーンリーダー、プレーンモード、動き）	references/visual-patterns.md
キー、フォーカス、ナビゲーション、モード、フォーム、マウス、確認、取り消し、OSC 機能	references/interaction-patterns.md
ケーススタディ：lazygit、k9s、fzf、btop、helix、yazi、atuin	references/exemplar-apps.md
スクリーンショットまたはデモ録画	インストール済みの場合は vhs-cli-demos スキル。それ以外の場合は references/cli-basics.md → デモ録画

タスクに必要なリファレンスだけを読み込んでください。プロンプトでフレームワークまたはエコシステムが指定されている場合は、API、ライフサイクル、実装、テストに関する説明をする前に、必ずそのエコシステムのリファレンスを読み込んでください。エコシステム固有の詳細は、各エコシステムのリファレンスが担当します。ビジュアルとインタラクションに関する領域は、すべてのエコシステムでそれぞれのパターンリファレンスが担当します。代表的なアプリは根拠や着想として扱い、パターンリファレンスの代わりにはしないでください。

言語が指定されていない場合、エコシステムの選択が回答や実装を大きく左右する場合に限り、質問してください。それ以外の場合は、妥当な推奨を示して進めてください。洗練された単一バイナリには Go、制御性と信頼性には Rust、迅速なプロダクト開発には Python、React または npm での配布がすでに有利な場合には TypeScript を選びます。

まずプロダクトを分類する

フレームワークやレイアウトを選ぶ前に、出力の契約を決めてください。

プロダクトの形態	デフォルトの契約
単発 CLI	ライブのフルスクリーン UI は使用しません。結果は安定した stdout に、診断情報は stderr に出力し、意味のある終了コードを返します。cli-basics.md を読み込みます。
呼び出して選択し終了するツール	シェルのコンテキストが重要な場合は、インライン表示を優先します。インタラクティブな表示要素は stderr または /dev/tty に、選択結果は stdout に出力します。大きなプレビューや作業セットに安定した表示領域が必要な場合に限り、フルスクリーンを使用します。
フルスクリーンセッション	代替画面と安定した空間モデルを使用します。ターミナルの復元、サイズ変更、一時停止、再描画の動作をプロダクト要件として扱います。

次に、ワークフローの形を決めます。永続パネル、Miller カラム、ドリルダウンスタック、ダッシュボード、IDE 風ペイン、オーバーレイ、タブのいずれかを選び、visual-patterns.md に照らして確認してください。コードを書く前に、初期、読み込み中、空、部分表示、成功、エラー、切断、最小サイズの各状態とレイアウトをスケッチします。

タスクを進める

1. プロダクトの形態と stdout/stderr の契約を分類します。
2. ユーザーの主要な操作ループと、最もよく使われる 5～8 個の操作を特定します。
3. エコシステムを選び、そのリファレンスと関連するパターンリファレンスを読み込みます。
4. 広いサイズ、標準サイズ、狭いサイズ、最小サイズでのレイアウトと状態遷移をスケッチします。
5. エコシステム固有のネイティブなアーキテクチャで実装し、フレームワークが対応する場合は、状態、更新、イベントの処理を描画から分離します。
6. ライフサイクルのクリーンアップ、入力方法の見つけやすさ、出力の動作、幅への対応、非同期処理を確認します。
7. まず最も低コストで安定したレイヤーをテストし、次に描画フレームをテストします。その後、統合リスクに見合う場合に限り、小規模な PTY スモークテストを行います。

設計に関する質問には、説明より先に推奨を示してください。実装では、新しいフレームワークや抽象化を導入する前に、既存のアーキテクチャと依存関係を確認してください。レビューでは具体的な所見を挙げ、ユーザーへの害に応じて変更の優先順位を付けてください。

画面全体に関わる次の契約を守る

ターミナルのライフサイクル

• 全画面セッションでは代替画面を使用し、範囲が限定されたワークフローや一度きりのワークフローは、可能な限りインラインに表示します。
• ターミナルのクリーンアップは、フレームワークによる管理を優先します。エラーやパニックを含む、あらゆる終了経路で、raw モード、画面バッファー、カーソル、入力モードを復元します。フレームワークがすでに管理している場合は、独自のシグナル処理を追加しないでください。
• リサイズ時は、現在のフレームまたはウィンドウサイズに合わせて再レイアウトします。レイアウト処理の負荷が高い場合に限り、連続して発生するリサイズイベントをまとめます。
• 最終終了と一時的な引き継ぎは、異なる境界として扱います。エディター、シェル、またはサポートされている一時停止の場合は、フレームワークの引き継ぎ API を優先します。UI の入力を一時停止し、シェルで使える状態にターミナルを復元して待機した後、モードに再入し、外部から変更されたデータを再読み込みして、画面全体を強制的に再描画します。再描画で更新されるのは現在のモデルの表示だけで、変更されたデータは更新されません。再開が必要なアプリを最終アンマウントしないでください。また、POSIX シグナルが Windows に存在するとは限りません。
• ログやデバッグ出力は、TUI が占有する画面に表示しないでください。ファイル、フレームワークのコンソール、または独立した診断用ストリームを使用します。

描画、データ、パフォーマンス

• UI／イベントスレッドをディスク、ネットワーク、サブプロセスの処理でブロックしないでください。コマンド、メッセージ、タスク、チャネル、またはフレームワークイベントを通じて結果を返します。
• 入力、データ、リサイズ、または意図的なタイマーイベントが発生したときに描画します。状態に変化がないのに無条件のループで再描画しないでください。
• バイト数、コードポイント数、len()、JavaScript の文字列長ではなく、ターミナル上のセル幅を測定します。CJK 文字、結合文字、絵文字をテストしてください。
• 数百行を超える可能性があるコレクションは仮想化します。テーブル内では折り返さずに切り詰め、詳細ビューで値全体を表示します。
• ユーザーが明示的にレイアウトを変更しない限り、パネルの位置を安定させます。空間的な記憶はナビゲーションの一部です。

意味とアクセシビリティ

• 色のリテラルをあちこちに散在させず、意味を表すスタイルトークンを定義します。自動カラー指定モードでは NO_COLOR に従い、モノクロでも意味が伝わるようにします。
• 色だけに頼らないでください。テキスト、形、位置、記号を組み合わせ、Unicode のサポートが不確かな場合に備えて ASCII の代替表現も用意します。
• すべての操作をキーボードから実行できるようにします。マウス対応で操作を速めることはできますが、マウス操作を必須にしてはいけません。
• テキスト入力や、キー割り当てが完結した範囲限定プロンプトと競合しない場合にのみ、使い慣れたナビゲーション用エイリアスを用意します。予約キーに期待される動作を維持してください。Ctrl+C はキャンセルまたは終了、Ctrl+Z はフレームワークを通じた一時停止に使用します。raw モードでは、どちらもキー入力として届き、XON/XOFF が無効になります。そのため、全画面アプリでは Ctrl+S を割り当てられます。フロー制御の影響を受けるのは、ラインモードのプログラムだけです。
• 操作の複雑さに合わせて見つけやすさを確保します。範囲限定プロンプトには必要な操作をすべてインラインで表示し、操作の多い全画面アプリには、状況に応じたヒント、ヘルプ、必要に応じてコマンドパレットを用意します。
• 自動化やアクセシビリティ上の重大なニーズに対応するため、プレーンな --no-tui または同等のモードを用意します。必要な内容については、visual-patterns.md → アクセシビリティ を参照してください。

求められる前に、次の 2 つのレビュー観点を適用する

これらは、ユーザーがめったに指摘しない問題を見つけるためのものです。質問が別の内容であっても、設計またはレビューするすべてのレイアウトに両方を適用してください。

混雑度を監査する

「ごちゃごちゃしている」を数値で示します。次の項目を報告してください。

• 枠線の入れ子の深さ。ターミナルの端からコンテンツまでに枠線が 2 つ以上ある場合は、通常多すぎます。
• 同じ状態を表すシグナルの数。[PASS]、緑色、チェックマーク、行マーカーがあれば 4 つです。
• すべての行に表示されているため、何も示せていないマーカー。
• データではなく、装飾、ラベル、繰り返しの定型文に使われているセルの割合。

削除する枠線、マーカー、ラベル、繰り返しフィールドを具体的に挙げてください。「簡素化する」だけで終わらせないでください。詳しい手法については、visual-patterns.md → 混雑度の監査 を参照してください。

表示領域に負荷をかけてテストする

80×24 および 60 列の tmux 分割画面で何が起きるかを明記してください。どのペインが優先されるか、何が隠れるか、何が切り詰められるか、何が詳細表示に切り替わるか、そして「ターミナルが小さすぎます」という正直な状態がいつ表示されるかを説明してください。複数列のデザインには、必ず単一ペインのフォールバックを用意してください。visual-patterns.md → レスポンシブデザイン のブレークポイントの段階と最小サイズの決め方を使用してください。

ビルドと検証の方針

ターミナルなしでもテストできるように、ビジネス状態を十分に分離してください。MVU または即時モードシステムでは、合成イベントを更新ロジックに渡し、状態をアサートします。保持モード／ウィジェットシステムでは、対象の動作を担う最小のウィジェットまたはアプリのハーネスを操作します。

下層を厚くしたテストピラミッドを使用してください。

1. 状態遷移、解析、ソート、フィルタリング、コマンド構築をユニットテストします。
2. 80×24、60 列、最小サイズを含む、固定したターミナルサイズとカラープロファイルで、描画フレームをスナップショットまたはゴールデンテストします。
3. ライフサイクルと実際のキーボードとの統合には、PTY エンドツーエンドフローを 1～2 件使用し、主要なテストスイートにはしません。

少なくとも以下を検証してください。

• 正常終了、中断、エラー、パニック時のクリーンアップ。
• リサイズ、小さすぎる場合の動作、サポートされている場合は一時停止／再開。
• 空、読み込み中、一部表示、エラー、切断、大量データの各状態。
• キーボードでの操作性、フォーカスの可視性、ヘルプの正確さ。
• NO_COLOR、16 色またはモノクロ、ASCII フォールバック、非 TTY 出力。
• 全角文字、結合文字、切り詰め、ソート、仮想化。
• stdout の破損がなく、イベント／描画パスでブロッキング I/O が発生しないこと。

エコシステムのリファレンスにある、正確なテスト API とデバッグ API を使用してください。raw モードまたは代替画面で UI が動作中に、診断情報を出力してはいけません。

既存のインターフェースをレビューする

優先順位の高い順に、根拠を示して報告してください。

1. プロダクトの形は適切ですか。それとも、全画面のフローをインラインまたは単発の処理にすべきですか。
2. 終了経路のいずれかで、raw モード、カーソル状態、マウスキャプチャ、画面バッファが復元されずに残る可能性はありますか。
3. UI の処理がブロックされる、無駄に再描画される、リサイズ時にクラッシュする、またはセル幅を誤って測定することはありますか。
4. 初めて使うユーザーが、テキスト入力やターミナルの慣例を損なわずに、重要な操作を見つけて実行できますか。
5. 煩雑さの監査では何を数え、具体的にどの要素を削除すべきですか。
6. 80×24、60 列、宣言された最小サイズでは何が起きますか。
7. 出力ストリーム、終了コード、非 TTY の動作、NO_COLOR、プレーンモードは、スクリプトとアクセシビリティをサポートしていますか。
8. 状態遷移と固定フレームは、適切なテストレイヤーでカバーされていますか。

一般論だけの評価は避けてください。それぞれの推奨事項を、ユーザーに見える不具合、実装上のリスク、または測定可能なノイズの削減に結び付けてください。

有用な推奨事項を提示する

実践方法が確立している項目については、明確に推奨してください。セマンティックカラー、ターミナルの確実な復元、レスポンシブなフォールバック、ノンブロッキング処理、幅を考慮した描画、正直なストリーム仕様が該当します。インライン表示と全画面表示、モーダル入力とモードレス入力、マウスサポート、破壊的操作の確認については、実際のトレードオフを説明してください。

選択したエコシステムの慣用的な方法を使い、別のフレームワークのアーキテクチャをそのまま置き換えてはいけません。デザイン上の選択がまだ抽象的な場合は、exemplar-apps.md の関連するケーススタディを示し、その解決策のどの部分を応用できるかを説明してください。