From bubbletea-designer
Automates Bubble Tea TUI design by analyzing requirements, mapping to appropriate components from the Charmbracelet ecosystem, generating component architecture, and creating implementation workflows. Use when designing terminal UIs, planning Bubble Tea applications, selecting components, or needing design guidance for TUI development.
npx claudepluginhub human-frontier-labs-inc/human-frontier-labs-marketplace --plugin bubbletea-designerThis skill uses the workspace's default tool permissions.
Automate the design process for Bubble Tea terminal user interfaces with intelligent component mapping, architecture generation, and implementation planning.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Automate the design process for Bubble Tea terminal user interfaces with intelligent component mapping, architecture generation, and implementation planning.
This skill automatically activates when you need help designing, planning, or structuring Bubble Tea TUI applications:
Use this skill when you:
The skill responds to questions like:
The Bubble Tea Designer follows a systematic 6-step design process:
Purpose: Extract structured requirements from natural language descriptions
Process:
Output: Structured requirements dictionary with:
Purpose: Map requirements to appropriate Bubble Tea components
Process:
Output: Component recommendations with:
Purpose: Identify relevant example files from charm-examples-inventory
Process:
Output: List of example files to reference:
Purpose: Create component hierarchy and interaction model
Process:
Output: Architecture specification with:
Purpose: Create ordered implementation steps
Process:
Output: Step-by-step implementation plan:
Purpose: Generate complete design document combining all analyses
Process:
Output: Complete TUI design specification with:
This skill references a curated inventory of 46 Bubble Tea examples from the Charmbracelet ecosystem.
Location: charm-examples-inventory/bubbletea/examples/
Index File: CONTEXTUAL-INVENTORY.md
Categories (11 capability groups):
Input Components:
textinput - Single-line text inputtextarea - Multi-line text editingtextinputs - Multiple inputs with focus managementfilepicker - File system navigation and selectionautocomplete - Text input with suggestionsDisplay Components:
table - Tabular data with row selectionlist - Filterable, paginated listsviewport - Scrollable content areapager - Document viewerpaginator - Page-based navigationFeedback Components:
spinner - Loading indicatorprogress - Progress bar (animated & static)timer - Countdown timerstopwatch - Elapsed time trackerLayout Components:
views - Multiple screen statescomposable-views - Composed bubble modelstabs - Tab-based navigationhelp - Help menu systemUtility Patterns:
http)exec)realtime)altscreen-toggle)mouse)window-size)The skill uses pattern matching to identify:
By Feature:
progress, spinner, package-managercredit-card-form, textinputstable, table-resizefile-picker, list-defaultviews, package-managerBy Interaction:
helpmouse, tableviewport, pagerlist-default, autocompleteBy Architecture:
simple, spinner, textinputviewscomposable-viewstabsUser Query: "Which component should I use for [feature]?"
Process:
Example:
User: "Which component for file selection?"
Response:
Top recommendations:
1. filepicker.Model - Dedicated file system navigation
- Built-in directory traversal
- File type filtering
- Selection callbacks
Reference: examples/file-picker/main.go
2. list.Model - Custom file list
- More control over display
- Custom item rendering
- Can add file metadata
Reference: examples/list-fancy/main.go
3. table.Model - Tabular file display
- Show multiple file attributes
- Sortable columns
- Good for detailed views
Reference: examples/table/main.go
User Query: "Design a TUI for [application]"
Process:
requirement_analysis(description)component_mapping(requirements)pattern_selection(components)architecture_design(components, patterns)workflow_generation(architecture)Example:
User: "Design a TUI for a log file viewer with search and highlighting"
Response: [Comprehensive design report including]:
REQUIREMENTS:
- View: Scrollable text display
- Interaction: Search, highlight matches, navigate results
- Data: Log file lines (streaming or loaded)
COMPONENTS:
- viewport.Model (scrollable display)
- textinput.Model (search query)
- Custom highlighter (Lipgloss styles)
ARCHITECTURE:
model struct {
viewport viewport.Model
searchInput textinput.Model
logLines []string
searchMode bool
matches []int
currentMatch int
}
WORKFLOW:
Phase 1: Basic viewer (viewport + file loading)
Phase 2: Add search input
Phase 3: Implement highlighting
Phase 4: Add navigation between matches
Phase 5: Polish (status bar, help text)
[Full implementation steps with file references...]
User Query: "Plan architecture for [complex TUI]"
Process:
Example:
User: "Plan architecture for a package manager TUI with installation queue and progress"
Response:
ARCHITECTURE DIAGRAM:
┌─────────────────────────────────────┐
│ Main Model │
├─────────────────────────────────────┤
│ view: currentView │
│ packages: []PackageItem │
│ queue: InstallQueue │
│ progress: ProgressState │
└────────────┬───────────────┬────────┘
│ │
┌────▼────┐ ┌───▼─────┐
│ List │ │Progress │
│ Model │ │ Model │
└─────────┘ └─────────┘
STATE MANAGEMENT:
- currentView: enum (selectView, installView, completeView)
- packages: list of selectable items
- queue: ordered installation queue
- progress: current package progress (0-100)
MESSAGE FLOW:
User Input → Update() → Route to current view handler
Install Start → Switch view + Init progress
Package Complete → Update progress + Next package
All Complete → Switch to complete view
[Detailed implementation guidance...]
User Query: "Show me examples for [capability]"
Process:
Example:
User: "Show me examples for progress tracking"
Response:
PROGRESS TRACKING EXAMPLES:
1. package-manager (examples/package-manager/main.go)
Category: Installation & Progress Tracking
Key Patterns:
- Combined spinner + progress bar
- Sequential task execution
- Tea.Println for persistent output above TUI
- Custom completion messages
2. progress-animated (examples/progress-animated/main.go)
Category: Loading & Status Indicators
Key Patterns:
- Gradient progress styling
- Smooth animation with FrameMsg
- Indeterminate/determinate modes
3. progress-download (examples/progress-download/main.go)
Category: Loading & Status Indicators
Key Patterns:
- Network operation tracking
- Real-time percentage updates
- HTTP integration
Study these in order:
1. progress-animated (learn basics)
2. package-manager (see real-world usage)
3. progress-download (network-specific)
All scripts are in scripts/ directory and can be run independently or through the main orchestrator.
design_tui.py
Comprehensive design report generator - combines all analyses.
Usage:
from scripts.design_tui import comprehensive_tui_design_report
report = comprehensive_tui_design_report(
description="Log viewer with search and highlighting",
inventory_path="/path/to/charm-examples-inventory"
)
print(report['summary'])
print(report['architecture'])
print(report['workflow'])
Parameters:
description (str): Natural language TUI descriptioninventory_path (str): Path to charm-examples-inventory directoryinclude_sections (List[str], optional): Which sections to includedetail_level (str): "summary" | "detailed" | "complete"Returns:
{
'description': str,
'generated_at': str (ISO timestamp),
'sections': {
'requirements': {...},
'components': {...},
'patterns': {...},
'architecture': {...},
'workflow': {...}
},
'summary': str,
'scaffolding': str (code template),
'next_steps': List[str]
}
analyze_requirements.py
Extract structured requirements from natural language.
Functions:
extract_requirements(description) - Parse descriptionclassify_tui_type(requirements) - Determine archetypeidentify_interactions(requirements) - Find interaction patternsmap_components.py
Map requirements to Bubble Tea components.
Functions:
map_to_components(requirements, inventory) - Main mappingfind_alternatives(component) - Alternative suggestionsjustify_selection(component, requirement) - Explain choiceselect_patterns.py
Select relevant example files from inventory.
Functions:
search_inventory(capability, inventory) - Search by capabilityrank_by_relevance(examples, requirements) - Relevance scoringextract_key_patterns(example_file) - Identify key code patternsdesign_architecture.py
Generate component architecture and structure.
Functions:
design_model_struct(components) - Create model definitionplan_message_handlers(interactions) - Design Update() logicgenerate_architecture_diagram(structure) - ASCII diagramgenerate_workflow.py
Create ordered implementation steps.
Functions:
break_into_phases(architecture) - Phase planningorder_tasks_by_dependency(tasks) - Dependency sortingestimate_time(task) - Time estimationgenerate_workflow_document(phases) - Formatted outpututils/inventory_loader.py
Load and parse the examples inventory.
Functions:
load_inventory(path) - Load CONTEXTUAL-INVENTORY.mdparse_inventory_markdown(content) - Parse structurebuild_capability_index(inventory) - Index by capabilitysearch_by_keyword(keyword, inventory) - Keyword searchutils/component_matcher.py
Component matching and scoring logic.
Functions:
match_score(requirement, component) - Relevance scorefind_best_match(requirements, components) - Top matchsuggest_combinations(requirements) - Component combosutils/template_generator.py
Generate code templates and scaffolding.
Functions:
generate_model_struct(components) - Model struct codegenerate_init_function(components) - Init() implementationgenerate_update_skeleton(messages) - Update() skeletongenerate_view_skeleton(layout) - View() skeletonutils/ascii_diagram.py
Create ASCII architecture diagrams.
Functions:
draw_component_tree(structure) - Tree diagramdraw_message_flow(flow) - Flow diagramdraw_state_machine(states) - State diagramutils/validators/requirement_validator.py
Validate requirement extraction quality.
Functions:
validate_description_clarity(description) - Check clarityvalidate_requirements_completeness(requirements) - Completenesssuggest_clarifications(requirements) - Ask for missing infoutils/validators/design_validator.py
Validate design outputs.
Functions:
validate_component_selection(components, requirements) - Check fitvalidate_architecture(architecture) - Structural validationvalidate_workflow_completeness(workflow) - Ensure all stepsFunction: extract_requirements(description)
Purpose: Convert natural language to structured requirements
Methodology:
Output Structure:
{
'archetype': str, # file-manager, installer, dashboard, etc.
'features': List[str], # [navigation, selection, preview, ...]
'interactions': {
'keyboard': List[str], # [arrow keys, enter, search, ...]
'mouse': List[str] # [click, drag, ...]
},
'data_types': List[str], # [files, text, tabular, streaming, ...]
'views': str, # single, multi, tabbed
'special_requirements': List[str] # [validation, progress, real-time, ...]
}
Interpretation:
Validations:
Function: map_to_components(requirements, inventory)
Purpose: Map requirements to specific Bubble Tea components
Methodology:
Output Structure:
{
'primary_components': [
{
'component': 'viewport.Model',
'score': 95,
'justification': 'Scrollable display for log content',
'example_file': 'examples/pager/main.go',
'key_patterns': ['viewport scrolling', 'content loading']
}
],
'supporting_components': [...],
'styling': ['lipgloss for highlighting'],
'alternatives': {
'viewport.Model': ['pager package', 'custom viewport']
}
}
Scoring Criteria:
Validations:
Function: select_relevant_patterns(components, inventory)
Purpose: Find most relevant example files to study
Methodology:
Output Structure:
{
'examples': [
{
'file': 'examples/pager/main.go',
'capability': 'Content Viewing',
'relevance_score': 90,
'key_patterns': [
'viewport.Model initialization',
'content scrolling (lines 45-67)',
'keyboard navigation (lines 80-95)'
],
'study_order': 1,
'estimated_study_time': '15 minutes'
}
],
'recommended_study_order': [1, 2, 3],
'total_study_time': '45 minutes'
}
Ranking Factors:
Validations:
Function: design_architecture(components, patterns, requirements)
Purpose: Create complete component architecture
Methodology:
Output Structure:
{
'model_struct': str, # Go code
'init_logic': str, # Initialization steps
'message_handlers': {
'tea.KeyMsg': str, # Keyboard handling
'tea.WindowSizeMsg': str, # Resize handling
# Custom messages...
},
'view_logic': str, # Rendering strategy
'diagrams': {
'component_hierarchy': str, # ASCII tree
'message_flow': str, # Flow diagram
'state_machine': str # State transitions (if multi-view)
}
}
Design Patterns Applied:
Validations:
Function: generate_implementation_workflow(architecture, patterns)
Purpose: Create step-by-step implementation plan
Methodology:
Output Structure:
{
'phases': [
{
'name': 'Phase 1: Setup',
'tasks': [
{
'task': 'Initialize Go module',
'reference': None,
'dependencies': [],
'estimated_time': '2 minutes'
},
{
'task': 'Install dependencies (bubbletea, lipgloss)',
'reference': 'See README in any example',
'dependencies': ['Initialize Go module'],
'estimated_time': '3 minutes'
}
],
'total_time': '5 minutes'
},
# More phases...
],
'total_estimated_time': '2-3 hours',
'testing_checkpoints': [
'After Phase 1: go build succeeds',
'After Phase 2: Basic display working',
# ...
]
}
Phase Breakdown:
Validations:
Function: comprehensive_tui_design_report(description, inventory_path)
Purpose: Generate complete TUI design combining all analyses
Process:
Output Structure:
{
'description': str,
'generated_at': str,
'tui_type': str,
'summary': str, # Executive summary
'sections': {
'requirements': {...},
'components': {...},
'patterns': {...},
'architecture': {...},
'workflow': {...}
},
'scaffolding': {
'main_go': str, # Basic main.go template
'model_go': str, # Model struct + Init/Update/View
'readme_md': str # README outline
},
'file_structure': {
'recommended': [
'main.go',
'model.go',
'view.go',
'messages.go',
'go.mod'
]
},
'next_steps': [
'1. Review architecture diagram',
'2. Study recommended examples',
'3. Implement Phase 1 tasks',
# ...
],
'resources': {
'documentation': [...],
'tutorials': [...],
'community': [...]
}
}
Report Sections:
Executive Summary (auto-generated):
Requirements Analysis:
Component Selection:
Pattern References:
Architecture:
Implementation Workflow:
Code Scaffolding:
main.go templateNext Steps:
Validation Report:
Error: Cannot locate charm-examples-inventory
Cause: Inventory path not provided or incorrect
Resolution:
~/charmtuitemplate/vinw/charm-examples-inventorygit clone https://github.com/charmbracelet/bubbletea examplesFallback: Use minimal built-in component knowledge (less detailed)
Error: Cannot extract clear requirements from description
Cause: Description too vague or ambiguous
Resolution:
Clarification Questions:
Fallback: Make reasonable assumptions, note them in report
Error: No components found for requirements
Cause: Requirements very specific or unusual
Resolution:
Alternative Suggestions:
Error: Generated architecture has structural issues
Cause: Conflicting component requirements or circular dependencies
Resolution:
Common Issues:
All analyses include automatic validation. Reports include validation sections.
Checks:
Output:
{
'validation': {
'passed': True/False,
'checks': [
{'name': 'description_not_empty', 'passed': True},
{'name': 'features_found', 'passed': True, 'count': 5},
# ...
],
'warnings': [
'No mouse interactions specified - assuming keyboard only'
]
}
}
Checks:
Warnings:
Checks:
Errors:
Checks:
Warnings:
Strategy: Load once, cache in memory
Performance: O(1) lookup after initial O(n) indexing
Strategy: Pre-computed similarity scores
Performance: O(log n) search with indexing
Strategy: Template-based with caching
Performance: O(n) where n = number of components
This skill activates when you mention:
Technologies:
Components:
Design Actions:
TUI Types:
Patterns:
Questions:
User: "Design a TUI for viewing log files with search"
Response:
TUI DESIGN: Log File Viewer
ARCHETYPE: Text Viewer
REQUIREMENTS ANALYSIS:
- View: Scrollable text display
- Interaction: Search, navigate matches
- Data: Text file (log lines)
COMPONENT SELECTION:
Primary Components:
1. viewport.Model - Scrollable text display
Justification: Built for viewing large text content
Example: examples/pager/main.go
2. textinput.Model - Search query input
Justification: Standard text input for search
Example: examples/textinput/main.go
Supporting:
- Lipgloss styles for match highlighting
ARCHITECTURE:
Model Struct:
```go
type model struct {
viewport viewport.Model
searchInput textinput.Model
content []string
searchMode bool
matches []int
currentMatch int
ready bool
}
WORKFLOW:
Phase 1: Basic Viewer (30min)
Phase 2: Search (45min)
Phase 3: Navigation (20min)
Total: ~2 hours
NEXT STEPS:
### Example 2: Installation Progress Tracker
**User**: "Create a package installer UI with progress bars"
**Response**:
TUI DESIGN: Package Installer
ARCHETYPE: Installer/Progress Tracker
REQUIREMENTS ANALYSIS:
COMPONENT SELECTION:
Primary Components:
progress.Model - Individual package progress Justification: Animated progress visualization Example: examples/progress-animated/main.go
spinner.Model - Loading indicator Justification: Feedback during package download Example: examples/spinner/main.go
Reference Pattern:
ARCHITECTURE:
Model Struct:
type model struct {
packages []Package
currentIdx int
progress progress.Model
spinner spinner.Model
installed []string
err error
}
type Package struct {
name string
status string // pending, installing, done
}
Message Flow: Install Start → Download Package → Update Progress → Package Done → Next Package
WORKFLOW:
Phase 1: Package List (20min)
Phase 2: Add Progress (30min)
Phase 3: Add Spinner (15min)
Phase 4: Sequential Logic (30min)
Total: ~2 hours
REFERENCE STUDY:
NEXT STEPS:
### Example 3: Configuration Wizard
**User**: "Build a multi-step configuration wizard with validation"
**Response**:
TUI DESIGN: Configuration Wizard
ARCHETYPE: Multi-Step Form
REQUIREMENTS ANALYSIS:
COMPONENT SELECTION:
Primary Components:
textinput.Model (array) - Multiple input fields Justification: Standard form inputs Example: examples/textinputs/main.go
State machine for steps Justification: Multi-step workflow Example: examples/views/main.go
Reference Pattern:
ARCHITECTURE:
Model Struct:
type model struct {
currentStep int
steps []Step
inputs []textinput.Model
focusIdx int
err error
}
type Step struct {
name string
fields []Field
valid bool
}
State Machine: Step 1 (Basic Info) → Step 2 (Advanced) → Step 3 (Confirm) → Done
WORKFLOW:
Phase 1: Basic Form (45min)
Phase 2: Add Steps (30min)
Phase 3: Validation (45min)
Phase 4: Polish (30min)
Total: ~2.5 hours
REFERENCE STUDY ORDER:
NEXT STEPS:
### Example 4: File Manager
**User**: "Design a file manager TUI like ranger"
**Response**:
TUI DESIGN: File Manager
ARCHETYPE: File Manager
REQUIREMENTS ANALYSIS:
COMPONENT SELECTION:
Primary Components:
filepicker.Model - File navigation Justification: Built-in file system navigation Example: examples/file-picker/main.go Alternative: Custom with list.Model for more control
viewport.Model - File preview Justification: Preview pane for selected file Example: examples/pager/main.go
Lipgloss layout - Three-column layout Justification: Side-by-side panels Example: examples/split-editors/main.go (two-pane reference)
ARCHITECTURE:
Model Struct:
type model struct {
parentList list.Model // Parent directory
currentList list.Model // Current directory
preview viewport.Model // File preview
currentDir string
selectedFile string
width int
height int
}
Layout: ┌────────────┬─────────────┬──────────────┐ │ Parent │ Current │ Preview │ │ Dir │ Dir │ Pane │ │ │ │ │ │ ../ │ > file1.txt │ File content │ │ docs/ │ file2.go │ ... │ │ src/ │ dir/ │ │ └────────────┴─────────────┴──────────────┘
WORKFLOW:
Phase 1: Single Dir Nav (1h)
Phase 2: Three-Pane Layout (1h)
Phase 3: File Preview (45min)
Phase 4: Polish (45min)
Total: ~3.5 hours
REFERENCE STUDY:
NEXT STEPS:
### Example 5: Quick Component Lookup
**User**: "Which component for a dropdown menu?"
**Response**:
COMPONENT RECOMMENDATIONS: Dropdown Menu
Since Bubble Tea doesn't have a built-in dropdown component, here are the best approaches:
list.Model (Recommended)
autocomplete
Custom with viewport
IMPLEMENTATION PATTERN:
type model struct {
dropdownOpen bool
dropdownList list.Model
selectedValue string
}
func (m model) Update(msg tea.Msg) (tea.Model, tea.Cmd) {
switch msg := msg.(type) {
case tea.KeyMsg:
if msg.String() == "enter" && !m.dropdownOpen {
// Open dropdown
m.dropdownOpen = true
return m, nil
}
if m.dropdownOpen {
// Delegate to list
var cmd tea.Cmd
m.dropdownList, cmd = m.dropdownList.Update(msg)
return m, cmd
}
}
return m, nil
}
RECOMMENDED APPROACH: Use list.Model in "dropdown mode" - render as overlay when open, hide when closed.
Study: examples/list-simple/main.go
---
**Total Word Count**: ~7,200 words
This comprehensive skill documentation provides:
- Clear activation criteria
- Complete workflow explanations
- Detailed function documentation
- Architecture patterns
- Error handling guidance
- Extensive usage examples
- Integration with charm-examples-inventory