color-value-tools

A comprehensive utility library for parsing, converting, manipulating, and analyzing color values across all major color models — hex, RGB, HSL, HSV, HWB, Lab, LCH, Oklab, Oklch, CMYK, Display P3 — plus CSS variables and named colors. Zero dependencies.

Features

• Universal parser — normalizeColor() accepts hex (3/4/6/8-digit), rgb() / rgba(), hsl() / hsla(), hwb(), oklch() / oklcha(), color(display-p3 ...), CSS named colors (all 148), and plain {r,g,b} / {h,s,l} objects
• Conversions — every path between hex, RGB, HSL, HSV, HWB, Lab, LCH, Oklab, Oklch, CMYK, Display P3; all round-trip accurate
• Manipulation — lighten, darken, saturate, desaturate, invertColor, grayscale, setAlpha, rotateHue, adjustHexBrightness
• Mixing & Interpolation — mixColors and interpolateColors in 6 color spaces with 4 hue interpolation modes; createColorScale across multiple anchor colors with custom positions; midpointColor for a perceptual midpoint
• Color Harmonies — complement, triadic, analogous, splitComplementary, tetradic
• Palette Generation — colorShades, monochromatic, tints, shades, tones — all Oklab-accurate where applicable
• WCAG Accessibility — relativeLuminance, contrastRatio, wcagLevel, bestTextColor, bestContrastColor, bestContrastPalette, isReadableOnBackground (solid, semi-transparent, and gradient backgrounds)
• Color Blindness Simulation — protanopia, deuteranopia, tritanopia using Vienot 1999 matrices on linear RGB
• Perceptual color distance — colorDeltaE implementing the full CIEDE2000 formula
• CSS Formatting — toHslString, toHwbString, toOklchString, toColorP3String
• Cache — LRU-style normalizeColorCached; getCacheStats, clearColorCache, enableCache / disableCache
• Generator functions — generateGradientColors*, generateTints*, generateShades* for lazy iteration without pre-allocating arrays
• CLI (cvt) — inspect any color from the terminal: full info, all conversions, WCAG contrast, shades, harmonies, nearest named color
• Zero dependencies — no runtime deps; ships as tree-shakeable ESM + CommonJS

Installation

npm install color-value-tools

No peer dependencies required.

Quick start

import {
  normalizeColor,
  mixColors,
  lighten,
  darken,
  saturate,
  complement,
  triadic,
  wcagLevel,
  bestTextColor,
  colorDeltaE,
  randomColor,
} from 'color-value-tools'

// Parse any color format
normalizeColor('#3498db')
// { type: 'hex', hex: '#3498db', r: 52, g: 152, b: 219, h: 204, s: 70, l: 53, v: 86, a: 1 }

// Manipulate
lighten('#3498db', 15) // '#6ab4e8'
darken('#3498db', 15) // '#1a6da3'
saturate('#3498db', 20) // '#1a8fe8'

// Harmonies
complement('#3498db') // '#db6034'
triadic('#3498db') // ['#3498db', '#db3498', '#98db34']

// WCAG accessibility
wcagLevel('#ffffff', '#3498db') // 'AA'
bestTextColor('#3498db') // '#ffffff'

// Perceptual color distance (CIEDE2000)
colorDeltaE('#ff0000', '#fe0000') // ~0.9

// Random color
randomColor({ hRange: [200, 260], sRange: [60, 80] })

CommonJS:

const { normalizeColor, mixColors } = require('color-value-tools')