Documentation
¶
Overview ¶
Package colour provides public types and utilities for working with color palettes.
Package colour provides public types and utilities for working with color palettes.
Package colour provides public types and utilities for working with color palettes.
Package colour provides public types and utilities for working with color palettes.
Package colour provides public types and utilities for working with color palettes. This package is designed for use by external plugins that need to access and format categorized color data from tinct.
Index ¶
- func ANSIColorInfo(colorName string) (name string, r, g, b uint8, isBright, found bool)
- func GetANSIColorNames() []string
- type ANSIColor
- type ANSIColors
- type CategorisedColour
- type CategorisedPalette
- type ColorFormat
- type ColorValue
- func (cv ColorValue) A() uint8
- func (cv ColorValue) AlphaFloat() float64
- func (cv ColorValue) B() uint8
- func (cv ColorValue) Format(format ColorFormat) string
- func (cv ColorValue) G() uint8
- func (cv ColorValue) Hex() string
- func (cv ColorValue) HexAlpha() string
- func (cv ColorValue) HexNoHash() string
- func (cv ColorValue) Index() int
- func (cv ColorValue) R() uint8
- func (cv ColorValue) RGB() string
- func (cv ColorValue) RGBA() string
- func (cv ColorValue) RGBDecimal() string
- func (cv ColorValue) Role() Role
- func (cv ColorValue) WithAlpha(alpha float64) ColorValue
- type PaletteHelper
- func (ph *PaletteHelper) AllColors() []ColorValue
- func (ph *PaletteHelper) AllRoles() []Role
- func (ph *PaletteHelper) Count() int
- func (ph *PaletteHelper) FindClosestANSIColor(colorName string) (ColorValue, bool)
- func (ph *PaletteHelper) Get(role Role) ColorValue
- func (ph *PaletteHelper) GetByIndex(index int) (ColorValue, bool)
- func (ph *PaletteHelper) GetSafe(role Role) (ColorValue, bool)
- func (ph *PaletteHelper) GetWithFallback(role Role, fallbackHex string) ColorValue
- func (ph *PaletteHelper) Has(role Role) bool
- func (ph *PaletteHelper) ThemeType() ThemeType
- func (ph *PaletteHelper) ThemeTypeString() string
- type RGB
- type RGBA
- type Role
- type ThemeData
- type ThemeType
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ANSIColorInfo ¶
ANSIColorInfo returns information about an ANSI color name. Returns the canonical name, RGB values, and whether it's a bright variant.
func GetANSIColorNames ¶
func GetANSIColorNames() []string
GetANSIColorNames returns all supported ANSI color names. Useful for documentation and autocomplete.
Types ¶
type ANSIColor ¶
ANSIColor represents a standard ANSI terminal color name and its typical RGB value.
type ANSIColors ¶
type ANSIColors struct {
// Standard colors (0-7).
Black RGBA `json:"black"`
Red RGBA `json:"red"`
Green RGBA `json:"green"`
Yellow RGBA `json:"yellow"`
Blue RGBA `json:"blue"`
Magenta RGBA `json:"magenta"`
Cyan RGBA `json:"cyan"`
White RGBA `json:"white"`
// Bright colors (8-15).
BrightBlack RGBA `json:"bright_black"`
BrightRed RGBA `json:"bright_red"`
BrightGreen RGBA `json:"bright_green"`
BrightYellow RGBA `json:"bright_yellow"`
BrightBlue RGBA `json:"bright_blue"`
BrightMagenta RGBA `json:"bright_magenta"`
BrightCyan RGBA `json:"bright_cyan"`
BrightWhite RGBA `json:"bright_white"`
}
ANSIColors represents the 16-color ANSI palette for terminal emulators.
type CategorisedColour ¶
type CategorisedColour struct {
Colour color.Color `json:"-"`
Role Role `json:"role"`
Hex string `json:"hex"` // #RRGGBB format (backwards compatible)
RGB RGB `json:"rgb"` // RGB without alpha (backwards compatible)
RGBA RGBA `json:"rgba"` // RGBA with alpha channel (defaults to 255/opaque)
Luminance float64 `json:"luminance"`
IsLight bool `json:"is_light"`
Hue float64 `json:"hue,omitempty"` // HSL hue (0-360)
Saturation float64 `json:"saturation,omitempty"` // HSL saturation (0-1)
Index int `json:"index,omitempty"` // Index in AllColours array (sorted by luminance)
IsGenerated bool `json:"is_generated,omitempty"` // True if colour was generated/enhanced, not extracted
Weight float64 `json:"weight,omitempty"` // Original weight from palette (0.0-1.0, 0 if generated)
}
CategorisedColour represents a colour with its assigned role and metadata.
type CategorisedPalette ¶
type CategorisedPalette struct {
Colours map[Role]CategorisedColour `json:"colours"`
ThemeType ThemeType `json:"theme_type"`
AllColours []CategorisedColour `json:"all_colours,omitempty"`
ANSI *ANSIColors `json:"ansi,omitempty"` // ANSI terminal colors
}
CategorisedPalette represents a palette with categorised colours.
type ColorFormat ¶
type ColorFormat int
ColorFormat represents different color string formats.
const ( FormatHex ColorFormat = iota // #RRGGBB FormatHexAlpha // #RRGGBBAA FormatRGB // rgb(r,g,b) FormatRGBA // rgba(r,g,b,a) FormatHexNoHash // RRGGBB (for Hyprland) FormatRGBDecimal // "r,g,b" (for Hyprland) FormatRGBADecimal // "r,g,b,a" decimal format )
type ColorValue ¶
type ColorValue struct {
// contains filtered or unexported fields
}
ColorValue provides multiple format accessors for a single color. This is the primary type templates and plugins will interact with.
func NewColorValue ¶
func NewColorValue(rgba RGBA, role Role, index int) ColorValue
NewColorValue creates a ColorValue from RGBA with optional metadata.
func (ColorValue) A ¶
func (cv ColorValue) A() uint8
func (ColorValue) AlphaFloat ¶
func (cv ColorValue) AlphaFloat() float64
func (ColorValue) B ¶
func (cv ColorValue) B() uint8
func (ColorValue) Format ¶
func (cv ColorValue) Format(format ColorFormat) string
Format returns the color in the specified format.
func (ColorValue) G ¶
func (cv ColorValue) G() uint8
func (ColorValue) HexAlpha ¶
func (cv ColorValue) HexAlpha() string
func (ColorValue) HexNoHash ¶
func (cv ColorValue) HexNoHash() string
func (ColorValue) Index ¶
func (cv ColorValue) Index() int
func (ColorValue) R ¶
func (cv ColorValue) R() uint8
Component accessors (for advanced template use).
func (ColorValue) RGB ¶
func (cv ColorValue) RGB() string
func (ColorValue) RGBA ¶
func (cv ColorValue) RGBA() string
func (ColorValue) RGBDecimal ¶
func (cv ColorValue) RGBDecimal() string
func (ColorValue) WithAlpha ¶
func (cv ColorValue) WithAlpha(alpha float64) ColorValue
WithAlpha returns a copy of the ColorValue with custom alpha (0.0-1.0). This is useful for creating transparent variants in templates.
type PaletteHelper ¶
type PaletteHelper struct {
// contains filtered or unexported fields
}
PaletteHelper provides utilities for output plugins to access palette colors. This eliminates code duplication across all output plugins.
func NewPaletteHelper ¶
func NewPaletteHelper(themeType ThemeType, colors map[Role]ColorValue, indexed []ColorValue) *PaletteHelper
NewPaletteHelper creates a helper for the given theme type and color map. This should be called once per plugin Generate() invocation.
func (*PaletteHelper) AllColors ¶
func (ph *PaletteHelper) AllColors() []ColorValue
AllColors returns all colors indexed by palette order (AllColours array).
func (*PaletteHelper) AllRoles ¶
func (ph *PaletteHelper) AllRoles() []Role
AllRoles returns all roles in deterministic order (core → accents → semantic → surface → variants).
func (*PaletteHelper) Count ¶
func (ph *PaletteHelper) Count() int
Count returns total number of colors in the palette.
func (*PaletteHelper) FindClosestANSIColor ¶
func (ph *PaletteHelper) FindClosestANSIColor(colorName string) (ColorValue, bool)
FindClosestANSIColor finds the color in the palette that most closely matches the given ANSI color name using perceptual color distance. Returns the ColorValue and true if found, or ColorValue{} and false if not found.
Supported color names include:
- Standard ANSI: black, red, green, yellow, blue, magenta, cyan, white
- Bright variants: brightblack, brightred, brightgreen, etc.
- Aliases: color0-color15, gray, grey, purple, darkgray, etc.
- Extended: orange, pink, brown, lime, navy, teal, maroon, olive, violet, indigo
Name matching is case-insensitive.
func (*PaletteHelper) Get ¶
func (ph *PaletteHelper) Get(role Role) ColorValue
Get returns color by role. Panics if role doesn't exist - use Has() first to check.
func (*PaletteHelper) GetByIndex ¶
func (ph *PaletteHelper) GetByIndex(index int) (ColorValue, bool)
GetByIndex returns color by index in the AllColours array. Returns false if index is out of bounds.
func (*PaletteHelper) GetSafe ¶
func (ph *PaletteHelper) GetSafe(role Role) (ColorValue, bool)
GetSafe returns color by role with a boolean indicating if it exists.
func (*PaletteHelper) GetWithFallback ¶
func (ph *PaletteHelper) GetWithFallback(role Role, fallbackHex string) ColorValue
GetWithFallback returns color by role or parses a fallback hex string if missing.
func (*PaletteHelper) Has ¶
func (ph *PaletteHelper) Has(role Role) bool
Has checks if a role exists in the palette.
func (*PaletteHelper) ThemeType ¶
func (ph *PaletteHelper) ThemeType() ThemeType
ThemeType returns the detected or specified theme type.
func (*PaletteHelper) ThemeTypeString ¶
func (ph *PaletteHelper) ThemeTypeString() string
ThemeTypeString returns the theme type as a string ("dark" or "light").
type RGB ¶
RGB represents a color in RGB format (without alpha).
type RGBA ¶
type RGBA struct {
R uint8 `json:"r"`
G uint8 `json:"g"`
B uint8 `json:"b"`
A uint8 `json:"a"` // 0-255 (0 = transparent, 255 = opaque)
}
RGBA represents a color with alpha channel.
func (RGBA) AlphaFloat ¶
AlphaFloat returns the alpha channel as a float in the range 0.0-1.0.
func (RGBA) CSSRgba ¶
CSSRgba returns the color in CSS rgba() format (e.g., "rgba(26, 43, 60, 1.00)"). This format is used by CSS and applications like SwayOSD.
func (RGBA) Hex ¶
Hex returns the RGB color as a hex string without alpha (e.g., "#1a2b3c"). This maintains backwards compatibility with RGB.Hex().
func (RGBA) HexAlpha ¶
HexAlpha returns the RGBA color as a hex string with alpha (e.g., "#1a2b3cff"). This format is used by some applications like Dunst.
type Role ¶
type Role string
Role represents the semantic role of a colour in a theme.
const ( // Core roles. RoleBackground Role = "background" RoleBackgroundMuted Role = "backgroundMuted" RoleForeground Role = "foreground" RoleForegroundMuted Role = "foregroundMuted" // Accent roles. RoleAccent1 Role = "accent1" RoleAccent1Muted Role = "accent1Muted" RoleAccent2 Role = "accent2" RoleAccent2Muted Role = "accent2Muted" RoleAccent3 Role = "accent3" RoleAccent3Muted Role = "accent3Muted" RoleAccent4 Role = "accent4" RoleAccent4Muted Role = "accent4Muted" // Semantic roles. RoleDanger Role = "danger" RoleWarning Role = "warning" RoleSuccess Role = "success" RoleInfo Role = "info" RoleNotification Role = "notification" // Surface and container roles (Priority 1 - Material Design 3). RoleSurface Role = "surface" // Base surface for cards, sheets, dialogs RoleOnSurface Role = "onSurface" // Text/icons on surface RoleOutline Role = "outline" // Borders, dividers, outlines RoleBorder Role = "border" // Primary border color // Surface and border variants (Priority 2). RoleSurfaceVariant Role = "surfaceVariant" // Alternate surface color RoleOnSurfaceVariant Role = "onSurfaceVariant" // Text on surface variant RoleBorderMuted Role = "borderMuted" // Inactive/muted borders RoleOutlineVariant Role = "outlineVariant" // Secondary outline // On-colors for accents (Priority 2). RoleOnAccent1 Role = "onAccent1" // Text on accent1 background RoleOnAccent2 Role = "onAccent2" // Text on accent2 background RoleOnAccent3 Role = "onAccent3" // Text on accent3 background RoleOnAccent4 Role = "onAccent4" // Text on accent4 background // On-colors for semantic roles (Priority 2). RoleOnDanger Role = "onDanger" // Text on danger background RoleOnWarning Role = "onWarning" // Text on warning background RoleOnSuccess Role = "onSuccess" // Text on success background RoleOnInfo Role = "onInfo" // Text on info background // Inverse colors for overlays (Priority 3). RoleInverseSurface Role = "inverseSurface" // Inverse surface (tooltip backgrounds) RoleInverseOnSurface Role = "inverseOnSurface" // Text on inverse surface RoleInversePrimary Role = "inversePrimary" // Inverse accent color // Scrim and shadow with alpha (Priority 3). RoleScrim Role = "scrim" // Modal backdrop overlay (with alpha) RoleShadow Role = "shadow" // Elevation shadows (with alpha) // Surface container elevation variants (Priority 3 - Material Design 3). RoleSurfaceContainerLowest Role = "surfaceContainerLowest" // Lowest elevation RoleSurfaceContainerLow Role = "surfaceContainerLow" // Low elevation RoleSurfaceContainer Role = "surfaceContainer" // Default container RoleSurfaceContainerHigh Role = "surfaceContainerHigh" // High elevation RoleSurfaceContainerHighest Role = "surfaceContainerHighest" // Highest elevation // Positional roles for ambient lighting. // Core 8 positions (corners + mid-edges). RolePositionTopLeft Role = "positionTopLeft" RolePositionTop Role = "positionTop" RolePositionTopRight Role = "positionTopRight" RolePositionRight Role = "positionRight" RolePositionBottomRight Role = "positionBottomRight" RolePositionBottom Role = "positionBottom" RolePositionBottomLeft Role = "positionBottomLeft" RolePositionLeft Role = "positionLeft" // Extended positions for 12+ region configurations. RolePositionTopLeftInner Role = "positionTopLeftInner" RolePositionTopCenter Role = "positionTopCenter" RolePositionTopRightInner Role = "positionTopRightInner" RolePositionRightTop Role = "positionRightTop" RolePositionRightBottom Role = "positionRightBottom" RolePositionBottomRightInner Role = "positionBottomRightInner" RolePositionBottomCenter Role = "positionBottomCenter" RolePositionBottomLeftInner Role = "positionBottomLeftInner" RolePositionLeftBottom Role = "positionLeftBottom" RolePositionLeftTop Role = "positionLeftTop" // Ultra-extended positions for 16+ region configurations. RolePositionTopLeftOuter Role = "positionTopLeftOuter" RolePositionTopLeftCenter Role = "positionTopLeftCenter" RolePositionTopRightCenter Role = "positionTopRightCenter" RolePositionTopRightOuter Role = "positionTopRightOuter" RolePositionRightTopOuter Role = "positionRightTopOuter" RolePositionRightBottomOuter Role = "positionRightBottomOuter" RolePositionBottomRightOuter Role = "positionBottomRightOuter" RolePositionBottomRightCenter Role = "positionBottomRightCenter" RolePositionBottomLeftCenter Role = "positionBottomLeftCenter" RolePositionBottomLeftOuter Role = "positionBottomLeftOuter" RolePositionLeftBottomOuter Role = "positionLeftBottomOuter" RolePositionLeftTopOuter Role = "positionLeftTopOuter" )
type ThemeData ¶
type ThemeData struct {
*PaletteHelper
WallpaperPath string
ThemeName string
}
ThemeData wraps a categorised palette with additional metadata for plugins. This is the primary data structure passed to templates and external plugins.
func NewThemeData ¶
func NewThemeData(palette *CategorisedPalette, wallpaperPath, themeName string) *ThemeData
NewThemeData creates a ThemeData wrapper from a CategorisedPalette. This is called by tinct when preparing data for plugins.
func (*ThemeData) GetPaletteHelper ¶ added in v0.1.1
func (td *ThemeData) GetPaletteHelper() *PaletteHelper
GetPaletteHelper returns the embedded PaletteHelper. This method allows ThemeData to satisfy the PaletteProvider interface.