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
単発コマンド、引数、ストリーム、終了コード、--json とエラー、補完、ページング、設定、Windows、CLI テスト、自動化	references/cli-basics.md
レイアウトとワイヤーフレーム、インライン表示と代替画面、境界線、階層、色、情報密度、レスポンシブ動作と最小サイズ、状態（空、読み込み中、一部表示、エラー、古いデータ）、テーブル、差分表示、モーダル、ステータスバーとメッセージ、進行状況とスピナー、テーマ、アイコンと Nerd Fonts、ローカライズと Unicode の幅、アクセシビリティ（スクリーンリーダー、プレーンモード、動き）	references/visual-patterns.md
キー、Esc/q/Ctrl+C の終了順序、tmux やキーエンコーディングに横取りされるキー、フォーカス、ナビゲーション、検索とフィルター、複数選択、ヘルプとコマンドパレット、スクロール、ライブデータの選択、ログの追従モード、ツリー、テキスト入力、フォーム、マウス、確認、元に戻す	references/interaction-patterns.md
ちらつきや画面の乱れ、エスケープシーケンスと端末モード（ブラケット付きペースト、キーボードプロトコル、届かない Shift+Enter、マウス、フォーカス、同期出力、カーソル、タイトル、進行状況）、tmux、screen、Zellij、SSH、Windows の動作、クリップボード、リンク、通知、色深度とテーマ検出	references/terminal-protocols.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 を読み込みます。
呼び出し・選択・終了型ツール	シェルのコンテキストが重要な場合は、インライン表示を優先します。対話型の UI は stderr または /dev/tty に表示し、選択結果は stdout に出力します。大きなプレビューや作業対象を安定した領域に表示する必要がある場合に限り、全画面を使用します。
全画面セッション	代替画面と安定した空間モデルを使用します。端末の復元、サイズ変更、中断、再描画の動作をプロダクト要件として扱います。

次に、ワークフローの形（固定パネル、Miller カラム、ドリルダウンスタック、ダッシュボード、IDE 風ペイン、オーバーレイ、タブ）を明示し、visual-patterns.md と照合します。コードを書く前に、初期状態、読み込み中、空、一部表示、成功、エラー、切断、画面が小さすぎる状態（visual-patterns.md → 状態）を含む状態とレイアウトをスケッチします。設計に関する回答では、最小サイズ（60 列）と幅の広い画面の両方について、レイアウトの ASCII スケッチを含めてください。

タスクの進め方

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

設計に関する質問では、説明より先に推奨案を示します。実装では、新しいフレームワークや抽象化を導入する前に、既存のアーキテクチャと依存関係を確認します。レビューでは、具体的な観察事項を挙げ、ユーザーへの悪影響が大きい変更を優先します。

以下の横断的な契約を守る

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

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

レンダリング、データ、パフォーマンス

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

意味とアクセシビリティ

• 色のリテラルをあちこちに散在させず、意味を持つスタイルトークンを定義します。自動カラーモードでは NO_COLOR を尊重し、モノクロでも意味を保ちます。
• 色だけで情報を伝えないでください。テキスト、形状、位置、記号を組み合わせ、Unicode 対応が不確かな場合は ASCII による代替表示を用意します。
• すべての操作をキーボードで実行できるようにします。マウス操作は効率化に役立ちますが、必須にしてはいけません。
• テキスト入力や、範囲が限定されたプロンプトの完全なキー割り当てと競合しない場合に限り、一般的なナビゲーション用エイリアスを用意します。予約キーの想定動作を維持します。Ctrl+C はキャンセルまたは終了に、Ctrl+Z はフレームワーク経由の一時停止に使います。その他の予約キーと、raw モードで Ctrl+S が使える理由については、interaction-patterns.md → Reserved keys を参照してください。
• 複雑さに応じて操作の見つけやすさを調整します。範囲が限定されたプロンプトには操作方法をすべてインラインで表示し、操作が多い全画面アプリには状況に応じたヒント、ヘルプ、必要に応じてコマンドパレットを用意します。
• 自動化や重大なアクセシビリティ上のニーズに線形出力が必要な場合に備え、標準的な --no-tui モード、または同等のモードを用意します。そのモードに必要な内容は、visual-patterns.md → Accessibility で定義されています。

2つのレビュー観点を促される前に適用する

ユーザーが指摘することの少ない失敗を見つけます。質問が別の内容でも、設計またはレビューするすべてのレイアウトに、この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が発生しないこと。
• 単発実行の CLI では、TTY なし、かつ NO_COLOR 設定下で、ゴールデンテストにより stdout、stderr、終了コードを検証すること（cli-basics.md → 単発実行の CLI のテスト）。

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

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

優先度順に根拠を示してください。

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

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

役立つ推奨事項を提示する

実践方法が確立している部分については、明確な推奨を示してください。意味に基づいた色使い、ターミナル状態の適切な復元、応答性が保てない場合の代替手段、ブロックしない処理、幅を考慮したレンダリング、そして実態に即したストリームの契約が該当します。インライン表示と全画面表示、モーダル入力とモードレス入力、マウス対応、破壊的な操作の確認については、実際のトレードオフを説明してください。

別のフレームワークのアーキテクチャをそのまま置き換えるのではなく、選んだエコシステムの慣例に沿ってください。設計上の選択が抽象的なままの場合は、exemplar-apps.md の該当するケーススタディを示し、そこでの解決策のどの部分を応用できるか説明してください。