cli-ui-ux-optimization

Status: ✅ Complete · Priority: High · Created: 2025-11-03 · Tags: cli, ux, enhancement

Project: lean-spec
Team: Core Development

Overview

The current CLI rendering has inconsistent UI/UX that lacks the polish and richness of modern CLI tools like Python's rich library. We want to create a beautiful, feature-rich terminal experience using Ink/React while maintaining consistency.

Current Problems:

1. Inconsistent rendering: Some commands use plain console.log, others use Ink - creating a jarring mix
2. Underutilized Ink: Where we use Ink, we're not leveraging its full power (animations, layouts, interactions)
3. Poor visual design: Awkward borders, fixed widths, cluttered spacing
4. Limited interactivity: No way to navigate, filter, or interact with results
5. Missing rich features: No syntax highlighting, progress indicators, live updates, or animations
6. Primitive components: Current Board/Stats components are basic and don't showcase what's possible

Why now: Modern CLI tools (GitHub CLI, Vercel CLI, rich in Python) set high UX standards. We should match that quality.

Design

Vision: rich for Node.js

Create a rich, beautiful CLI experience inspired by Python's rich library:

• Beautiful tables with automatic column sizing, borders, and alignment
• Rich panels with rounded corners, padding, and titles
• Syntax highlighting for code snippets and file content
• Progress bars and spinners for async operations
• Live updating displays (e.g., real-time build status)
• Interactive elements (arrow keys to navigate, space to select)
• Color gradients and visual flair (when appropriate)
• Responsive layouts that adapt to terminal width

Unified Ink Architecture

ALL commands should use Ink/React for consistent, rich rendering:

Benefits:

• Beautiful, modern UI with professional polish
• Interactive features (keyboard navigation, selection)
• Live updates without re-rendering full screen
• Component reusability and composition
• Consistent spacing, colors, and layouts
• Easy to add animations and transitions

Visual Design Principles

Inspired by rich (Python):

1. Beautiful typography: Use box-drawing characters, rounded corners, proper spacing
2. Smart colors: Gradients, semantic colors, and theme consistency
3. Visual hierarchy: Clear structure with panels, tables, and sections
4. Responsive design: Adapt to terminal width (80 cols minimum, expand to full width)
5. Rich information density: Show more data in an organized, scannable way
6. Smooth interactions: Animations for transitions, loading states

Component Library

Build reusable Ink components:

<Panel> - Rounded box with title, padding, and optional footer

<Panel title="📊 Spec Statistics" border="rounded" padding={1}>
  {content}
</Panel>

<Table> - Auto-sized columns with headers, borders, alignment

<Table
  columns={[
    { header: 'Spec', align: 'left', width: 'auto' },
    { header: 'Status', align: 'center', width: 12 },
    { header: 'Priority', align: 'left', width: 10 }
  ]}
  rows={rows}
  border="rounded"
/>

<ProgressBar> - Rich progress indicator with percentage, ETA

<ProgressBar
  current={15}
  total={26}
  label="Loading specs"
  showPercentage
  showETA
/>

<KeyValueList> - Aligned key-value pairs

<KeyValueList
  items={[
    { key: 'Status', value: 'In Progress', color: 'yellow' },
    { key: 'Priority', value: 'High', color: 'red' }
  ]}
  keyWidth={15}
/>

<Tree> - Hierarchical display with indent lines

<Tree
  data={specsByDate}
  renderNode={(spec) => <SpecNode spec={spec} />}
  expandable
/>

<Tabs> - Multiple views with tab navigation

<Tabs activeTab={activeTab} onChange={setActiveTab}>
  <Tab name="board" label="📋 Board">
    <Board specs={specs} />
  </Tab>
  <Tab name="list" label="📄 List">
    <SpecList specs={specs} />
  </Tab>
</Tabs>

Enhanced Commands

lean-spec list - Interactive tree view:

• Group by date with collapsible sections
• Filter with j/k keys, select with space
• Show inline previews (first line of spec)
• Responsive columns that adapt to terminal width

lean-spec stats - Rich dashboard:

• Multiple panels (status, priority, tags, timeline)
• Bar charts for distribution
• Sparklines for trends over time
• Color gradients for visual appeal

lean-spec board - Enhanced kanban:

• Prettier cards with rounded corners
• Syntax-highlighted metadata
• Drag-and-drop to change status (with arrow keys)
• Live updates if specs change

