go-colorful

go-colorful is a small, dependency-free Go library for working with colors beyond plain RGB. It implements Go’s standard color.Color interface while adding conversions to HSL, HSV, CIE-XYZ, CIE-xyY, CIE-Lab, CIE-Luv, HCL, HSLuv, HPLuv, Oklab, Oklch, and the CSS Color Level 4 wide-gamut spaces (Display P3, A98 RGB, ProPhoto RGB, Rec2020).

Beyond conversion, it provides perceptually-aware color distance functions (CIE76, CIE94, CIEDE2000, Riemersma), blending across multiple color spaces, k-means-based palette generation, and color sorting — color math with no equivalent in Go’s standard library.

What You Get

• Conversions between RGB, HSL, HSV, CIE-XYZ, CIE-xyY, CIE-Lab, CIE-Luv, HCL, HSLuv, HPLuv, Oklab, and Oklch color spaces
• CSS Color Level 4 wide-gamut support: Display P3, A98 RGB, ProPhoto RGB, and Rec2020, with D50/D65 Bradford chromatic adaptation
• Perceptual color-distance functions (CIE76, CIE94, CIEDE2000, Riemersma) for comparing colors the way humans see them
• Color blending functions across RGB, HSV, Oklab, Oklch, and the CIE-Lab family of spaces
• K-means-based palette generators (soft, warm, and ‘happy’ palettes) for producing distinct, pleasant color sets
• A disjoint-set-based color sorting algorithm for ordering palettes so similar colors sit next to each other

Common Use Cases

• Assigning visually distinct random colors to game players or UI elements
• Generating aesthetically pleasing color palettes for data visualization or generative art
• Comparing two colors perceptually instead of with naive RGB Euclidean distance
• Smoothly interpolating (blending) between colors for gradients and animations

Under The Hood

Architecture go-colorful is a single flat package built around one core Color struct storing sRGB values, with every color-space conversion, distance function, and blend implemented as a method or free function operating on that struct. Concerns are split across files by responsibility rather than by layer: colors.go holds the core RGB/HSL/HSV/CIE conversions and distance metrics, hsluv.go and widegamut.go add HSLuv/HPLuv and the CSS Color 4 gamuts respectively, soft_palettegen.go/warm_palettegen.go/happy_palettegen.go implement k-means palette generation constrained by a caller-supplied CheckColor predicate, and sort.go implements a disjoint-set-forest algorithm for ordering palettes. There is no dependency injection or internal service boundary — everything is stateless pure-math functions — so the core Color struct is the one abstraction the entire package depends on; changing its shape (e.g. adding an alpha channel) would ripple through every conversion function in every file.

Tech Stack The library targets Go 1.12+ and has zero third-party dependencies, relying only on fmt, image/color, math, sort, strconv, math/rand, and strings from the standard library. It integrates with Go’s image/color.Color interface directly rather than defining a parallel type system. CI (GitHub Actions) runs go test -race ./... across Go 1.22 and 1.23, and there is no additional build tooling beyond go build/go get since it ships as a plain importable module.

Code Quality Seven test files mirror the source files (colors_test.go, hsluv_test.go, widegamut_test.go, soft_palettegen_test.go, sort_test.go, colorgens_test.go, hexcolor_test.go), using table-driven tests against Go’s standard testing package plus a large third-party HSLuv snapshot fixture for cross-implementation validation. Error handling is explicit — constructors like Hex() return (Color, error) rather than panicking — and CI runs the suite under the race detector across two Go versions. There is no linter or go vet step wired into CI, and the changelog documents a few historical naming inconsistencies (e.g. DistanceLinearRGB deprecated in favor of DistanceLinearRgb) being cleaned up over time.

What Makes It Unique Few Go libraries implement this level of colorimetric completeness: the full CIE family (XYZ, xyY, Lab, Luv, HCL, LCh(uv)) alongside newer perceptual spaces like Oklab/Oklch and HSLuv/HPLuv, plus CIEDE2000 distance and the CSS Color 4 wide-gamut spaces with proper Bradford chromatic adaptation between D50 and D65 white points. The k-means-based palette generators, constrained by an arbitrary CheckColor predicate over the Lab color space, are a distinctive and broadly reusable technique for constrained, visually distinct palette generation — something otherwise absent from Go’s ecosystem.