tui-components

name

tui-components

description

Use when building or restyling strike's TUI — views, panels, modals, pickers, badges, dashboards, status rows, or any layout work in internal/frontend/tui. Covers the internal/frontend/tui/ui component catalog and internal/frontend/tui/theme tokens. Do not use for backend/engine work (internal/engine, internal/provider, internal/tool, internal/permission, internal/persist/session, internal/product/auth, internal/frontend/host) — those packages have no UI surface.

TUI components (strike-cli)

internal/frontend/tui/theme is the resolved token source and internal/frontend/tui/ui is the component library. Root views compose completed theme styles and ui components, then perform only structural operations (joining, allocation, selection, and layout). Keep this catalog synchronized with internal/frontend/tui/ui.

Boundaries

• Edit internal/frontend/tui/app/_src/<group>/ only for package tui. Flattened internal/frontend/tui/app/*.go are gitignored and regenerated by go generate ./internal/frontend/tui/app / make / CI — edits there are silently lost. Real packages theme, ui, term, common are edited in place.
• internal/frontend/tui/... may import only internal/protocol, internal/frontend/host, internal/frontend/tui/..., stdlib, and third-party packages. The boundary test enforces this. Kit packages (ui, theme, common, term) must not import protocol or host. Charm modules: v1 github.com/charmbracelet/… or v2 charm.land/… — never github.com/charmbracelet/…/v2.
• internal/frontend/tui/ui may import only stdlib, lipgloss, bubbles, charmbracelet/x/ansi, and internal/frontend/tui/theme; components do not import the app model or handle tea.Msg. The Strike wordmark lives in the app.
• Resolve a supplied theme before reading tokens: th = th.Resolve(). Colors, glyphs, borders, spacing, and emphasis come only from that resolved theme. Never put literal colors, visual glyphs, border/spacing values, or visual modifiers in a root view. A ui visual-modifier argument must trace to a resolved theme value; manually review unknown or interprocedural origins.
• Components are pure renderers: exported rendering functions take a theme.Theme and options and return a string. State and key handling remain in internal/frontend/tui/app model files.

Component catalog

Tone is ToneDefault, ToneAccent, ToneAccentAlt, ToneSuccess, ToneWarning, ToneError, ToneDanger, or ToneMuted. Level is LevelInfo, LevelSuccess, LevelWarning, or LevelError.

Component	Exact signature	Use
Panel	Panel(th theme.Theme, opts PanelOpts, body string) string	Width-safe framed tile. PanelOpts has Title, Footer, mandatory Width, optional Height, Focused, Dim, Tone, and Borderless. Default chrome is bordered (outline only, square ┌┐└┘). Focused bordered panes: BorderFocus outline, no title-edge wash, no FocusBar. Soft (chrome: soft) keeps surface-filled body + rounded ╭╮╰╯; focused soft panes: body stays Surface, title edge uses SurfaceFocus, outline uses BorderFocus. Solid chrome keeps title-edge SurfaceFocus + thin FocusBar. Never a full-panel wash. TextSelection is a separate role. Tone dialogs keep elevated SurfaceFocus body. Soft degrades below width 6. Borderless omits chrome.
Panel geometry	InnerWidth(width int) int; PanelInnerWidth(th theme.Theme, width int) int; PanelInnerHeight(width, height int) int; PanelInnerHeightFor(th, width, height int) int; PanelContentOrigin(th theme.Theme, width int) (x, y int)	Body dimensions and content-cell origin under chrome. Themed callers must use PanelInnerWidth; InnerWidth is default-theme compatibility only. PanelInnerHeight uses default bordered chrome; use PanelInnerHeightFor for non-default themes.
Dialog	Dialog(th theme.Theme, opts DialogOpts, body string) string	Focused Panel with a muted final hint. DialogOpts: Title, Hint, Width, Height, Tone. Body lines longer than inner width are word-wrapped (idempotent if already wrapped).
Badge	Badge(th theme.Theme, tone Tone, text string) string

Dialog word-wraps body lines to PanelInnerWidth; Panel still truncates any over-long line as a safety net. Prefer pre-wrapping free text for clarity. List truncates by default; set Wrap: true for multi-line option bodies (question modal). Card wraps its own body. Size panel-backed child windows with ui.PanelInnerHeight / PanelInnerHeightFor rather than unconditionally subtracting border rows, so unbordered narrow panels retain their full height.

Theme tokens

Theme.Resolve fills every unset role from theme.Default(). It preserves only theme.NoBackground() as the explicit transparent-background choice; otherwise Background resolves to a solid lipgloss.TerminalColor.

Token	Role
Text, TextMuted	primary and secondary foreground
OverlayScrim	de-emphasized modal background (scrim) fill
Accent, AccentAlt, Highlight	primary, secondary, and selected emphasis
Success, Warning, Error, Danger	semantic state colors
Background	application background (lipgloss.TerminalColor)
Surface, SurfaceFocus, SurfaceMuted	panel fills: body default / title-edge focus (and tone dialogs) / dim
Border, BorderFocus, BorderMuted	soft/bordered frame colors
UserLabel, ToolLabel, DiffAdded, DiffRemoved	transcript and diff roles
Chrome	ChromeBordered (default, square ┌┐└┘), ChromeSolid, or ChromeSoft (opt-in rounded)
BorderStyle	soft/bordered panel border weight and six glyphs
Spacing	None, XS, SM, MD, LG layout gaps; left|right pane gutter uses XS (keeps 93-col split); bento/welcome card gaps use SM; Label is the gap between a numbered permission-choice shortcut (for example, 1)) and its label, defaulting to 1 when resolved
Icons	glyph set below
AgentState	runtime status coloring via Theme.AgentStateColor / (not a palette field)

Icons fields are Prompt, Assistant, Tool, OK, Err, Info, Agent, Bolt, Dot, Cursor, InputCursor, FilterCursor, ToolGuide, FocusBar, BadgeLeft, BadgeRight, DetailSeparator, Ellipsis, LogoTopRule, LogoBottomRule, MeterFill, MeterEmpty, TreeExpanded, TreeCollapsed, CheckboxOn ([x]), CheckboxOff ([ ]), and Sparkline (low→high bar runes). Stock badge delimiters are empty (soft pills). Use th.Icons, never the literal glyph.

theme.AgentState is the live session/agent status vocabulary for dynamic coloring: Ready → Success, Working → AccentAlt, Attention → Warning, Error → Error, and reserved Dead → TextMuted (unmapped by reducers until dead-session lifecycle exists). Use th.AgentStateColor/AgentStateStyle/AgentStateStrongStyle; never hardcode state colors in views. Spinner uses the working token (AccentAlt).

th.S() returns semantic styles: Text, Muted, Accent, AccentAlt, Title, Success, Warning, Error, Danger; their *Strong variants; Selected, SelectedUnderline; UserLabel, AssistantLabel, ToolLabel; Input, InputPrompt, InputPlaceholder, InputCursor, Spinner; Border, BorderFocus, BorderMuted; DiffAdded, DiffRemoved, DiffAddedStrong, DiffRemovedStrong (bold word-diff spans); and DiffAddedLine, DiffRemovedLine (role FG on SurfaceMuted wash). Call it once per render and reuse it.

BorderStyle selects BorderWeightUnset, BorderWeightLight, or BorderWeightHeavy; resolving selects the matching preset and fills invalid or missing one-cell glyphs. NewSpacing(xs, sm, md, lg) Spacing initializes XS, SM, MD, and LG, including explicit zero values. It does not initialize Label, so Theme.Resolve supplies the default Label value of 1. WithXS(v int) Spacing, WithSM(v int) Spacing, WithMD(v int) Spacing, WithLG(v int) Spacing, and WithLabel(v int) Spacing set their respective token and preserve an explicit zero. Literal nonzero fields, including Label, are inferred as set; use the constructor or corresponding With method when an explicit zero must be preserved.

Configure Bubble widgets from the resolved foreground/cursor/spinner styles and glyphs, without setting widget backgrounds. ui.Canvas owns background painting after root views and overlays compose, filling every cell unless the theme explicitly uses theme.NoBackground().

Recipes

body := ui.List(th, ui.ListOpts{
    Items: items, Cursor: m.cursor,
    Width: max(1, ui.PanelInnerWidth(th, width)),
    Visible: providerModalVisible, Empty: "no providers configured",
})
return ui.Dialog(th, ui.DialogOpts{Title: "Select provider", Width: width}, body)

The empty-transcript dashboard is app composition, not a component API. Its header owns the compact brand; the dashboard directly allocates fixed-height Panel cards (bordered chrome by default), with one or two columns according to available width. It has no outer welcome panel or logo card. The keys card is always present; get started is present only when no provider is selected or the selected provider is unauthenticated; agents & skills requires at least one valid configured agent or skill; and recent prompts requires history. Preserve those conditions and the short-view fallback when changing the dashboard, without exposing app-private helpers as component recipes.

Extending and verification

Add a component under internal/frontend/tui/ui, make it width-safe and zero-value tolerant, document it, add its production-appropriate coverage, and update this catalog in the same change. New colors, glyphs, borders, spacing, and emphasis belong in theme.

go test ./internal/frontend/tui/... -count=1
make test

For visual review, the opt-in gallery renders parameterized scenarios rather than every view at both 80×24 and 120×40. Its current matrix is: 80×24 left dashboard and right context; 93×40 canonical split; 92×60 left-only; 120×40 split; 120×80 cycle, permission modal, provider picker, command palette, and busy transcript; and 160×45 long-data/status and danger-modal cases:

STRIKE_GALLERY=1 go test ./internal/frontend/tui/app/ -run Gallery -count=1 -v

Review the constrained 80×24 dashboard, split and modal scenarios, and the long-data cases appropriate to the change.