f93068e1b0
Kept the more comprehensive version (115 lines vs 58) and renamed to match docs/ naming convention (SCREAMING_SNAKE_CASE).
115 lines
4.3 KiB
Markdown
115 lines
4.3 KiB
Markdown
# 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)
|