TUI デザインシステム

優れたターミナルユーザーインターフェースを構築するための汎用デザインパターン。フレームワーク非依存で、Ratatui、Ink、Textual、Bubbletea、または任意の TUI ツールキットで機能します。

コア哲学: TUI は空間的一貫性、キーボード操作の流暢さ、人間の注意を尊重する情報密度によって力を得ます。専門家のスピードに対応しながら、初心者の発見可能性を放棄しないように設計してください。

TUI デザインプロセス

digraph tui_design {
    rankdir=TB;
    "What are you building?" [shape=diamond];
    "Select layout paradigm" [shape=box];
    "Design interaction model" [shape=box];
    "Define visual system" [shape=box];
    "Validate against anti-patterns" [shape=box];
    "Ship it" [shape=doublecircle];

    "What are you building?" -> "Select layout paradigm";
    "Select layout paradigm" -> "Design interaction model";
    "Design interaction model" -> "Define visual system";
    "Define visual system" -> "Validate against anti-patterns";
    "Validate against anti-patterns" -> "Ship it";
}

---

1. レイアウトパラダイムセレクタ

構築内容に基づいてプライマリレイアウトを選択してください:

アプリケーション型	パラダイム	例
ファイルマネージャ	Miller Columns	yazi, ranger
Git / DevOps ツール	Persistent Multi-Panel	lazygit, lazydocker
システムモニター	Widget Dashboard	btop, bottom, oxker
データブラウザ / K8s	Drill-Down Stack	k9s, diskonaut
SQL / HTTP クライアント	IDE Three-Panel	harlequin, posting
シェル拡張	Overlay / Popup	atuin, fzf
ログ / イベントビューア	Header + Scrollable List	htop, tig

Persistent Multi-Panel

すべてのパネルが同時に表示されます。フォーカスはそれらの間を移動します。ユーザーは空間記憶を構築し、「ブランチは常に左上」というような認識を得ます。

┌─ Status ──┬─────────── Detail ──────────┐
├─ Files ───┤                              │
│ > file.rs │  diff content here...        │
│   main.rs │                              │
├─ Branches ┤                              │
│ * main    │                              │
│   feat/x  │                              │
├─ Commits ─┤                              │
│ abc1234   │                              │
└───────────┴──────────────────────────────┘
  [q]uit [c]ommit [p]ush [?]help

いつ使用するか: マルチファセットなツール。ユーザーが同時コンテキストを必要とします (git クライアント、コンテナマネージャ、モニタリング)。 主要ルール: パネルはセッション全体で固定位置を保ちます。ユーザーアクションなしに再配置してはいけません。

Miller Columns

3 ペイン過去/現在/未来ナビゲーション。親ディレクトリ (左)、現在 (中央)、プレビュー (右)。

┌── Parent ──┬── Current ──┬── Preview ────────┐
│   ..       │ > config/   │ port: 8080        │
│   src/     │   lib/      │ host: localhost    │
│ > config/  │   main.rs   │ log_level: debug   │
│   tests/   │   mod.rs    │ db_url: postgres://│
└────────────┴─────────────┴───────────────────┘

いつ使用するか: 階層的なデータナビゲーション (ファイルシステム、ツリー構造、ネストされた設定)。 主要ルール: プレビューペインのコンテンツは選択タイプに適応します。コードはハイライト表示され、画像はレンダリングされ、ディレクトリは内容を表示します。

Drill-Down Stack

Enter で下降、Esc で上昇。階層的データのブラウザ型ナビゲーション。

いつ使用するか: すべてのレベルを同時に表示することが非現実的な深い階層 (Kubernetes リソース、データベーススキーマ)。 主要ルール: 常に現在のナビゲーションパスをブレッドクラムとして表示してください。:resource コマンドモードで直接ジャンプを実現します。

Widget Dashboard

独立したデータを持つ自己完結したウィジェットパネル。すべての情報が一度に表示されます。ナビゲーションは不要です。

┌─── CPU ──────────────┬─── Memory ──────────┐
│ ▁▂▃▅▇█▇▅▃▂▁▂▃▅▇     │ ████████░░ 78%      │
│ core0: 45% core1: 67%│ 12.4G / 16.0G       │
├─── Network ──────────┼─── Disk ────────────┤
│ ▲ 1.2 MB/s  ▼ 340KB/s│ /: 67%  /home: 45%  │
├─── Processes ────────┴─────────────────────┤
│ PID   USER  CPU%  MEM%  CMD                 │
│ 1234  root  23.4  4.5   postgres             │
└─────────────────────────────────────────────┘

