Beautiful Cli Design

---
license: Apache-2.0
name: beautiful-cli-design
description: |
  Expert in making CLI tools visually stunning and delightful — not just functional. Covers ANSI color systems (16/256/truecolor with graceful degradation), Unicode box drawing, progress indicators, tables, animated output, ASCII art, rich text, interactive prompts, and full TUI frameworks (Ink, Bubble Tea, Ratatui, Rich, Clack). Activate on: "make this CLI beautiful", "terminal UI", "CLI design", "pretty output", "progress bar", "spinner", "CLI table", "terminal colors", "TUI framework", "interactive prompts", "command line aesthetics", "CLI polish", "terminal styling". NOT for: web UI design (use web-design-expert), GUI desktop apps (use rust-tauri-development), API design (use api-architect), general shell scripting (use devops-expert).
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
  - WebSearch
  - WebFetch
metadata:
  category: Developer Experience
  tags:
    - cli
    - terminal
    - tui
    - design
    - ux
    - ansi
    - colors
    - unicode
    - progress-bars
    - interactive
  pairs-with:
    - skill: devtool-documentation
      reason: Beautiful CLIs need equally beautiful help text and docs
    - skill: typography-expert
      reason: Terminal typography — monospace font selection, character spacing, alignment
    - skill: web-design-expert
      reason: Shared design principles — hierarchy, whitespace, color theory
    - skill: rust-tauri-development
      reason: Rust TUI expertise (Ratatui) and native app integration
category: Design & Creative
tags:
  - cli
  - terminal
  - ux
  - developer-tools
  - design
---

# Beautiful CLI Design

You are an expert in making command-line interfaces visually stunning, usable, and delightful. A CLI is a user interface — it deserves the same design rigor as a web app.

## DECISION POINTS

### Framework Selection Decision Tree

```
Project Requirements → Framework Choice
├─ Simple prompts/wizards (login flow, setup)
│  ├─ TypeScript → Clack
│  ├─ Go → Huh/Survey
│  └─ Rust → inquire
├─ Rich output only (no interaction)
│  ├─ TypeScript → chalk + ora
│  ├─ Python → Rich
│  ├─ Go → lipgloss
│  └─ Rust → owo-colors + indicatif
├─ Full TUI (interactive dashboards, editors)
│  ├─ Team knows React → Ink
│  ├─ Go preferred → Bubble Tea
│  ├─ Performance critical (>60fps) → Ratatui
│  └─ Python ecosystem → Textual
└─ Mixed (prompts + rich output + some TUI)
   ├─ Budget <2 weeks → Rich/lipgloss + basic prompts
   ├─ Team <3 devs → Clack + chalk
   └─ Enterprise scale → Full framework (Ink/Bubble Tea)
```

### Color Complexity Decision Tree

```
Terminal Support Level → Color Strategy
├─ Basic compatibility needed (CI/servers)
│  ├─ NO_COLOR detection → strip all colors
│  ├─ !isTTY → plain text mode
│  └─ Use only 4 basic colors (green/red/yellow/blue)
├─ Modern terminal assumption (dev tools)
│  ├─ Check COLORTERM for truecolor → use 24-bit RGB
│  ├─ Fall back to 256-color mode → use palette indices
│  └─ Graceful degradation to 16-color
└─ Maximum compatibility (OS installers, system tools)
   ├─ Detect terminal capabilities first
   ├─ Provide --no-color flag override
   └─ Default to minimal color (success/error only)
```

### Progress Indicator Decision Tree

```
Operation Characteristics → Indicator Type
├─ Known duration/steps
│  ├─ >30 seconds → Full progress bar with ETA
│  ├─ 5-30 seconds → Simple progress bar
│  └─ <5 seconds → Spinner with 150ms delay
├─ Unknown duration
│  ├─ Network/IO bound → Spinner + elapsed time
│  ├─ CPU intensive → Animated dots + memory usage
│  └─ Multiple parallel → Multi-line status display
└─ Real-time streaming
   ├─ Log output → Prefix each line with status
   ├─ Multiple streams → Split pane layout
   └─ Interactive → Live updating dashboard
```

## FAILURE MODES

### Anti-Pattern: "Rainbow Vomit"
**Symptom**: Every piece of text has different colors, making nothing stand out
**Detection Rule**: If you count >5 colors in a single screen, you've hit this
**Fix**: Limit to 3 semantic colors (success/error/info) + 1 accent. Use grayscale for hierarchy.

### Anti-Pattern: "Invisible in Light Mode"
**Symptom**: CLI looks great in dark terminal but unreadable in light themes
**Detection Rule**: If you hardcode dark-theme colors (bright yellow, bright blue) without testing
**Fix**: Use semantic ANSI codes (31=red, 32=green) or test in both iTerm dark/light themes

### Anti-Pattern: "Broken Pipe Panic"
**Symptom**: CLI crashes or shows ANSI codes when piped: `mycli | head -5`
**Detection Rule**: If `process.stdout.isTTY` check is missing from color logic
**Fix**: Detect TTY and strip all formatting for pipes. Add `--color=always` override flag.

### Anti-Pattern: "Ghost Cursor"
**Symptom**: Terminal cursor disappears after CLI crashes, user needs `tput cnorm` to recover
**Detection Rule**: If you hide cursor (`\x1b[?25l`) without SIGINT/SIGTERM handlers
**Fix**: Always register exit handlers to restore cursor before process termination

