Version v26.11.26 Size 4.8 KB gzip Dependencies Zero dependencies
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| Feature | Palette | Ad-hoc color helpers |
|---|---|---|
| Bundle size | 4.8 KB | n/a |
| Zero dependencies | n/a | |
CSS Color 4 oklab()/oklch() parsing | Built in | Manual |
| CSS named colors | Built in | Manual |
| OKLab mixing with premultiplied alpha | Built in, matches color-mix(in oklab) | Manual |
| WCAG 2.x contrast | Built in | Manual |
| Perceptual ramps | OKLCH lightness, gamut-fitted | Manual |
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/palettesh
npm install @vielzeug/palettesh
yarn add @vielzeug/paletteQuick 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 4oklab()/oklch(), and CSS named colorstoHex(),toRgbString(),toHslString(),toOklchString(): formatting with documented clamping at the display boundarysrgbToOklch()/oklchToSrgb(),srgbToHsl()/hslToSrgb(): lossless round-trippable conversions via the standard Björn Ottosson OKLab matricesisDisplayable(): gamut test for anyRgbaagainst sRGBmix(): OKLab interpolation with premultiplied alpha, matching CSScolor-mix(in oklab)contrastRatio()andrelativeLuminance(): WCAG 2.x ratios on clamped sRGBreadableOn(): picks the first candidate meeting the AA/AAA threshold, with large-text thresholdsramp(): deterministic OKLCH lightness ramps that keep hue and stay inside the gamut- Typed errors:
PaletteParseErrorandPaletteConfigErrorshare thePaletteErrorbase - Pure functions only: no DOM, no disposal contract, zero dependencies