Module: color-metrics

Provides functions to calculate various color metrics, including CIE Relative Luminance (Y) from sRGB, WCAG contrast ratio, CIEDE2000 color difference (between Lab colors), and a perceptual difference metric for Oklch colors.
Source:

Methods

(static) calculateCiede2000(lab1, lab2, weightsopt) → {number}

Calculates the perceptual color difference between two CIELAB colors using CIEDE2000.
Parameters:
Name Type Attributes Description
lab1 LabColor First CIELAB color.
lab2 LabColor Second CIELAB color.
weights Object <optional>
 Optional weighting factors.
Properties
Name Type Attributes Default Description
kL number <optional>
 1 Lightness weighting factor.
kC number <optional>
 1 Chroma weighting factor.
kH number <optional>
 1 Hue weighting factor.
Source:
Returns:
The Delta E (ΔE₀₀) value.
Type
number

(static) calculateOklchDifference(oklch1, oklch2, weightsopt) → {number}

Calculates a perceptual difference metric between two Oklch colors. This is a simplified weighted Euclidean distance in the Oklch space.
Parameters:
Name Type Attributes Description
oklch1 OklchColor First Oklch color.
oklch2 OklchColor Second Oklch color.
weights Object <optional>
 Optional weighting factors.
Properties
Name Type Attributes Default Description
wL number <optional>
 1 Lightness weight.
wC number <optional>
 1 Chroma weight.
wH number <optional>
 0.5 Hue weight (scaled by mean chroma).
Source:
Returns:
The perceptual difference value.
Type
number

(static) calculateWcagContrast(color1, color2) → {number}

Calculates the WCAG contrast ratio between two colors.
Parameters:
Name Type Description
color1 SrgbColor | string First color (sRGB object or hex string).
color2 SrgbColor | string Second color (sRGB object or hex string).
Source:
Returns:
The contrast ratio (≥1, with 21 being the maximum).
Type
number
Example
calculateWcagContrast("#FFFFFF", "#000000"); // 21
calculateWcagContrast("#777777", "#FFFFFF"); // ~4.48

(static) getSrgbRelativeLuminance(colorInput) → {number}

Calculates the CIE relative luminance (Y) of an sRGB color. The input can be an SrgbColor object or a hex string.
Parameters:
Name Type Description
colorInput SrgbColor | string The sRGB color.
Source:
Returns:
The CIE relative luminance (Y), ranging from 0 to 1.
Type
number
Example
getSrgbRelativeLuminance("#FFFFFF"); // ≈ 1.0
getSrgbRelativeLuminance({ r: 0.5, g: 0.5, b: 0.5 }); // ≈ 0.214

(static) isWcagContrastSufficient(color1, color2, levelopt) → {boolean}

Checks if the WCAG contrast ratio between two colors meets a specified level.
Parameters:
Name Type Attributes Default Description
color1 SrgbColor | string First color.
color2 SrgbColor | string Second color.
level 'AA' | 'AA-large' | 'AAA' | 'AAA-large' <optional>
 'AA' WCAG conformance level.
Source:
Returns:
True if the contrast meets or exceeds the required level.
Type
boolean