tui-design · diff
git:20260711.50f65ee to git:20260819.ccef008
91 added, 266 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
---
name: tui-design
- description: Design and build clean, professional, minimal terminal UI (TUI) applications and command-line tools. Use this skill whenever the user is building, designing, refactoring, reviewing, or asking about terminal interfaces — full-screen TUIs (file managers, dashboards, monitors, git/k8s tools, REPLs), interactive CLI prompts, or simple command-line utilities. Use it for library questions ("Bubble Tea vs Ratatui vs Textual vs Ink"), design questions ("how should I lay out this dashboard"), and concrete build requests ("build me a TUI for X"), even when the user doesn't say "TUI" explicitly — phrases like "terminal app", "ncurses-style", "interactive shell tool", "CLI dashboard", "fzf-like picker", or naming a known TUI app (lazygit, k9s, btop, helix, yazi) all qualify.
+ description: Design, build, refactor, or review terminal interfaces—full-screen TUIs, interactive prompts, and command-line tools. Use for terminal-app layout and UX, CLI behavior, ncurses-style tools, dashboards, REPLs, fzf-like pickers, and libraries such as Bubble Tea, Ratatui, Textual, or Ink, including requests that name a known TUI such as lazygit, k9s, btop, helix, or yazi instead of saying “TUI.” Do not use for browser or web UI, native GUI, editor or font configuration, or backend and shell work that has no terminal interface.
---
# TUI & CLI Design
- Build terminal applications that feel professional — the way `lazygit`, `k9s`, `btop`, `helix`, `fzf`, and `yazi` feel. The terminal is enjoying a renaissance: Charm (Go), Ratatui (Rust), Textual (Python), and Ink (TypeScript) have each crystallized a mature philosophy. This skill teaches the universal patterns that make TUIs feel good plus per-ecosystem deep-dives in `references/`.
-
- ## When to read which reference
+ Design terminal software that is calm, predictable, fast, and honest about the medium. Treat this file as the workflow and cross-cutting contract. Load detailed guidance from the one reference that owns it instead of reconstructing or repeating it here.
- Use this skill's body for the **universal principles** below. Then load reference files on demand:
+ ## Route before answering
- | Situation | Read |
+ | Need | Authoritative reference |
|---|---|
- | User picked Go / mentioned Bubble Tea, Charm, Lipgloss, tview, gocui | `references/ecosystem-go.md` |
- | User picked Rust / mentioned Ratatui, crossterm, tui-rs, Cursive | `references/ecosystem-rust.md` |
- | User picked Python / mentioned Textual, Rich, prompt_toolkit, urwid | `references/ecosystem-python.md` |
- | User picked TS/JS / mentioned Ink, blessed, OpenTUI, Clack, Inquirer | `references/ecosystem-typescript.md` |
- | Building a non-interactive CLI (no full-screen UI) | `references/cli-basics.md` |
- | Designing layout, borders, color, typography, density, theming, icons, progress/loading/disconnected states | `references/visual-patterns.md` |
- | Designing keybindings, focus, navigation, modal vs modeless, forms/settings screens | `references/interaction-patterns.md` |
- | Studying what makes specific apps great (lazygit, k9s, fzf, btop, helix, yazi, atuin) | `references/exemplar-apps.md` |
- | Testing or debugging a TUI | that ecosystem's `references/ecosystem-*.md` (Testing / Debugging sections) |
- | Inline vs full-screen; clipboard, hyperlinks, notifications (OSC) | `references/visual-patterns.md` → *Inline, alt-screen, or overlay*; `references/interaction-patterns.md` → *Talking to the terminal emulator* |
- | Capturing a screenshot or demo GIF of the finished app | Not this skill — use the separate `vhs-cli-demos` skill |
-
- If the user hasn't named a language, ask which ecosystem before diving into framework specifics. The universal principles below apply regardless.
-
- ---
-
- ## The terminal is a constrained design medium
-
- Every cell is the same width. Type size doesn't change. You have ~80×24 characters at the small end, maybe 200×60 if you're lucky. You can't draw arbitrary pixels; you compose grids of characters with foreground/background colors and a handful of attributes (bold, dim, italic, underline, reverse). These constraints are the **point** — they force clarity. When something feels cramped or noisy in a TUI, the answer is almost never "add more"; it's usually "remove something or use whitespace."
-
- Three observations that drive everything else:
-
- 1. **Spatial memory is the navigation.** Users learn where things live: the file list is left, the diff is right, the status bar is bottom. Once that's established, panels must never move without explicit action. Reordering panels on focus is among the worst sins a TUI can commit.
- 2. **Color encodes meaning, not appearance.** Treat colors as semantic tokens (`status.error`, `text.muted`, `accent.primary`), not raw hex codes. The app should be *usable in monochrome* — color is enhancement, never the only signal. ~8% of males have red-green CVD; pair color with letters or symbols.
- 3. **Keyboard is primary; mouse is augmentation.** Every action must be reachable from the keyboard. Mouse can speed things up but never gates functionality. Vim motions (`hjkl`, `/`, `?`, `Esc`, `q`, `gg`, `G`) are the lingua franca even for non-vim users — supporting them is a courtesy that costs nothing.
-
- ## The seven canonical layouts
-
- Most successful TUIs use one of these. Choose by workflow shape, not by aesthetics:
-
- - **Persistent multi-panel** — All panels visible in fixed positions, focus shifts between them. Numeric keys (`1`–`5`) jump directly. Used by **lazygit, btop, htop**. Best for at-a-glance observation and switching between views of related state.
- - **Miller columns** — Three (or N) columns: parent → current → preview. `h`/`l` ascend/descend. Used by **yazi, ranger, broot**. Best for hierarchies (filesystems, JSON, K8s resources). Degrades poorly on narrow terminals — provide a single-pane fallback.
- - **Drill-down stack** — Browser-style: navigate deeper with a back-stack, `Esc` returns. Often paired with command-mode navigation (`:pods`, `:nodes`). Used by **k9s, lazydocker**. Best when there are many resource types and the user needs to pivot between them.
- - **Widget dashboard** — Independent widgets in a grid, each owning its data lifecycle. Layout configurable via TOML/YAML. Used by **bottom, btop, glances**. Best for monitoring/observability where users want to compose their own view.
- - **IDE three-panel** — Sidebar → main content → detail/output, often with tabs in the main panel. Used by **Posting, Harlequin, helix**. Best for editor-like workflows.
- - **Overlay / popup** — Appears over the shell, does one thing, exits. Used by **fzf, atuin, zoxide+fzf**. Best for "summon → choose → output" interactions. See `references/visual-patterns.md` → *Inline, alt-screen, or overlay* for the buffer choice and exit contract.
- - **Tabbed within panel** — Tab bars cycled with `[`/`]`. Used inside larger layouts (lazygit's Local/Remotes/Tags, lazydocker's Logs/Stats/Env tabs). Best when one panel needs multiple personalities without changing the global layout.
-
- The universal rule: **panels never move without explicit user action.**
-
- ## Visual hierarchy without varying type size
-
- Since you can't change font size, hierarchy comes from:
-
- - **Position** — top/left reads first; status bar at bottom; headers at top.
- - **Color and weight** — bold + accent color for titles and focused panel borders; dim for metadata, timestamps, disabled items; default weight for primary text.
- - **Reverse video** — universally available since VT100; the canonical way to mark current selection. Works on every terminal.
- - **Indentation and connectors** — `├─ └─` for trees; consistent indent units (2 cells is standard).
- - **Whitespace and bullets** — `▶` expandable, `▼` expanded, `●` active, `○` inactive, `•` static bullet.
- - **Borders for focus** — border *color* change is the strongest focus indicator. Lipgloss, Ratatui, Textual, and Ink all support per-side border styling.
-
- Use **bold** for titles, selection labels, and primary content. Use **dim** for metadata and disabled items. Use **italic** sparingly (poorly supported on many terminals — never the only signal). Use **underline** for hyperlinks (OSC 8) and shortcut hints. Use **reverse video** for the cursor row and current selection. Avoid blink (disabled in most modern terminals; accessibility hazard) and strikethrough (limited support).
-
- ## Color as a semantic system
-
- Design in three tiers:
-
- 1. **Monochrome** — does the app work with `NO_COLOR=1`? If layout, weight, and reverse video carry the meaning, yes.
- 2. **16 ANSI** — does it look right with the user's theme (Solarized, Gruvbox, whatever)? You don't control these; theme-coherent palettes do.
- 3. **256 / truecolor** — fine-grained palette for designed themes (Catppuccin, Dracula, Nord). Detect via `$COLORTERM=truecolor`.
-
- **Always respect `NO_COLOR`** (no-color.org). `ripgrep`, `bat`, `eza`, `delta`, `fd` all do.
-
- Conventional meanings have crystallized:
- - **Green** → success, added, online
- - **Red** → error, deleted, danger
- - **Yellow** → warning, modified, pending
- - **Cyan / Blue** → info, paths, links
- - **Magenta** → special, highlights
- - **Dim / gray** → secondary, disabled
-
- Define semantic tokens (`status.error`, `git.staged`, `text.muted`) and theme them. Lipgloss's `LightDark` (v2; `AdaptiveColor` in v1/compat), Textual's CSS variables, and Ratatui's palette pipelines all implement this indirection. Scattering hex codes through code is a phase you grow out of.
-
- **Never use color alone.** Pair with letters (lazygit's file status: `M` modified, `A` added, `D` deleted, `??` untracked) or symbols (delta's `+`/`-` line prefixes). Safe color pairs for CVD: blue+orange, blue+yellow, black+white.
-
- ## Borders, density, and whitespace
-
- Use single-line borders (`─ │ ┌ ┐ └ ┘`) by default. Rounded (`╭ ╮ ╰ ╯`) is the modern Charm aesthetic — fine, slightly softer. Heavy (`━ ┃ ┏`) for emphasis sparingly. **Avoid double-line** (`═ ║ ╔`) — it reads as "DOS." Always provide ASCII fallback (`+`, `-`, `|`) for legacy SSH and `TERM=dumb`.
-
- When to use borders vs whitespace:
- - **Borders** — when the pane has dynamic content needing a visible boundary, when focus state must be shown, when adjacent panels need clear separation.
- - **Whitespace alone** — when content is static (htop has no internal borders) or density matters more than structure. A single blank row often beats a heavy border.
-
- Density choices:
- - **Pack** when data is scanned at a glance, updates in real time, or is read horizontally across rows (htop, btop, k9s).
- - **Pad** when reading prose, filling forms, or making single decisions (gum/huh forms, Glow markdown, Posting).
-
- Don't decorate. Borders that exist purely for "looks polished" usually make the app feel busier without adding meaning.
-
- ## Two reflexes to apply unprompted
-
- These are the two things the default instinct misses most, because users rarely ask for them by name — and a strong base model will answer the literal question without raising either. Apply both to **any** layout you design or review, even when the user asked about something else entirely (a color choice, a keybinding, "why does this feel busy"). This is where most of the value is.
-
- **1. Run a clutter audit — make "feels busy" countable.** Never answer "it feels noisy" with "simplify it." Count the offenders and name the specific cuts: border-nesting depth (more than *one* border between the terminal edge and the content is too many; an outer full-screen frame is almost always redundant), how many separate signals encode the same state (`[PASS]` + green + `✅` + a row marker is four), markers that sit on every row (a glyph on 100% of rows marks nothing), and the ratio of cells spent on chrome — borders, labels, repeated boilerplate like a full datestamp on every log line — versus actual data. The full method is in `references/visual-patterns.md` → *The clutter audit*.
-
- **2. Pressure-test the floor.** A layout designed at the author's own window size is unfinished — they never see it break because they only ever see their own terminal. State concretely what happens at **80×24 and a 60-column tmux split**: what collapses to a single pane, what hides, what truncates, and the "terminal too small" message below the minimum. Multi-column layouts (Miller columns, 2×N grids) must have a single-pane fallback. **Raise this in every layout review even when size was never mentioned** — it is the single most-missed issue in TUI design, and "it looks great on my screen" is exactly the blind spot it addresses. Breakpoint ladder in `references/visual-patterns.md` → *Responsive design*.
-
- ## Tables and lists
-
- Always:
- - **Align numerics right, text left, dates as fixed-width ISO-8601.**
- - **Truncate, don't wrap, in cells.** Tail truncation (`/usr/local/share/...`) for paths in lists. Middle truncation (`/usr/.../file.txt`) when the basename matters. Reserve a cell for the ellipsis.
- - **Show a count** (`123/45678` like fzf does) when filtering.
- - **Sort indicator** (`▲`/`▼`) on the active column.
- - **Detail-on-Enter** as the universal escape hatch — pressing Enter on a row reveals all fields in a side panel or modal. This lets you hide low-priority columns at narrow widths without losing access to the data.
- - **Virtualize** any list that might exceed a few hundred items. k9s renders thousands of pods, Toolong tails multi-GB logs — both virtualize. Built into Textual `DataTable`, Ratatui `Table`+`TableState`, Bubbles `list`, Ink with `<Static>`.
-
- ## Status bars, headers, footers
-
- The convention that has converged across nearly every modern TUI:
+ | Go, Bubble Tea, Lipgloss, Bubbles, tview, gocui | `references/ecosystem-go.md` |
+ | Rust, Ratatui, crossterm, Cursive | `references/ecosystem-rust.md` |
+ | Python, Textual, Rich, prompt_toolkit, urwid | `references/ecosystem-python.md` |
+ | TypeScript/JavaScript, Ink, OpenTUI, Clack, Inquirer | `references/ecosystem-typescript.md` |
+ | One-shot commands, arguments, streams, exit codes, automation | `references/cli-basics.md` |
+ | Layouts, buffers, borders, hierarchy, color, density, responsive behavior, tables, themes, accessibility | `references/visual-patterns.md` |
+ | Keys, focus, navigation, modes, forms, mouse, confirmation, undo, OSC features | `references/interaction-patterns.md` |
+ | Case studies: lazygit, k9s, fzf, btop, helix, yazi, atuin | `references/exemplar-apps.md` |
+ | Screenshots or demo recordings | Use the separate `vhs-cli-demos` skill |
- - **Header (top)** — persistent context: what app, what dataset, what mode. htop's CPU/mem meters; k9s's cluster/context/namespace; lazygit's branch and repo.
- - **Main area (middle)** — the panels. This is where the work happens.
- - **Status / mode line** — ephemeral feedback ("Saved", "3 files changed") with auto-fade. Vim-style mode indicators (NORMAL/INSERT/SELECT) with distinct cursor shapes.
- - **Footer hint bar (bottom)** — 3–5 most-useful shortcuts always visible, full reference behind `?`.
+ Load only the references the task needs. When the prompt names a framework or ecosystem, always load its ecosystem reference before making API, lifecycle, implementation, or testing claims. Ecosystem references own those specifics. The visual and interaction references own their domains for every ecosystem. Exemplar apps are evidence and inspiration, not substitutes for the pattern references.
- The footer hint bar is the single most important discoverability tool. htop's F1–F10 strip; lazygit's per-pane hints; Bubble Tea's `bubbles/help` auto-generates from the keymap; Textual's `Footer` widget renders bindings declared via `BINDINGS`. **Don't make users read docs to discover basic actions.**
+ If no language is named, ask only when ecosystem choice would materially change the answer or implementation. Otherwise state a reasonable recommendation and proceed: Go for polished single binaries, Rust for control and reliability, Python for rapid product work, and TypeScript when React or npm distribution is already an advantage.
- ## Keys: discoverability and conventions
+ ## Classify the product first
- **Cross-app conventions** that have crystallized — use these unless you have a strong reason not to:
+ Choose the output contract before choosing a framework or layout:
- | Key | Action |
+ | Product shape | Default contract |
|---|---|
- | `q` | quit |
- | `?` | help |
- | `/` | search |
- | `n` / `N` | next / prev match |
- | `Esc` | cancel / back |
- | `Enter` | confirm / drill in |
- | `Space` | toggle / mark for multi-select |
- | `:` | command mode |
- | `gg` / `G` | top / bottom |
- | `Tab` / `Shift+Tab` | switch focus |
- | `r` | refresh |
- | `1`–`9` | jump to panel / numbered tab |
- | `hjkl` *and* arrows | move (support both) |
-
- **Never bind these — they belong to the terminal:**
- - `Ctrl+C` (SIGINT — should always quit cleanly)
- - `Ctrl+Z` (SIGTSTP — suspend; you must restore terminal state on resume)
- - `Ctrl+\` (SIGQUIT)
- - `Ctrl+S` / `Ctrl+Q` (XON/XOFF flow control on legacy terminals)
-
- **Discoverability is layered:**
-
- 1. Always-visible footer hints (3–5 most useful keys)
- 2. `?` opens a help screen with all bindings
- 3. Leader-key prefixes show a which-key popup (helix's `Space-` menu is the gold standard)
- 4. Command palette (`Ctrl+P`) — every action with a binding should also be a palette command
- 5. Documentation as the last resort, not the first
-
- **Modal vs modeless** is a real choice. Modal apps (vim, helix, k9s ex-mode) get denser keybindings and need persistent mode indicators (status-bar color or label) plus distinct cursor shapes. Modeless apps (Textual, Bubble Tea, btop) lean on widget focus. Both are valid; pick one paradigm and stick with it.
-
- **Mouse support** is contested. The pragmatic answer: support mouse where it's natural (clicking a tab, scrolling a list, focusing a pane) but require nothing of it. Every mouse-reachable target needs a keyboard equivalent. Note that mouse capture disables terminal text-selection — most emulators bypass with Shift.
-
- ## The non-negotiables (terminal hygiene)
-
- These four are the difference between an app that feels professional and one that doesn't:
-
- 1. **Use the alternate screen for full-screen TUIs.** Don't pollute the user's scrollback. On exit, the terminal returns to where it was.
- 2. **Always restore terminal state on exit — even on panic.** Install panic/atexit handlers that disable raw mode, leave alt screen, and restore the cursor *before* printing the trace. A panicking TUI that leaves raw mode + alt screen is the worst possible UX. Ratatui's `color_eyre` integration, Bubble Tea's `defer p.RestoreTerminal()`, Textual's exception cleanup, Ink's `unmount()` all do this.
- 3. **Handle resize (`SIGWINCH`).** Re-layout on every resize event; debounce rapid resizes. Define a minimum size (typically 80×24) and render a clear "terminal too small" message rather than crash. Use percentages, `fr` units, `min`/`max`, and ratios — never absolute positions.
- 4. **Handle suspend (`Ctrl+Z` / `SIGTSTP`).** On suspend: disable raw mode, leave alt screen, restore cursor, then `kill(0, SIGTSTP)`. On `SIGCONT`: re-enter alt screen and force a full redraw. Windows lacks SIGTSTP; that's fine.
-
- Other essentials:
-
- - **Never block the UI thread on I/O.** All network/disk/subprocess work happens in goroutines/tasks/promises; results flow back via messages/channels/events.
- - **Don't redraw on a fixed timer.** Redraw on events. Most apps idle at 0 fps until something happens. Cap animations at 30–60 fps.
- - **Logging can't go to stdout.** Alt-screen + raw mode would corrupt the UI — see *Testing and debugging* below for the file-log + `tail -f` workflow and per-ecosystem APIs.
- - **Cell width ≠ string length.** CJK ideographs are width 2; emoji should be width 2 (legacy `wcwidth` lies). Use `unicode-segmentation` (Rust), `golang.org/x/text` + `mattn/go-runewidth` (Go), `wcwidth` (Python), `string-width` (JS — Ink uses this) — never `len()` or `.length`.
- - **Clipboard, hyperlinks, and desktop notifications go through OSC escapes** (52 / 8 / 9) — the *local* emulator interprets them, so they work over SSH where shelling out to `pbcopy`/`xclip` can't. Support matrices and tmux caveats: `references/interaction-patterns.md` → *Talking to the terminal emulator*.
-
- ## Testing and debugging
-
- TUIs are testable; teams that skip tests usually just don't know the shape. Three layers, bottom-heavy:
-
- 1. **Unit-test the update/event layer as pure functions.** Every modern framework separates state change from rendering — feed a synthetic key event in, assert on state out. Cheapest, least flaky, and catches the "Tab silently stopped working" class of regression. Even Charm's own apps lean on this layer over harnesses.
- 2. **Golden/snapshot the rendered frame** at a *pinned terminal size and color profile* — unpinned size or profile is the #1 cause of snapshot tests that flap in CI. Harnesses: teatest/v2 golden files (Go), `TestBackend` + insta (Rust), Pilot + pytest-textual-snapshot (Python), ink-testing-library frame assertions (TS).
- 3. **PTY end-to-end sparingly** — one or two smoke flows at most; it's slow and the tooling is thin in every ecosystem.
-
- Debugging follows one rule: **never write debug output to the terminal the TUI owns** — raw mode + alt screen turn `print` into screen corruption. Log to a file and `tail -f` it in a second terminal, or use the framework's dev console. Exact APIs live in each ecosystem reference's Testing / Debugging sections.
-
- ## Performance and compatibility
-
- **Truecolor is now safe to assume** in 2026. Detect via `$COLORTERM=truecolor`; fall back to 256 then 16 then monochrome. The Kitty keyboard protocol (CSI u) is supported by kitty, foot, WezTerm, Alacritty, iTerm2, Ghostty, Rio, and Windows Terminal — opt-in for advanced bindings (Ctrl+I distinct from Tab, Shift+Enter distinct from Enter), always with legacy fallback.
+ | One-shot CLI | No live full-screen UI. Stable stdout for results, stderr for diagnostics, meaningful exit codes. Load `cli-basics.md`. |
+ | Summon–choose–exit tool | Prefer inline when shell context matters. Put interactive chrome on stderr or `/dev/tty` and the selected result on stdout. Use full-screen only when a large preview or working set needs stable space. |
+ | Full-screen session | Use the alternate screen and a stable spatial model. Treat terminal restoration, resize, suspend, and redraw behavior as product requirements. |
- **SSH and tmux** strip features unless explicitly enabled. For tmux:
- ```
- set -ga terminal-overrides ",*:Tc" # truecolor passthrough
- set -g extended-keys on # CSI u
- set -g extended-keys-format csi-u
- set -g allow-passthrough on # kitty graphics
- set -g mouse on # mouse forwarding
- set -g set-clipboard on # OSC 52 clipboard
- ```
+ Then name the workflow shape—persistent panels, Miller columns, drill-down stack, dashboard, IDE-style panes, overlay, or tabs—and verify it against `visual-patterns.md`. Sketch the states and layout before writing code: initial, loading, empty, partial, success, error, disconnected, and too-small.
- **Image protocols are fragmented**: kitty graphics (best quality) → Sixel (broadest compat) → iTerm2 inline. yazi auto-detects and supports all three.
+ ## Work the task
- ## Accessibility — the honest take
+ 1. Classify the product shape and its stdout/stderr contract.
+ 2. Identify the dominant user loop and the 5–8 most common actions.
+ 3. Select the ecosystem and load its reference plus any relevant pattern reference.
+ 4. Sketch the layout and state transitions at wide, standard, narrow, and minimum sizes.
+ 5. Implement in the ecosystem's native architecture; keep state/update/event work separate from rendering where the framework permits.
+ 6. Verify lifecycle cleanup, input discoverability, output behavior, width handling, and async work.
+ 7. Test the cheapest stable layer first, then rendered frames, then a small PTY smoke path only if its integration risk justifies it.
- TUIs are inherently inaccessible to screen readers. NVDA, JAWS, VoiceOver, and Orca read the visible buffer like a textbox, with no concept of widgets or focus. Best current practices when accessibility matters:
+ For design questions, make the recommendation before explaining it. For implementation, inspect the existing architecture and dependencies before introducing a new framework or abstraction. For reviews, cite concrete observations and prioritize changes by user harm.
- - Linear left-to-right, top-to-bottom layouts where possible.
- - Never color-alone signals; pair with words (`[ERROR]`, `[OK]`, `[!]`).
- - Full keyboard parity — every action reachable via keyboard.
- - Provide a `--no-tui` plain mode that just prints output linearly.
- - For Python/Textual specifically, `textual serve` → HTML is currently the best a11y route — same code runs in a browser, where real accessibility tooling exists.
+ ## Preserve these cross-cutting contracts
- If a11y matters seriously, ship a web alternative or a plain-CLI mode alongside the TUI. Don't pretend the TUI alone is accessible.
+ ### Terminal lifecycle
- ## Theming
+ - Use the alternate screen for full-screen sessions; keep bounded and one-shot workflows inline when possible.
+ - Prefer framework-managed terminal cleanup. Restore raw mode, screen buffer, cursor, and input modes on every exit path, including errors and panics. Do not invent custom signal handling when the framework already owns it.
+ - Re-layout from the current frame or window size on resize. Coalesce bursts only when layout work is expensive.
+ - Treat final shutdown and temporary handoff as different boundaries. For an editor, shell, or supported suspend, prefer the framework's handoff API: pause UI input, restore the shell-facing terminal, wait, re-enter modes, reload externally mutable data, and force a full redraw. Redrawing only repaints the current model; it does not refresh changed data. Do not final-unmount an app that must resume, and do not assume POSIX signals exist on Windows.
+ - Keep logs and debug output away from the screen the TUI owns. Use a file, framework console, or separate diagnostic stream.
- Most production TUIs support themes via TOML/YAML config (lazygit, bottom, btop, helix, delta, bat, fzf), TCSS files (Textual), or composable styles (Lipgloss). Light/dark detection via OSC `]11;?` query or `$COLORFGBG`; Lipgloss's `LightDark` and Textual's runtime theme switching are the cleanest implementations.
+ ### Rendering, data, and performance
- Community palettes you should be able to support: Catppuccin (Latte/Frappé/Macchiato/Mocha), Dracula, Nord, Gruvbox, Tokyo Night, Rose Pine, Solarized, base16. Build your theme via semantic tokens, then map tokens → palette colors. Adding a new theme should be one config file, not a code change.
+ - Never block the UI/event thread on disk, network, or subprocess work. Return results through commands, messages, tasks, channels, or framework events.
+ - Render on input, data, resize, or intentional ticks; do not redraw unchanged state in an unconditional loop.
+ - Measure terminal cell width, not bytes, code points, `len()`, or JavaScript string length. Test CJK, combining marks, and emoji.
+ - Virtualize collections that can grow beyond a few hundred rows. Truncate rather than wrap inside tables; reveal full values in a detail view.
+ - Keep panel positions stable unless the user explicitly changes the layout. Spatial memory is part of navigation.
- ## Patterns worth naming
+ ### Meaning and access
- Recognize these and refer to them by name. Implementation recipes live in `references/interaction-patterns.md`; case studies of the apps that exemplify them live in `references/exemplar-apps.md`.
+ - Define semantic style tokens rather than scattering color literals. Honor `NO_COLOR` in automatic color mode and preserve meaning in monochrome.
+ - Never use color alone. Pair it with text, shape, position, or symbols, and provide an ASCII fallback when Unicode support is uncertain.
+ - Make every action keyboard-reachable. Mouse support may accelerate an action but must not gate it.
+ - Offer familiar navigation aliases only where they do not conflict with text entry or a complete bounded prompt keymap. Preserve terminal-reserved behavior such as interrupt, suspend, and flow control.
+ - Match discoverability to complexity: complete inline controls for bounded prompts; contextual hints, help, and optionally a command palette for action-rich full-screen apps.
+ - Provide a plain `--no-tui` or equivalent mode when automation or serious accessibility needs require linear output.
- - **The fzf pattern** — instant fuzzy filter as the core interaction. fzf, skim, telescope.nvim, atuin, zoxide, helix, Textual's command palette.
- - **The lazygit pattern** — multi-pane with numeric tab navigation and panel-specific letter actions.
- - **The k9s pattern** — command-driven via vim-style ex-commands with tab-completion.
- - **The helix pattern** — selection-first modal editing with multi-cursor as primary.
- - **The miller-columns pattern** — three columns (parent / current / preview). ranger, lf, nnn, yazi, broot.
- - **The command palette pattern** — `Ctrl+P` fuzzy-matched action list; every bound action should also be a palette command.
- - **Dual product** — ship CLI + TUI from the same core (helix, atuin, posting, gh); the CLI handles scripts, the TUI handles exploration.
+ ## Apply two review reflexes unprompted
- ## Common pitfalls
+ These catch the failures users rarely name. Apply both to every layout you design or review, even when the question is about something else.
- Ranked by real-world complaint frequency:
+ ### Run a clutter audit
- 1. **Hardcoded colors clashing with user themes.** Use semantic tokens.
- 2. **Crash on resize.** Subscribe to `SIGWINCH`; debounce; never assume fixed dimensions.
- 3. **Blocking the UI thread on I/O.** Async everything.
- 4. **Color-only signaling.** Add letters or symbols.
- 5. **Unicode glyphs failing on minimal SSH or Windows conhost.** Provide ASCII fallback.
- 6. **Polluting scrollback.** Use the alternate screen.
- 7. **Binding terminal-reserved keys** (Ctrl+C, Ctrl+Z, Ctrl+S/Q).
- 8. **Wall-of-shortcuts with no progressive disclosure.** Footer → `?` → palette.
- 9. **Inconsistent spatial layout** (panels reordering on focus). Don't.
- 10. **Misaligned tables** when text contains CJK or emoji. Use cell-width libraries.
+ Make “busy” countable. Report:
- ## Decision flow for new TUI/CLI projects
+ - border-nesting depth—more than one border between the terminal edge and content is usually too much;
+ - how many signals encode the same state—`[PASS]`, green, a checkmark, and a row marker is four;
+ - markers present on every row, which therefore mark nothing;
+ - the share of cells spent on chrome, labels, and repeated boilerplate instead of data.
- When the user asks you to build something:
+ Name the exact borders, markers, labels, or repeated fields to remove. Do not stop at “simplify it.” Use the full method in `visual-patterns.md` → *The clutter audit*.
- 1. **Is this a one-shot command, a summon-choose-exit tool, or a full-screen app?**
- - One-shot CLI (no UI, exits when done) → load `references/cli-basics.md`. Apply argparse + color + maybe a spinner and you're done.
- - Summon–choose–exit tool (fzf-class picker, prompt, wizard, live progress) → render **inline**, not on the alt screen: bounded height, machine-readable result to stdout, a one-line receipt left in scrollback. See `references/visual-patterns.md` → *Inline, alt-screen, or overlay*.
- - Full-screen interactive (a session you live in) → alt screen; continue.
+ ### Pressure-test the floor
- 2. **What ecosystem?**
- - Already chosen → load that ecosystem's reference.
- - Not chosen → ask. Quick guide: Go for compiled binaries with great styling (Bubble Tea); Rust for performance and reliability (Ratatui); Python for rapid development with web-deploy option (Textual); TS/JS for npm distribution and React-familiar teams (Ink).
+ State what happens at 80×24 and in a 60-column tmux split: which pane wins, what hides, what truncates, what becomes drill-down, and when the truthful “terminal too small” state appears. Every multi-column design needs a single-pane fallback. Use the breakpoint ladder and minimum-size method in `visual-patterns.md` → *Responsive design*.
- 3. **What's the workflow shape?** Match to one of the seven canonical layouts above before writing any code. Sketch the panels in ASCII first.
+ ## Build and verification discipline
- 4. **What are the 5–8 most common actions?** Those become the always-visible footer hints. Everything else lives behind `?` or the command palette.
+ Keep business state independent enough to test without a terminal. In MVU or immediate-mode systems, feed synthetic events into update logic and assert state. In retained/widget systems, drive the smallest widget or app harness that owns the behavior.
- 5. **What's the data model?** Lists, trees, tables, forms, free-text? This determines which widgets you need and whether to virtualize.
+ Use a bottom-heavy test pyramid:
- 6. **What's the responsive plan across sizes?** Don't design for one window. Walk the breakpoint ladder (wide >120 / standard 80–120 / narrow 60–80 / too-small below) and decide what gets hidden, collapsed, or stacked at each — and the "terminal too small" message below the 80×24 floor. A fixed grid that can't fold to a single pane is a design smell; drill-down degrades more gracefully. See `references/visual-patterns.md` → *Responsive design*.
+ 1. Unit-test state transitions, parsing, sorting, filtering, and command construction.
+ 2. Snapshot or golden-test rendered frames at pinned terminal sizes and color profiles, including 80×24, 60 columns, and the hard minimum.
+ 3. Use one or two PTY end-to-end flows for lifecycle and real-keyboard integration, not as the primary suite.
- Then, with the ecosystem reference loaded, write the code. The non-negotiables (alt screen, terminal restoration, resize, suspend, async I/O, no UI-thread blocking) apply regardless of language.
+ Verify at least:
- ## When reviewing or refactoring an existing TUI
+ - normal exit, interrupt, error, and panic cleanup;
+ - resize, too-small behavior, and suspend/resume where supported;
+ - empty, loading, partial, error, disconnected, and large-data states;
+ - keyboard reachability, focus visibility, and help accuracy;
+ - `NO_COLOR`, 16-color or monochrome, ASCII fallback, and non-TTY output;
+ - wide characters, combining marks, truncation, sorting, and virtualization;
+ - no stdout corruption and no blocking I/O in the event/render path.
- Walk through this checklist:
+ Use the ecosystem reference's exact testing and debugging APIs. Never print diagnostics into an active raw-mode or alternate-screen UI.
- - **Should this even be full-screen?** A summon-choose-exit tool (picker, prompt, one-shot progress) belongs inline, not on the alt screen — see *Inline, alt-screen, or overlay*. If full-screen is right: does it use the alternate screen, and restore terminal state on panic?
- - Does it handle resize and suspend?
- - Are colors semantic tokens, or hardcoded? Is `NO_COLOR` honored?
- - Is the app usable in monochrome (color removed, layout still readable)?
- - Are there always-visible footer hints? Does `?` show full help?
- - Is every action keyboard-reachable? Are `q` and `Esc` consistent?
- - Are panels in fixed positions? Or do they jump around on focus?
- - **Clutter audit** — border-nesting depth (>1 inside a panel?), duplicate signals encoding one state, markers on every row, chrome-vs-data ratio. Name specific cuts, not "simplify."
- - **Pressure-test the floor** — what does this do at 80×24 and a 60-col tmux split? Is there a degradation plan (what hides / collapses / stacks) and a "too small" message? Flag this even if the user didn't ask about size.
- - Are tables aligned correctly? Do they handle CJK / emoji width?
- - Are long lists virtualized?
- - Does I/O block the UI thread anywhere?
- - Are reserved keys (Ctrl+C/Z/S/Q) bound to anything?
- - Does copy/yank go through OSC 52 so it survives SSH and tmux? Are OSC 8 links and OSC 9 notifications used where they'd help, and not overused?
- - Does it ship with at least one popular community theme support (Catppuccin, Gruvbox, etc.) or a way to define one?
- - Is the update/event layer unit-testable as pure functions? Are frame snapshots (if any) pinned to a size and color profile?
+ ## Review existing interfaces
- Most existing TUIs fail 3–5 of these. Calling them out specifically gives the user a concrete improvement path.
+ Report evidence in priority order:
- ---
+ 1. Is the product shape right, or should a full-screen flow be inline or one-shot?
+ 2. Can any exit path leave raw mode, cursor state, mouse capture, or the screen buffer behind?
+ 3. Does the UI block, redraw wastefully, crash on resize, or mismeasure cell width?
+ 4. Can a first-time user find and reach the important actions without breaking text entry or terminal conventions?
+ 5. What does the clutter audit count, and which exact elements should be cut?
+ 6. What happens at 80×24, 60 columns, and the declared minimum?
+ 7. Do output streams, exit codes, non-TTY behavior, `NO_COLOR`, and plain mode support scripts and accessibility?
+ 8. Are state transitions and pinned frames covered at the right test layers?
- ## Style of help to give
+ Avoid generic verdicts. Tie each recommendation to a user-visible failure, an implementation risk, or a measurable reduction in noise.
- When the user asks "should I do X or Y?" — give a recommendation. The terminal renaissance has produced enough convergent design that many questions have a clear best answer (use the alternate screen, support `hjkl`+arrows, honor `NO_COLOR`, use semantic color tokens). Don't hedge on settled questions. Hedge on real tradeoffs (modal vs modeless, mouse support, single-key destructive actions vs always-confirm).
+ ## Give useful recommendations
- When showing code, prefer the idiom of the chosen ecosystem — don't translate Bubble Tea's MVU into Ratatui's immediate-mode and call it good. Each ecosystem has converged on a style; meet it where it is. The reference files document each one in detail.
+ Be decisive where practice has converged: semantic colors, clean terminal restoration, responsive fallback, non-blocking work, width-aware rendering, and honest stream contracts. Explain real tradeoffs for inline versus full-screen, modal versus modeless input, mouse support, and destructive-action confirmation.
- When the user is stuck on a design decision, point at an exemplar app that solved the same problem (`references/exemplar-apps.md`) — concrete examples beat abstract principles for design questions.
+ Use the chosen ecosystem's idioms rather than translating another framework's architecture literally. When a design choice remains abstract, point to the relevant case study in `exemplar-apps.md` and explain which part of its solution transfers.