Reference

TypeScript types

All public types are exported from the package root:

import type {
  ColorType, // 'hex' | 'css-var' | 'rgb' | 'hsl' | 'named' | 'oklch' | 'color' | 'unknown'
  WcagLevel, // 'AAA' | 'AA' | 'AA-large' | 'fail'
  ColorBlindnessType, // 'protanopia' | 'deuteranopia' | 'tritanopia'
  BackgroundSpec, // string | { type: 'semi-transparent'; ... } | { type: 'gradient'; ... }
  PaletteScore, // { palette, minContrastRatio, avgContrastRatio }
} from 'color-value-tools'

BackgroundSpec — discriminated union

import type { BackgroundSpec } from 'color-value-tools'

const solid: BackgroundSpec = '#3498db'

const semiTransparent: BackgroundSpec = {
  type: 'semi-transparent',
  color: 'rgba(0,0,0,0.4)',
  underlay: '#ffffff', // optional, defaults to white
}

const gradient: BackgroundSpec = {
  type: 'gradient',
  stops: ['#1a1a2e', '#e94560', '#f5a623'],
}

PaletteScore — from bestContrastPalette

import type { PaletteScore } from 'color-value-tools'

const result: PaletteScore & { paletteIndex: number } = bestContrastPalette(bg, palettes)
result.paletteIndex // number
result.palette // string[]
result.minContrastRatio // number
result.avgContrastRatio // number

Inference from normalizeColor

import { normalizeColor } from 'color-value-tools'

const n = normalizeColor('#3498db')
// TypeScript knows: n.hex, n.r, n.g, n.b, n.h, n.s, n.l, n.v, n.a, n.type

if (n.type !== 'unknown' && n.type !== 'css-var') {
  const r: number = n.r! // available for all resolved color types
}

Architecture

color-value-tools
│
├── Detection
│     getColorType, isHexColor, isRgbColor, isHslColor,
│     isOklchColor, isColorFunction, isCssVariable
│
├── Parsing
│     normalizeColor          → universal entry point; handles all formats + objects
│     rgbaStringToRgba        → rgb()/rgba() parser
│     hex8ToRgba              → 8-digit and 4-digit hex with alpha
│     parseOklchString        → oklch(L C H / alpha) with % L support
│     parseColorFn            → color(display-p3 ...) / color(srgb ...)
│     parseHwbString          → hwb() string
│     parseCssVar             → var(--name, fallback)
│
├── Color Math — every space via RGB as the hub
│     sRGB ↔ Linear (srgbChanToLinear / linearChanToSrgb)
│     XYZ D65 intermediate for Lab/LCH
│     Oklab/Oklch — Björn Ottosson matrices
│     Display P3 — ICC sRGB→P3 and P3→sRGB matrices
│
├── Manipulation
│     lighten / darken / saturate / desaturate — via HSL
│     invertColor — RGB invert
│     grayscale — BT.709 perceptual weights
│     rotateHue — via HSL hue shift
│     adjustHexBrightness — linear channel blend toward 0/255
│     setAlpha / getAlpha — rgba string manipulation
│
├── mixColors  (core of interpolation system)
│     6 color space modes: rgb | hsl | lab | lch | oklab | oklch
│     4 hue interpolation modes: shorter | longer | increasing | decreasing
│     4 output formats: hex | rgb | rgba | hsl
│     Used internally by: interpolateColors, createColorScale,
│       midpointColor, tints, shades, tones,
│       generateGradientColors*, generateTints*, generateShades*
│
├── Color Harmonies
│     All implemented as hue rotations on normalized hex
│
├── Palette Generation
│     colorShades — HSL lightness sweep
│     monochromatic — HSL saturation sweep
│     tints / shades / tones — Oklab interpolation via mixColors
│
├── Accessibility
│     relativeLuminance — WCAG linearization formula
│     contrastRatio — (L1+0.05)/(L2+0.05)
│     wcagLevel — ratio thresholds 3 / 4.5 / 7
│     isReadableOnBackground — handles 3 background types;
│       semi-transparent: alpha-composites onto underlay before ratio check
│       gradient: evaluates each stop, uses minimum ratio
│     bestContrastPalette — score = avg×0.4 + min×0.6
│
├── Color Blindness
│     Vienot 1999 matrices on linear RGB
│     3 types: protanopia / deuteranopia / tritanopia
│
├── Cache
│     Simple Map<string, NormalizeResult>
│     normalizeColorCached — Map lookup before calling normalizeColor
│     getCacheStats / clearColorCache / enableCache / disableCache
│
├── Generator functions
│     ES2015 generator syntax (*) — yield one color at a time
│     generateGradientColors* → mixColors inside the generator
│     generateTints* / generateShades* → Oklab mix toward white/black
│
└── CLI (dist/cli/cli.js → cvt)
      Commands: info | convert | contrast | shades | harmonies | nearest
      Accepts any color format normalizeColor understands
      Imports the package's own build — no separate copy of the library

Modules

The source is split into modules, and each one is also published as a subpath import:

Module	Subpath	Contents
parse	color-value-tools/parse	Detection, CSS string parsers, normalizeColor, named colors
convert	color-value-tools/convert	Conversions between color spaces, CSS string formatters
manipulate	color-value-tools/manipulate	Lightness/saturation/alpha adjustments, rotateHue, mixColors
palette	color-value-tools/palette	Harmonies, scales, tints/shades/tones, generators, randomColor
a11y	color-value-tools/a11y	Luminance, contrast, WCAG, colorDeltaE, color blindness
cache	color-value-tools/cache	normalizeColorCached and cache controls

The package root color-value-tools re-exports all of them.

Bundle size & dependencies

Node.js	>=18
Runtime dependencies	None
Peer dependencies	None
Dev dependencies	TypeScript, Vitest, Prettier
ESM entry	dist/esm/index.js (tree-shakeable)
CJS entry	dist/cjs/index.js
Types	.d.ts for both ESM and CJS builds
CLI entry	dist/cli/cli.js → cvt

The package ships both ESM and CommonJS builds: the package itself is CommonJS, and the ESM build lives in dist/esm with its own type: module. Every function is a named export, and the package is marked sideEffects: false, so bundlers that support tree-shaking eliminate unused functions.

License

MIT