tui-design

name	tui-design
description	Decide whether a full-screen TUI is warranted (vs a scriptable CLI), pick the framework (Ink / Bubble Tea / Textual / ratatui), and design the render-loop + non-TTY fallback. Use for interactive terminal dashboards, pickers, and wizards.

TUI Design

First: is a TUI even warranted?

A full-screen TUI is right for sustained, stateful interaction — dashboards, file/log explorers, multi-step wizards. For a one-shot job a scriptable CLI wins (it pipes, automates, composes). If you take the screen, you owe a non-TTY fallback.

Framework by language + model

Language	Framework	Model
TS/JS	Ink	React-style components
Go	Bubble Tea (+ Lip Gloss)	Elm-style model/update/view
Python	Textual	CSS-like, async
Rust	ratatui	Immediate-mode, you own the loop

The render loop

Keep a model → update → view cycle: input arrives as messages, the model updates, the view re-renders. Diff, don't repaint the whole screen each tick. Never block the render thread — push slow work to a task and feed results back as messages.

Survive reality

• Resize is a first-class event: re-lay-out, don't corrupt the buffer.
• Restore the terminal (exit alt-screen, show cursor, leave raw mode) on every exit path — including panics and signals.
• Non-TTY: when stdout/stdin isn't a terminal, fall back to plain line output (or refuse with a clear message) — never emit alt-screen/escape codes into a pipe.
• Accessibility: keyboard-first navigation; keep output screen-reader-tolerant.

See the CLI-vs-TUI branch of the command-surface tree in ../../knowledge/cli-tooling-decision-trees.md.