[terminal-stylist] Console Output Analysis: Terminal Styling Patterns

[github-actions[bot]]

Overview

This report analyzes console output patterns across 879 Go source files in pkg/. The codebase has a mature, well-structured terminal styling layer built on the Charmbracelet ecosystem (Lipgloss v2 + Huh v2), with very consistent adoption.

Key Metrics

Metric	Value
Total Go source files (non-test)	879
Files using console.* formatters	150+
Direct fmt.Print* to stdout (non-console)	3
huh.NewForm(...) instances	16
Forms missing WithTheme/WithAccessible	0
Lipgloss styles used directly in pkg/cli	2 files

Architecture Summary

The codebase follows a clean three-layer styling architecture:

1. pkg/styles/theme.go — Centralized color palette (Dracula-inspired adaptive colors via compat.AdaptiveColor) and pre-configured lipgloss.Style variables.
2. pkg/console/console.go — Higher-level formatting helpers (FormatError, FormatSuccessMessage, FormatWarningMessage, RenderTable, RenderTitleBox, etc.) with TTY detection guard (applyStyle).
3. pkg/cli/ — Commands consume console.* formatters exclusively in nearly all files.

Strengths — What the codebase does well

✅ TTY-Aware Rendering

applyStyle() in pkg/console/console.go gates all Lipgloss styling behind tty.IsStdoutTerminal(). All render helpers (RenderTitleBox, RenderErrorBox, RenderInfoSection, RenderComposedSections) additionally check tty.IsStderrTerminal(), providing clean plain-text fallbacks for pipes and CI.

✅ Adaptive Colors

All colors in pkg/styles/theme.go use compat.AdaptiveColor with explicit light and dark hex variants. The Dracula palette is used for dark mode; high-contrast alternatives are provided for light terminals. lipgloss.HasDarkBackground() is called at init() time.

✅ Huh Form Consistency

All 16 huh.NewForm(...) calls in pkg/cli/ use .WithTheme(styles.HuhTheme).WithAccessible(console.IsAccessibleMode()). The custom HuhTheme in pkg/styles/huh_theme.go maps the full palette to all huh field states (focused, blurred, select options, buttons, text inputs).

✅ Centralized Table Rendering

console.RenderTable(TableConfig{...}) wraps lipgloss/table with consistent styleFunc, alternating row colors, total-row styling, and rounded borders. No ad-hoc manual table formatting was observed in pkg/cli/.

✅ Consistent Message Types

Seven named formatter functions cover all message types: FormatSuccessMessage, FormatInfoMessage, FormatWarningMessage, FormatCommandMessage, FormatProgressMessage, FormatPromptMessage, FormatVerboseMessage. These are widely used (1,435+ call sites for console.* in pkg/cli/).

✅ Error Chain Formatting

FormatErrorChain(err) recursively unwraps %w-wrapped errors and indents each level, giving Rust-like readable error output. FormatError(CompilerError) renders file:line:column with source context and ^ pointer highlighting.

Minor Observations

⚠️ Direct fmt.Print* calls (3 instances)

Only 3 calls bypass console.* formatters to write directly to stdout:

pkg/cli/logs_report.go:540     fmt.Print(console.RenderStruct(data))
pkg/cli/status_command.go:276  fmt.Print(console.RenderStruct(statuses))
pkg/cli/view_command.go:170    fmt.Print(output)

These are intentional — they use console.RenderStruct() for structured data or pass already-formatted output strings, so the usage is correct. No action needed.

i️ Lipgloss used directly in pkg/cli/compile_schedule_calendar.go

intensityStyle() builds lipgloss.NewStyle() directly for calendar heat-map rendering. This is a justified specialization (intensity levels → color gradient) not covered by the generic pkg/styles palette. The function accepts isTerminal bool and returns a plain style when not a TTY — correct pattern.

i️ Logger uses Lipgloss directly

pkg/logger/logger.go builds a colorPalette of lipgloss.Style values for debug namespace coloring. This is appropriate for debug tooling and correctly uses styles.Color* constants.

i️ Huh used directly in pkg/cli/ (outside pkg/console/)

16 huh.NewForm(...) calls exist in pkg/cli/ rather than being wrapped in pkg/console/. All apply WithTheme and WithAccessible. This is consistent and acceptable; the forms are command-specific and would be harder to generalize into console helpers.

Recommendations

Priority	Area	Recommendation
Low	pkg/console/confirm.go	Consider exposing the ConfirmAction variant with RunWithContext support for cancellation in long-running interactive flows
Low	pkg/console/	Add FormatCountMessage(n int, label string) using styles.Count to standardize "X items" output patterns
None	Huh forms	All forms correctly use WithTheme + WithAccessible — no remediation needed
None	Lipgloss direct usage	The 2 direct-use sites are justified specializations — no remediation needed
None	fmt.Print to stdout	The 3 instances are all wrapping console.RenderStruct or pre-formatted output — correct

Conclusion

The codebase demonstrates excellent adherence to Charmbracelet ecosystem best practices. The pkg/styles → pkg/console → pkg/cli layering is clean, TTY detection is applied consistently, adaptive colors are used throughout, and all interactive forms share the same theme and accessibility configuration. No critical issues were identified.

References:

• §26944468740

Generated by 💄 Terminal Stylist · sonnet46 1.2M · ◷

• expires on Jun 5, 2026, 9:59 AM UTC

[github-actions[bot]]

This discussion has been marked as outdated by Terminal Stylist.

A newer discussion is available at Discussion #37087.