theme

package
v1.202.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Dec 21, 2025 License: Apache-2.0 Imports: 20 Imported by: 0

README

Terminal Themes Package

This package provides terminal theme support for Atmos markdown rendering.

Attribution

The themes.json file contains terminal color themes sourced from:

Each individual theme in the collection maintains its original creator's attribution in the meta.credits field. See LICENSE-THEMES for full attribution details.

Files

  • theme.go - Core theme structures and management
  • registry.go - Theme registry for loading and accessing themes
  • converter.go - Converts terminal themes to glamour styles
  • themes.json - Embedded JSON file with 349 terminal themes
  • LICENSE-THEMES - Full attribution and license information

Usage

// Load a theme by name
registry, err := theme.NewRegistry()
if err != nil {
    return err
}

// Get a specific theme
dracula, exists := registry.Get("dracula")

// Convert to glamour style
style, err := theme.ConvertToGlamourStyle(dracula)

Adding New Themes

New themes can be added to themes.json. Each theme should include:

  • Standard terminal colors (black, red, green, yellow, blue, magenta, cyan, white, and bright variants)
  • Background and foreground colors
  • Metadata including isDark flag and credits

The "default" theme is the first entry and is optimized for Atmos output.

Documentation

Index

Constants

View Source
const (
	// Base colors - DEPRECATED: Use theme.GetCurrentStyles() instead.
	ColorGray         = "#808080" // Deprecated: Use styles.Muted
	ColorGreen        = "#00FF00" // Deprecated: Use styles.Success or GetSuccessColor()
	ColorCyan         = "#00FFFF" // Deprecated: Use styles.Info
	ColorPink         = "#FF69B4" // Deprecated: Use styles.Secondary
	ColorBlue         = "#5F5FFF" // Deprecated: Use styles.Primary or GetPrimaryColor()
	ColorDarkGray     = "#626262" // Deprecated: Use styles.Muted
	ColorRed          = "#FF0000" // Deprecated: Use styles.Error or GetErrorColor()
	ColorYellow       = "#FFFF00" // Deprecated: Use styles.Warning
	ColorOrange       = "#FFA500" // Deprecated: Use styles.Warning
	ColorCheckmark    = "#00D700" // Deprecated: Use styles.Success
	ColorWhite        = "#FFFFFF" // Deprecated: Use styles.Body
	ColorBrightYellow = "#FFFF00" // Deprecated: Use theme-aware colors
	ColorGold         = "#FFD700" // Deprecated: Use theme-aware colors

	ColorSelectedItem = "#10ff10" // Deprecated: Use styles.Selected
	ColorBorder       = "#5F5FD7" // Deprecated: Use GetBorderColor()
)

Legacy color constants - DEPRECATED. These hard-coded colors are no longer recommended for use in new code. Instead, use the theme-aware system via GetCurrentStyles() which automatically adapts colors based on the user's configured theme.

Migration guide:

  • Replace ColorGreen with styles.Success (or GetSuccessColor())
  • Replace ColorRed with styles.Error (or GetErrorColor())
  • Replace ColorCyan with styles.Info
  • Replace ColorBlue with styles.Primary (or GetPrimaryColor())
  • Replace ColorBorder with GetBorderColor()

Example:

// Old (deprecated):
style := lipgloss.NewStyle().Foreground(lipgloss.Color(ColorGreen))

// New (theme-aware):
styles := theme.GetCurrentStyles()
style := styles.Success
View Source
const (
	// Status indicators.
	IconActive      = "●" // Active/selected item indicator.
	IconRecommended = "★" // Recommended item indicator.
	IconCheckmark   = "✓" // Success/completion indicator.
	IconXMark       = "✗" // Error/failure indicator.
	IconWarning     = "⚠" // Warning indicator.
	IconInfo        = "ℹ" // Information indicator.
	IconColorBlock  = "█" // Color palette block character.
)

Icon constants for terminal UI elements. These UTF-8 symbols are used throughout the theme system for consistent visual representation.