lean-spec search - Rich results:

• Highlight matching text
• Context snippets with line numbers
• Preview pane for selected result
• Fuzzy matching scores

lean-spec timeline/gantt - Visual timeline:

• Rich ASCII chart with colors
• Milestone markers
• Dependencies shown with lines/arrows
• Zoom controls

Standardized UI Patterns

Panel Headers (with rounded corners):

╭─ 📊 Spec Statistics ────────────────────────────────────╮
│                                                          │
│  Content here...                                         │
│                                                          │
╰──────────────────────────────────────────────────────────╯

Tables (auto-sized, aligned):

╭────────────────────────────┬──────────┬──────────┬────────────────╮
│ Spec                       │  Status  │ Priority │ Tags           │
├────────────────────────────┼──────────┼──────────┼────────────────┤
│ 001-auth-system            │    ✅    │ high     │ api, security  │
│ 002-ui-components          │    🔨    │ medium   │ frontend, ui   │
│ 003-performance-opt        │    📅    │ low      │ optimization   │
╰────────────────────────────┴──────────┴──────────┴────────────────╯

Progress Bars:

Loading specs ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% (26/26) ⠹

Hierarchical Lists:

📂 20251103/
├─ 📄 001-feature-a/          ✅ high     [api, backend]
├─ 📄 002-feature-b/          🔨 medium   [frontend]
└─ 📄 003-feature-c/          📅 low      [docs]

Status Cards:

╭─ 📅 Planned (6) ──────────────╮
│                               │
│  • auth-system                │
│    [api, security]            │
│                               │
│  • ui-components              │
│    [frontend, ui]             │
│                               │
╰───────────────────────────────╯

Key-Value Displays:

Status:         🔨 In Progress
Priority:       🔴 High
Created:        2025-11-03
Tags:           cli, ux, enhancement
Assignee:       @alice

Additional Ink Libraries

Consider integrating:

• ink-box - Beautiful boxes/panels with borders
• ink-gradient - Gradient text effects
• ink-table - Rich table rendering
• ink-spinner - Enhanced spinners and loading states
• ink-select-input - Interactive selection lists
• ink-text-input - Text input for search/filter
• ink-progress-bar - Progress indicators
• ink-big-text - Large ASCII art text for headers

Plan

Phase 1: Component Library Foundation

• Audit current rendering patterns
• Install additional Ink libraries (ink-box, ink-table, ink-gradient, ink-spinner, etc.)
• Create shared component library in src/components/ui/:
  • Panel.tsx - Rounded boxes with titles
  • Table.tsx - Auto-sized table with borders
  • ProgressBar.tsx - Rich progress indicator
  • KeyValueList.tsx - Aligned key-value pairs
  • Tree.tsx - Hierarchical tree view
  • StatusBadge.tsx - Styled status indicators
  • Card.tsx - Content cards with metadata
• Document component usage patterns

Phase 2: Migrate Commands to Rich UI

• Refactor stats command:
  • Multi-panel dashboard layout
  • Bar charts for distributions
  • Sparklines for trends
  • Color gradients
• Refactor board command:
  • Beautiful kanban cards with rounded corners
  • Better column layout
  • Interactive navigation (arrow keys)
  • Smooth transitions
• Refactor list command:
  • Convert to Ink component
  • Interactive tree view
  • Collapsible date groups
  • Filter/search capabilities
• Refactor search command:
  • Rich result cards
  • Highlighted matches
  • Preview pane
  • Navigation controls

Phase 3: Interactive Features

• Add keyboard navigation to all commands
• Implement selection/multi-select where appropriate
• Add live-updating displays (watch mode)
• Add interactive filtering (press / to filter)
• Add help overlays (press ? for help)

Phase 4: Advanced Visualizations

• Enhance timeline command with rich ASCII chart
• Enhance gantt command with colors and dependencies
• Add deps command visualization (dependency graph)
• Add spec preview/quick view feature
• Add diff view for spec changes

Phase 5: Polish & Testing

• Ensure responsive layouts (80-200+ column terminals)
• Test with various terminal emulators
• Add loading states and transitions
• Performance optimization for large spec counts
• Accessibility considerations (high contrast mode)

Test

Visual Quality Tests

• All commands render beautifully with rich UI
• Tables auto-size correctly and align properly
• Panels have proper rounded corners and padding
• Colors are vibrant but not overwhelming
• Typography is clean and readable

