Documentation
¶
Overview ¶
Package charmtheme provides a unified theming system for Charmbracelet libraries (huh, Lipgloss, Glamour). Define your theme once and reuse it across adapters while automatically adapting to light/dark terminals.
Index ¶
- func AdaptiveColor(light, dark string) lipgloss.AdaptiveColor
- func AdjustBrightness(r, g, b uint8, factor float64) (uint8, uint8, uint8)
- func AdjustSaturation(r, g, b uint8, factor float64) (uint8, uint8, uint8)
- func ApplyColorModifier(c lipgloss.AdaptiveColor, op string, amount float64) lipgloss.AdaptiveColor
- func AutoAdaptiveColor(lightHex string) lipgloss.AdaptiveColor
- func DegradeColorForProfile(color lipgloss.AdaptiveColor, profile termenv.Profile, isDark bool) string
- func PadCodeBlock(code string, pad int) string
- func PadFencedCodeBlocks(md string, pad int) string
- func ParseHex(hex string) (uint8, uint8, uint8, error)
- func ToHex(r, g, b uint8) string
- func ValidateThemeColors(t Theme) error
- type BrandColors
- type Role
- type StyleDefinition
- func (sd *StyleDefinition) UnmarshalJSON(data []byte) error
- func (sd StyleDefinition) WithBackground(ref string) StyleDefinition
- func (sd StyleDefinition) WithBold(v bool) StyleDefinition
- func (sd StyleDefinition) WithBorder(name string) StyleDefinition
- func (sd StyleDefinition) WithBorderColor(ref string) StyleDefinition
- func (sd StyleDefinition) WithForeground(ref string) StyleDefinition
- func (sd StyleDefinition) WithItalic(v bool) StyleDefinition
- func (sd StyleDefinition) WithPrefix(prefix string) StyleDefinition
- func (sd StyleDefinition) WithStrikethrough(v bool) StyleDefinition
- func (sd StyleDefinition) WithSuffix(suffix string) StyleDefinition
- func (sd StyleDefinition) WithUnderline(v bool) StyleDefinition
- type TerminalCapabilities
- type Theme
- func (t Theme) Apply(other *Theme) Theme
- func (t Theme) Color(ref string) lipgloss.AdaptiveColor
- func (t Theme) GlamourOption() glamour.TermRendererOption
- func (t Theme) GlamourOptionFor(caps TerminalCapabilities) glamour.TermRendererOption
- func (t Theme) GlamourStyleJSON() (string, error)
- func (t Theme) GlamourStyleJSONFor(caps TerminalCapabilities) (string, error)
- func (t Theme) Huh() *huh.Theme
- func (t Theme) Lipgloss(role Role) lipgloss.Style
- func (t Theme) RegisterChromaStyle(baseName string) string
- func (t Theme) Render(role Role, text ...string) string
- func (t Theme) RenderMarkdown(md string) (string, error)
- func (t Theme) RenderMarkdownWithPadding(md string, pad int) (string, error)
- func (t Theme) ResolveColor(role Role) lipgloss.AdaptiveColor
- func (t Theme) ToJSON() ([]byte, error)
- func (t Theme) WithCustomChroma() Theme
- func (t Theme) WithGlamourTemplate(tpl *template.Template) Theme
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AdaptiveColor ¶
func AdaptiveColor(light, dark string) lipgloss.AdaptiveColor
AdaptiveColor constructs a lipgloss.AdaptiveColor from the given light/dark hex strings. Light should be tuned for light backgrounds, dark for dark backgrounds.
func AdjustBrightness ¶
AdjustBrightness applies a multiplier to the HSL lightness component of the supplied RGB color. Values >1 increase brightness, <1 decrease brightness.
func AdjustSaturation ¶
AdjustSaturation scales the HSL saturation component by the provided factor. Values >1 intensify the color, <1 desaturate it.
func ApplyColorModifier ¶ added in v0.2.1
func ApplyColorModifier(c lipgloss.AdaptiveColor, op string, amount float64) lipgloss.AdaptiveColor
ApplyColorModifier applies a CSS-like transformation (lighten, darken, saturate, desaturate) to both variants of the adaptive color. amount is typically between 0.0 and 1.0 (e.g. 0.1 for 10%).
func AutoAdaptiveColor ¶
func AutoAdaptiveColor(lightHex string) lipgloss.AdaptiveColor
AutoAdaptiveColor derives a dark-variant color from the provided light variant. The light hex is used as provided, while the dark variant goes through a brightness/saturation adjustment to keep contrast on dark terminals. If parsing the light color fails, the returned color uses the same value for both variants.
func DegradeColorForProfile ¶
func DegradeColorForProfile(color lipgloss.AdaptiveColor, profile termenv.Profile, isDark bool) string
DegradeColorForProfile converts an adaptive color into a format suitable for the provided terminal profile. Colors automatically degrade for limited palettes while respecting adaptive light/dark variants.
func PadCodeBlock ¶ added in v0.2.1
PadCodeBlock right-pads every line to the longest line and adds a solid background border of the given thickness. This helps code blocks render as a uniform rectangle when used with background-preserving Chroma formatters.
The returned string preserves original newlines; callers can wrap it in a Markdown fenced block or feed it directly to a Glamour renderer.
func PadFencedCodeBlocks ¶ added in v0.2.1
PadFencedCodeBlocks applies PadCodeBlock to every fenced code block in the markdown string, preserving language tags and fences.
func ParseHex ¶
ParseHex parses strings in the form "#RRGGBB", "#RGB", "#RRGGBBAA", or "#RGBA" (leading # optional) into RGB components. Alpha values, when provided, are ignored for now. It returns errInvalidHex for malformed inputs.
func ValidateThemeColors ¶ added in v0.2.1
ValidateThemeColors ensures all color values are valid hex strings (3/4/6/8 digits).
Types ¶
type BrandColors ¶ added in v0.2.0
BrandColors represents a minimal brand palette used to derive a Theme. Empty fields are treated as "keep defaults" so callers can override only the colors they care about.
type Role ¶
type Role string
Role represents a semantic UI element that needs consistent theming across libraries.
const ( RoleHeading Role = "heading" RoleSubheading Role = "subheading" RoleBody Role = "body" RoleCode Role = "code" RoleEmphasis Role = "emphasis" RoleStrong Role = "strong" RoleError Role = "error" RoleSuccess Role = "success" RoleWarning Role = "warning" RoleInfo Role = "info" RoleFieldLabel Role = "field_label" RoleFieldValue Role = "field_value" RoleFieldDescription Role = "field_description" RoleButton Role = "button" RoleButtonActive Role = "button_active" RoleBorder Role = "border" RoleSelection Role = "selection" RoleCommandName Role = "command_name" RoleCommandShort Role = "command_short" RoleFlagName Role = "flag_name" RoleFlagShort Role = "flag_short" RoleTableHeader Role = "table_header" RoleTableCell Role = "table_cell" )
type StyleDefinition ¶ added in v0.2.1
type StyleDefinition struct {
Inherit string `json:"inherit,omitempty"`
Foreground string `json:"foreground,omitempty"`
Background string `json:"background,omitempty"`
Bold bool `json:"bold,omitempty"`
Italic bool `json:"italic,omitempty"`
Underline bool `json:"underline,omitempty"`
Strikethrough bool `json:"strikethrough,omitempty"`
Padding []int `json:"padding,omitempty"`
Margin []int `json:"margin,omitempty"`
Prefix string `json:"prefix,omitempty"`
Suffix string `json:"suffix,omitempty"`
Border string `json:"border,omitempty"`
BorderColor string `json:"border_color,omitempty"`
// contains filtered or unexported fields
}
StyleDefinition describes a serializable styling rule that can be shared across adapters. All fields are optional and may inherit from a parent style via the Inherit field.
func (*StyleDefinition) UnmarshalJSON ¶ added in v0.2.1
func (sd *StyleDefinition) UnmarshalJSON(data []byte) error
func (StyleDefinition) WithBackground ¶ added in v0.2.1
func (sd StyleDefinition) WithBackground(ref string) StyleDefinition
WithBackground marks the Background field as explicitly set.
func (StyleDefinition) WithBold ¶ added in v0.2.1
func (sd StyleDefinition) WithBold(v bool) StyleDefinition
WithBold marks the Bold flag as explicitly set.
func (StyleDefinition) WithBorder ¶ added in v0.2.1
func (sd StyleDefinition) WithBorder(name string) StyleDefinition
WithBorder marks the Border field as explicitly set.
func (StyleDefinition) WithBorderColor ¶ added in v0.2.1
func (sd StyleDefinition) WithBorderColor(ref string) StyleDefinition
WithBorderColor marks the BorderColor field as explicitly set.
func (StyleDefinition) WithForeground ¶ added in v0.2.1
func (sd StyleDefinition) WithForeground(ref string) StyleDefinition
WithForeground marks the Foreground field as explicitly set.
func (StyleDefinition) WithItalic ¶ added in v0.2.1
func (sd StyleDefinition) WithItalic(v bool) StyleDefinition
WithItalic marks the Italic flag as explicitly set.
func (StyleDefinition) WithPrefix ¶ added in v0.2.1
func (sd StyleDefinition) WithPrefix(prefix string) StyleDefinition
WithPrefix marks the Prefix field as explicitly set.
func (StyleDefinition) WithStrikethrough ¶ added in v0.2.1
func (sd StyleDefinition) WithStrikethrough(v bool) StyleDefinition
WithStrikethrough marks the Strikethrough flag as explicitly set.
func (StyleDefinition) WithSuffix ¶ added in v0.2.1
func (sd StyleDefinition) WithSuffix(suffix string) StyleDefinition
WithSuffix marks the Suffix field as explicitly set.
func (StyleDefinition) WithUnderline ¶ added in v0.2.1
func (sd StyleDefinition) WithUnderline(v bool) StyleDefinition
WithUnderline marks the Underline flag as explicitly set.
type TerminalCapabilities ¶
TerminalCapabilities describes the color capabilities of the terminal.
func DetectTerminalCapabilities ¶
func DetectTerminalCapabilities() TerminalCapabilities
DetectTerminalCapabilities inspects stdout to determine terminal support.
type Theme ¶
type Theme struct {
Colors map[string]lipgloss.AdaptiveColor `json:"colors" yaml:"colors"`
Styles map[string]StyleDefinition `json:"styles" yaml:"styles"`
// ChromaStyle stores the registered Chroma theme used for Glamour code
// blocks. It remains serialized so users can persist explicit overrides.
ChromaStyle string `json:"chroma_style,omitempty" yaml:"chroma_style,omitempty"`
// contains filtered or unexported fields
}
Theme is a data-driven representation of a charm-theme palette. Colors hold the adaptive palette, while Styles map semantic roles (and markdown-specific keys like "h1") to StyleDefinitions. Themes can be loaded from JSON/YAML or built programmatically.
func DefaultTheme ¶
func DefaultTheme() Theme
DefaultTheme returns the opinionated default palette and style sheet.
func FromBrandColors ¶ added in v0.2.0
func FromBrandColors(b BrandColors) Theme
FromBrandColors generates a Theme from up to three brand colors. It starts from DefaultTheme to inherit typography, layout, and semantic defaults, then selectively overrides the core palette. Invalid hex inputs are ignored.
func MinimalTheme ¶
func MinimalTheme() Theme
MinimalTheme returns a conservative theme tuned for basic terminals.
func UnmarshalTheme ¶ added in v0.2.1
UnmarshalTheme parses raw JSON data into a Theme.
func (Theme) Apply ¶ added in v0.2.1
Apply returns a new Theme where values from other override the receiver. Colors are replaced per-key; styles are deep-merged using StyleDefinition semantics so overrides can tweak a single field without redefining the whole style.
func (Theme) Color ¶ added in v0.2.1
func (t Theme) Color(ref string) lipgloss.AdaptiveColor
Color resolves a color reference. It supports: 1. Direct Hex: "#FFFFFF" 2. Variable Lookup: "$primary" 3. Modifiers: "$primary | darken 0.2"
func (Theme) GlamourOption ¶
func (t Theme) GlamourOption() glamour.TermRendererOption
GlamourOption returns a Glamour renderer option that applies this theme using the detected terminal capabilities.
func (Theme) GlamourOptionFor ¶ added in v0.2.1
func (t Theme) GlamourOptionFor(caps TerminalCapabilities) glamour.TermRendererOption
GlamourOptionFor returns a Glamour renderer option that applies this theme for the provided terminal capabilities.
func (Theme) GlamourStyleJSON ¶
GlamourStyleJSON returns a Glamour JSON style config derived from Theme for the current terminal (light/dark, color depth, etc.).
func (Theme) GlamourStyleJSONFor ¶ added in v0.2.1
func (t Theme) GlamourStyleJSONFor(caps TerminalCapabilities) (string, error)
GlamourStyleJSONFor returns a Glamour JSON style config derived from Theme for the provided terminal capabilities. This is useful for server-side rendering scenarios where the desired background mode is known (e.g., a web preview toggling light/dark) and may differ from the host terminal.
func (Theme) Lipgloss ¶
Lipgloss returns a lipgloss.Style configured for the requested role. Use this when you need to compose styles or use them in Bubble Tea models. Note: This returns the visual style (colors, bold, border) but does NOT include the Prefix or Suffix defined in the theme, as those are content decorations.
func (Theme) RegisterChromaStyle ¶ added in v0.2.1
RegisterChromaStyle generates and registers a Chroma style derived from the theme's adaptive palette. It returns the registered style name which can be assigned to Theme.ChromaStyle.
func (Theme) Render ¶ added in v0.2.1
Render applies the theme's style, prefix, and suffix to the provided text. Use this for one-off printing where you want the full "Themed" look, including decorations like "> " or "Error: ".
func (Theme) RenderMarkdown ¶ added in v0.2.1
RenderMarkdown renders markdown using the theme's Glamour option, first padding fenced code blocks so their background fills align neatly. Padding defaults to 1.
func (Theme) RenderMarkdownWithPadding ¶ added in v0.2.1
RenderMarkdownWithPadding renders markdown after padding all fenced code blocks with the supplied pad thickness.
func (Theme) ResolveColor ¶
func (t Theme) ResolveColor(role Role) lipgloss.AdaptiveColor
ResolveColor now delegates to the StyleDefinition assigned to the role. If no style or color is found it falls back to the body text color.
func (Theme) ToJSON ¶ added in v0.2.1
ToJSON marshals the theme to indented JSON for exporting/sharing.
func (Theme) WithCustomChroma ¶ added in v0.2.1
WithCustomChroma returns a copy of the theme that registers and applies a Chroma style derived from its current palette.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
theme-editor
command
|
|
|
examples
|
|
|
basic
command
|
|
|
brand-colors
command
|
|
|
custom-theme
command
|
|
|
debug-blocks
command
|
|
|
green-screen
command
|
|
|
json-override
command
|
|
|
kitchen-sink
command
|