Bubbletea TUI Development

Production-ready skill for building beautiful terminal user interfaces with Go, Bubbletea, and Lipgloss.

When to Use This Skill

Use this skill when:

• Creating new TUI applications with Go

• Adding Bubbletea components to existing apps

• Fixing layout/rendering issues (borders, alignment, overflow)

• Implementing mouse/keyboard interactions

• Building dual-pane or multi-panel layouts

• Adding visual effects (metaballs, waves, rainbow text)

• Troubleshooting TUI rendering problems

Core Principles

CRITICAL: Before implementing ANY layout, consult references/golden-rules.md for the 4 Golden Rules. These rules prevent the most common and frustrating TUI layout bugs.

The 4 Golden Rules (Summary)

• Always Account for Borders - Subtract 2 from height calculations BEFORE rendering panels

• Never Auto-Wrap in Bordered Panels - Always truncate text explicitly

• Match Mouse Detection to Layout - Use X coords for horizontal, Y coords for vertical

• Use Weights, Not Pixels - Proportional layouts scale perfectly

Full details and examples in references/golden-rules.md .

Creating New Projects

This project includes a production-ready template system. When this skill is bundled with a new project (via new_project.sh ), use the existing template structure as the starting point.

Project Structure

All new projects follow this architecture:

your-app/ ├── main.go # Entry point (minimal, ~21 lines) ├── types.go # Type definitions, structs, enums ├── model.go # Model initialization & layout calculation ├── update.go # Message dispatcher ├── update_keyboard.go # Keyboard handling ├── update_mouse.go # Mouse handling ├── view.go # View rendering & layouts ├── styles.go # Lipgloss style definitions ├── config.go # Configuration management └── .claude/skills/bubbletea/ # This skill (bundled)

Architecture Guidelines

• Keep main.go minimal (entry point only, ~21 lines)

• All types in types.go (structs, enums, constants)

• Separate keyboard and mouse handling into dedicated files

• One file, one responsibility

• Maximum file size: 800 lines (ideally <500)

• Configuration via YAML with hot-reload support

Available Components

See references/components.md for the complete catalog of reusable components:

• Panel System: Single, dual-pane, multi-panel, tabbed layouts

• Lists: Simple list, filtered list, tree view

• Input: Text input, multiline, forms, autocomplete

• Dialogs: Confirm, input, progress, modal

• Menus: Context menu, command palette, menu bar

• Status: Status bar, title bar, breadcrumbs

• Preview: Text, markdown, syntax highlighting, images, hex

• Tables: Simple and interactive tables

Effects Library

Beautiful physics-based animations available in the template:

• 🔮 Metaballs - Lava lamp-style floating blobs

• 🌊 Wave Effects - Sine wave distortions

• 🌈 Rainbow Cycling - Animated color gradients

• 🎭 Layer Compositor - ANSI-aware multi-layer rendering

See references/effects.md for usage examples and integration patterns.

Layout Implementation Pattern

When implementing layouts, follow this sequence:

1. Calculate Available Space

func (m model) calculateLayout() (int, int) { contentWidth := m.width contentHeight := m.height

// Subtract UI elements
if m.config.UI.ShowTitle {
    contentHeight -= 3  // title bar (3 lines)
}
if m.config.UI.ShowStatus {
    contentHeight -= 1  // status bar
}

// CRITICAL: Account for panel borders
contentHeight -= 2  // top + bottom borders

return contentWidth, contentHeight

}

2. Use Weight-Based Panel Sizing

// Calculate weights based on focus/accordion mode leftWeight, rightWeight := 1, 1 if m.accordionMode && m.focusedPanel == "left" { leftWeight = 2 // Focused panel gets 2x weight }

// Calculate actual widths from weights totalWeight := leftWeight + rightWeight leftWidth := (availableWidth * leftWeight) / totalWeight rightWidth := availableWidth - leftWidth

3. Truncate Text to Prevent Wrapping

// Calculate max text width to prevent wrapping maxTextWidth := panelWidth - 4 // -2 borders, -2 padding

// Truncate ALL text before rendering title = truncateString(title, maxTextWidth) subtitle = truncateString(subtitle, maxTextWidth)

func truncateString(s string, maxLen int) string { if len(s) <= maxLen { return s } return s[:maxLen-1] + "…" }

Mouse Interaction Pattern

Always check layout mode before processing mouse events:

func (m model) handleLeftClick(msg tea.MouseMsg) (tea.Model, tea.Cmd) { if m.shouldUseVerticalStack() { // Vertical stack mode: use Y coordinates topHeight, _ := m.calculateVerticalStackLayout() relY := msg.Y - contentStartY

    if relY < topHeight {
        m.focusedPanel = "left"  // Top panel
    } else {
        m.focusedPanel = "right" // Bottom panel
    }
} else {
    // Side-by-side mode: use X coordinates
    leftWidth, _ := m.calculateDualPaneLayout()

    if msg.X < leftWidth {
        m.focusedPanel = "left"
    } else {
        m.focusedPanel = "right"
    }
}

return m, nil

}

Common Pitfalls to Avoid

See references/troubleshooting.md for detailed solutions to common issues:

❌ DON'T: Set explicit Height() on bordered panels

// BAD: Can cause misalignment panelStyle := lipgloss.NewStyle(). Border(border). Height(height) // Don't do this!

✅ DO: Fill content to exact height

// GOOD: Fill content lines to exact height for len(lines) < innerHeight { lines = append(lines, "") } panelStyle := lipgloss.NewStyle().Border(border)

Testing and Debugging

When panels don't align or render incorrectly:

• Check height accounting - Verify contentHeight calculation subtracts all UI elements + borders

• Check text wrapping - Ensure all strings are truncated to maxTextWidth

• Check mouse detection - Verify X/Y coordinate usage matches layout orientation

• Check border consistency - Use same border style for all panels

See references/troubleshooting.md for the complete debugging decision tree.

Configuration System

All projects support YAML configuration with hot-reload:

theme: "dark" keybindings: "default"

layout: type: "dual_pane" split_ratio: 0.5 accordion_mode: true

ui: show_title: true show_status: true mouse_enabled: true show_icons: true

Configuration files are loaded from:

• ~/.config/your-app/config.yaml (user config)

• ./config.yaml (local override)

Dependencies

Required:

github.com/charmbracelet/bubbletea github.com/charmbracelet/lipgloss github.com/charmbracelet/bubbles gopkg.in/yaml.v3

Optional (uncomment in go.mod as needed):

github.com/charmbracelet/glamour # Markdown rendering github.com/charmbracelet/huh # Forms github.com/alecthomas/chroma/v2 # Syntax highlighting github.com/evertras/bubble-table # Interactive tables github.com/koki-develop/go-fzf # Fuzzy finder

Reference Documentation

All reference files are loaded progressively as needed:

• golden-rules.md - Critical layout patterns and anti-patterns

• components.md - Complete catalog of reusable components

• troubleshooting.md - Common issues and debugging decision tree

• emoji-width-fix.md - Battle-tested solution for emoji alignment across terminals (xterm, WezTerm, Termux, Windows Terminal)

External Resources

• Bubbletea Documentation

• Lipgloss Documentation

• Bubbles Components

• Charm Ecosystem

Best Practices Summary

• Always consult golden-rules.md before implementing layouts

• Always use weight-based sizing for flexible layouts

• Always truncate text explicitly (never rely on auto-wrap)

• Always match mouse detection to layout orientation

• Always account for borders in height calculations

• Never set explicit Height() on bordered Lipgloss styles

• Never assume layout orientation in mouse handlers

Follow these patterns and you'll avoid 90% of TUI layout bugs.