docs: consolidate duplicate UI_PHILOSOPHY files (GH#745)
Kept the more comprehensive version (115 lines vs 58) and renamed to match docs/ naming convention (SCREAMING_SNAKE_CASE).
This commit is contained in:
Steve Yegge
@@ -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 <cmd> --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)
|
||||
|
||||
Reference in New Issue
Block a user