diff --git a/docs/UI_PHILOSOPHY.md b/docs/UI_PHILOSOPHY.md index a2ea416e..f7cf87c4 100644 --- a/docs/UI_PHILOSOPHY.md +++ b/docs/UI_PHILOSOPHY.md @@ -1,57 +1,114 @@ # UI/UX Philosophy -Beads CLI follows Tufte-inspired design principles for terminal output. +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**: Only color what demands attention -2. **Respect cognitive load**: Let whitespace and position do most of the work -3. **Create scannable hierarchy**: Headers mark territory, bold creates scan targets +### 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) -## Color Usage +**Anti-pattern**: Coloring everything defeats the purpose and creates cognitive overload. -| Purpose | Style | When to Use | -|---------|-------|-------------| -| Navigation landmarks | Accent (blue) | Section headers, group titles | -| Scan targets | Bold | Command names, flag names | -| De-emphasized | Muted (gray) | Types, defaults, closed items | -| Semantic states | Pass/Warn/Fail | P0/P1 priority, bugs, blocked | -| Standard text | Plain | Descriptions, prose, examples | +### 2. Semantic Color Tokens +Use meaning-based tokens, not raw colors: -## Anti-Patterns +| Token | Semantic Meaning | Use Cases | +|-------|-----------------|-----------| +| `Pass` | Success, completion, ready | Checkmarks, completed items, healthy status | +| `Warn` | Attention needed, caution | Warnings, in-progress items, action required | +| `Fail` | Error, blocked, critical | Errors, blocked items, failures | +| `Accent` | Navigation, emphasis | Headers, links, key information | +| `Muted` | De-emphasized, secondary | Defaults, closed items, metadata | +| `Command` | Interactive elements | Command names, flags | -- Don't highlight everything (defeats the purpose) -- Don't use color for decoration -- Don't style closed/completed items (they're done, users don't care) -- Keep examples plain (copy-paste friendly) +### 3. Perceptual Optimization (Light/Dark Modes) +Lipgloss `AdaptiveColor` ensures optimal contrast in both terminal modes: -## Help Output Styling +```go +ColorPass = lipgloss.AdaptiveColor{ + Light: "#86b300", // Darker green for light backgrounds + Dark: "#c2d94c", // Brighter green for dark backgrounds +} +``` -### Main Help (`bd help`) +**Why this matters**: +- Light terminals need darker colors for contrast +- Dark terminals need brighter colors for visibility +- Same semantic meaning, optimized perception -- **Group headers** (Working With Issues:, Views & Reports:, etc.): Accent color -- **Command names** in listings: Bold -- **Command references** in descriptions ('comments add'): Bold +### 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 -### Subcommand Help (`bd --help`) +## Color Usage Guide -- **Section headers** (Usage:, Flags:, Examples:): Accent color -- **Flag names** (-f, --file): Bold -- **Type annotations** (string, int, duration): Muted -- **Default values** (default: ...): Muted -- **Descriptions**: Plain -- **Examples**: Plain (copy-paste friendly) +### When to Color + +| Situation | Style | Rationale | +|-----------|-------|-----------| +| Navigation landmarks | Accent | Helps users orient in output | +| Command/flag names | Bold | Creates vertical scan targets | +| Success indicators | Pass (green) | Immediate positive feedback | +| Warnings | Warn (yellow) | Draws attention without alarm | +| Errors | Fail (red) | Demands immediate attention | +| Closed/done items | Muted | Visually recedes, "done" | +| High priority (P0/P1) | Semantic color | Only urgent items deserve color | +| Normal priority (P2+) | Plain | Most 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 with adaptive light/dark mode support. -See `internal/ui/styles.go` for implementation. +All colors use the [Ayu theme](https://github.com/ayu-theme/ayu-colors) for consistency: -| Color | Light Mode | Dark Mode | Usage | -|-------|------------|-----------|-------| -| Accent | #399ee6 | #59c2ff | Headers, links | -| Command | Bold white | Bold white | Command/flag names | -| Muted | #828c99 | #6c7680 | Types, defaults | -| Pass | #6cbf43 | #7fd962 | Success states | -| Warn | #e6ba7e | #ffb454 | Warnings, P1 | -| Fail | #f07171 | #f26d78 | Errors, bugs, P0 | +```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 + +- Tufte, E. (2001). *The Visual Display of Quantitative Information* +- [Ayu Theme Colors](https://github.com/ayu-theme/ayu-colors) +- [Lipgloss - Terminal Styling](https://github.com/charmbracelet/lipgloss) +- [WCAG Color Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) diff --git a/docs/ui-philosophy.md b/docs/ui-philosophy.md deleted file mode 100644 index f7cf87c4..00000000 --- a/docs/ui-philosophy.md +++ /dev/null @@ -1,114 +0,0 @@ -# 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: - -| Token | Semantic Meaning | Use Cases | -|-------|-----------------|-----------| -| `Pass` | Success, completion, ready | Checkmarks, completed items, healthy status | -| `Warn` | Attention needed, caution | Warnings, in-progress items, action required | -| `Fail` | Error, blocked, critical | Errors, blocked items, failures | -| `Accent` | Navigation, emphasis | Headers, links, key information | -| `Muted` | De-emphasized, secondary | Defaults, closed items, metadata | -| `Command` | Interactive elements | Command 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 - -| Situation | Style | Rationale | -|-----------|-------|-----------| -| Navigation landmarks | Accent | Helps users orient in output | -| Command/flag names | Bold | Creates vertical scan targets | -| Success indicators | Pass (green) | Immediate positive feedback | -| Warnings | Warn (yellow) | Draws attention without alarm | -| Errors | Fail (red) | Demands immediate attention | -| Closed/done items | Muted | Visually recedes, "done" | -| High priority (P0/P1) | Semantic color | Only urgent items deserve color | -| Normal priority (P2+) | Plain | Most 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](https://github.com/ayu-theme/ayu-colors) 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 - -- Tufte, E. (2001). *The Visual Display of Quantitative Information* -- [Ayu Theme Colors](https://github.com/ayu-theme/ayu-colors) -- [Lipgloss - Terminal Styling](https://github.com/charmbracelet/lipgloss) -- [WCAG Color Contrast Guidelines](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html)