cli-ui-modernization

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

Project: lean-spec
Team: Core Development

Overview

The current CLI UI has two main issues:

1. Output is too scattered - Components like lean-spec stats, lean-spec board, and lean-spec list have excessive spacing between elements, making the output feel bloated and hard to scan
2. Rainbow gradients feel dated - The ink-gradient rainbow effect on titles doesn't match modern CLI aesthetics (see GitHub CLI, Vercel CLI, etc.)

This impacts user experience by making the tool feel less polished and harder to use efficiently.

Design

Compact Spacing Strategy

Current issues:

• marginBottom={1} used everywhere (full blank lines between sections)
• Panels have large internal padding
• List items have full line gaps
• Filter info takes up too much vertical space

Solution:

• Reduce margins to 0 for most cases, use gaps only between major sections
• Tighten panel padding from padding={1} to minimal/inline spacing
• Remove blank lines between list items
• Make filter info inline/compact

Modern Color Scheme

Replace rainbow gradients with:

• Cyan/Blue for main titles (#00d7ff / #0070f3 style)
• Magenta/Purple for secondary emphasis (#d946ef / #7928ca style)
• Use bold + single color instead of gradient
• Reference: GitHub CLI, Vercel CLI, Next.js CLI aesthetics

Components affected:

• StatsDisplay.tsx - Title and section headers
• Board.tsx - Main title
• SpecListView.tsx - Title

Implementation Approach

1. Remove ink-gradient dependency and imports
2. Replace <Gradient name="rainbow"> with styled <Text> components
3. Reduce marginBottom and marginTop props across all components
4. Adjust panel and card internal spacing
5. Test visual output with real data

Plan

• Create spec for CLI UI improvements
• Examine current components and styling
• Update color scheme (remove gradients, use modern colors)
• Implement compact spacing across all components
• Update StatsDisplay.tsx
• Update Board.tsx
• Update SpecListView.tsx
• Fix border alignment issues in Board component
• Add vertical line separators in SpecListView
• Modernize lean-spec timeline output
• Test with lean-spec stats, lean-spec board, lean-spec list

Test

Manual verification:

• Run lean-spec stats - output is compact, colors modern
• Run lean-spec board - columns are tighter, title not rainbow, borders aligned
• Run lean-spec list - date groups closer together, clean colors, vertical lines
• Run lean-spec list --tag=cli - filter info is compact
• Run lean-spec timeline - modern output with better bars and formatting
• Overall: Less vertical scrolling required, cleaner aesthetic

Visual quality checks:

• No rainbow gradients anywhere
• Consistent use of cyan/magenta for emphasis
• Maximum 1 blank line between major sections
• All panels/cards have minimal padding
• Text is still readable and not cramped
• Border lines are properly aligned
• Vertical separators between list items

Implementation Summary

Phase 1: Initial modernization

• Removed ink-gradient from all components
• Replaced rainbow gradients with bold cyan titles
• Reduced spacing (marginBottom/marginTop) throughout
• Changed panel padding from 1 to 0

Phase 2: Bug fixes

1. Fixed board border alignment by correcting width calculations
2. Added vertical line (│) separators in spec list view
3. Changed tree connectors to use └─ for last items
4. Added separator lines between specs in list

Phase 3: Timeline enhancement

• Changed title to bold cyan
• Improved bar charts with ━ character and proportional sizing
• Added "Activity" and "Monthly Overview" section titles
• Simplified completion rate display with arrows
• Modernized tag/assignee breakdown formatting
• Converted to column-based table layout with headers
• Fixed column width alignment issues

Phase 4: Stats alignment improvements

• Fixed Panel component to respect padding={0}
• Aligned status labels using padEnd()
• Aligned priority labels using padEnd()
• Attempted emoji width compensation

Known Issues

Alignment Problems

Root cause: Emojis have inconsistent visual width in terminals

• Different emojis render at different widths (some as 1 char, some as 2)
• Terminals handle emoji width differently (iTerm, VS Code, etc.)
• String .padEnd() works on character count, not visual width
• This makes it nearly impossible to align text after emojis consistently

Current issues in lean-spec stats:

1. Status Distribution bars not perfectly aligned despite using .padEnd(13)
2. Priority Breakdown bars not perfectly aligned despite using .padEnd(13)
3. The alignment looks different in different terminals

Potential solutions:

1. Remove emojis from labels entirely (just use text)
2. Put emojis in a fixed-width column separate from text
3. Use a library that handles emoji width (e.g., string-width from npm)
4. Accept that terminal emoji rendering is inconsistent

Example of the issue:

📅 Planned       ← emoji + 1 space + text
🔨 In Progress   ← emoji takes more visual space
✅ Complete      ← emoji takes even more space

Other Potential Issues

• Board component may still have spacing inconsistencies
• List view vertical lines may not align in all cases
• Timeline bars might overflow on narrow terminals

Notes

Modern CLI references:

• GitHub CLI: Bold cyan titles, minimal spacing
• Vercel CLI: Magenta accents, clean output
• Next.js CLI: Blue/cyan, tight formatting

Design decisions:

• Used ━ (U+2501) for timeline bars instead of █ for cleaner look
• Used │ (U+2502) for vertical lines in list view
• Used ├─ and └─ for tree structure consistency
• Kept readability as priority while reducing whitespace

Future consideration: Could add --compact flag for users who prefer minimal spacing vs. default with some breathing room.