ContextQMD
Back to Beads

UI/UX Philosophy

docs/UI_PHILOSOPHY.md

1.0.34.3 KB
Original Source

UI/UX Philosophy

Beads CLI follows Tufte-inspired design principles for terminal output, using semantic color tokens with adaptive light/dark mode support via Lipgloss.

Core Principles

1. Maximize Data-Ink Ratio (Tufte)

Only color what demands attention. Every colored element should serve a purpose:

  • Navigation landmarks (section headers, group titles)
  • Scan targets (command names, flag names)
  • Semantic states (success, warning, error, blocked)

Anti-pattern: Coloring everything defeats the purpose and creates cognitive overload.

2. Semantic Color Tokens

Use meaning-based tokens, not raw colors:

TokenSemantic MeaningUse Cases
PassSuccess, completion, readyCheckmarks, completed items, healthy status
WarnAttention needed, cautionWarnings, in-progress items, action required
FailError, blocked, criticalErrors, blocked items, failures
AccentNavigation, emphasisHeaders, links, key information
MutedDe-emphasized, secondaryDefaults, closed items, metadata
CommandInteractive elementsCommand names, flags

3. Perceptual Optimization (Light/Dark Modes)

Lipgloss AdaptiveColor ensures optimal contrast in both terminal modes:

go
ColorPass = lipgloss.AdaptiveColor{
    Light: "#86b300", // Darker green for light backgrounds
    Dark:  "#c2d94c", // Brighter green for dark backgrounds
}

Why this matters:

  • Light terminals need darker colors for contrast
  • Dark terminals need brighter colors for visibility
  • Same semantic meaning, optimized perception

4. Respect Cognitive Load

Let whitespace and position do most of the work:

  • Group related information visually
  • Use indentation for hierarchy
  • Reserve color for exceptional states

Color Usage Guide

When to Color

SituationStyleRationale
Navigation landmarksAccentHelps users orient in output
Command/flag namesBoldCreates vertical scan targets
Success indicatorsPass (green)Immediate positive feedback
WarningsWarn (yellow)Draws attention without alarm
ErrorsFail (red)Demands immediate attention
Closed/done itemsMutedVisually recedes, "done"
High priority (P0/P1)Semantic colorOnly urgent items deserve color
Normal priority (P2+)PlainMost items don't need highlighting

When NOT to Color

  • Descriptions and prose: Let content speak for itself
  • Examples in help text: Keep copy-paste friendly
  • Every list item: Only color exceptional states
  • Decorative purposes: Color is functional, not aesthetic

Ayu Theme

All colors use the Ayu theme for consistency:

go
// Semantic colors with light/dark adaptation
ColorPass   = AdaptiveColor{Light: "#86b300", Dark: "#c2d94c"}  // Green
ColorWarn   = AdaptiveColor{Light: "#f2ae49", Dark: "#ffb454"}  // Yellow
ColorFail   = AdaptiveColor{Light: "#f07171", Dark: "#f07178"}  // Red
ColorAccent = AdaptiveColor{Light: "#399ee6", Dark: "#59c2ff"}  // Blue
ColorMuted  = AdaptiveColor{Light: "#828c99", Dark: "#6c7680"}  // Gray

Implementation

All styling is centralized in internal/ui/styles.go:

go
// Render functions for semantic styling
ui.RenderPass("✓")     // Success indicator
ui.RenderWarn("⚠")     // Warning indicator
ui.RenderFail("✗")     // Error indicator
ui.RenderAccent("→")   // Accent/link
ui.RenderMuted("...")  // Secondary info
ui.RenderBold("name")  // Emphasis
ui.RenderCommand("bd") // Command reference

Help Text Styling

Following Tufte's principle of layered information:

  1. Section headers (Flags:, Examples:) - Accent color for navigation
  2. Flag names (--file) - Bold for scannability
  3. Type annotations (string) - Muted, reference info
  4. Default values ((default: ...)) - Muted, secondary
  5. Descriptions - Plain, primary content
  6. Examples - Plain, copy-paste friendly

References