tui-design

Files (1)

• SKILL.md

SKILL.md (first lines)

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

  ```bash
  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.

From caarlos0/dotfiles, MIT.

More from caarlos0/dotfiles