Tui Design

TUI Design System

Universal design patterns for building exceptional terminal user interfaces. Framework-agnostic — works with Ratatui, Ink, Textual, Bubbletea, or any TUI toolkit.

Core philosophy: TUIs earn their power through spatial consistency, keyboard fluency, and information density that respects human attention. Design for the expert's speed without abandoning the beginner's discoverability.

TUI Design Process

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. Layout Paradigm Selector

Choose your primary layout based on what you're building:

Persistent Multi-Panel

All panels visible simultaneously. Focus shifts between them. Users build spatial memory — "branches are always top-left."

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

When to use: Multi-faceted tools where users need simultaneous context (git clients, container managers, monitoring). Key rule: Panels maintain fixed positions across sessions. Never rearrange without user action.

Miller Columns

Three-pane past/present/future navigation. Parent directory (left), current (center), preview (right).

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

When to use: Hierarchical data navigation (file systems, tree structures, nested configs). Key rule: Preview pane content adapts to selection type — code gets highlighting, images render, directories show contents.

Drill-Down Stack

Enter descends, Esc ascends. Browser-like navigation through hierarchical data.

When to use: Deep hierarchies where showing all levels simultaneously is impractical (Kubernetes resources, database schemas). Key rule: Always show the current navigation path as a breadcrumb. Provide :resource command-mode for direct jumps.

Widget Dashboard

Self-contained widget panels with independent data. All information visible at once, no navigation required.

┌─── 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             │
└─────────────────────────────────────────────┘

When to use: Monitoring, real-time status, system dashboards. Key rule: Each widget is self-contained with its own title. Use braille/block characters for high-density data.

IDE Three-Panel

Sidebar (left), editor/main (center), detail/output (bottom). Tab bar along top.

When to use: Editing-focused tools (SQL clients, HTTP tools, config editors). Key rule: Sidebar toggles with a single key. Center panel supports tabs. Bottom panel can expand to full height.

Overlay / Popup

TUI appears on demand over the shell, disappears after use.

When to use: Shell augmentations (history search, file picker, command palette). Key rule: Configurable height. Return selection to the caller. Never disrupt scrollback.

Header + Scrollable List

Fixed header with meters/stats, scrollable data below, function bar at bottom.

When to use: Single-list tools with metadata (process viewers, log viewers, sorted listings). Key rule: The header creates a natural "overview then detail" reading flow. Sort by the most actionable dimension by default.

2. Responsive Terminal Design

Terminals resize. Your TUI must handle it gracefully.

Rules:

• Define a minimum terminal size (typically 80x24). Below that, show a resize message.
• Never crash on resize. Handle SIGWINCH gracefully.
• Use constraint-based layouts (percentages, min/max, ratios) — not absolute positions.
• Test at 80x24, 120x40, and 200x60 to verify scaling.

3. Interaction Model

Navigation Style Selector

Keyboard Design Layers

Design keybindings in four progressive layers:

Keybinding conventions (lingua franca):

• j/k — move down/up
• h/l — move left/right (or collapse/expand)
• / — search
• ? — help overlay
• : — command mode
• q — quit (or Esc to go back one level)
• Enter — select / confirm / drill in
• Tab — switch focus between panels
• Space — toggle selection
• g/G — jump to top/bottom

Never bind: Ctrl+C (interrupt), Ctrl+Z (suspend), Ctrl+\ (quit signal). These belong to the terminal.

Focus Management

• Only one widget receives keyboard input at a time
• Tab cycles focus forward, Shift+Tab backward
• Focus indicator: highlighted border, color change, or cursor presence
• Unfocused panels: dimmed or thinner borders
• Modal dialogs create focus traps — background receives no events
• Nested focus: outer container routes events to focused child

Search & Filtering

The universal pattern: press /, type query, results filter live.

• n/N — next/previous match
• Esc — dismiss search
• Fuzzy matching by default, ' prefix for exact match
• Highlight matched characters in results
• Preview pane updates for highlighted result

Help System — Three Tiers

Footer format: [q]uit [/]search [?]help [Tab]focus [Enter]select

Context-sensitive footers update based on the active panel or mode. Show only what's actionable right now.

Dialogs & Confirmation

• Modal overlays: render popup on top of dimmed/blurred background
• Toast notifications: auto-dismiss after 3-5 seconds, no interaction required
• Status bar messages: vim-style one-liner feedback, auto-fade

4. Color Design System

Terminal Color Tiers

Design for graceful degradation across all three tiers:

Detection hierarchy:

1. $COLORTERM = truecolor or 24bit → true color
2. $TERM contains 256color → 256 colors
3. $NO_COLOR is set → disable all color
4. Default → 16 ANSI colors

Golden rule: Your TUI must be usable in 16-color mode. True color enhances — it never creates the hierarchy.

Semantic Color Slots

Define colors by function, not appearance. Map semantics to actual colors through your theme:

Never hardcode hex values in widget code. Always reference semantic slots.

Visual Hierarchy Techniques

Color is one tool among several. Use them in combination:

Hierarchy recipe: 80% of content in fg.default. Headers in bold + fg.emphasis. Metadata in dim + fg.muted. Status in their semantic colors. Accents for interactive elements only.

Background Layering

Create depth without borders by layering background lightness:

bg.base (darkest) → bg.surface → bg.overlay (lightest)

Each step ~5-8% lighter in dark themes. The eye perceives depth from the contrast gradient. This reduces the need for box-drawing borders while maintaining clear visual zones.