Interactive Tests

• Keyboard navigation works (arrow keys, enter, esc)
• Selection states are visually clear
• Live updates don't cause flicker
• Transitions are smooth
• Help overlays appear on ? key

Responsive Tests

• Works in 80-column terminal (minimum)
• Expands nicely in wide terminals (200+ columns)
• Content doesn't overflow or wrap awkwardly
• Tables adapt column widths intelligently
• Mobile terminal emulators (Termux, etc.)

Terminal Compatibility

• iTerm2 (macOS)
• Terminal.app (macOS)
• Windows Terminal
• VS Code integrated terminal
• Alacritty, Kitty, WezTerm
• tmux/screen sessions

Performance Tests

• 50+ specs render smoothly
• 100+ specs don't cause lag
• Interactive navigation is responsive
• Live updates don't impact performance
• Memory usage is reasonable

Edge Cases

• Empty states look good (no specs)
• Single spec displays properly
• Very long spec names are truncated nicely
• Many tags (10+) display without clutter
• Unicode/emoji render correctly
• Custom frontmatter fields display well

Integration Tests

• All existing tests pass
• Output can still be piped/redirected (fallback to plain text)
• --json flags work alongside rich UI
• CI/CD detects non-interactive terminals correctly
• Works with NO_COLOR environment variable

Notes

Inspiration: Python's rich Library

Python's rich is the gold standard for beautiful CLI UIs. Key features to emulate:

• Rich tables: Auto-sized, aligned, with beautiful borders
• Syntax highlighting: For code, JSON, YAML, Markdown
• Progress bars: With percentage, ETA, visual appeal
• Panels: Rounded boxes with titles and padding
• Tree views: Hierarchical data with connecting lines
• Live displays: Real-time updating without flicker
• Colors & gradients: Vibrant but tasteful
• Typography: Smart use of box-drawing characters

Ink Ecosystem

Existing libraries to leverage:

• ink-box: Rounded panels and boxes
• ink-table: Feature-rich tables
• ink-gradient: Text gradients
• ink-spinner: Enhanced loading indicators
• ink-select-input: Interactive lists
• ink-text-input: Search/filter inputs
• ink-progress-bar: Progress indicators
• ink-link: Clickable terminal links
• ink-testing-library: Component testing

Design Philosophy

"Rich but tasteful" - We want beautiful, feature-rich UI that:

• Delights users with polish and attention to detail
• Makes information clear and scannable
• Adds interactivity where it helps productivity
• Looks professional and modern
• Stays performant even with lots of data

Not aiming for:

• Over-the-top animations or effects
• Complexity for complexity's sake
• Slowness or lag
• Unusable in non-interactive contexts

Current State Analysis

What works:

• Basic Ink integration for stats/board
• Spinner for loading states
• Color usage for status/priority

What needs improvement:

• Limited component reusability
• Basic layouts (no panels, limited tables)
• No interactivity (navigation, selection)
• Inconsistent across commands (list uses console.log)
• Fixed widths don't adapt to terminal
• Missing advanced features (syntax highlighting, live updates)

Technical Considerations

Performance:

• Ink's React reconciliation is fast enough for our use case
• Virtual rendering prevents full-screen redraws
• Component memoization for optimal updates

Compatibility:

• Detect interactive vs non-interactive terminals
• Fallback to plain output for pipes/redirects
• Support NO_COLOR environment variable
• Handle narrow terminals gracefully (80 col minimum)

Testing:

• Use ink-testing-library for component tests
• Snapshot tests for visual regression
• Integration tests for command output

Alternatives Considered

1. Blessed - Lower-level, more complex, less React-like
2. Plain chalk/console.log - Too simple, lacks richness
3. Charm's Bubble Tea (Go) - Wrong language, but great inspiration
4. Textual (Python) - Another Python rich library, good reference

Future Enhancements

Phase 2 (post-launch):

• Interactive spec editing (TUI editor)
• Real-time collaboration indicators
• Git diff visualization
• Dependency graph visualization
• Custom themes/color schemes
• Plugin system for custom commands
• Watch mode with live updates
• Export to HTML/PDF with styling

Advanced features:

• Mouse support (click to navigate)
• Split-pane views
• Fuzzy search with live preview
• Animated transitions
• Sound effects (optional, for fun)
• ASCII art banners