tui-design

Human-Centered TUI Design Reasoning

This section addresses the what and why of TUI design: terminal-specific constraints, keyboard interaction, focus models, and known design failures. The terminal requires its own design vocabulary. For implementation guidance, see TUI & CLI Design below. Any agent may use either section as needed.

The Terminal as a Constrained Design Environment

A terminal is not a canvas. It is a character-cell grid with properties that make it categorically different from a pixel-based surface:

Character-cell grid constraint. Every layout decision is made in character columns and rows, not pixels. An element that is 40 characters wide occupies exactly 40 character cells. There is no sub-pixel rendering, no anti-aliasing, no fractional positioning. Layout is integer arithmetic — splitting a 79-column terminal into two equal halves produces one 39-column and one 40-column pane (with one column for a border). Borders consume cells; a 1-character border on each side of a 40-column panel leaves 38 columns of content. This is not a limitation to work around — it is the design medium, and designing with it (not against it) produces clean, correct TUI layouts.

Cell-width ≠ byte-length. CJK characters are 2 cells wide. Many emoji are 2 cells wide. Combining marks may be 0 cells wide. Designing a table column as "20 characters" is ambiguous; designing it as "20 terminal cells" is precise. Truncation, alignment, and padding must all be specified in cell units.

Color depth varies by terminal. Three tiers:

• 16 ANSI colors — the universal baseline; maps to user's terminal color scheme (user controls exact RGB values). A TUI using only 16 colors works everywhere and respects the user's theme.
• 256 xterm colors — de facto standard for modern terminals; includes a 6×6×6 color cube and 24-color grayscale ramp.
• 24-bit true color — supported by most modern terminals (kitty, iTerm2, Windows Terminal, GNOME Terminal); not available in some SSH or embedded environments.