tui-design

Files (3)

• SKILL.md
• app-patterns.md · references/
• visual-catalog.md · references/

SKILL.md (first lines)

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

From kodi/topchester-agent, MIT.

More from kodi/topchester-agent