Variables

View Source
var Colors = struct {
	Error   *color.Color
	Info    *color.Color
	Success *color.Color
	Warning *color.Color
	Default *color.Color
}{
	Error:   color.New(color.FgRed),
	Info:    color.New(color.FgCyan),
	Success: color.New(color.FgGreen),
	Warning: color.New(color.FgYellow),
	Default: color.New(color.Reset),
}

Colors - DEPRECATED: Use theme.GetCurrentStyles() instead. This global variable provides legacy fatih/color styling which doesn't support theme switching. New code should call GetCurrentStyles() to get theme-aware lipgloss styles.

Example migration:

// Old (deprecated):
Colors.Success.Println("Operation complete")

// New (theme-aware):
styles := theme.GetCurrentStyles()
fmt.Println(styles.Success.Render("Operation complete"))
View Source
var ErrInvalidTheme = errors.New("invalid theme")

ErrInvalidTheme is returned when an invalid theme is specified.

View Source
var ErrThemeNotFound = errors.New("theme not found")

ErrThemeNotFound is returned when a requested theme is not found.

View Source
var RecommendedThemes = []string{
	"atmos",
	"Dracula",
	"Catppuccin Mocha",
	"Catppuccin Latte",
	"Tokyo Night",
	"Nord",
	"Gruvbox Dark",
	"Gruvbox Light",
	"GitHub Dark",
	"GitHub Light",
	"One Dark",
	"Solarized Dark",
	"Solarized Light",
	"Material",
}

RecommendedThemes is a curated list of themes that work well with Atmos.

View Source
var Styles = createLegacyStyles()

Styles - DEPRECATED: Use theme.GetCurrentStyles() instead. This global variable uses hard-coded colors that don't respond to theme changes. New code should call GetCurrentStyles() to get theme-aware styles.

Example migration:

// Old (deprecated):
fmt.Print(Styles.Checkmark.String())

// New (theme-aware):
styles := theme.GetCurrentStyles()
fmt.Print(styles.Success.Render(theme.IconCheckmark))

Functions

func ConvertToGlamourStyle added in v1.198.0

func ConvertToGlamourStyle(t *Theme) ([]byte, error)

ConvertToGlamourStyle converts a terminal theme to a glamour style configuration.

func CreateBorderedTable added in v1.198.0

func CreateBorderedTable(headers []string, rows [][]string) string

CreateBorderedTable creates a table with full borders.

func CreateMinimalTable added in v1.198.0

func CreateMinimalTable(headers []string, rows [][]string) string

CreateMinimalTable creates a table with minimal styling (header separator only).

func CreatePlainTable added in v1.198.0

func CreatePlainTable(headers []string, rows [][]string) string

CreatePlainTable creates a table with no borders or separators.

func CreateTable added in v1.198.0

func CreateTable(config *TableConfig, headers []string, rows [][]string) string

CreateTable creates a styled table based on the configuration.

func CreateThemedTable added in v1.198.0

func CreateThemedTable(headers []string, rows [][]string) string

CreateThemedTable creates a table with theme-aware styling for the list themes command.

func FormatColorPalette added in v1.198.0

func FormatColorPalette(t *Theme) string

FormatColorPalette displays the theme's color palette.

func GenerateLogDemo added in v1.198.0

func GenerateLogDemo(scheme *ColorScheme) string

GenerateLogDemo creates a demonstration of log output with styled levels and key-value pairs.

func GetBorderColor added in v1.198.0

func GetBorderColor() string

GetBorderColor returns the border color from the current theme.

func GetContrastColor added in v1.198.0

func GetContrastColor(hexColor string) string

GetContrastColor returns white or black depending on the background color.

func GetDebugStyle added in v1.198.0

func GetDebugStyle() lipgloss.Style

GetDebugStyle returns the debug style from the current theme.

func GetErrorColor added in v1.198.0

func GetErrorColor() string

GetErrorColor returns the error color from the current theme.

func GetErrorStyle added in v1.198.0

