Color Class

The Color class is the primary interface for object-oriented workflows in Saturon. It encapsulates a color's model and internal coordinates, providing a chainable and developer-friendly API for color science, formatting, and manipulation.

Constructor

Instantiates a new Color object directly from a registered color model name and an array of numeric coordinates.

const red = new Color("rgb", [255, 0, 0]);

// Instance Properties
console.log(red.model); // "rgb"
console.log(red.coords); // [255, 0, 0, 1]

When called, the constructor executes the following logic:

1. Verifies that the provided model exists within the engine's registered color models (colorModels); throws an error if unsupported.
2. Ensures the coords array contains exactly 3 or 4 elements.
3. Clones the coordinate array and automatically appends a default alpha channel (1) if a 3-element array is provided.

Static Color.config

A static getter that returns the global configuration settings for the engine (such as default fitting methods or serialization precision).

Static Color.configure()

Merges a partial runtime configuration into the global configuration object.

Color.configure({ defaults: { fit: "css-gamut-map" } });

Static Color.use()

Registers one or more plugins to extend the Color class with custom methods or properties at runtime.

When invoked, it validates that all arguments are functions, skips any plugins that have already been executed, passes the static Color class reference to each new plugin function, and tracks registered plugins in a global set to prevent duplicate initialization.

Static Color.register()

Injects custom color models, formatters, syntax rules, or gamut spaces into the core engine.

Static Color.unregister()

Removes previously registered custom color models, formatters, syntax rules, or gamut spaces from the core engine.

Static Color.from()

Parses any valid CSS color string, named color, or complex function (like color-mix() or relative colors) into a Color instance.

Static Color.isValid()

A static helper to quickly determine if a string is a valid, parseable CSS color without throwing an error or instantiating a class.

const valid = Color.isValid("rgb(255 32 98)");
const invalid = Color.isValid("rgb(255deg 32 98)");
console.log(valid); // true
console.log(invalid); // false

Static Color.get()

Retrieves a list of registered items (like available color models or gamut spaces) from the engine's registry.

const fitMethods = Color.get("fit-methods");
console.log(fitMethods); // ["none", "clip", "chrome-reduction", "css-gamut-map"]

Static Color.random()

Generates a random Color instance based on specific criteria or constraints (e.g., restricted to a certain model or coordinate range).

Color.random({ model: "lab", limits: { alpha: [1, 1] } });

Static Color.mix()

Statically mixes multiple colors together by specified percentages, replicating the exact W3C behavior of the CSS color-mix() function.

const red = Color.from("red");
const blue = Color.from("blue");
const mixed = Color.mix([{ color: red, percentage: 0.3 }, { color: blue }], {
    in: "oklch",
    hue: "decreasing",
});
console.log(mixed); // result is equivalent to parsing the string "color-mix(in oklch decreasing hue, red 30%, blue)"

Static Color.interpolate()

const red = Color.from("red");
const yellow = Color.from("yellow");
const blue = Color.from("blue");

// Create an interpolator across multiple colors in Oklab space
const palette = Color.interpolate([red, yellow, blue], { in: "oklab" });

// Sample colors along the multi-stop gradient (t from 0 to 1)
const start = palette(0); // Returns Color instance for red
const mid = palette(0.5); // Returns Color instance for yellow
const end = palette(1); // Returns Color instance for blue

Returns a function that interpolates across an array of colors. The returned function accepts a progress value t (0 to 1) and returns the interpolated Color.

Static Color.scale()

Generates an array of Color instances (a palette) by interpolating evenly across the provided colors in a specific number of steps.

Static Color.contrast()

Calculates the WCAG 2.1 contrast ratio between two Color instances. Returns a value from 1 to 21.

const white = Color.from("white");
const black = Color.from("black");
const contrast = Color.contrast(white, black);
console.log(contrast); // ~21

Static Color.deltaE76()

Calculates the basic CIE 1976 color difference (Euclidean distance in Lab space). 0 = identical, ~1 = Just Noticeable Difference (JND).

Static Color.deltaE94()

Calculates the CIE 1994 color difference, addressing perceptual non-uniformities with weighted improvements over standard Lab space.

Static Color.deltaE2000()

Calculates the CIEDE2000 color difference, the most accurate CIE standard for addressing complex perceptual interactions.

Static Color.deltaEOK()

Calculates the OKLab color difference. Modern, highly accurate, and based on the perceptually uniform OKLab space. Scaled to match standard Delta E ranges.

Color.prototype.to()

Converts and serializes the color into a specific output format (e.g., hex-color, rgb, oklab).

// Convert to different formats
const color = Color.from("hsl(50 100% 30%)");
console.log(color.to("rgb")); // rgb(153 128 0)
console.log(color.to("hex-color")); // #998000

// Use legacy syntax
console.log(color.to("rgb", { legacy: true })); // rgb(153, 128, 0)

// Constrain to sRGB gamut with different fit methods
const wideColor = Color.from("color(display-p3 1 0 0)");
console.log(wideColor.to("rgb", { fit: "clip" })); // rgb(255 0 0)
console.log(wideColor.to("rgb", { fit: "css-gamut-map" })); // rgb(255 0 0)

// Include units and custom precision
console.log(color.to("hsl", { units: true, precision: 2 })); // hsl(50deg 100% 30%)

Color.prototype.in()

Converts the color's internal coordinates to a target color model.

const rgb = new Color("rgb", [255, 87, 51]);
const hsl = rgb.in("hsl");
console.log({ ...hsl }); // { model: "hsl", coords: [15, 100, 60, 1] }

Color.prototype.toArray()

Returns the color as a raw numeric array of component values, optionally normalized and fitted.

const color = new Color("rgb", [255, 0, 0]);
const arr = color.toArray();
console.log(arr); // [255, 0, 0, 1]

Color.prototype.toObject()

Returns the color as an object mapping each component to its numeric value. Accepts options for precision and gamut fitting.

const color = new Color("rgb", [255, 0, 0]);
const obj = color.toObject();
console.log(obj); // { r: 255, g: 0, b: 0, alpha: 1 }

Color.prototype.toString()

Formats the color as a CSS-compliant string in its current internal model. Accepts options for precision, legacy syntax, and units.

Color.prototype.with()

Creates a new Color instance with modified component values. It supports several flexible update patterns:

// Direct object
color.with({ l: 50 });

// Functional component
color.with({ r: (r) => r * 2 });

// Functional bulk
color.with(({ r, g, b }) => ({ r: r * 0.5 }));

// Array replacement
color.with([0.5, 0.6, 0.7, 1]);

// Functional array
color.with(({ r, g, b }) => [r, g, b, 0.5]);

Color.prototype.fit()

Creates a new Color instance with its coordinates strictly fitted to its own model's standard gamut boundaries using the specified mapping method.

const extreme = new Color("rgb", [300, 0, 0]);
const fitted = extreme.fit();
console.log(fitted.coords); // [255, 0, 0, 1]

Color.prototype.within()

Fits out-of-bounds coordinates to a target physical gamut space.

const extreme = new Color("rgb", [300, 0, 0]);
const fitted = extreme.within("srgb");
console.log(fitted.coords); // [255, 0, 0, 1]

Color.prototype.inGamut()

Determines whether the current color coordinates lie strictly within the boundaries of a given physical gamut space. See saturon/gamut for more details.

const color = new Color("display-p3", [1, 0, 0]);
console.log(color.inGamut("srgb")); // false
console.log(color.inGamut("display-p3")); // true