Makes the repo's agent and contributor surface describe developing beads, not using bd, and requires every PR to link a documented issue. - Contributor-only root AGENTS.md with a routing table; cmd/bd/AGENTS.md and engdocs/AGENTS.md seam files; CLAUDE.md symlinks so Claude Code loads nested files. - Bug and feature issue forms, a PR template that requires Closes #, CONTRIBUTING sections for the triage and pipeline labels, and the opt-in fork-cache during dev setup. - ROADMAP.md for 1.4: versioned beads (#6132), Graph Preview 2 (#7170), contributor onboarding (#7228). - docsync guards: root AGENTS.md at or under 20 KB; every AGENTS.md symlinked, routed, and with resolving links, paths, and guard-test names. Agent-Signature: claude-code-claude-opus-5-5-high on behalf of Julian Knutsen Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
7.9 KiB
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:
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 for consistency:
// 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:
// 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:
- Section headers (
Flags:,Examples:) - Accent color for navigation - Flag names (
--file) - Bold for scannability - Type annotations (
string) - Muted, reference info - Default values (
(default: ...)) - Muted, secondary - Descriptions - Plain, primary content
- Examples - Plain, copy-paste friendly
Visual Design System
When adding CLI output features, follow these design principles for consistent, cognitively friendly visuals.
No Emoji-Style Icons
Do not use large colored emoji icons like red/orange/yellow/blue/white circles for priorities or status. They cause cognitive overload and break visual consistency.
Use small Unicode symbols with semantic colors applied via lipgloss:
- Status:
○ ◐ ● ✓ ❄ - Priority:
P0–P4label with color (no status glyph)
Status Icons
Use these symbols consistently across all commands:
○ open - Available to work (white/default)
◐ in_progress - Currently being worked (yellow)
● blocked - Waiting on dependencies (red)
✓ closed - Completed (muted gray)
❄ deferred - Scheduled for later (blue/muted)
Priority Labels and Colors
Format priority as the P-label with color only (no status glyph — ● is blocked status):
P0: Red + bold (critical)P1: Orange (high)P2: Amber (elevated)P3–P4: Default text
Issue Type Colors
bug: Red (problems need attention)epic: Purple (larger scope)- Others: Default text
Design Principles
- Small Unicode symbols only; avoid emoji blobs.
- Semantic colors only for actionable items; do not color everything.
- Closed items fade using muted gray.
- Prefer icons over text labels for scanability.
- Keep icons consistent across list, graph, show, and related commands.
- Use tree connectors (
├──,└──,│) for hierarchies. - Reduce cognitive noise; do not show
needs:1when it is just the parent epic.
Semantic Styles
Use exported styles from internal/ui/styles.go:
// Status styles
ui.StatusInProgressStyle // Yellow - active work
ui.StatusBlockedStyle // Red - needs attention
ui.StatusClosedStyle // Muted gray - done
// Priority styles
ui.PriorityP0Style // Red + bold
ui.PriorityP1Style // Orange
// Type styles
ui.TypeBugStyle // Red
ui.TypeEpicStyle // Purple
// General styles
ui.PassStyle, ui.WarnStyle, ui.FailStyle
ui.MutedStyle, ui.AccentStyle
ui.RenderMuted(text), ui.RenderAccent(text)
Example:
switch issue.Status {
case types.StatusOpen:
icon = "○"
case types.StatusInProgress:
icon = ui.StatusInProgressStyle.Render("◐")
case types.StatusBlocked:
icon = ui.StatusBlockedStyle.Render("●")
case types.StatusClosed:
icon = ui.StatusClosedStyle.Render("✓")
}
CLI Design Principles
Minimize cognitive overload. Every new command, flag, or option adds cognitive burden for users. Before adding anything:
-
Recovery/fix operations →
bd doctor --fix: Don't create separate commands likebd recoverorbd repair. Doctor already detects problems - let--fixhandle remediation. This keeps all health-related operations in one discoverable place. For git hook marker migration specifically: usebd migrate hooks --dry-runto preview operations, andbd doctor --fixfor the standard apply path. -
Prefer flags on existing commands: Before creating a new command, ask: "Can this be a flag on an existing command?" Example:
bd list --staleinstead ofbd stale. -
Consolidate related operations: Related operations should live together. Version control uses
bd vc {log,diff,commit}, not separate top-level commands. -
Count the commands: Run
bd --helpand count. If we're approaching 30+ commands, we have a discoverability problem. Consider subcommand grouping. -
New commands need strong justification: A new command should represent a fundamentally different operation, not just a convenience wrapper.
References
- Tufte, E. (2001). The Visual Display of Quantitative Information
- Ayu Theme Colors
- Lipgloss - Terminal Styling
- WCAG Color Contrast Guidelines