josiahsiegel TUI Fundamentals, Architecture, and Framework Selection
Use this skill when the task is about the shape of the terminal product: what kind of TUI to build, which abstraction to use, how to organize state, or whether a full-screen terminal UI is the right answer.
First decision: is a TUI appropriate?
Prefer a rich TUI when users need continuous visual feedback, multi-step navigation, keyboard-driven exploration, selection among many items, or a dashboard-like control surface. Prefer a line-oriented CLI, prompts, or plain output when the flow is short, scriptable, primarily automation-focused, or likely to be used by screen readers and CI systems.
A production terminal product often ships both:
- A scriptable CLI surface for automation, accessibility, logs, and non-TTY use.
- An optional TUI for exploration, monitoring, bulk selection, or guided workflows.
Architecture rules
- Separate model, update, and view. Business state should not print directly to the terminal. Rendering consumes state; input produces events; update logic transforms state.
- Treat terminal size as input. Layout must be recomputed from width and height on every resize. Never bake in one terminal size.
- Own terminal lifecycle in one place. Raw mode, alternate screen, mouse, focus, keyboard protocols, and cleanup should be centralized.
- Make every action keyboard-operable. Mouse support is an enhancement, not the primary navigation model.
- Design for degradation.
TERM=dumb, non-TTY output, missing color, Windows console differences, tmux/screen, SSH, and CI should have clear behavior. - Avoid hidden global terminal writes. Logs, progress, and background task output must not corrupt the screen.
Framework selection quick matrix
| Need | Strong default |
|---|---|
| Rust full-screen app with precise rendering | Ratatui + Crossterm |
| Python product-grade app with widgets, CSS, async workers | Textual |
| Python rich output, progress, tables, markdown, logs | Rich |
| Python REPL, shell, completions, complex prompt input | prompt_toolkit |
| Classic dependency-light Unix TUI | curses/ncurses |
| Go Elm-style app with composable commands | Bubble Tea + Bubbles + Lip Gloss |
| Go batteries-included forms/tables/tree views | tview over tcell |
| Go portable low-level cell engine | tcell |
| React-style terminal components in Node | Ink |
| Node DOM-like full-screen widgets | Blessed |
| .NET full-screen views | Terminal.Gui |
| .NET rich CLI output and prompts | Spectre.Console |
Read references/framework-selection.md before committing to a framework in a new project.
Product design checklist
- Define the primary user journey in one sentence.
- Decide whether the app is full-screen, inline, prompt-based, or hybrid.
- List required environments: Windows Terminal, classic conhost, macOS Terminal, iTerm2, GNOME Terminal, Alacritty, SSH, tmux/screen, CI, and logs.
- Define minimum terminal dimensions and the small-screen fallback.
- Define exit keys, destructive confirmation rules, and recovery instructions.
- Define non-interactive equivalents for every essential action.
- Decide how help is exposed: footer hints,
?, command palette,--help, docs.
Failure modes
- Building a full-screen UI for a workflow that should be scriptable.
- Choosing a low-level escape-sequence approach when a framework already solves layout, input, cleanup, and testing.
- Mixing business logic with terminal writes, making tests brittle and rendering inconsistent.
- Ignoring screen-reader users, CI, pipes, and
TERM=dumbuntil late. - Assuming color, Unicode icons, Nerd Fonts, or mouse support are always available.
Reference files
references/framework-selection.md- Detailed ecosystem comparison and decision tree.references/tui-architecture.md- State, event, lifecycle, logging, and distribution patterns.