golang-tui

Go TUI Development

Expert Go TUI developer specializing in the Charm ecosystem (Bubble Tea, Lip Gloss, Bubbles) and supporting libraries (bubbletint, chroma, go-nf). Builds production-grade terminal applications following the Elm Architecture with proper theming, composition, and terminal compatibility.

For TUI UX and layout guidance, tui-design (hyperskills) is a recommended companion skill.

Core Workflow

1. Analyze -- Understand the codebase, component tree, state flow, dimensions (width, height, weights, padding, margins, borders, etc), and theme setup
2. Structure -- Break UI into components (pages, dialogs, etc); keep main.go small
3. Implement -- Elm Architecture (Init/Update/View) with idiomatic Charm library usage, accounting for standard styling, theming, and layout conventions
4. Test & Lint -- Run tests and linters to ensure the codebase is healthy
5. Review -- Ensure changes do not go against this skill's constraints, gotchas, or core patterns

Reference Guide

Load detailed guidance based on context:

Core Pattern Example

Minimal Bubble Tea v2 fullscreen application:

package main

import (
    "fmt"
    "os"

    tea "charm.land/bubbletea/v2"
)

type model struct {
    width, height int
    count         int
}

func (m model) Init() tea.Cmd { return nil }

func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
    switch msg := msg.(type) {
    case tea.WindowSizeMsg:
        m.width, m.height = msg.Width, msg.Height
    case tea.KeyPressMsg:
        switch msg.String() {
        case "q", "ctrl+c":
            return m, tea.Quit
        case "up", "k":
            m.count++
        case "down", "j":
            m.count--
        }
    }
    return m, nil
}

func (m model) View() tea.View {
    v := tea.NewView(fmt.Sprintf("Count: %d\n\n  up/down: change -- q: quit\n", m.count))
    v.AltScreen = true
    v.WindowTitle = "My App"
    return v
}

func main() {
    if _, err := tea.NewProgram(model{}).Run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

Constraints

MUST DO

• Handle tea.WindowSizeMsg in every application (sent on startup and resize)
• Handle tea.ColorProfileMsg and tea.BackgroundColorMsg for theme/color detection
• Use strings.Builder in View to avoid allocations
• Use ansi.StringWidth or lipgloss.Width instead of len() for calculating string width
• Use key.Matches with centralized (or per-component) key bindings instead of raw string

comparison

• Wrap all I/O (HTTP, file, clipboard, blocking calls, etc) in tea.Cmd functions
• Components (pages, views, dialogs, buttons, status bars, etc) should always be

ELM-architecture compliant, not extraneous Render(...) string functions

• Keep main.go minimal (flag parsing, dependency creation, tea.NewProgram, error handling)
• Account for borders in layout calculations (subtract 2 from height for top+bottom border

or use <style>.GetVerticalBorderSize() / GetVerticalFrameSize())

• Derive width per layout region: do not reuse one m.width - N for full-bleed chrome

and inset form content unless the same outer padding applies; use GetHorizontalFrameSize() when truncating text inside a bordered/padded block (see references/view-styling.md)

• Degrade gracefully when the terminal is smaller than the content: wrap or truncate

intentionally, hide lower-priority UI first, and render a centered "window too small" style warning if the app cannot be used meaningfully at the current size (prefer to only do this when the window is really small)

• Always show most frequently used keybinds/help text for the user to know what to do. If

there are extensive keybinds, opt for a separate help menu or dialog.

MUST NOT DO

• Block in Update() (no I/O, no time.Sleep, no blocking channel reads)
• Use fmt.Println (stdout is owned by the TUI renderer; use tea.Println or log/slog)
• Create styles inside View() (define at package level or in Update)
• Use len() on strings that will be rendered/displayed
• Hardcode terminal dimensions (always read from tea.WindowSizeMsg in Update), and prefer using

GetHorizontalFrameSize() / GetVerticalFrameSize() (or similar) functions on the style you render with, rather than hardcoding 2, 4, etc for borders and padding. references:

• references/view-styling.md
• references/libraries/lipgloss-v2.md
• Let important content overflow, clip, or disappear without an intentional fallback

for constrained terminal sizes

Knowledge Reference

Bubble Tea v2, Lip Gloss v2, Bubbles v2, Elm Architecture, tea.Model, tea.Cmd, tea.Msg, tea.View, tea.Program, tea.NewView, tea.KeyPressMsg, tea.WindowSizeMsg, tea.ColorProfileMsg, tea.BackgroundColorMsg, bubbletint, tint registry, chroma, chromatint, go-nf, Nerd Fonts, beeep, x/ansi, x/editor, steep, x/charm/steep, x/exp/teatest, x/exp/golden, go-snaps, go-snap, lipgloss.JoinHorizontal, lipgloss.JoinVertical, lipgloss.Place, lipgloss.Darken, lipgloss.Lighten, lipgloss.LightDark, weight-based layout, compositor, spinner, textinput, textarea, list, table, viewport, paginator, progress, help, filepicker, key.Binding, key.Matches, OSC 52, clipboard, colorprofile, alt screen, bracketed paste, PasteMsg, KeyboardEnhancements, KeyReleaseMsg, OSC 9 progress, view.ProgressBar, snapshot testing, golden files.