castle-x/tui-design

CLI TUI Design Specification

This document provides comprehensive design guidelines for implementing interactive terminal user interface (TUI) applications.

When to Use This Skill

• Developing or modifying CLI TUI components
• Adding new UI pages or interactions
• Implementing new visual styles or themes
• Creating similar TUI applications following this pattern

---

1. Page Layout Structure

Every TUI page follows a consistent four-section layout:

┌────────────────────────────────────────────────────────────────┐
│  Header: Title Line + Separator + ASCII Logo + Separator       │
├────────────────────────────────────────────────────────────────┤
│  Info Bar: Context-dependent information (Dynamic)             │
├────────────────────────────────────────────────────────────────┤
│  Content Area: Interactive options/list (Scrollable)           │
│                                                                │
├────────────────────────────────────────────────────────────────┤
│  Footer: Status Bar + Separator + Keyboard Hints               │
└────────────────────────────────────────────────────────────────┘

Section Details

1.1 Header Section (Always Visible)

The header consists of a title line, separator, ASCII logo, and separator with symmetric spacing:

🚀 Skills-X - AI Agent Skills Manager  v0.2.12
────────────────────────────────────────────────────────────
                                                  <- 1 blank line (from logo constant leading \n)
   ███████╗██╗  ██╗██╗██╗     ...
   ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝...
                                                  <- 1 blank line (from logo constant trailing \n + 1 extra \n)
────────────────────────────────────────────────────────────

Spacing rules:

• The logo constant uses backtick string, which naturally includes a leading \n (after opening backtick) and trailing \n (before closing backtick)
• After logoStyle.Render(logo), add exactly one \n — this produces symmetric 1-blank-line padding on both sides
• Never add \n\n after logo — it creates asymmetric bottom padding

func RenderLogo(version string) string {
    var b strings.Builder
    // Title + version (strip -dirty suffix for display)
    b.WriteString(accentStyle.Render("🚀 Skills-X - AI Agent Skills Manager"))
    if version != "" {
        displayVersion := strings.TrimSuffix(version, "-dirty")
        b.WriteString("  " + hintStyle.Render(displayVersion))
    }
    b.WriteString("\n")
    // Upper separator
    b.WriteString(separatorStyle.Render(strings.Repeat("─", SeparatorWidth)))
    b.WriteString("\n")
    // Logo (constant has leading \n and trailing \n built-in)
    b.WriteString(logoStyle.Render(logo))
    b.WriteString("\n")  // exactly 1 \n — symmetric with leading \n
    // Lower separator
    b.WriteString(separatorStyle.Render(strings.Repeat("─", SeparatorWidth)))
    b.WriteString("\n")
    return b.String()
}

Newline budget between header and content:

• RenderLogo ends with separator + \n
• View should not add extra \n after RenderLogo() — content starts immediately

1.2 Info Bar Section (Dynamic)

• Page-specific context: table headers, counts, search box
• Context info uses dim/hint color
• No working directory display on LV1 — only shown on pages where it adds value (e.g. LV3 skills list)

1.3 Content Area (Interactive)

• Table View: Column headers + data rows with visual-width alignment
• List View: Scrollable list with checkbox multi-selection
• Progress View: Progress bar with percentage and counts

Key features:

• Visual-width-aware column alignment (see Section 3)
• Numeric columns right-aligned with fmt.Sprintf("%4d")
• Checkbox (☐/☑) for multi-selection
• Cursor indicator (❯) for current position
• Empty line padding to maintain stable page height

1.4 Footer Section

(共 30 个，已安装 12 个，将安装 3 个，将卸载 1 个)

────────────────────────────────────────────────────────────
/ 搜索 | 空格 选择/反选 | A 全选 | Enter 确认安装/卸载 | b 返回 | q 退出

Composition:

1. Status bar: \n + counts in dim color, parenthesized
2. Separator: \n + 60-char ─ line + \n
3. Hints: Keyboard shortcuts in dim color, pipe-separated