func GetErrorStyle() lipgloss.Style

GetErrorStyle returns the error style from the current theme.

func GetGlamourStyleForTheme added in v1.198.0

func GetGlamourStyleForTheme(themeName string) ([]byte, error)

GetGlamourStyleForTheme returns a glamour style for a theme by name.

func GetInfoStyle added in v1.198.0

func GetInfoStyle() lipgloss.Style

GetInfoStyle returns the info style from the current theme.

func GetLogStyles added in v1.198.0

func GetLogStyles(scheme *ColorScheme) *log.Styles

GetLogStyles returns charm/log styles configured with the current theme colors. This includes background colors for log level badges and key-value pair styling.

func GetLogStylesNoColor added in v1.198.0

func GetLogStylesNoColor() *log.Styles

GetLogStylesNoColor returns charm/log styles with no colors for --no-color mode.

func GetNoticeStyle added in v1.199.0

func GetNoticeStyle() lipgloss.Style

GetNoticeStyle returns the notice style from the current theme. Notice style is used for neutral informational messages, typically in empty states.

func GetPrimaryColor added in v1.198.0

func GetPrimaryColor() string

GetPrimaryColor returns the primary color from the current theme.

func GetSuccessColor added in v1.198.0

func GetSuccessColor() string

GetSuccessColor returns the success color from the current theme.

func GetSuccessStyle added in v1.198.0

func GetSuccessStyle() lipgloss.Style

GetSuccessStyle returns the success style from the current theme.

func GetTraceStyle added in v1.198.0

func GetTraceStyle() lipgloss.Style

GetTraceStyle returns the trace style from the current theme.

func GetWarningStyle added in v1.198.0

func GetWarningStyle() lipgloss.Style

GetWarningStyle returns the warning style from the current theme.

func InitializeStyles added in v1.198.0

func InitializeStyles(scheme *ColorScheme)

InitializeStyles initializes the styles with a specific color scheme. Note: Does not clear currentThemeName to retain manually-passed scheme.

func InitializeStylesFromTheme added in v1.198.0

func InitializeStylesFromTheme(themeName string) error

InitializeStylesFromTheme initializes the global CurrentStyles from the specified theme name. The themeName parameter specifies which color scheme to load (e.g., "atmos", "dracula"). Returns an error if the theme cannot be found or loaded.

func InvalidateStyleCache added in v1.200.0

func InvalidateStyleCache()

InvalidateStyleCache clears the cached styles, forcing them to be regenerated. This is needed when the terminal color profile changes (e.g., NO_COLOR is set) because lipgloss styles bake in ANSI codes at creation time.

Note: This also regenerates the deprecated theme.Styles global variable to ensure backward compatibility with code still using the legacy API.

func IsRecommended added in v1.198.0

func IsRecommended(themeName string) bool

IsRecommended checks if a theme is in the recommended list.

func SortThemes added in v1.198.0

func SortThemes(themes []*Theme)

SortThemes sorts themes alphabetically by name.

func ValidateTheme added in v1.198.0

func ValidateTheme(themeName string) error

ValidateTheme checks if a theme name is valid. Returns nil if the theme is valid or empty (will use default). Returns an error with available themes if the theme is invalid.

Types

type ColorScheme added in v1.198.0

