Tui Fundamentals

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

1. Separate model, update, and view. Business state should not print directly to the terminal. Rendering consumes state; input produces events; update logic transforms state. 2. Treat terminal size as input. Layout must be recomputed from width and height on every resize. Never bake in one terminal size. 3. Own terminal lifecycle in one place. Raw mode, alternate screen, mouse, focus, keyboard protocols, and cleanup should be centralized. 4. Make every action keyboard-operable. Mouse support is an enhancement, not the primary navigation model. 5. Design for degradation. TERM=dumb, non-TTY output, missing color, Windows console differences, tmux/screen, SSH, and CI should have clear behavior. 6. Avoid hidden global terminal writes. Logs, progress, and background task output must not corrupt the screen.

Framework selection quick matrix

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=dumb until 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.

TUI Framework Selection Reference

Selection decision tree

1. Is the output primarily read-only? Use rich output libraries before a full-screen app: Rich or Spectre.Console for tables, progress, markdown, trees, logs, and status panels. 2. Is the interaction mostly questions and answers? Use prompt libraries: prompt_toolkit, Inquirer-style libraries, Spectre prompts, or Huh-like forms. 3. Does the user need persistent navigation, panes, tables, editors, or live state? Use a full-screen framework. 4. Do you need complete control over cell rendering? Use a low-level cell engine such as tcell, Crossterm/Ratatui backend abstractions, or ncurses. 5. Do you need automation equally supported? Ship CLI commands and machine-readable output beside the TUI.

Ecosystem notes

Rust

Ratatui is the default for modern Rust TUIs. It is immediate-mode: the app redraws the whole logical frame while the backend optimizes terminal writes. Pair with Crossterm for practical cross-platform support. Avoid scattering terminal setup across modules; use one terminal manager and an event loop that can shut down cleanly.

Python

Textual is best for substantial applications: CSS-like styling, widgets, reactive state, workers, and test tooling. Rich is best for non-full-screen presentation. prompt_toolkit is best for shells, completions, multiline input, key bindings, and terminal prompt sophistication. curses is appropriate for small dependency-light classic TUIs, but demands careful cleanup and platform testing.

Go

Bubble Tea is a good default when the Elm architecture fits: Model, Update, View, commands, and messages. Lip Gloss handles styling and layout. Bubbles provides common components. tview gives higher-level widgets over tcell. tcell is the lower-level portable cell abstraction when you need custom rendering.

Node and TypeScript

Ink is strongest when React mental models and component tests matter. Blessed offers a DOM-like widget tree and has a large ecosystem, but verify maintenance, resize behavior, mouse handling, and Windows behavior for your target versions.

.NET

Terminal.Gui is suited to full-screen keyboard-first apps with views and layout. Spectre.Console is suited to rich command-line output, prompts, progress, status, and command app composition.

Avoid direct ANSI when

• You need robust input parsing.
• You need resize handling, mouse, paste, or raw mode.
• You need cross-platform Windows behavior.
• You need deterministic tests.
• You need complex layout or focus.

Direct ANSI is acceptable for tiny controlled surfaces, status lines, progress indicators, or library internals that already have capability fallbacks.

TUI Architecture Reference

Recommended layers

1. Domain model: application data and business rules, independent of terminal concerns. 2. UI model: selected row, focused control, modal state, viewport offsets, pending edits, theme, terminal size. 3. Event decoder: turns raw terminal/framework events into semantic app actions. 4. Update/reducer: transforms UI model and schedules side effects. 5. Renderer/view: converts state into widgets or a cell buffer. 6. Terminal manager: owns raw mode, alternate screen, protocol enablement, cleanup, panic/exception hooks, and signal handling.

Event loop pattern

• Read input, timers, worker messages, and resize notifications through one channel/queue when possible.
• Coalesce repeated resize, mouse move, and high-frequency data updates.
• Throttle dashboards to the perceptual rate users need, not the data arrival rate.
• Never block the UI loop on network, disk, process, or API work.

Logging pattern

Full-screen TUIs should not write logs to stdout/stderr while the screen is active. Use one of these patterns:

• Write logs to a file and expose the path in debug help.
• Render logs inside a dedicated scrollback panel.
• Buffer logs while alternate screen is active, flush after exit.
• Provide --debug-log path and --no-tui modes.

Distribution contract

Document supported operating systems and terminal emulators, required terminal features and fallbacks, non-interactive usage, exit codes, keybindings, display recovery steps, and environment variables honored for color, accessibility, telemetry, config, and terminal detection.