func RenderStatusBar(total, installed, newSelected, deselected int) string {
    return "\n" + hintStyle.Render(
        fmt.Sprintf("(共 %d 个，已安装 %d 个，将安装 %d 个，将卸载 %d 个)",
            total, installed, newSelected, deselected))
}

func RenderHint(hint string) string {
    return "\n" + RenderSeparator() + hintStyle.Render(hint)
}

func RenderSeparator() string {
    return separatorStyle.Render(strings.Repeat("─", SeparatorWidth)) + "\n"
}

---

2. Style Definitions

Color Palette

| Color Name | Hex Code | Variable | Usage | |------------|-----------|------------------|--------------------------| | Primary | #00D4AA | primaryColor | Selected items, logo | | Secondary | #FF6B6B | secondaryColor | Cursor, errors, alerts | | Accent | #4ECDC4 | accentColor | Title line, highlights | | Dim | #666666 | dimColor | Hints, separators | | White | #FFFFFF | whiteColor | Section titles, headers | | Yellow | #FFCC00 | yellowColor | Warnings (reserved) | | Blue | #5599FF | blueColor | Links (reserved) | | Cyan | #5A9FB8 | cyanColor | Selectable items |

Component Styles

logoStyle       = lipgloss.NewStyle().Foreground(primaryColor).Bold(true)
titleStyle      = lipgloss.NewStyle().Foreground(whiteColor).Bold(true)
selectedStyle   = lipgloss.NewStyle().Foreground(primaryColor).Bold(true)
normalStyle     = lipgloss.NewStyle().Foreground(lipgloss.Color("#AAAAAA"))
selectableStyle = lipgloss.NewStyle().Foreground(cyanColor)
hintStyle       = lipgloss.NewStyle().Foreground(dimColor)
cursorStyle     = lipgloss.NewStyle().Foreground(secondaryColor).Bold(true)
successStyle    = lipgloss.NewStyle().Foreground(lipgloss.Color("#00FF00"))
separatorStyle  = lipgloss.NewStyle().Foreground(dimColor)
searchStyle     = lipgloss.NewStyle().Foreground(whiteColor).Background(lipgloss.Color("#333333"))

Status Indicators

| Symbol | Meaning | Style | |--------|-----------------|---------------| | ☑ | Selected | selectedStyle | | ☐ | Not selected | — | | ❯ | Cursor position | cursorStyle |

---

3. Column Alignment & Visual Width

The Problem

fmt.Sprintf width specifiers count bytes, not terminal columns. This breaks alignment when:

• ANSI escape codes (lipgloss styles) add invisible bytes
• CJK characters (中文、日本語) occupy 2 terminal columns per rune

The Solution: Pad First, Style After

Rule: Always pad plain text to the target visual width, then apply lipgloss style.

// termWidth returns the visual width of a string in terminal columns.
func termWidth(s string) int {
    w := 0
    for _, r := range s {
        if isCJK(r) {
            w += 2
        } else {
            w++
        }
    }
    return w
}

// padRight pads a string with spaces to reach the target visual width.
func padRight(s string, targetWidth int) string {
    w := termWidth(s)
    for w < targetWidth {
        s += " "
        w++
    }
    return s
}

Usage Pattern

// Header: pad plain text, then style
headerName := padRight("AI 工具", 22)   // "AI 工具" = 7 visual cols → 15 spaces added
b.WriteString(fmt.Sprintf("  %s  %s  %s\n",
    titleStyle.Render(headerName),           // styled AFTER padding
    titleStyle.Render(padRight("全局", 4)),   // "全局" = 4 visual cols → 0 spaces
    titleStyle.Render(padRight("项目", 4))))

// Data rows: same column widths
name := padRight(p.Name, 22)             // "Claude Code" = 11 cols → 11 spaces
globalStr := fmt.Sprintf("%4d", count)   // right-aligned number, 4 chars
b.WriteString(fmt.Sprintf("%s%s  %s  %s\n",
    prefix,                               // "  " or "❯ " (always 2 visual cols)
    style.Render(name),                   // styled AFTER padding
    globalCountStyle.Render(globalStr),   // styled AFTER formatting
    projectCountStyle.Render(projectStr)))

Column Width Standards

