bubbletea

Files (5)

• SKILL.md
• components.md · references/
• emoji-width-fix.md · references/
• golden-rules.md · references/
• troubleshooting.md · references/

SKILL.md (first lines)

# 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)

1. **Always Account for Borders** - Subtract 2 from height calculations BEFORE rendering panels
2. **Never Auto-Wrap in Bordered Panels** - Always truncate text explicitly
3. **Match Mouse Detection to Layout** - Use X coords for horizontal, Y coords for vertical
4. **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:

- :crystal_ball: **Metaballs** - Lava lamp-style floating blobs
- :ocean: **Wave Effects** - Sine wave distortions
- :rainbow: **Rainbow Cycling** - Animated color gradients
- :performing_arts: **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

```go
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

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

From gethamster/skills, MIT.

More from gethamster/skills