curiositech/beautiful-cli-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

? What's your project name? my-app
? Choose framework: React
Installing dependencies...
Done.

After: Branded Clack experience with consistent design

┌  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

Running lint...
Lint completed
Running build...
Build completed
Running tests...
Tests completed

After: Live updating dashboard with parallel progress

╭─ 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

Error: ENOENT: no such file or directory, open 'windags.config.ts'
    at Object.openSync (fs.js:498:3)

After: Helpful, actionable error with context

╭─ 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.