Basic Usage
import { parseColor, toHex } from '@vielzeug/palette';
const brand = parseColor('#3366cc'); // { r: 51, g: 102, b: 204, a: 1 }
console.log(toHex(brand)); // "#3366cc"parseColor() accepts hex (3, 4, 6, and 8 digits), rgb()/rgba() and hsl()/hsla() in both comma and space syntax, CSS Color 4 oklab()/oklch(), and the CSS named colors (case-insensitive, including transparent). Anything else throws PaletteParseError with the offending input in the message. The color() notation is out of scope.
Parse CSS Colors
import { parseColor } from '@vielzeug/palette';
parseColor('#f09'); // #rgb: digits are duplicated
parseColor('#f098'); // #rgba
parseColor('rgb(1, 2, 3)'); // comma syntax
parseColor('rgba(1, 2, 3, 0.5)'); // legacy comma alpha
parseColor('rgb(1 2 3 / 0.5)'); // space syntax with slash alpha
parseColor('rgb(50% 25% 0%)'); // percentages map to 0–255
parseColor('hsl(120, 100%, 50%)'); // hue wraps: -120 and 480 are valid
parseColor('oklab(0.5 -0.1 0.1 / 0.5)'); // CSS Color 4
parseColor('oklch(50% 0.1 240deg)'); // percent lightness, deg hue
parseColor('RebeccaPurple'); // named colors, any case
parseColor('transparent'); // { r: 0, g: 0, b: 0, a: 0 }Percentage oklab a/b and oklch c map to the CSS Color 4 range of ±0.4. Alpha accepts a number or a percentage and is clamped to 0–1. Out-of-range channels (rgb(300 0 0)) are kept exactly — parsing never clips.
Convert Between Color Spaces
import { hslToSrgb, oklchToSrgb, parseColor, srgbToHsl, srgbToOklch } from '@vielzeug/palette';
const red = parseColor('#ff0000');
const oklch = srgbToOklch(red); // { l: 0.628, c: 0.2577, h: 29.23, a: 1 }
const hsl = srgbToHsl(red); // { h: 0, s: 100, l: 50, a: 1 }
const back = oklchToSrgb(oklch); // round-trips within ±1 per channelConversions use the standard sRGB → linear → OKLab → OKLCH pipeline (Björn Ottosson's matrices, sRGB transfer function sign-extended per CSS Color 4). The pipeline is lossless: oklchToSrgb() leaves out-of-gamut channels outside 0–255, so srgbToOklch() recovers the original values, and isDisplayable() tells you whether a color fits the screen.
Format Colors
import { parseColor, toHex, toHslString, toOklchString, toRgbString } from '@vielzeug/palette';
const translucent = parseColor('rgb(222 173 190 / 0.5)');
toHex(translucent); // "#deadbe80" — alpha is written when the color is translucent
toHex(translucent, { alpha: false }); // "#deadbe" — never write alpha...
toHex(parseColor('#deadbeef'), { alpha: true }); // "#deadbeff" — ...or always write it
toRgbString(translucent); // "rgb(222 173 190 / 0.5)"
toHslString(parseColor('#ff0000')); // "hsl(0 100% 50%)"
toOklchString(parseColor('#ff0000')); // "oklch(62.8% 0.2577 29.23)"toHex(), toRgbString(), and toHslString() clamp out-of-gamut channels to 0–255 and alpha to 0–1 before writing, so their output is always display-safe. A color produced by parseColor('rgb(300 0 0)') keeps its out-of-range channel until formatted, where it clamps to 255. toOklchString() writes the color's true OKLCH values — an out-of-gamut color round-trips through parseColor() exactly.
Mix in OKLab
import { mix, parseColor, toHex } from '@vielzeug/palette';
const mid = mix(parseColor('#000000'), parseColor('#ffffff'), 0.5);
toHex(mid); // "#636363" — the perceptual midpoint, not #808080
const hover = mix(parseColor('#ff0000'), parseColor('rgb(0 0 0 / 0)'), 0.5);
toHex(hover); // "#ff000080" — transparent endpoints don't darkenmix() interpolates in OKLab with premultiplied alpha, matching CSS color-mix(in oklab, ...): midpoints are perceptually even, and a transparent endpoint contributes no color instead of pulling the blend toward black. A t outside [0, 1] throws PaletteConfigError.
Check Contrast
import { contrastRatio, parseColor, readableOn } from '@vielzeug/palette';
contrastRatio(parseColor('#000000'), parseColor('#ffffff')); // 21
contrastRatio(parseColor('#767676'), parseColor('#ffffff')); // ≈ 4.54 (AA boundary)
const ink = readableOn(parseColor('#f8fafc'), [parseColor('#94a3b8'), parseColor('#0f172a')]);
// → #0f172a: the first candidate that reaches the thresholdcontrastRatio() uses WCAG 2.x relative luminance on channels clamped to 0–255. readableOn() picks the first candidate meeting 4.5 (AA) or 7 (AAA), or 3 / 4.5 with { large: true }, and returns null when nothing passes.
Build Lightness Ramps
import { parseColor, ramp, toHex } from '@vielzeug/palette';
const shades = ramp(parseColor('#3366cc'), { steps: 9 });
console.log(shades.map(toHex)); // nine swatches, dark to lightramp() interpolates OKLab lightness between minLightness (default 0.15) and maxLightness (default 0.95) at the base color's hue. Where a swatch would leave the sRGB gamut, its chroma is reduced until it fits — every swatch is displayable and the hue never shifts under clamping. The result is deterministic and runs dark to light. Invalid steps or lightness bounds throw PaletteConfigError.
Errors
All failures are PaletteError subclasses: PaletteParseError for malformed input and PaletteConfigError for invalid options. Catch the base class to handle both.
Best Practices
- Parse once at the boundary, keep
Rgbavalues, and format at the edges; conversions are cheap but parsing strings repeatedly is wasteful. - Use
mix()instead of averaging channels — gamma-space averages look muddy. - Use
ramp()for tonal scales andreadableOn()for ink selection instead of hand-tuned hex pairs. - Keep out-of-gamut colors in the pipeline as long as you like — conversions are lossless. Check
isDisplayable()before handing a color to something that can't represent it, and let the formatters clamp at the display boundary.