type ColorScheme struct {
	// Core semantic colors
	Primary   string // Main brand/action color (typically cyan or blue)
	Secondary string // Supporting actions (typically magenta)
	Success   string // Success states (typically green)
	Warning   string // Warning states (typically yellow)
	Error     string // Error states (typically red)

	// Text colors
	TextPrimary   string // Main text (typically white/brightWhite)
	TextSecondary string // Subtle/secondary text (typically brightBlack)
	TextMuted     string // Disabled/muted text (typically black)
	TextInverse   string // Text on dark backgrounds
	TextLight     string // Light theme indicator (white)

	// UI elements
	Border         string // Borders and dividers (typically blue or brightBlack)
	Background     string // Background colors
	BackgroundDark string // Dark background for status bars
	Surface        string // Card/panel backgrounds

	// Semantic elements
	Link      string // Links (typically cyan)
	Selected  string // Selected items (typically brightGreen)
	Highlight string // Highlighted text (typically magenta)
	Gold      string // Special indicators (typically yellow or brightYellow)
	Spinner   string // Loading/progress indicators (typically cyan)

	// Table specific
	HeaderText string // Table header text (typically brightCyan or green)
	RowText    string // Table row text (typically white)
	RowAlt     string // Alternating row background

	// Help/Documentation specific
	BackgroundHighlight string // Background for highlighted sections (usage/example blocks)

	// Interactive prompts (Huh library)
	ButtonForeground string // Button text color (light/cream)
	ButtonBackground string // Button background color (primary/purple)

	// Syntax highlighting
	ChromaTheme string // Chroma theme name for syntax highlighting

	// Log level colors (backgrounds)
	LogDebug   string // Debug log level background
	LogInfo    string // Info log level background
	LogWarning string // Warning log level background
	LogError   string // Error log level background
}

ColorScheme defines semantic color mappings for UI elements. These are derived from a Theme's ANSI colors.

func GenerateColorScheme added in v1.198.0

func GenerateColorScheme(t *Theme) ColorScheme

GenerateColorScheme creates a semantic color scheme from a Theme. This maps the 16 ANSI colors to semantic UI purposes.

func GetColorSchemeForTheme added in v1.198.0

func GetColorSchemeForTheme(themeName string) (*ColorScheme, error)

GetColorSchemeForTheme loads a theme by name and generates its color scheme.

type Credit added in v1.198.0

type Credit struct {
	Name string `json:"name"`
	Link string `json:"link"`
}

Credit represents theme author information.

type HelpStyle added in v1.152.0

type HelpStyle struct {
	Headings      *color.Color
	Commands      *color.Color
	Example       *color.Color
	ExecName      *color.Color
	Flags         *color.Color
	CmdShortDescr *color.Color
	FlagsDescr    *color.Color
	FlagsDataType *color.Color
	Aliases       *color.Color
}

HelpStyle - DEPRECATED: Use theme.GetCurrentStyles() instead. This struct provides legacy color.Color styling which doesn't support theme switching.

type ListThemesOptions added in v1.198.0

type ListThemesOptions struct {
	RecommendedOnly bool
	ActiveTheme     string
}

ListThemesOptions configures which themes to display and how to mark them. RecommendedOnly filters the list to show only recommended themes (marked with star indicator). ActiveTheme specifies the currently active theme name to be highlighted with an active indicator.

type ListThemesResult added in v1.198.0

type ListThemesResult struct {
	Output          string
	Error           error
	ThemeCount      int
	ActiveTheme     string
	ShowStars       bool
	RecommendedOnly bool
}

ListThemesResult represents the formatted output returned when listing themes. It includes the rendered output string, any error encountered, the total count of themes displayed, the name of the currently active theme, whether star indicators are shown for recommended themes, and whether the output is filtered to show only recommended themes.

func ListThemes added in v1.198.0

func ListThemes(opts ListThemesOptions) ListThemesResult

ListThemes generates a formatted list of available themes.

type Meta added in v1.198.0

type Meta struct {
	IsDark  bool      `json:"isDark"`
	Credits *[]Credit `json:"credits,omitempty"`
}

Meta holds theme metadata including whether the theme is designed for dark mode and optional credit information for the theme's creators or sources.

type Registry added in v1.198.0

type Registry struct {
	// contains filtered or unexported fields
}

Registry manages the collection of available themes.

func NewRegistry added in v1.198.0

func NewRegistry() (*Registry, error)

NewRegistry creates a new theme registry and loads all themes.

func (*Registry) Count added in v1.198.0

func (r *Registry) Count() int

Count returns the total number of themes in the registry.

func (*Registry) CountRecommended added in v1.198.0

func (r *Registry) CountRecommended() int

