/tui-design

name: tui-design
description: Use this skill when designing terminal user interfaces, creating TUI layouts, choosing TUI color schemes, implementing keyboard navigation, building terminal dashboards, or working with any TUI framework. Activates on mentions of TUI design, terminal UI, Ratatui layout, Ink components, Textual widgets, Bubbletea views, terminal color palette, keybinding design, panel layout, split panes, terminal dashboard, box-drawing characters, sparklines, progress bars, modal dialogs, focus management, or terminal accessibility.

TUI Design System

Design around the user's repeated action, the data they must keep in view, and the terminal capabilities actually available. Keep input responsive under slow I/O and make selection, focus, and operation state explicit.

**Primary documentation checked: 2026-09-04.** Framework APIs change; use the project's versions. Follow the project's visual identity (SilkCircuit Neon for Bliss's personal tools) rather than treating an example palette as a universal theme.

Choose the Layout from the Work

| Work | Layout | Useful invariant | | ---------------------------------------- | ------------------------------------ | --------------------------------------------------------- | | Browse related lists and details | Persistent multi-panel | Stable panel roles and visible focus | | Navigate a hierarchy | Miller columns or drill-down stack | Back restores selection and scroll position | | Monitor changing measurements | Widget dashboard | Labels, units, freshness, and a path to details | | Edit requests, queries, or configuration | Sidebar, editor, results | Keep editing state when switching panels | | Select a value for a shell command | Inline picker or overlay | Return a clean value and preserve shell scrollback | | Read logs or events | Fixed controls plus virtualized list | Follow mode is explicit; scrolling back stops auto-follow |

Read [app-patterns.md](references/app-patterns.md) for examples and tradeoffs. Read [visual-catalog.md](references/visual-catalog.md) only when selecting glyphs, borders, charts, or indicators.

Responsive Behavior

Use constraints and content priorities. Keep the selected item visible while collapsing secondary panels; preserve state when they reappear. Recompute layout on resize without treating a zero-sized transient area as an error. Clamp scrolling after filtering, deletion, or a smaller viewport.

Test narrow, ordinary, and wide layouts, including rapid resizing. The minimum usable size follows the task; 80x24 is a useful test case, not permission to disable a picker that would work in 40 columns. A size message should retain quit and recovery input.

Input, Focus, and Editing

| Concern | Decision | | ------------------- | ---------------------------------------------------------------------------------------- | | Basic navigation | Support arrows, Enter, Escape, and discoverable focus movement | | Expert shortcuts | Add vim motions or a command palette when they improve repeated work | | Text fields | Printable keys edit text; `q`, `j`, `/`, and mnemonic actions must not fire globally | | Multi-key shortcuts | Show pending context and resolve Escape/prefix ambiguity through the input library | | Modal dialog | Route input only to the modal; restore the prior valid focus target when it closes | | Destructive action | Show the exact target and consequence; choose confirmation proportional to reversibility | | Mouse support | Match keyboard actions and provide a way to disable capture for terminal text selection |

Maintain one owner for input parsing. With Crossterm, do not mix `EventStream` with `read`/`poll`, or run competing readers. Handle key press, repeat, and release deliberately; one physical press must not submit twice.

Enhanced keyboard protocols can distinguish keys that legacy terminals encode identically. Negotiate support and retain usable fallback bindings. Never assume Ctrl+I differs from Tab or Ctrl+M from Enter everywhere. Treat bracketed paste as a text event; pasted newlines must not accidentally submit destructive commands.

Raw mode can disable the terminal's normal signal handling. Implement Ctrl+C and suspend/resume deliberately through the framework; do not assume the OS will handle them unchanged. Restore terminal state before handing control to an editor, pager, shell, or suspended process, then reacquire it and redraw.

Show a short footer for currently available actions and a contextual help view. Keep essential instructions visible while a task is running. Durable errors need a retrievable location; a disappearing toast cannot be the only record.

State and Async Work

Separate input events, state transitions, effects, and rendering. Render a snapshot of state without starting network calls or mutating the domain model from a drawing function.

digraph tui_state {
    rankdir=LR;
    event -> update;
    update -> state;
    update -> effect;
    effect -> event [label="result + request identity"];
    state -> render;
}

| Failure mode | Design response | | ----------------------------------------------------- | ------------------------------------------------------------------------------------------ | | Search A completes after search B | Tag requests and discard results that no longer match the active query