color

Documentation

Overview

Package color is a standard-library-only Go port of the color primitives that underpin the popular npm packages color-convert, tinycolor2 and chroma-js, which Express/Node web apps reach for when generating themes, badges and UI palettes. It converts between the RGB, HSL and HSV colour models and CSS hex notation, and provides the everyday manipulation helpers — lighten, darken, saturate, desaturate, mix, invert, grayscale, complement and hue rotation — together with WCAG relative-luminance and contrast-ratio calculations for accessibility checks.

Colours are 8-bit sRGB. HexToRGB accepts "#rgb", "#rrggbb", "rgb" and "rrggbb" (the leading '#' and letter case are optional) and returns an error for anything else; RGBToHex always emits lowercase "#rrggbb". The HSL and HSV hue is in degrees [0,360); saturation, lightness and value are fractions in [0,1]. Conversions round to the nearest 8-bit channel and are stable round-trips for the canonical inputs exercised by the tests.

The manipulation helpers take an amount in [0,1]: Lighten(c, 0.2) moves the HSL lightness 20 percentage points toward white, Darken toward black, Saturate/Desaturate adjust HSL saturation, and Mix blends two colours by a weight (0 returns the first colour, 1 the second, 0.5 an even blend). Luminance returns the WCAG relative luminance of a colour and ContrastRatio returns the WCAG 2.1 contrast ratio between two colours (1 to 21), the basis for IsLight/IsDark. Everything is deterministic and depends only on the standard library (math, strings, fmt).

Index

• func Complement(hex string) (string, error)
• func ContrastColor(hex string) (string, error)
• func ContrastRatio(c1, c2 string) (float64, error)
• func Darken(hex string, amount float64) (string, error)
• func Desaturate(hex string, amount float64) (string, error)
• func Grayscale(hex string) (string, error)
• func HSLToHex(c HSL) string
• func Invert(hex string) (string, error)
• func IsDark(hex string) (bool, error)
• func IsLight(hex string) (bool, error)
• func Lighten(hex string, amount float64) (string, error)
• func Luminance(c RGB) float64
• func Mix(c1, c2 string, weight float64) (string, error)
• func RGBToHex(c RGB) string
• func RotateHue(hex string, deg float64) (string, error)
• func Saturate(hex string, amount float64) (string, error)
• func Shade(hex string, amount float64) (string, error)
• func Tint(hex string, amount float64) (string, error)
• type HSL
  • func HexToHSL(hex string) (HSL, error)
  • func RGBToHSL(c RGB) HSL
• type HSV
  • func RGBToHSV(c RGB) HSV
• type RGB
  • func HSLToRGB(c HSL) RGB
  • func HSVToRGB(c HSV) RGB
  • func HexToRGB(hex string) (RGB, error)
  • func (c RGB) Hex() string

Functions

func Complement

func Complement(hex string) (string, error)

Complement returns the complementary colour (hue rotated 180 degrees).

func ContrastColor

func ContrastColor(hex string) (string, error)

ContrastColor returns "#000000" or "#ffffff", whichever has the higher WCAG contrast ratio against the given background hex colour — the standard way to choose legible foreground text. It returns an error if hex is malformed.

func ContrastRatio

func ContrastRatio(c1, c2 string) (float64, error)

ContrastRatio returns the WCAG 2.1 contrast ratio between two hex colours, a value from 1 (identical) to 21 (black on white).

func Darken

func Darken(hex string, amount float64) (string, error)

Darken decreases the HSL lightness of a hex colour by amount and returns the new hex colour.

func Desaturate

func Desaturate(hex string, amount float64) (string, error)

Desaturate decreases the HSL saturation of a hex colour by amount and returns the new hex colour.

func Grayscale

func Grayscale(hex string) (string, error)

Grayscale removes all saturation from a hex colour, returning its grey equivalent (preserving lightness).

func HSLToHex

func HSLToHex(c HSL) string

HSLToHex converts an HSL colour to a "#rrggbb" hex string.

func Invert

func Invert(hex string) (string, error)

Invert returns the per-channel inverse (255-c) of a hex colour.

func IsDark

func IsDark(hex string) (bool, error)

IsDark reports whether a hex colour is not light (see IsLight).

func IsLight

func IsLight(hex string) (bool, error)

IsLight reports whether a hex colour has a relative luminance above 0.5, meaning dark text reads well on it.

func Lighten

func Lighten(hex string, amount float64) (string, error)

Lighten increases the HSL lightness of a hex colour by amount (a fraction in [0,1], clamped) and returns the new hex colour.

func Luminance

func Luminance(c RGB) float64

Luminance returns the WCAG 2.1 relative luminance of an RGB colour, a value in [0,1] where 0 is black and 1 is white.

func Mix

func Mix(c1, c2 string, weight float64) (string, error)

Mix blends two hex colours in sRGB space by weight (0 returns c1, 1 returns c2, 0.5 an even mix) and returns the resulting hex colour.

func RGBToHex

func RGBToHex(c RGB) string

RGBToHex returns the lowercase "#rrggbb" representation of the colour.

func RotateHue

func RotateHue(hex string, deg float64) (string, error)

RotateHue rotates the HSL hue of a hex colour by deg degrees (wrapping into [0,360)) and returns the new hex colour.

func Saturate

func Saturate(hex string, amount float64) (string, error)

Saturate increases the HSL saturation of a hex colour by amount and returns the new hex colour.

func Shade

func Shade(hex string, amount float64) (string, error)

Shade blends a hex colour toward black by amount (a fraction in [0,1]) and returns the resulting hex colour.

func Tint

func Tint(hex string, amount float64) (string, error)

Tint blends a hex colour toward white by amount (a fraction in [0,1]) and returns the resulting hex colour.

Types

type HSL

type HSL struct {
	H float64
	S float64
	L float64
}

HSL is a colour in the hue-saturation-lightness model. H is in degrees [0,360); S and L are fractions in [0,1].

func HexToHSL

func HexToHSL(hex string) (HSL, error)

HexToHSL parses a hex colour and returns it in the HSL model.

func RGBToHSL

func RGBToHSL(c RGB) HSL

RGBToHSL converts an RGB colour to HSL.

type HSV

type HSV struct {
	H float64
	S float64
	V float64
}

HSV is a colour in the hue-saturation-value model. H is in degrees [0,360); S and V are fractions in [0,1].

func RGBToHSV

func RGBToHSV(c RGB) HSV

RGBToHSV converts an RGB colour to HSV.

type RGB

type RGB struct {
	R uint8
	G uint8
	B uint8
}

RGB is an 8-bit sRGB colour with red, green and blue channels in [0,255].

func HSLToRGB

func HSLToRGB(c HSL) RGB

HSLToRGB converts an HSL colour to RGB.

func HSVToRGB

func HSVToRGB(c HSV) RGB

HSVToRGB converts an HSV colour to RGB.

func HexToRGB

func HexToRGB(hex string) (RGB, error)

HexToRGB parses a CSS hex colour ("#rgb", "#rrggbb", or the same without the leading '#') and returns the RGB colour. It returns an error for malformed input.

func (RGB) Hex

func (c RGB) Hex() string

Hex is the method form of RGBToHex.