johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: consolidate duplicate UI_PHILOSOPHY files (GH#745)

Browse Source 
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
2025-12-27 18:01:59 -08:00
parent d3fe6b0f32
commit f93068e1b0
2 changed files with 96 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

135
docs/UI_PHILOSOPHY.md
View File

@@ -1,57 +1,114 @@
# UI/UX Philosophy # 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 ## Core Principles
1. **Maximize data-ink ratio**: Only color what demands attention ### 1. Maximize Data-Ink Ratio (Tufte)
2. **Respect cognitive load**: Let whitespace and position do most of the work Only color what demands attention. Every colored element should serve a purpose:
3. **Create scannable hierarchy**: Headers mark territory, bold creates scan targets - 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 | ### 2. Semantic Color Tokens
|---------|-------|-------------| Use meaning-based tokens, not raw colors:
| 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 |
## 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) ### 3. Perceptual Optimization (Light/Dark Modes)
- Don't use color for decoration Lipgloss `AdaptiveColor` ensures optimal contrast in both terminal modes:
- Don't style closed/completed items (they're done, users don't care)
- Keep examples plain (copy-paste friendly)
## 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 ### 4. Respect Cognitive Load
- **Command names** in listings: Bold Let whitespace and position do most of the work:
- **Command references** in descriptions ('comments add'): Bold - 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 ### When to Color
- **Flag names** (-f, --file): Bold
- **Type annotations** (string, int, duration): Muted | Situation | Style | Rationale |
- **Default values** (default: ...): Muted |-----------|-------|-----------|
- **Descriptions**: Plain | Navigation landmarks | Accent | Helps users orient in output |
- **Examples**: Plain (copy-paste friendly) | 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 ## Ayu Theme
All colors use the Ayu theme with adaptive light/dark mode support. All colors use the [Ayu theme](https://github.com/ayu-theme/ayu-colors) for consistency:
See `internal/ui/styles.go` for implementation.
| Color | Light Mode | Dark Mode | Usage | ```go
|-------|------------|-----------|-------| // Semantic colors with light/dark adaptation
| Accent | #399ee6 | #59c2ff | Headers, links | ColorPass = AdaptiveColor{Light: "#86b300", Dark: "#c2d94c"} // Green
| Command | Bold white | Bold white | Command/flag names | ColorWarn = AdaptiveColor{Light: "#f2ae49", Dark: "#ffb454"} // Yellow
| Muted | #828c99 | #6c7680 | Types, defaults | ColorFail = AdaptiveColor{Light: "#f07171", Dark: "#f07178"} // Red
| Pass | #6cbf43 | #7fd962 | Success states | ColorAccent = AdaptiveColor{Light: "#399ee6", Dark: "#59c2ff"} // Blue
| Warn | #e6ba7e | #ffb454 | Warnings, P1 | ColorMuted = AdaptiveColor{Light: "#828c99", Dark: "#6c7680"} // Gray
| Fail | #f07171 | #f26d78 | Errors, bugs, P0 | ```
## 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)

114
docs/ui-philosophy.md
View File

@@ -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)