Tui Design

TUI Design

Design the command-line interface first. Add a full-screen TUI only when the task needs persistent context, fast navigation, selection, or live updates. A TUI owns the screen, the input, the scrollback, and the terminal state; do not take that cost without a reason.

Decide if a TUI is correct

• Use a plain command when the operation is one-shot, batchable, or scripted.

• Use the user's $PAGER when the task is reading or searching long output. Page only when stdout is a terminal, and provide --no-pager.

• Use a TUI when users repeatedly navigate, compare, filter, select, or watch changing data. Process monitors, resource browsers, and Git interfaces are good examples.

• Do not build a TUI only to get color or animation. Styled output, a prompt, or a single selector is usually enough.

• Never make the TUI the only way to do an important operation. Ship equivalent non-interactive subcommands and structured output:

  app                  # optional interactive interface
  app list --json
  app delete ID --yes

• Share the domain logic below both interfaces. The TUI is an adapter.

Keep the two interfaces separate

• Write results to stdout and write progress, warnings, and errors to stderr.
• Test each stream for a terminal independently. stdout can be a pipe while stderr is still a terminal.
• When output is not a terminal, change presentation only, never meaning. Remove color, cursor motion, progress animation, and the alternate screen.
• Provide --json for structured data and one JSON document per line for streaming events. Treat those schemas as a public interface.
• Prompt only when stdin is a terminal. Provide a flag for every prompt so a script can supply the answer. Never block a pipeline on input.
• Support -q/--quiet and --verbose, with the same meaning everywhere.

Lay out for a character grid

• Make 80x24 the minimum target. Essential navigation, current state, primary actions, and errors must stay usable there.
• Recompute the layout from the current size on every resize. Handle SIGWINCH, then query the real dimensions; do not cache the launch size.
• Use explicit breakpoints. Drop decoration and secondary metadata before you hide primary content. Below the minimum, print a plain "terminal too small".
• Clamp sizes before subtracting. Test 1x1, 20x5, and zero-size reports.
• Give headers, status bars, and key hints fixed heights; give the main view the rest; set minimum sizes on interactive panes.
• Wrap prose. Truncate scan-oriented rows with an ellipsis and offer a detail view. An ellipsis signals hidden content; silent clipping does not.
• Use the alternate screen for sustained applications, and inline rendering for command-shaped work that should leave output in scrollback.
• Spend borders carefully: two bordered panes cost at least four columns at
  80. Prefer whitespace, alignment, and one shared divider.

Handle text as the terminal sees it

• Measure rendered cells, not bytes, code points, or string length. CJK is usually two cells, combining marks are zero, and one emoji may be many code points.
• Cut and edit at grapheme-cluster boundaries, not code points.
• Do not treat East Asian Width as a complete width algorithm; ambiguous characters vary by terminal, locale, and font.
• Keep emoji out of borders, fixed columns, progress tracks, and cursors. Reported widths disagree across terminals and multiplexers.
• Treat Nerd Font and Powerline glyphs as optional. Keep an ASCII fallback and never let an unlabeled icon be the only meaning.
• Normalize tabs to a fixed width before measuring.

Use color as an enhancement

• Design a readable monochrome hierarchy first, then add semantic color.
• Support the ladder: no color, 16 colors, 256 colors, true color. Detect the capability; do not assume true color, and remember COLORTERM is lost through ssh and sudo.
• Define roles such as muted, surface, selected, success, warning, and error. Map roles through themes; do not scatter literal colors in the code.
• Detect the terminal background before you choose fixed colors, and keep an unknown state for terminals that do not answer.
• Never encode meaning in color alone. Add a label, symbol, border, or cursor.
• Honor NO_COLOR when it is present and not empty. An explicit flag or the user config may still override it.
• Target 4.5:1 contrast for ordinary text. You do not control the user's font size, theme, or rendering.

Bind keys that every terminal can send

• Support arrows and hjkl. Show arrows in the footer and the vim aliases in the full help.
• Make Ctrl+C a global, highest-priority exit that no focused widget can shadow. It must restore the terminal before it exits.
• Bind q to quit at the root, ? to full help, / to filter, : to a command palette, Enter to activate, Tab/Shift+Tab to move focus.
• Give Esc one consistent ladder: close a menu, cancel an edit or filter, close the overlay, go back one level. At the root it does nothing.
• Leave Ctrl+S, Ctrl+Q, Ctrl+D, and Ctrl+Z alone. They belong to the terminal and the shell.
• Do not require Ctrl+Shift, Ctrl+Enter, or a Tab and Ctrl+I distinction. Legacy terminals cannot encode them. Use the Kitty keyboard protocol only for optional accelerators.
• Keep mouse support off by default unless direct manipulation is central. Mouse reporting breaks ordinary text selection; document the Shift or Option override, and keep full keyboard equivalence.

Make the interface discoverable

• Keep a one-line footer with three to six actions for the current focus, for example up/down move Enter open / filter ? help q quit.
• Derive the footer from the active keymap so it cannot drift from reality.
• ? opens a full help overlay grouped by global, navigation, current pane, actions, and search.
• List aliases together, and never advertise a key that does nothing. Dim disabled actions and give the reason.
• Show the active sort, filter, mode, and match count. Do not overload plain typing silently.
• Treat empty states as content. Distinguish "nothing exists", "no match", "loading", "failed", and "no access", and give the next action: No matches for "prod". Press Esc to clear the filter.

Report state and errors honestly

• Print something within 100ms. Silence during slow work looks like a hang.
• Use a spinner only for unknown durations; switch to counts or a progress measure when totals are known. Always label what is happening.
• Stop animation on success, failure, cancellation, or non-interactive output, and keep the frame rate low enough for ssh and slow terminals.
• Show loading inside the affected pane and keep the surrounding context.
• Every error answers three questions: what failed, why, and what to do next. Rewrite low-level errors into domain language. Put the action last.
• Group repeated failures under one explanation instead of one paragraph each.
• Keep recoverable errors inside the TUI, preserve the user's input and selection, and offer the retry key. Restore the terminal before a fatal error prints.
• Confirm irreversible, broad, or externally visible actions, and name the target: Delete 12 pods in production? Default the focus to cancel.
• Do not confirm actions with reliable undo. Offer undo instead, and only advertise it when recovery is guaranteed.