BentoTUI Architecture

BentoTUI is a registry of copy-and-own terminal UI components built on Bubble Tea v2 and Lip Gloss v2.

Model

Copy and own

Live now

8 components

Core imports

theme, styles, layout

How It Works

Two things live in this repo:

Thing	What it is
component	Atomic UI piece. `bento add input` copies it into your project.
bentos	Pre-built layout composition. A complete screen pattern you copy wholesale.

registry/components/   ← copied into your project by `bento add`
bentos/                ← complete runnable screen patterns

Architecture Stack

Core Packages (Real Imports)

These are stable module deps your project imports directly:

Package	Import Path	What it is
theme	`github.com/cloudboy-jh/bentotui/theme`	Global theme store, 15 presets, goroutine-safe
styles	`github.com/cloudboy-jh/bentotui/styles`	Theme → Lip Gloss style mapping
layout	`github.com/cloudboy-jh/bentotui/layout`	`Horizontal` / `Vertical` split layout

The `surface` Primitive

surface is the key rendering primitive. It wraps Ultraviolet’s cell buffer so every cell is explicitly painted before Bubble Tea flushes the frame — eliminating ANSI whitespace-reset bleed that occurs with pure string composition.

Used by every full-screen layout.

Components

All components live in registry/components/ and are copied into your project by bento add. Once copied they live at yourmodule/components/<name> — you own the source.

Available Now

Component	Description
`surface`	Full-screen cell buffer backed by Ultraviolet. Deterministic background paint — no ANSI whitespace bleed. Used by every full-screen layout.
`bar`	Status/nav bar with left + right slots.
`input`	Single-line text input with left-border accent. Wraps `bubbles/textinput`.
`panel`	Titled, focusable content container.
`dialog`	Modal manager — `Confirm`, `Custom`, `ThemePicker`.
`list`	Scrollable log-style list.
`table`	Header + data rows.
`text`	Static styled label.

Coming Next — Tier 1

Component	Description
`badge`	Inline colored label.
`kbd`	Keyboard shortcut display. Dim/bright pair.
`wordmark`	Large centered app name. Theme-colored, responsive.
`statusbar`	Standalone registry version of `bar`.

Tier 2

Component	Description
`select`	Single-choice picker. Opens inline.
`checkbox`	Togglable boolean.
`textarea`	Multi-line input. Wraps `bubbles/textarea`.
`spinner`	Loading indicator. Wraps `bubbles/spinner`.
`progress`	Progress bar with optional label.

Tier 3

Component	Description
`command`	Command palette with fuzzy search.
`toast`	Ephemeral notification. Auto-dismisses, stacks.
`tabs`	Horizontal tab switcher.
`separator`	Horizontal or vertical rule.

Bentos

Bentos are complete runnable screen patterns you copy wholesale. Each is a single self-contained .go file demonstrating real component usage.

bentos/
  home-screen/   ← mirrors starter app (coming soon)
  app-shell/
  dashboard/
  detail-view/
  form/
  log-viewer/
  settings/
  command-view/

Planned Bentos

Bento	Components Used
`home-screen`	`wordmark`, `input`, `kbd`, `badge`, `bar`, `surface`
`app-shell`	`panel`, `layout`, `bar`, `tabs`, `surface`
`dashboard`	`panel`, `badge`, `table`, `layout`, `surface`
`detail-view`	`list`, `panel`, `layout`, `surface`
`form`	`input`, `textarea`, `checkbox`, `badge`, `surface`
`log-viewer`	`input`, `panel`, `spinner`, `badge`, `surface`
`settings`	`list`, `panel`, `checkbox`, `layout`, `surface`
`command-view`	`command`, `input`, `list`, `surface`

Theme System

15 built-in presets:

// Set once at startup
theme.SetTheme("tokyo-night")

// Components always call this in View() — never cache it
t := theme.CurrentTheme()

Available themes: catppuccin-mocha (default), catppuccin-macchiato, catppuccin-frappe, dracula, tokyo-night, tokyo-night-storm, nord, gruvbox-dark, monokai-pro, kanagawa, rose-pine, ayu-mirage, one-dark, material-ocean, github-dark.

Switch themes at runtime via the /theme command in the starter app.

CLI Usage

# Install the CLI
go install github.com/cloudboy-jh/bentotui/cmd/bento@latest

# Copy components into your project
bento add input bar surface

# Run the starter app
go run ./cmd/starter-app

Framework Roadmap — Execution priorities and milestones