The 4 Golden Rules
These four rules prevent 90% of TUI layout bugs. They were discovered the hard way across six projects and hundreds of debugging hours.
1
Always Account for Borders
Subtract 2 from height calculations BEFORE rendering panels. The #1 cause of TUI layout bugs. Every bordered panel steals 2 rows (top + bottom) and 2 columns (left + right) from your content area. If you forget, panels overflow and misalign.
2
Never Auto-Wrap in Bordered Panels
Always truncate text explicitly. Auto-wrap inside borders causes panel overflow and misalignment. One long string can push your entire layout down by a row, cascading into every panel below it.
3
Match Mouse Detection to Layout
Use X coords for horizontal layouts, Y coords for vertical. Getting this wrong means clicks register in the wrong panel. If your panels are side-by-side, mouse.X determines which panel was clicked, not mouse.Y.
4
Use Weights, Not Pixels
Proportional layouts scale perfectly across terminal sizes.
leftWeight=2, rightWeight=1 beats leftWidth=80. Hardcoded widths break when the terminal resizes.Architecture Pattern
Every Bubbletea project follows this file structure. Separation of concerns keeps each file under 300 lines and makes it easy for Claude to navigate.
your-app/ ========= | +-- main.go Entry point (~21 lines) | +-- types.go Type definitions, structs, enums | +-- model.go Model init & 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
Component Catalog
20+ ready-to-use components across 8 categories. Each one is documented with full code examples and integration patterns.
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
Visual effects for terminal UIs. These run entirely in ANSI text, no graphics libraries needed.
Metaballs
Lava lamp floating blobs
Wave Effects
Sine wave distortions
Rainbow Cycling
Animated color gradients
Layer Compositor
ANSI-aware multi-layer rendering
Key Patterns
Battle-tested code patterns extracted from 6+ production projects.
weight-based-panel-sizing.go
leftWeight, rightWeight := 1, 1 if m.accordionMode && m.focusedPanel == "left" { leftWeight = 2 } totalWeight := leftWeight + rightWeight leftWidth := (availableWidth * leftWeight) / totalWeight
text-truncation.go
// Never auto-wrap -- always truncate explicitly maxTextWidth := panelWidth - 4 // -2 borders, -2 padding title = truncateString(title, maxTextWidth)
border-height-trap.go
// BAD: Can cause misalignment panelStyle := lipgloss.NewStyle().Border(border).Height(height) // GOOD: Fill content to exact height, then wrap with border for len(lines) < innerHeight { lines = append(lines, "") } panelStyle := lipgloss.NewStyle().Border(border)
War Story: Emoji Width Fix
emoji-width-fix.md -- 295 lines of hard-won knowledge
Emoji alignment is broken across terminals. xterm, WezTerm, Termux, and Windows Terminal all render emoji widths differently. Some treat them as 1 cell wide, others as 2. This 295-line document captures a battle-tested solution for cross-terminal emoji alignment that took days of testing across every major terminal emulator. It includes width detection, fallback strategies, and a lookup table for common emoji.
Reference Files
Five files that make up the complete skill. Bundled as a Go module, included in every new TUI project.
SKILL.md
Core patterns and quick-start guide
277 lines
references/troubleshooting.md
Debugging decision tree
698 lines
references/components.md
Complete component catalog
647 lines
references/golden-rules.md
The 4 Golden Rules in depth
393 lines
references/emoji-width-fix.md
Cross-terminal emoji alignment
295 lines
By the Numbers
2,310
Total Lines
4
Golden Rules
20+
Components
8
Categories
4
Visual Effects
6+
Projects
The Story
This skill captures everything learned building six Go TUI projects in rapid succession -- TFE, TUIClassics, TUITemplate, CellBlocksTUI, Tmuxplexer, and ai-kanban-board -- between October and December 2025.
The 4 Golden Rules alone would have saved weeks of debugging if known from the start. Every project hit the same border-height trap, the same text-wrapping overflow, the same mouse-coordinate mismatch. By the third project, the patterns were clear. By the sixth, they were codified.
The emoji width fix took days of testing across xterm, WezTerm, Termux, and Windows Terminal. Each emulator had its own opinion about how wide an emoji should be. The solution is ugly but it works everywhere.
Now it is bundled as a Go module that gets included in every new TUI project, so Claude starts with all this knowledge on day one. No more rediscovering the border height trap. No more debugging why clicks register in the wrong panel. The field guide is written.