tui-design

What this skill does

# 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

```dot
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:

| App Type           | Paradigm                 | Examples            |
| ------------------ | ------------------------ | ------------------- |
| File manager       | Miller Columns           | yazi, ranger        |
| Git / DevOps tool  | Persistent Multi-Panel   | lazygit, lazydocker |
| System monitor     | Widget Dashboard         | btop, bottom, oxker |
| Data browser / K8s | Drill-Down Stack         | k9s, diskonaut      |
| SQL / HTTP client  | IDE Three-Panel          | harlequin, posting  |
| Shell augmentation | Overlay / Popup          | atuin, fzf          |
| Log / event viewer | Header + Scrollable List | htop, tig           |

### 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.

| Strategy               | When                                                                        |
| ---------------------- | --------------------------------------------------------------------------- |
| **Proportional split** | Panels maintain percentage ratios on resize                                 |
| **Priority collapse**  | Less important panels hide first below minimum width                        |
| **Stacking**           | Panels collapse to title-only bars, active one expands (zellij pattern)     |
| **Breakpoint modes**   | Switch layout entirely below a threshold (e.g., multi-panel → single panel) |
| **Minimum size gate**  | Display "terminal too small" if below usable minimum                        |

**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

| App Complexity              | Recommended Model                            |
| --------------------------- | -------------------------------------------- |
| Single-purpose, <20 actions | Direct keybinding (every key = action)       |
| Multi-view, complex         | Vim-style modes + contextual footer          |
| IDE-like, many features     | Command palette + tabs + vim motions         |
| Data browser                | Drill-down + fuzzy search + `:` command mode |

### Keyboard Design Layers

Design keybindings in four progressive layers:

| Layer               | Keys                                         | Audience      | Always show? |
| ------------------- | -------------------------------------------- | ------------- | ------------ |
| **L0: Universal**   | Arrow keys, Enter, Esc, q                    | Everyone      | Yes (footer) |
| **L1: Vim motions** | hjkl, /, ?, :, gg, G                         | Intermediate  | Yes (footer) |
| **L2: Actions**     | Single mnemonics: d(elete), c(ommit), p(ush) | Regular users | On `?` help  |
| **L3: Power**       | Composed commands, macros, custom bindings   | Power users   | Docs only    |

**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