@readytools/colors is a lightweight, zero-dependency library for color conversion, accessibility contrast checks, and palette generation. The package is distributed as an ECMAScript Module (ESM) and is intended for use in modern JavaScript environments.

Requirements

A modern JavaScript runtime with native ESM support.
Compatible frameworks include Next.js, Vite, Astro, and other ESM-based build tools.
CommonJS (require) is not supported; transpilation is required if your environment does not support ESM.

Installation

Install the package from npm using the following command:

bash

npm install @readytools/colors

Importing the Library

Functions can be imported individually. This ensures only the necessary utilities are included in your application bundle:

js

import { hexToRgb, rgbToHex, scale, getContrastColor, toCSS } from "@readytools/colors";

Verification Example

After installation, verify the setup by running the following example:

js

const rgb = hexToRgb("#ff6600");            // { r: 255, g: 102, b: 0 }
const hex = rgbToHex(rgb.r, rgb.g, rgb.b);  // "#ff6600"
console.log({ rgb, hex });

Common Usage

The library provides utilities for common color tasks. Examples include selecting a readable text color and performing conversions:

js

const bg = "#ff6600";
const text = getContrastColor(bg);
const css = toCSS(bg, "background-color", "oklch");
const ramp = scale("#ff6600", "#0066ff", 7, { space: "oklch" });

hexToRgb("#0af");
rgbToHex(0, 170, 255);

Supported Features

Color conversions: HEX, RGB, HSL, CMYK, XYZ, Lab, OKLab, and OKLCH.
Accessibility tools: luminance, contrast ratio, automatic contrast text color, and contrast adjustment.
Color difference: CIE76 and CIEDE2000 Delta E utilities.
Adjustments: lighten, darken, saturate, desaturate, hue rotation, inversion, and mixing.
Random generation: constrained random colors via randomColor and random.
Interpolation: RGB, HSL, Lab, OKLab, and OKLCH ramps via interpolate and scale.
Tailwind helpers: generated 50..950 palettes and Tailwind config fragments.
Palette generators: shades, tints, tones, hue variants, and perceptual shade scales.
Validation and parsing: hex validation, normalization, HEX alpha, OKLab, and OKLCH parsing.
CSS helpers: export colors directly as CSS declarations, including OKLab and OKLCH.

Environment Notes

This package is distributed as ESM only.
For CommonJS environments, transpilation or migration to ESM is required.
Errors such as "require() of ES Module not supported" indicate that your environment does not support ESM.