いつ使用するか: モニタリング、リアルタイムステータス、システムダッシュボード。 主要ルール: 各ウィジェットは独立していて独自のタイトルを持ちます。高密度データにはブライユ文字またはブロック文字を使用してください。

IDE Three-Panel

サイドバー (左)、エディタ/メイン (中央)、詳細/出力 (下部)。上部にタブバー。

いつ使用するか: 編集に焦点を当てたツール (SQL クライアント、HTTP ツール、設定エディタ)。 主要ルール: サイドバーは単一キーで切り替えます。中央パネルはタブをサポートします。下部パネルは全高度に拡張可能です。

Overlay / Popup

TUI はシェル上にオンデマンドで表示され、使用後に消えます。

いつ使用するか: シェル拡張 (履歴検索、ファイルピッカー、コマンドパレット)。 主要ルール: 設定可能な高さ。選択を呼び出し元に返します。スクロールバックを妨害してはいけません。

Header + Scrollable List

メーター/統計を備えた固定ヘッダー。下部にスクロール可能なデータ。下部に機能バー。

いつ使用するか: メタデータを伴う単一リストツール (プロセスビューア、ログビューア、ソート済みリスト)。 主要ルール: ヘッダーは自然な「概要次に詳細」の読み流れを作成します。デフォルトで最も実行可能なディメンションでソートしてください。

---

2. レスポンシブターミナルデザイン

ターミナルはリサイズされます。TUI はそれを優雅に処理する必要があります。

戦略	時期
比例スプリット	パネルはリサイズで比率を維持
優先度の高い崩壊	最小幅以下でより重要度の低いパネルが最初に非表示
スタッキング	パネルはタイトルのみのバーに崩壊。アクティブなものが拡張 (zellij パターン)
ブレークポイントモード	しきい値以下でレイアウト全体を切り替え (例: マルチパネル → シングルパネル)
最小サイズゲート	使用可能な最小値以下の場合、「ターミナルが小さすぎます」を表示

ルール:

• 最小ターミナルサイズを定義してください (通常 80x24)。それ以下の場合、リサイズメッセージを表示します。
• リサイズ時にクラッシュしないでください。SIGWINCH を優雅に処理します。
• 制約ベースのレイアウト (パーセンテージ、最小/最大、比率) を使用してください。絶対位置ではありません。
• 80x24、120x40、200x60 でテストしてスケーリングを確認してください。

---

3. インタラクションモデル

ナビゲーションスタイルセレクタ

アプリケーション複雑度	推奨モデル
シングルパーパス、<20 アクション	ダイレクトキーバインディング (すべてのキー = アクション)
マルチビュー、複雑	Vim スタイルモード + コンテキストフッター
IDE 型、多数機能	コマンドパレット + タブ + Vim モーション
データブラウザ	ドリルダウン + ファジー検索 + : コマンドモード

キーボード設計レイヤ

4 つの段階的レイヤーでキーバインディングを設計してください:

レイヤ	キー	オーディエンス	常に表示?
L0: Universal	矢印キー、Enter、Esc、q	全員	はい (フッター)
L1: Vim motions	hjkl、/、?、:、gg、G	中級	はい (フッター)
L2: Actions	シングルニーモニック: d(elete)、c(ommit)、p(ush)	定期ユーザー	? でヘルプ
L3: Power	構成されたコマンド、マクロ、カスタムバインディング	パワーユーザー	ドキュメントのみ

キーバインディング慣例 (lingua franca):

• j/k、下/上に移動
• h/l、左/右に移動 (または折りたたむ/展開)
• /、検索
• ?、ヘルプオーバーレイ
• :、コマンドモード
• q、終了 (または Esc で 1 レベル戻る)
• Enter、選択 / 確認 / ドリルイン
• Tab、パネル間のフォーカス切り替え
• Space、選択の切り替え
• g/G、上/下にジャンプ

バインドしてはいけません: Ctrl+C (割り込み)、Ctrl+Z (サスペンド)、Ctrl+\ (終了シグナル)。これらはターミナルに属します。

フォーカス管理

• 一度に 1 つのウィジェットのみキーボード入力を受け取ります
• Tab がフォーカスを前進させ、Shift+Tab を後退させます
• フォーカス指標: ハイライトされたボーダー、色の変更、またはカーソルの存在
• フォーカスされていないパネル: 薄暗い、またはより細いボーダー
• モーダルダイアログはフォーカストラップを作成し、背景はイベントを受け取りません
• ネストされたフォーカス: 外部コンテナはイベントをフォーカスされたチャイルドにルーティングします

検索とフィルタリング

ユニバーサルパターン: / を押して、クエリを入力し、結果をリアルタイムでフィルタリングします。

