Skip to content
palette logoPaletteUtilities
Color parsing, conversion, mixing, and contrast for design tools
Version
v26.11.26
Size
4.8 KB gzip
Dependencies
Zero dependencies
BrowserNode ≥22
parseColortoHextoRgbStringtoHslStringtoOklchString View all 17 exports

Why Palette? ​

Design tools need color math that is correct where it matters — perceptual OKLab mixing, WCAG contrast, lossless extended-range conversions — without pulling in a color library that assumes a DOM, a canvas, or a particular color model.

ts
// Before
const mid = { r: (a.r + b.r) / 2, g: (a.g + b.g) / 2, b: (a.b + b.b) / 2 }; // gamma-space average, looks wrong
const ratio = /* hand-rolled luminance, usually forgets the sRGB transfer function */;

// After
import { contrastRatio, mix, parseColor, ramp } from '@vielzeug/palette';

const mid = mix(parseColor('#000000'), parseColor('#ffffff'), 0.5); // perceptual OKLab midpoint
const ratio = contrastRatio(parseColor('#767676'), parseColor('#ffffff')); // 4.54
const shades = ramp(parseColor('#3366cc'), { steps: 9 }); // OKLCH lightness ramp
FeaturePaletteAd-hoc color helpers
Bundle size4.8 KBn/a
Zero dependenciesn/a
CSS Color 4 oklab()/oklch() parsingBuilt inManual
CSS named colorsBuilt inManual
OKLab mixing with premultiplied alphaBuilt in, matches color-mix(in oklab)Manual
WCAG 2.x contrastBuilt inManual
Perceptual rampsOKLCH lightness, gamut-fittedManual

Use Palette when an application needs headless color parsing, conversion, mixing, or contrast checks with no DOM or rendering assumptions.

Consider a rendering-layer color API when the work is applying colors to a surface rather than computing them.

Installation ​

sh
pnpm add @vielzeug/palette
sh
npm install @vielzeug/palette
sh
yarn add @vielzeug/palette

Quick Start ​

ts
import { mix, parseColor, ramp, readableOn, toHex } from '@vielzeug/palette';

const brand = parseColor('#3366cc');
const surface = parseColor('rgb(248 250 252)');

const ink = readableOn(surface, [parseColor('#0f172a'), parseColor('#334155')]);
const midpoint = mix(brand, surface, 0.5); // OKLab interpolation, like color-mix(in oklab)
const shades = ramp(brand, { steps: 9 }); // OKLCH lightness ramp

console.log(toHex(ink ?? brand), toHex(midpoint), shades.map(toHex));

Features ​

  • parseColor(): #rgb/#rgba/#rrggbb/#rrggbbaa, rgb()/hsl() comma and space syntax, CSS Color 4 oklab()/oklch(), and CSS named colors
  • toHex(), toRgbString(), toHslString(), toOklchString(): formatting with documented clamping at the display boundary
  • srgbToOklch() / oklchToSrgb(), srgbToHsl() / hslToSrgb(): lossless round-trippable conversions via the standard Björn Ottosson OKLab matrices
  • isDisplayable(): gamut test for any Rgba against sRGB
  • mix(): OKLab interpolation with premultiplied alpha, matching CSS color-mix(in oklab)
  • contrastRatio() and relativeLuminance(): WCAG 2.x ratios on clamped sRGB
  • readableOn(): picks the first candidate meeting the AA/AAA threshold, with large-text thresholds
  • ramp(): deterministic OKLCH lightness ramps that keep hue and stay inside the gamut
  • Typed errors: PaletteParseError and PaletteConfigError share the PaletteError base
  • Pure functions only: no DOM, no disposal contract, zero dependencies

Documentation ​

See Also ​

  • Arsenal: general-purpose utilities that complement headless color math.
  • Refine: components styled with design tokens that tools like this generate and check.