| Column | Visual Width | Alignment | Padding Method | |--------------|-------------|-----------|-------------------------------| | Name | 22 | Left | padRight(text, 22) | | Skill name | 40 | Left | padRight(text, 40) | | Number | 4 | Right | fmt.Sprintf("%4d", n) | | Status (✓/✗) | 1 | Center | Direct render | | Prefix (❯) | 2 | Left | " " or cursorStyle("❯ ") |

Gap Between Columns

Use 2 spaces (" ") between columns in fmt.Sprintf:

fmt.Sprintf("%s%s  %s  %s\n", prefix, name, col1, col2)
//                ^^    ^^  two-space gaps

---

4. Separator Rules

All separators use the same constant width:

const SeparatorWidth = 60

| Location | Character | Width | Color | |----------------------|-----------|-------|----------| | Above ASCII logo | ─ | 60 | dimColor | | Below ASCII logo | ─ | 60 | dimColor | | Below table header | ─ | 60 | dimColor | | Above footer hints | ─ | 60 | dimColor |

All separators use SeparatorWidth (60). Never hardcode different widths.

---

5. Keyboard Navigation

Universal Keys (All Levels)

| Key | Action | |----------|------------------| | q | Quit application | | Ctrl+C | Force quit |

List Navigation

| Key | Action | |----------|---------------------------------| | ↑ | Move cursor up (wrap to bottom) | | ↓ | Move cursor down (wrap to top) | | PgUp | Page up | | PgDown | Page down | | Home | Jump to first item | | End | Jump to last item |

Selection

| Key | Action | |-----------|--------------------------------------| | Space | Toggle selection (cursor stays) | | a / A | Select all visible items | | Enter | Confirm selection |

Multi-Level Navigation

| Key | Action | |--------------|-----------------------------| | Esc / b | Go back to previous level | | Enter | Proceed to next level |

Search Mode

| Key | Action | |-----------------|-------------------------------| | / / Ctrl+F | Enter search mode | | Typing | Append to search query | | Backspace | Remove last character | | Esc | Exit search mode, clear query |

---

6. Multi-Level Page Architecture

Page Flow

Level 1           Level 2             Level 3            Level 4
  │                  │                   │                  │
  ▼                  ▼                   ▼                  ▼
Select ────────► Select ──────────► Select ──────────► Install
AI Tool          Target (global/     Skills (multi-     Progress
                 project)            select + search)

Navigation Rules

1. Forward: Enter confirms and proceeds to next level
2. Backward: Esc or b returns to previous level (restarts the loop)
3. Quit: q or Ctrl+C exits at any level
4. State preservation: Going back re-runs the previous level from scratch

Orchestration Pattern

Alt screen is managed once at the top level to avoid flicker between pages:

func RunTUI(opts TUIOptions) error {
    // Enter alt screen ONCE for the entire TUI session
    fmt.Print(EnterAltScreen)
    fmt.Print(HideCursor)
    defer func() {
        fmt.Print(ShowCursor)
        fmt.Print(ExitAltScreen)
    }()
    return runTUIFlow(opts)
}

func runTUIFlow(opts TUIOptions) error {
    // Level 1
    fmt.Print(ClearScreen)
    product, err := RunProductSelect(opts.Version, opts.TargetDir)
    if err != nil || product == nil {
        return err
    }

    // Level 2
    fmt.Print(ClearScreen)
    target, err := RunInstallTargetSelect(product, opts.TargetDir)
    ...

    // Level 3
    fmt.Print(ClearScreen)
    selected, deselected, err := RunSkillsSelect(...)
    if err != nil && err.Error() == "go back" {
        return runTUIFlow(opts)  // recursive restart
    }

    // Level 4
    fmt.Print(ClearScreen)
    RunInstaller(selected, deselected, targetDir)

    // Exit alt screen to show final result on normal terminal
    fmt.Print(ShowCursor)
    fmt.Print(ExitAltScreen)
    fmt.Printf("Completed: %d\n", completed)
    return nil
}

---

7. Terminal Control

Two-Layer Rendering Strategy

The rendering uses a two-layer approach to eliminate flicker:

