bubbletea_skill

Overview

This skill teaches building production-ready terminal user interfaces in Go using the Bubbletea framework and Lipgloss styling. It provides battle-tested layout patterns, reusable components, an effects library, and templates to accelerate TUI projects. The focus is on reliable layouts, mouse/keyboard handling, and practical safeguards that prevent common rendering bugs.

How this skill works

The skill packages a minimal project architecture and a set of reference patterns: layout calculation, weight-based sizing, explicit text truncation, and coordinated mouse handling. It inspects available terminal space, subtracts UI chrome and borders, computes proportional panel sizes, and truncates text before rendering to avoid auto-wrap. Included components and effects plug into the Elm-style Bubbletea model-update-view flow for easy composition.

When to use it

• Starting a new Go TUI project or bootstrapping a production-ready template
• Adding Bubbletea components (panels, lists, inputs, dialogs) to existing apps
• Implementing dual-pane, accordion, or multi-panel layouts that must scale
• Handling mouse and keyboard interactions reliably across layout modes
• Fixing layout/rendering issues such as misaligned borders, overflow, or wrapping

Best practices

• Always account for borders when computing inner height and width
• Use weight-based sizing for panels rather than fixed pixel widths
• Truncate all text to a calculated max width; never rely on automatic wrapping
• Match mouse coordinate checks (X vs Y) to the current layout orientation
• Keep files single-responsibility (types, update, view, input handlers) and keep main.go minimal

Example use cases

• A dual-pane file manager with focus-driven accordion mode and proportional resize
• A markdown previewer with left-side editor, right-side rendered preview and syntax highlighting
• An interactive dashboard with status bar, tabbed panels, and animated background effects
• A form-driven CLI tool with input validation, modal dialogs, and keyboard-first navigation
• Debugging misaligned panels by verifying height accounting, border consistency, and text truncation