Vibe Rust Tui

Vibe Rust TUI

UI conventions for vibe/cli-rust/. Every screen follows them so the TUI reads as one product. Process rules (porting from Python, scenarios, goldens) live in migrate-cli-to-rust; local code rules live in vibe/cli-rust/AGENTS.md.

Shortcut hints

• Name keys and actions only through src/hints.rs: key::*, action::* and the shared pairs (hints::NAVIGATE, SELECT, SEARCH, CANCEL, CLOSE, BACK). Never write a key or action as a string literal at a call site. A single letter key ("d", "r") is fine as long as its action comes from action::*. When a key or verb is missing, add it to src/hints.rs.
• A hint is an unpadded (key, action) pair (hints::Hint). The renderer owns all spacing; never bake spaces into a label.
• Wording: actions are lowercase verbs (navigate, select, close); keys keep their canonical casing (Enter, Esc, Ctrl+C, Backspace). Combined keys use / (Space/Enter, Esc/Ctrl+C).
• Vertical navigation is key::NAV (↑↓/jk) whenever j/k work; use key::ARROWS (↑↓) only where a focused text field owns the letters. Horizontal navigation is key::LEFT_RIGHT (←→).
• Footers read key action key action, ending with the Esc hint. Inline status lines (loading line, narrator) are the one exception and read key to action.
• Render every footer through ui/hint_line.rs (draw, draw_clipped, line, spans, styled): they apply the shared key/action styles and clip to the box. Never place hint text with hardcoded x offsets or custom key styles. Center a hint with hints::width.
• Onboarding and dialogs follow the same footer form (Enter continue, Esc back), not sentences like "Press Esc to go back".

Keyboard navigation

• Every navigable list accepts j/k alongside ↑/↓ when no text field is focused. Match only plain keys (no Ctrl/Alt/Super) so Ctrl+J/Ctrl+K keep their editing meaning.
• Show the navigation keys a screen actually handles: write ↑↓/jk only where j/k are wired.
• Edges: ↑↓/jk (and ←→ across dialog options) wrap at both ends; PageUp/PageDown/Home/End clamp. Move through list_nav::wrap, or list_nav::wrap_selectable when some rows (section headers, notes, blanks) cannot take the cursor; never hand-roll saturating_sub/min(len - 1) for arrow moves. The only lists that do not wrap are the ones attached to the composer: Down past the newest queued prompt leaves queue mode, and Up at the top of the subagent list returns focus to the composer.
• Back: Esc goes back exactly one level (field → list, detail → list, auth flow → its /mcp list) and closes only at the top level. Backspace edits text and is never a navigation key. A nested view's footer ends with hints::BACK (Esc back); a top-level view's footer ends with hints::CLOSE or hints::CANCEL.
• Digits: a row's digit shortcut exists if and only if the row displays its number (1. Trust folder). Pressing it is the same as moving to the row and pressing Enter. Parse it with list_nav::digit; never accept digits on unnumbered rows, and never number rows that do not accept their digit.

Scrolling

• A scrolling list keeps the highlighted option in view through ui/list_scroll.rs follow, passing which lines are options; never write its own scroll = selected reconciliation. It moves the viewport the least and brings the option's non-selectable neighbours along: its section header above it, the list's leading lines for the first option, the trailing lines for the last one. Wrapping from the bottom back to the top therefore always shows the very top of the list.
• Mouse-wheel scrolling sets the list's free_scroll and skips follow until the next keyboard move; it only clamps the offset.

Searchable lists

• Use search_field::Search, search_field::handle_key and search_field::paste for any filterable list, and build its footer with search_field::hints.
• The model: lists open with the list focused; / focuses the field; typing filters live (letters, including j/k, go to the field); ↑↓, PageUp/PageDown and Enter keep acting on the list while the field is focused; Esc first leaves the field (the filter stays), then clears the filter, then closes the screen.
• Do not add other entry points into search (Tab, Left, type-to-search on open). Do not make Enter only "apply" the filter: it acts on the highlighted item.
• The list footer includes hints::SEARCH.
• The search row sits directly under the title, followed by one blank row, and reads / placeholder (Search plugins, Search settings). It is always visible in the list view and hidden in detail views. Draw it only with ui/search_field.rs draw_row, which owns the / and the field's indent; never put a search field at the bottom of a list or in the footer. The project picker is the one exception: its labelled Search projects: field shares the form Field of its create view.

Selection

• The focused row is the list-cursor bar: ui/list_cursor.rs style() across the full row width (block-cursor colors, bold). No glyph cursors (›, ▸, >) for focus.
• Draw the bar only through list_cursor: paint(f, area) fills a row area, styles(highlighted) / styles_on(highlighted, bg) give the (text, dim) styles of a row, marker_style styles the current-value marker on it. Never read theme::block_cursor_bg/block_cursor_fg outside ui/theme/ and ui/list_cursor.rs (a unit test enforces it). Text-field carets are not list cursors: use theme::block_caret (TextArea-like fields) or theme::fixed::input_caret (compact Input-like fields).
• Horizontal options (dialog buttons) render each option as a label chip; the selected chip takes list_cursor::style(). Keep labels at the same columns when switching selection.
• The current value (the active model, theme, level, layer or session) is marked with list_cursor::marker(true) (› ) in list_cursor::current_color(), in a two-column slot that stays blank (list_cursor::BLANK) on other rows.
• (String, Style) row renderers paint the full-width bar for rows where list_cursor::is_bar holds, and keep a span's own background instead of overwriting it.

Colors

• Every color value lives in src/ui/theme/: theme-dependent colors in the theme palettes (theme::foreground(), theme::muted_style(), ...), fixed brand and terminal colors in ui/theme/fixed.rs (ORANGE, LOADING_GRADIENT, onboarding colors, sgr::* escape codes, the Monokai/Alabaster named palette via fixed::named), syntax colors in ui/theme/syntax.rs. A fixed color such as the brand orange is fine, but it is defined once there and imported everywhere else.
• Outside src/ui/theme/, never write Color::Rgb(..), Color::Indexed(..), a named Color::* variant or a raw SGR color code. When a screen needs a new color, add a named constant or theme accessor first. tests/units/color_literals.rs fails on any literal outside the theme module (only update_prompt/ansi.rs, which converts any Color to SGR, and test code are exempt).

Verification

• Any change to a hint, a key, a list behavior (wrap, back, digits, scroll, search) or a selection style is user-visible: update the affected client-e2e scenarios (screen_contains, key sequences, mouse coordinates) and regenerate their goldens following migrate-cli-to-rust. A new behavior gets its own scenario (for example mcp/mcp_wrap_scroll).
• Shared helpers carry their own unit tests (tests/units/list_nav.rs, list_scroll.rs, search_field.rs); extend them when a helper changes instead of testing the rule screen by screen.
• tests/units/color_literals.rs guards the color and list-cursor rules. Do not add exemptions to make it pass: move the color into src/ui/theme/ or route the bar through list_cursor.