🐹 Go Fan Report: Lip Gloss (v2)
Module Overview
charm.land/lipgloss/v2 is Charm's declarative library for styling terminal output — colors, borders, padding, alignment, layout joins, plus table, tree, and list sub-packages. It is the foundation of all styled CLI output in gh-aw.
Current Usage in gh-aw
- Files: 10 non-test files
- Version:
v2.0.5 — ✅ the latest release (published 2026-07-03). No upgrade needed.
- Key APIs Used:
NewStyle (44x), Color (38x), Style (8x), border helpers (Normal/Rounded/Thick/Double/HiddenBorder), LightDark, HasDarkBackground, Fprintf, JoinVertical, Center/Left
- Sub-packages:
table (console output), tree (status, mcp_inspect)
Files using lipgloss
pkg/styles/theme.go — central palette, adaptive-color system, borders, startup probepkg/styles/huh_theme.go — palette to huh forms via lipgloss.LightDarkpkg/console/console.go — table, boxes, JoinVertical, style gatingpkg/console/spinner.go, pkg/console/banner.gopkg/logger/logger.go — lipgloss.Fprintf to a colorprofile-aware stderr writerpkg/cli/status_command.go, pkg/cli/mcp_inspect.go — treepkg/cli/compile_schedule_calendar.go, pkg/cli/gateway_logs_timeline_render.go
Research Findings
- Releases: v2.0.5 (07-03), v2.0.4 (06-12), v2.0.3 (04-13), v2.0.0 (2026-02-24). v2.0.5 is a maintenance release — grapheme/emoji rendering edge-case fixes via an
ultraviolet bump. No API changes since v2.0.0.
- v2 vs v1: v2 dropped the global renderer and the standalone
AdaptiveColor/CompleteColor types. Colors are now plain color.Color; light/dark selection happens at render time via LightDark(isDark) / HasDarkBackground; color-profile downgrading moved to the separate colorprofile package.
Best Practices
gh-aw already follows the maintainer-recommended v2 idioms: color.Color-based palette, LightDark for per-render selection, a StyleFunc for table styling, and colorprofile.Writer (via pkg/colorwriter) for degradation. Nicely done. 👏
Improvement Opportunities
🏃 Quick Wins
huh_theme.go re-parses hex on every call: lipgloss.Color(hexColor...) runs on each HuhTheme(isDark) invocation and duplicates the hex parsing already in theme.go. Pre-convert the hexColor* constants to package-level color.Color values once and reference them from both files. Low impact (ThemeFunc is called rarely) — pure tidiness + drift prevention.
✨ Feature Opportunities
list sub-package: v2 ships a list package (bullet/ordered lists with custom enumerators) that could replace any hand-built bulleted output, matching the existing tree/table adoption. Only worth it where such output already exists.
📐 Best Practice Alignment
- TTY gating vs colorprofile (subtle, worth an audit):
console.applyStyleWithTTY strips styling based only on a TTY check. The recommended v2 path is to always render and let a colorprofile.Writer degrade output (already used for stderr). The manual gate does not honor NO_COLOR by itself — strings from applyStyle printed to a color TTY stay colored even when NO_COLOR is set, unless they pass through the colorprofile writer. Suggest auditing that all styled stdout paths flow through a colorprofile writer so NO_COLOR/COLORTERM/TERM are honored consistently; the manual TTY gate can then be simplified.
🔧 General Improvements
- The dual adaptive-color strategy (package-global
adaptiveColor + per-render LightDark) is intentional and documented — no change needed. A one-line cross-link comment noting both consume the same hexColor* constants would help prevent drift.
Recommendations
- (Low) Audit styled stdout paths for consistent
colorprofile.Writer usage so NO_COLOR is honored everywhere, then simplify the manual TTY gate.
- (Low) Hoist
hexColor* to color.Color conversions to package level, shared by theme.go and huh_theme.go.
- (Optional) Adopt the
list sub-package where hand-built bullet lists exist.
Next Steps
- No urgent action: usage is idiomatic and on the latest version.
- Treat the items above as small, opportunistic cleanups.
Generated by Go Fan
Module summary saved to: scratchpad/mods/lipgloss.md
Generated by 🐹 Go Fan · 127 AIC · ⌖ 13.1 AIC · ⊞ 7.3K · ◷
🐹 Go Fan Report: Lip Gloss (v2)
Module Overview
charm.land/lipgloss/v2is Charm's declarative library for styling terminal output — colors, borders, padding, alignment, layout joins, plustable,tree, andlistsub-packages. It is the foundation of all styled CLI output in gh-aw.Current Usage in gh-aw
v2.0.5— ✅ the latest release (published 2026-07-03). No upgrade needed.NewStyle(44x),Color(38x),Style(8x), border helpers (Normal/Rounded/Thick/Double/HiddenBorder),LightDark,HasDarkBackground,Fprintf,JoinVertical,Center/Lefttable(console output),tree(status,mcp_inspect)Files using lipgloss
pkg/styles/theme.go— central palette, adaptive-color system, borders, startup probepkg/styles/huh_theme.go— palette to huh forms vialipgloss.LightDarkpkg/console/console.go—table, boxes,JoinVertical, style gatingpkg/console/spinner.go,pkg/console/banner.gopkg/logger/logger.go—lipgloss.Fprintfto a colorprofile-aware stderr writerpkg/cli/status_command.go,pkg/cli/mcp_inspect.go—treepkg/cli/compile_schedule_calendar.go,pkg/cli/gateway_logs_timeline_render.goResearch Findings
ultravioletbump. No API changes since v2.0.0.AdaptiveColor/CompleteColortypes. Colors are now plaincolor.Color; light/dark selection happens at render time viaLightDark(isDark)/HasDarkBackground; color-profile downgrading moved to the separatecolorprofilepackage.Best Practices
gh-aw already follows the maintainer-recommended v2 idioms:
color.Color-based palette,LightDarkfor per-render selection, aStyleFuncfor table styling, andcolorprofile.Writer(viapkg/colorwriter) for degradation. Nicely done. 👏Improvement Opportunities
🏃 Quick Wins
huh_theme.gore-parses hex on every call:lipgloss.Color(hexColor...)runs on eachHuhTheme(isDark)invocation and duplicates the hex parsing already intheme.go. Pre-convert thehexColor*constants to package-levelcolor.Colorvalues once and reference them from both files. Low impact (ThemeFunc is called rarely) — pure tidiness + drift prevention.✨ Feature Opportunities
listsub-package: v2 ships alistpackage (bullet/ordered lists with custom enumerators) that could replace any hand-built bulleted output, matching the existingtree/tableadoption. Only worth it where such output already exists.📐 Best Practice Alignment
console.applyStyleWithTTYstrips styling based only on a TTY check. The recommended v2 path is to always render and let acolorprofile.Writerdegrade output (already used for stderr). The manual gate does not honorNO_COLORby itself — strings fromapplyStyleprinted to a color TTY stay colored even whenNO_COLORis set, unless they pass through the colorprofile writer. Suggest auditing that all styled stdout paths flow through a colorprofile writer soNO_COLOR/COLORTERM/TERMare honored consistently; the manual TTY gate can then be simplified.🔧 General Improvements
adaptiveColor+ per-renderLightDark) is intentional and documented — no change needed. A one-line cross-link comment noting both consume the samehexColor*constants would help prevent drift.Recommendations
colorprofile.Writerusage soNO_COLORis honored everywhere, then simplify the manual TTY gate.hexColor*tocolor.Colorconversions to package level, shared bytheme.goandhuh_theme.go.listsub-package where hand-built bullet lists exist.Next Steps
Generated by Go Fan
Module summary saved to: scratchpad/mods/lipgloss.md