Layer 1: Alt screen lifecycle (managed by RunTUI)

• Enter alt screen once at the start, exit once at the end
• ClearScreen between each page transition (within the alt screen buffer)
• Never use tea.WithAltScreen() on individual programs — it causes exit/enter cycles that flash the normal terminal

Layer 2: Per-page rendering (managed by Bubble Tea)

• Each page runs as tea.NewProgram(model) (no WithAltScreen)
• Bubble Tea handles incremental rendering within the page
• View() returns complete page content; never include ClearScreen in View()

// Individual programs: NO WithAltScreen
p := tea.NewProgram(model)  // Bubble Tea renders incrementally

// Page transitions: ClearScreen within the shared alt screen
fmt.Print(ClearScreen)      // clears alt screen buffer between pages

Anti-patterns:

• tea.NewProgram(model, tea.WithAltScreen()) per level → flicker on every page switch
• ClearScreen inside View() → full repaint on every keystroke
• fmt.Printf(...) between levels while in alt screen → cursor position corruption

ANSI Sequences

const ClearScreen    = "\033[2J\033[H"    // Clear screen + cursor home
const EnterAltScreen = "\033[?1049h"      // Enter alternate screen buffer
const ExitAltScreen  = "\033[?1049l"      // Exit alternate screen buffer
const HideCursor     = "\033[?25l"        // Hide cursor
const ShowCursor     = "\033[?25h"        // Show cursor

---

8. Layout Examples

Level 1: Product Selection

🚀 Skills-X - AI Agent Skills Manager  v0.2.12
────────────────────────────────────────────────────────────

   ███████╗██╗  ██╗██╗██╗     ██╗     ███████╗     ██╗  ██╗
   ...
   ╚══════╝╚═╝  ╚═╝╚═╝╚══════╝╚══════╝╚══════╝     ╚═╝  ╚═╝

────────────────────────────────────────────────────────────
  AI 工具                 全局  项目
────────────────────────────────────────────────────────────
❯ Claude Code               45     0
  Cursor                      0    36
  Windsurf                    0     0

────────────────────────────────────────────────────────────
↑↓ 选择 | Enter 确定 | q 退出

Level 3: Skills Selection

🚀 Skills-X - AI Agent Skills Manager  v0.2.12
────────────────────────────────────────────────────────────

   ███████╗...
   ╚══════╝...

────────────────────────────────────────────────────────────

选择要安装的 Skills  Cursor
📁 /path/to/project

 🔍 搜索技能...
                                          已安装
────────────────────────────────────────────────────────────
❯ ☑ anthropic/brainstorming                ✓
  ☑ anthropic/doc-coauthoring              ✓
  ☐ anthropic/frontend-design              ✗
  ...

↑ 3/30 ↓

(共 30 个，已安装 12 个，将安装 3 个，将卸载 1 个)

────────────────────────────────────────────────────────────
/ 搜索 | 空格 选择/反选 | A 全选 | Enter 确认安装/卸载 | b 返回 | q 退出

Level 4: Installation Progress

Installing Skills

Progress: [========================================] 100% (9/9)
Completed: 9 | Failed: 0

To uninstall:
   [OK] anthropic/doc-coauthoring
   [OK] anthropic/frontend-design

────────────────────────────────────────────────────────────
Done! 9 completed.

---

9. Constants

const SeparatorWidth  = 60  // All separators use this width
const DefaultPageSize = 10  // Default items per page in scrollable lists

---

10. Design Principles Summary

1. Consistent Layout: Every page has Header → Info Bar → Content → Footer
2. Uniform Separators: All ─ lines use SeparatorWidth (60), never hardcode other values
3. Symmetric Spacing: Logo has equal blank-line padding above and below
4. Visual-Width Alignment: Use padRight/termWidth for CJK-aware column alignment; pad plain text first, style after
5. Flicker-Free: Manage alt screen at RunTUI level (enter once, exit once), use ClearScreen between pages, never ClearScreen in View()
6. Stable UI: Fixed column widths, empty line fill, scroll offset tracking
7. Multi-Level Flow: Independent programs per level, back/forward navigation