CountRecommended returns the number of recommended themes.

func (*Registry) Get added in v1.198.0

func (r *Registry) Get(name string) (*Theme, bool)

Get returns a theme by name (case-insensitive).

func (*Registry) GetOrDefault added in v1.198.0

func (r *Registry) GetOrDefault(name string) *Theme

GetOrDefault returns a theme by name, falling back to default if not found.

func (*Registry) List added in v1.198.0

func (r *Registry) List() []*Theme

List returns all themes sorted alphabetically.

func (*Registry) ListRecommended added in v1.198.0

func (r *Registry) ListRecommended() []*Theme

ListRecommended returns only the recommended themes.

func (*Registry) Search added in v1.198.0

func (r *Registry) Search(query string) []*Theme

Search returns themes matching the given query (case-insensitive partial match).

type ShowThemeOptions added in v1.198.0

type ShowThemeOptions struct {
	ThemeName string
}

ShowThemeOptions contains options for showing theme details.

type ShowThemeResult added in v1.198.0

type ShowThemeResult struct {
	Output string
	Error  error
}

ShowThemeResult contains the formatted output for a theme.

func ShowTheme added in v1.198.0

func ShowTheme(opts ShowThemeOptions) ShowThemeResult

ShowTheme generates a detailed preview of a theme including color palette, sample UI elements, markdown preview, and log output preview.

type StyleSet added in v1.198.0

type StyleSet struct {
	// Text styles
	Title   lipgloss.Style
	Heading lipgloss.Style
	Body    lipgloss.Style
	Muted   lipgloss.Style

	// Status styles
	Success lipgloss.Style
	Warning lipgloss.Style
	Error   lipgloss.Style
	Info    lipgloss.Style
	Notice  lipgloss.Style
	Debug   lipgloss.Style
	Trace   lipgloss.Style

	// UI element styles
	Selected    lipgloss.Style
	Link        lipgloss.Style
	Command     lipgloss.Style
	Description lipgloss.Style
	Label       lipgloss.Style // Section labels/headers (non-status)
	Spinner     lipgloss.Style // Loading/progress indicators

	// Table styles
	TableHeader    lipgloss.Style
	TableRow       lipgloss.Style
	TableActive    lipgloss.Style
	TableBorder    lipgloss.Style
	TableSpecial   lipgloss.Style // For special indicators like stars
	TableDarkType  lipgloss.Style // For "Dark" theme type
	TableLightType lipgloss.Style // For "Light" theme type

	// Special elements
	Checkmark lipgloss.Style
	XMark     lipgloss.Style
	Footer    lipgloss.Style
	Border    lipgloss.Style

	// Version styles
	VersionNumber lipgloss.Style
	NewVersion    lipgloss.Style
	PackageName   lipgloss.Style

	// Pager styles
	Pager struct {
		StatusBar        lipgloss.Style
		StatusBarHelp    lipgloss.Style
		StatusBarMessage lipgloss.Style
		ErrorMessage     lipgloss.Style
		Highlight        lipgloss.Style
		HelpView         lipgloss.Style
	}

	// TUI component styles
	TUI struct {
		ItemStyle         lipgloss.Style
		SelectedItemStyle lipgloss.Style
		BorderFocused     lipgloss.Style
		BorderUnfocused   lipgloss.Style
	}

	// Interactive prompt styles for the Huh library's buttons and UI elements.
	Interactive struct {
		ButtonForeground lipgloss.Style // Button text style
		ButtonBackground lipgloss.Style // Button background style
	}

	// Diff/Output styles
	Diff struct {
		Added   lipgloss.Style
		Removed lipgloss.Style
		Changed lipgloss.Style
		Header  lipgloss.Style
	}

	// Help/Documentation styles
	Help struct {
		Heading      lipgloss.Style // Section headings (uppercase)
		CommandName  lipgloss.Style // Command names in lists
		CommandDesc  lipgloss.Style // Command descriptions
		FlagName     lipgloss.Style // Flag names
		FlagDesc     lipgloss.Style // Flag descriptions
		FlagDataType lipgloss.Style // Flag data types
		UsageBlock   lipgloss.Style // Styled box for usage examples
		ExampleBlock lipgloss.Style // Styled box for code examples
		Code         lipgloss.Style // Inline code elements
	}
}