• n/N、次/前のマッチ
• Esc、検索を閉じる
• デフォルトではファジーマッチング、' プレフィックスで完全一致
• マッチ文字を結果で強調表示
• ハイライトされた結果のプレビューペイン更新

ヘルプシステム: 3 つのティア

ティア	トリガー	コンテンツ	オーディエンス
常に表示	フッターバー	3-5 の重要なショートカット	全員
オンデマンド	? キー	現在のコンテキストの完全なキーバインディングオーバーレイ	定期ユーザー
ドキュメンテーション	--help、man ページ	完全なリファレンス	パワーユーザー

フッター形式: [q]uit [/]search [?]help [Tab]focus [Enter]select

コンテキスト依存のフッターは、アクティブなパネルまたはモードに基づいて更新します。今すぐ 実行可能なものだけを表示してください。

ダイアログと確認

アクション重大度	パターン
可逆的	それをやりなさい、ステータスバーに簡潔な確認を表示
中程度 (ファイル削除)	インライン「確認するために y を押してください」
重大 (データベースドロップ)	リソース名入力が必須のモーダルダイアログ
不可逆バッチ	--dry-run フラグ + 明示的な確認

• モーダルオーバーレイ: 薄暗い/ぼやけた背景の上にポップアップをレンダリング
• トースト通知: 3-5 秒後に自動的に非表示。相互作用不要
• ステータスバーメッセージ: Vim スタイルの 1 行のフィードバック。自動フェード

---

4. カラーデザインシステム

ターミナルカラーティア

すべての 3 つのティア全体でグレースフルデグラデーションを設計してください:

