Przejdź do treści
Biblioteka skilli
Programowanie · Budowanie i kod

bubbletea

/bubbletea

Buduje interfejsy terminalowe w Go na Bubbletea, z układami dwupanelowymi, obsługą myszy i stylami Lipgloss.

Repozytorium
ksail ↗
Licencja
MIT
Ostatnia zmiana repozytorium
13.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
5
Przestarzałość

Brak sygnałów. Repozytorium zmienione 13.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Buduje interfejsy terminalowe w Go na Bubbletea, z układami dwupanelowymi, obsługą myszy i stylami Lipgloss.

Oryginalny opis (EN)

Build terminal user interfaces with Go and Bubbletea framework. Use for creating TUI apps with the Elm architecture, dual-pane layouts, accordion modes, mouse/keyboard handling, Lipgloss styling, and reusable components. Includes production-ready templates, effects library, and battle-tested layout patterns from real projects.

Jak działa

  1. When to Use This Skill
  2. Core Principles
  3. Creating New Projects
  4. Available Components
  5. Effects Library
  6. Layout Implementation Pattern
  7. Mouse Interaction Pattern
  8. Common Pitfalls to Avoid
  9. Testing and Debugging
  10. Configuration System
Sekcje z nagłówków SKILL.md, w oryginale · 272 linii, 1 081 słów
Podgląd SKILL.md
---
description: Build terminal user interfaces with Go and Bubbletea framework. Use for creating TUI apps with the Elm architecture, dual-pane layouts, accordion modes, mouse/keyboard handling, Lipgloss styling, and reusable components. Includes production-ready templates, effects library, and battle-tested layout patterns from real projects.
license: MIT
metadata:
    github-path: .claude/skills/bubbletea
    github-ref: refs/tags/v1.0.3
    github-repo: https://github.com/ggprompts/tfe
    github-tree-sha: b3dceb6065a02f1960f92483d9f44a1c2e4e36aa
    internal: true
name: bubbletea
---
# 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:

- 🔮 **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
```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
}

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

### 3. Truncate Text to Prevent Wrapping
```go
// 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:

```go
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
```go
// BAD: Can cause misalignment
panelStyle := lipgloss.NewStyle().
    Border(border).
    Height(height)  // Don't do this!
```

### ✅ DO: Fill content to exact height
```go
// 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:

1. **Check height accounting** - Verify contentHeight calculation subtracts all UI elements + borders
2. **Check text wrapping** - Ensure all strings are truncated to maxTextWidth
3. **Check mouse detection** - Verify X/Y coordinate usage matches layout orientation
4. **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:

```yaml
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:
1. `~/.config/your-app/config.yaml` (user config)
2. `./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](https://github.com/charmbracelet/bubbletea)
- [Lipgloss Documentation](https://github.com/charmbracelet/lipgloss)
- [Bubbles Components](https://github.com/charmbracelet/bubbles)
- [Charm Ecosystem](https://charm.sh/)

## Best Practices Summary

1. **Always** consult golden-rules.md before implementing layouts
2. **Always** use weight-based sizing for flexible layouts
3. **Always** truncate text explicitly (never rely on auto-wrap)
4. **Always** match mouse detection to layout orientation
5. **Always** account for borders in height calculations
6. **Never** set explicit Height() on bordered Lipgloss styles
7. **Never** assume layout orientation in mouse handlers

Follow these patterns and you'll avoid 90% of TUI layout bugs.
Pliki w paczce (5)
  • SKILL.md 9 KB
  • references/components.md 12 KB
  • references/emoji-width-fix.md 8 KB
  • references/golden-rules.md 11 KB
  • references/troubleshooting.md 15 KB

Wersje

W bazie nie ma innych skilli o nazwie bubbletea.

Migawka bazy z 13.11.2026 · wersja paczki 64659715db9c (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100bubbletea-code-review
    Przegląda kod TUI w BubbleTea pod kątem architektury Elm, wzorców model, update i view oraz stylowania Lipgloss, dla aplikacji terminalowych z charmbracelet/bubbletea.
  • 100review-tui
    Prowadzi pełny code review aplikacji terminalowych BubbleTea: charmbracelet/bubbletea, lipgloss, bubbles i Wish SSH, opcjonalnie współbieżnie dla każdego obszaru.
  • 100charm-bracelet-tui
    Prowadzi przez budowę interaktywnych aplikacji TUI w Go z ekosystemem Charm Bracelet: bubbletea, bubbles, lipgloss, glamour, huh i pokrewne biblioteki.
  • 100tui-design
    Pomaga projektować interfejsy terminalowe: układ paneli, paletę kolorów, nawigację klawiaturą i dashboardy w Ratatui, Ink, Textual czy Bubbletea.
  • 100rtxui
    Buduje i sprawdza interfejsy terminalowe w C++ w bibliotece RTXUI, gdzie komponenty są szablonami HTML i CSS zapisanymi w napisie.
  • 100tui-engineering
    Buduje pełnoekranowe interfejsy TUI dla telefonu bez bibliotek terminalowych: architekturę, układ, obsługę myszy i testy.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.