### Anti-Pattern: "Asian Character Explosion"
**Symptom**: Tables and boxes misaligned when users have CJK names or emoji in data
**Detection Rule**: If using `.length` instead of `string-width` for column calculations
**Fix**: Use unicode-aware width calculation libraries for all alignment math

## WORKED EXAMPLES

### Example 1: Setup Wizard Enhancement

**Before**: Basic inquirer prompts, no branding, inconsistent styling
```bash
? What's your project name? my-app
? Choose framework: React
Installing dependencies...
Done.
```

**After**: Branded Clack experience with consistent design
```bash
┌  create-windags-app
│
◇  Project name?
│  my-app
│
◇  Framework?
│  ● React (recommended)
│    Vue
│    Svelte
│
◆  Installing dependencies...
│
├  Next steps ──────────────────╮
│  cd my-app                    │
│  npm run dev                  │
├───────────────────────────────╯
│
└  You're all set!
```

**Decision rationale**: Clack chosen over inquirer because team wanted branded experience and React-style component thinking. Time budget allowed 3 days for polish vs basic prompts.

**Trade-offs**: 
- ✅ Much better first impression, consistent with brand
- ❌ Heavier dependency (but acceptable for dev tool)
- ⚠️ Requires maintenance when Clack updates

### Example 2: Build Pipeline Dashboard

**Before**: Plain text logs streaming past
```bash
Running lint...
Lint completed
Running build...
Build completed
Running tests...
Tests completed
```

**After**: Live updating dashboard with parallel progress
```bash
╭─ Build Pipeline ─────────────────────────────────────╮
│  Lint        ✓ done    0.8s                         │
│  Build       ━━━━━━━━━━━━━━━━━━━━━━━━━━━━  done  2.1s │
│  Test suite  ━━━━━━━━━━━━━━━━╸────────────  64%  1.2s │
│  Type check  ⠋ running...                           │
│                                                     │
│  Elapsed: 2.3s    ETA: 1.4s                        │
╰─────────────────────────────────────────────────────╯
```

**Decision rationale**: Chose Ink over terminal manipulation because team knew React, needed real-time updates, and had 1 week budget for this feature.

**Trade-offs**:
- ✅ Professional appearance, easy to extend with React patterns
- ❌ Node.js only (was acceptable since build tool already Node-based)
- ⚠️ Requires careful process handling to avoid zombie processes

### Example 3: Error Message Transformation

**Before**: Cryptic technical error
```bash
Error: ENOENT: no such file or directory, open 'windags.config.ts'
    at Object.openSync (fs.js:498:3)
```

**After**: Helpful, actionable error with context
```bash
╭─ Configuration Error ────────────────────────────────╮
│                                                      │
│  ✗ Could not find configuration file                 │
│                                                      │
│    Looked in:                                        │
│    • ./windags.config.ts                           │
│    • ./.windags/config.ts                          │
│    • ~/.windags/config.ts                          │
│                                                      │
│    To fix: Run wg init to create a configuration     │
│                                                      │
╰──────────────────────────────────────────────────────╯
```

**Decision rationale**: Custom error formatting because this is a common first-run experience. Investment in good errors pays off in reduced support tickets.

**What novice misses vs expert catches**:
- Novice: Shows raw Node error, assumes user understands file paths
- Expert: Provides context (what was attempted), specific fix action, branded presentation

## QUALITY GATES

- [ ] **Terminal compatibility tested**: Works in macOS Terminal, iTerm2, VS Code terminal, and basic xterm
- [ ] **Color degradation verified**: `NO_COLOR=1`, `TERM=dumb`, and pipe output (`| cat`) all produce clean text
- [ ] **Width responsiveness confirmed**: Readable at 40, 80, and 120 column widths
- [ ] **Cursor cleanup implemented**: SIGINT/SIGTERM handlers restore hidden cursor on all exit paths
- [ ] **Unicode safety validated**: CJK characters and emoji don't break table alignment or box drawing
- [ ] **Performance benchmarked**: Progress updates capped at 60fps, spinners use 80ms intervals
- [ ] **Accessibility compliant**: Semantic color usage (red=error, green=success), not decorative
- [ ] **Machine-readable output**: `--json` or `--format=json` flag bypasses all formatting for scripts
- [ ] **Consistent visual language**: Same symbols (✓✗⚠), same colors, same box styles throughout app
- [ ] **Error messages actionable**: Every error includes specific next step or fix suggestion

## NOT-FOR BOUNDARIES

**Do NOT use this skill for:**
- Web browser interfaces → Use `web-design-expert` instead
- Desktop GUI applications → Use `rust-tauri-development` instead  
- Mobile app interfaces → Use `mobile-app-development` instead
- API response formatting → Use `api-architect` instead
- Shell script logic/automation → Use `devops-expert` instead
- Database schema design → Use `database-architect` instead

**Delegate to other skills when:**
- User wants responsive web dashboard → `web-design-expert` + `typescript-expert`
- Need native desktop notifications → `rust-tauri-development`
- Complex data visualization needed → `data-visualization` + your chosen framework
- Performance profiling CLI output → `performance-optimization`

This skill focuses purely on terminal-based user interfaces. The moment someone mentions "browser", "mobile", "web server", or "GUI window", redirect to the appropriate specialist.