ティア	エスケープシーケンス	色	戦略
16 ANSI	\033[31m	16 (相対)	基盤。ターミナルテーマが外観を制御します。
256 Color	\033[38;5;{n}m	256 (16 相対 + 240 固定)	拡張パレット。固定色はテーマと競合する可能性があります。
True Color	\033[38;2;{r};{g};{b}m	16.7M (絶対)	完全な制御。COLORTERM=truecolor が必要です。

検出階層:

1. $COLORTERM = truecolor または 24bit → トゥルーカラー
2. $TERM に 256color が含まれている → 256 色
3. $NO_COLOR が設定されている → すべての色を無効化
4. デフォルト → 16 ANSI 色

黄金律: TUI は 16 色モードで 使用可能 である必要があります。トゥルーカラー は拡張 し、決して 階層を作成しません。

セマンティックカラースロット

見た目ではなく関数によってカラーを定義してください。セマンティックをテーマを通じた実際の色にマップしてください:

スロット	目的	典型的なダークテーマ
fg.default	本文テキスト	オフホワイト (#c0caf5)
fg.muted	二次テキスト、メタデータ	グレー (#565f89)
fg.emphasis	ヘッダー、フォーカスアイテム	明るい白 (#e0e0e0)
bg.base	プライマリ背景	近い黒 (#1a1b26)
bg.surface	パネル/ウィジェット背景	わずかに軽い (#24283b)
bg.overlay	ポップアップ/ダイアログ背景	さらに軽い (#414868)
bg.selection	選択アイテムハイライト	区別 (#364a82)
accent.primary	インタラクティブ要素、フォーカス	ブランドカラー (#7aa2f7)
accent.secondary	サポートインタラクション	補色 (#bb9af7)
status.error	エラー、削除	赤 (#f7768e)
status.warning	警告、注意	黄色 (#e0af68)
status.success	成功、追加	緑 (#9ece6a)
status.info	情報	シアン (#7dcfff)

ウィジェットコード内に 16 進値をハードコードしないでください。 常にセマンティックスロットを参照してください。

ビジュアル階層テクニック

色は複数のツールの 1 つです。それらを組み合わせて使用してください:

テクニック	エフェクト	用途
ボールド (SGR 1)	視覚的重みを増加	ヘッダー、ラベル、アクティブアイテム
Dim (SGR 2)	視覚的重みを減少	メタデータ、タイムスタンプ、二次情報
イタリック (SGR 3)	セマンティック区別	コメント、型、注釈
アンダーライン (SGR 4)	リンク、実行可能アイテム	クリック可能要素、URL
リバース (SGR 7)	fg/bg をスワップ	選択ハイライト (常に機能!)
取り消し線 (SGR 9)	否定	削除されたアイテム、非推奨機能

階層レシピ: コンテンツの 80% は fg.default。ボールド + fg.emphasis のヘッダー。薄暗い + fg.muted のメタデータ。セマンティック色のステータス。インタラクティブ要素のみのアクセント。

バックグラウンドレイヤリング

ボーダーなしで背景の明るさをレイヤリングして深さを作成します:

bg.base (最も暗い) → bg.surface → bg.overlay (最も明るい)

各ステップ。ダークテーマで ~5-8% 軽い。眼は対比グラデーションから深さを知覚します。これは、明確な視覚的ゾーンを保ちながら、ボックス描画ボーダーの必要性を減らします。

テーマアーキテクチャ

Base16 パターンに従ってください: 16 個の名前付きカラースロットを定義し、セマンティックにマップしてください:

• 8 つのモノトーン (base00-base07): 背景/前景グラデーション
• 8 つのアクセント (base08-base0F): 構文/セマンティック色

デフォルトではダークテーマを配布してください。OSC エスケープクエリまたは terminal-light クレートを介してライト/ダーク終端を検出します。少なくとも 1 つのライトバリアントを提供してください。NO_COLOR を尊重してください。

アクセシビリティ要件

• WCAG AA コントラスト: 本文テキスト 4.5:1 比率、大きなテキスト/UI 要素 3:1
• 色だけに依存しないでください: シンボル (チェックマーク、X、三角形)、テキストラベル、位置、またはタイポグラフィと組み合わせる
• 色盲セーフペア: 青+オレンジ、青+黄、黒+白。赤対緑への依存を避けてください。
• テスト: モノクロモード、色盲シミュレータ、3+ ターミナルエミュレータ、ライト/ダークテーマ

---

5. データビジュアライゼーション

文字解像度ビルディングブロック

要素	文字	解像度	用途
フルブロック	█▉▊▋▌▍▎▏	セル当たり 8 ステップ	プログレスバー、棒グラフ
シェードブロック	░▒▓█	4 つの密度	ヒートマップ、密度プロット
ブライユ	⠁⠂⠃...⣿ (U+2800-U+28FF)	セル当たり 2x4 ドット	高解像度折れ線グラフ、散布図
スパークライン	▁▂▃▄▅▆▇█	8 つの高さ	インラインミニチャート

一般的なウィジェット

ウィジェット	パターン	ヒント
プログレスバー	[████████░░░░] 67%	パーセンテージ + ETA を表示。緊急度に応じて色グラデーション緑→黄→赤。
スパークライン	▁▂▃▅▇█▇▅▃▂	ヘッダー/ステータスバーのインラインタイムシリーズに最適。
ゲージ	CPU [██████████░░] 83%	ラベル + バー + 値。しきい値で色。
テーブル	ソート可能な列、シマウマストライプ	数字を右配置、テキストを左配置。… で切り詰め。
ツリー	├── 、└── 、│ ガイド	レベルあたり 2-4 文字インデント。Enter で展開/折りたたみ。
Diff	緑 + 行、赤 - 行	変更行内の単語レベルハイライトは品質を向上させます。
ログ	カラー付きレベル、タイムスタンプ、メッセージ	TRACE=dim、DEBUG=cyan、INFO=default、WARN=yellow、ERROR=red、FATAL=red+bold。

スピナー選択

コンテキスト	スピナー	間隔
デフォルト / モダン	ブライユドット ⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏	80ms
最小	線 -|/	130ms
重い処理	ブロック ▖▘▝▗	100ms
楽しい / ブランデッド	カスタムフレーム	70-100ms

不定操作にスピナーを使用してください。決定的なものにはプログレスバー。高速操作でのフラッシュを避けるため、スピナーは 200ms の遅延後にのみ表示してください。

---

6. アニメーションとモーション

フリッカーフリーレンダリングスタック

3 つのレイヤー。すべてスムーズな TUI レンダリングに必須:

1. ダブルバッファリング: オフスクリーンバッファにレンダリング、前フレームに対して差分を取得、変更されたセルのみを発行
2. 同期された出力: フレームを CSI ? 2026 h ... CSI ? 2026 l でラップしてアトミックターミナルレンダリング
3. バッチ処理された書き込み: すべてのエスケープシーケンスを単一の write() syscall に統合

アニメーション化する時期

状況	アニメーション	期間
ビュー遷移	フェードまたはスライド	100-200ms
選択の変更	即座のハイライト	0ms (決してアニメーション化しないでください)
データ読み込み	スピナーまたはスケルトン	完了まで
成功フィードバック	簡潔なフラッシュ/チェックマーク	1-2 秒
パネルリサイズ	即座のリフロー	0ms
チャートデータ更新	スムーズな値遷移	200-500ms

ルール: アニメーションはユーザー入力を遅延させてはいけません。ユーザーが遷移中にキーを押した場合、キャンセルして即座に応答してください。

リアルタイム更新

• ダッシュボードの更新を 15-30 FPS に上限してください (CPU を節約し、フリッカーを防止)
• 差分更新を使用して、変更されたセルのみを再描画してください
• テキストをストリーム配信 (AI レスポンス、ログ) を読める速度で配信してください。ネットワークバースト速度ではなく
• バックグラウンド操作: ステータスバーウィジェットに状態を表示します。メインループをブロックしないでください

---

7. 7 つの設計原則

1. キーボード優先、マウスはオプション: 各機能がキーボードでアクセス可能。マウスは拡張するが、決して置き換えません。Shift+click はテキスト選択のためのマウスキャプチャをバイパスする必要があります。

2. 空間的一貫性: パネルは固定位置に留まります。ユーザーはメンタルマップを構築します。明示的なユーザーアクションなしに再配置しないでください。タブは安定した目印を提供します。

3. 段階的な露出: フッターに 5 つの重要なショートカットを表示します。? の背後の完全なヘルプ。ドキュメント内の完全なリファレンス。床はアクセス可能で、天井は無制限です。

4. 非同期すべて: UI をフリーズしないでください。ファイル操作、ネットワークリクエスト、スキャンはすべてバックグラウンドで実行され、進捗表示があります。Esc でキャンセル。

5. セマンティック色: 色は意味をエンコードし、装飾ではありません。すべての色を削除した場合、インターフェースはレイアウト、タイポグラフィ、シンボルを通じて 使用可能 である必要があります。

6. コンテキスト知能: パネルごとにキーバインディングを更新します。ステータスバーは現在の状態を反映します。ヘルプは、すべてではなく、今 実行可能なものを表示します。

7. レイヤーで設計: モノクロで開始 (使用可能?)。16 ANSI 色を追加 (読める?)。トゥルーカラーをレイヤー (美しい?)。各ティアは独立して機能する必要があります。

---

アンチパターン

ランク付けされたこれらの落とし穴に対してデザインを検証してください (実際のコンプレーント頻度の順):

#	アンチパターン	修正
1	異なるターミナルで色が崩壊	基盤として 16 ANSI 色を使用。3+ エミュレータ + ライト/ダークテーマをテスト。
2	フリッカリング / 完全な再描画	ダブルバッファ + 同期された出力 + バッチ処理された書き込み。上書き、クリアしない。
3	発見不可能なキーバインディング	コンテキスト依存のフッター + ? ヘルプオーバーレイ + Which-Key スタイルのヒント。
4	Windows / WSL で破損	Windows Terminal でテストしてください。ボックス描画を超えた高度な Unicode を避けてください。
5	Unicode レンダリング不一貫性	ボックス描画 + ブロック要素に固執。絵文字を Unicode 9.0 に制限してください。
6	ターミナルマルチプレクサ非互換性	tmux と zellij の内部でテストしてください。マウスキャプチャは選択を壊してはいけません。
7	アクセシビリティサポートなし	NO_COLOR を尊重。モノクロモードを提供。決して色だけの意味を使用しないでください。
8	操作中の UI ブロッキング	100ms 以内にフィードバックを表示。非同期 + スピナー + プログレスバーを使用。
9	モーダルの混乱	ステータスバーに現在のモードを常に表示してください。カーソルシェイプはモードごとに変わります。
10	過度に装飾されたクロム	ボーダーと色はコンテンツを提供し、エゴではありません。コンテンツ が インターフェースです。

9. 互換性チェックリスト

配布前に、以下を確認してください:

• 最小ターミナルサイズ 80x24 で動作
• ターミナルリサイズをクラッシュなしで処理
• ダーク と ライトターミナルテーマで正しく表示
• NO_COLOR 環境変数を尊重
• tmux / zellij / screen 内で動作
• SSH 経由で機能 (ローカルのみのプロトコルが必要な機能なし)
• マウスキャプチャがテキスト選択を壊さない (Shift+click)
• キーボードのみですべての機能にアクセス可能
• ANSI エスケープシーケンスリークがパイプ/リダイレクト出力にない
• Ctrl+C / SIGINT できれいに終了 (ターミナル状態を復元)

---

Unicode 文字参照テーブルと枠線スタイルギャラリーについては、visual-catalog.md を参照してください。 実世界の TUI アプリデザイン分析とインスピレーションについては、app-patterns.md を参照してください。

このスキルが ではない もの

• フレームワーク固有の API リファレンス。
• ターミナルツールを過度に装飾するための言い訳。
• 実際のターミナルエミュレータでのテストの代替品。
• Rust のみ。パターンは TUI フレームワーク全体に適用されます。