StyleSet provides pre-configured lipgloss styles for common UI elements.

var CurrentStyles *StyleSet

CurrentStyles holds the active styles for the application.

func GetCurrentStyles added in v1.198.0

func GetCurrentStyles() *StyleSet

GetCurrentStyles returns the current active styles based on the configured theme. It loads the theme from configuration or environment variable.

func GetStyles added in v1.198.0

func GetStyles(scheme *ColorScheme) *StyleSet

GetStyles generates styles from a color scheme.

type StylesStruct added in v1.200.0

type StylesStruct struct {
	VersionNumber lipgloss.Style
	NewVersion    lipgloss.Style
	Link          lipgloss.Style
	PackageName   lipgloss.Style
	Checkmark     lipgloss.Style
	XMark         lipgloss.Style
	GrayText      lipgloss.Style
	SelectedItem  lipgloss.Style
	CommandName   lipgloss.Style
	Description   lipgloss.Style
	Border        lipgloss.Style
	Help          HelpStyle
}

StylesStruct defines the structure for legacy deprecated styles.

type TableConfig added in v1.198.0

type TableConfig struct {
	Style       TableStyle      // The table style to use
	ShowBorders bool            // Override for borders (when true, forces borders regardless of Style)
	ShowHeader  bool            // Show header separator (default true for Minimal)
	BorderStyle lipgloss.Border // Border style when borders are shown
	Styles      *StyleSet       // Reference to theme styles
	StyleFunc   table.StyleFunc // Optional custom style function
}

TableConfig defines the configuration for table rendering.

func DefaultTableConfig added in v1.198.0

func DefaultTableConfig() TableConfig

DefaultTableConfig returns a default table configuration with minimal style.

type TableStyle added in v1.198.0

type TableStyle int

TableStyle represents the different table design styles used for rendering tables in the terminal. Supported styles include bordered (full borders), minimal (header separator only), and plain (no borders).

const (
	// TableStyleBordered shows full borders around and within the table.
	TableStyleBordered TableStyle = iota
	// TableStyleMinimal shows no borders except header separator.
	TableStyleMinimal
	// TableStylePlain shows no borders at all.
	TableStylePlain
)

type Theme added in v1.198.0

type Theme struct {
	Name          string `json:"name"`
	Black         string `json:"black"`
	Red           string `json:"red"`
	Green         string `json:"green"`
	Yellow        string `json:"yellow"`
	Blue          string `json:"blue"`
	Magenta       string `json:"magenta"`
	Cyan          string `json:"cyan"`
	White         string `json:"white"`
	BrightBlack   string `json:"brightBlack"`
	BrightRed     string `json:"brightRed"`
	BrightGreen   string `json:"brightGreen"`
	BrightYellow  string `json:"brightYellow"`
	BrightBlue    string `json:"brightBlue"`
	BrightMagenta string `json:"brightMagenta"`
	BrightCyan    string `json:"brightCyan"`
	BrightWhite   string `json:"brightWhite"`
	Background    string `json:"background"`
	Foreground    string `json:"foreground"`
	Cursor        string `json:"cursor"`
	Selection     string `json:"selection"`
	Meta          Meta   `json:"meta"`
}

Theme represents a terminal color theme.

func FilterRecommended added in v1.198.0

func FilterRecommended(themes []*Theme) []*Theme

FilterRecommended returns only recommended themes from the given list.

func FindTheme added in v1.198.0

func FindTheme(themes []*Theme, name string) (*Theme, bool)

FindTheme searches for a theme by name (case-insensitive).

func LoadThemes added in v1.198.0

func LoadThemes() ([]*Theme, error)

LoadThemes loads all themes from the embedded JSON file.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL