suaveplan/packages/media/image/colours/README.md

@suaveplan/colours - Universal colour manipulation: parsing, conversion, analysis, mixing, blending, and palette generation

Universal colour manipulation library: parsing, conversion, analysis, mixing, blending, and palette generation. Parses hex (3/4/6/8 digit), CSS rgb(), hsl(), lab(), lch(), oklab(), oklch(), named colours, and plain objects. Converts between RGB, HSL, HSV, LAB, LCH, OKLAB, OKLCH, XYZ, and CMYK. Supports manipulation (lighten, darken, saturate, desaturate, rotate, alpha, fade, opaquer, negate, grayscale, mix), analysis (luminance, perceived brightness, contrast ratio, distance), and factories (random colours, temperature-based black-body curves, blend modes, gradient steps, harmonious palettes).

Documentation tree

• colour — colour.ts implements the Colour class — an immutable, chainable colour value object. It wraps an internal RGBA st…
  • colour-formatters — colour-formatters.ts provides deterministic string-formatting functions for every colour representation supported by…
  • colour — colour.ts implements the Colour class — an immutable, chainable colour value object. It wraps an internal RGBA st…
• colour-factories — colour-factories.ts provides pure, deterministic helpers for generating colours and colour collections. It is complet…
  • colour-factories — colour-factories.ts provides pure, deterministic helpers for generating colours and colour collections. It is complet…
• conversions — conversions.ts provides deterministic, side-effect-free mathematical transforms between colour spaces. Every function…
  • conversions — conversions.ts provides deterministic, side-effect-free mathematical transforms between colour spaces. Every function…
• error-codes — error-codes.ts declares the canonical error-code registry for @suaveplan/colours. Every failure mode that the colou…
  • error-codes — error-codes.ts declares the canonical error-code registry for @suaveplan/colours. Every failure mode that the colou…
• errors — errors.ts provides the typed error hierarchy for @suaveplan/colours. ColourError extends SuaveplanError so that…
  • errors — errors.ts provides the typed error hierarchy for @suaveplan/colours. ColourError extends SuaveplanError so that…
• parser — parser.ts converts arbitrary colour input into a canonical RGBA object. It supports hex strings (3/4/6/8 digit), mo…
  • parser — parser.ts converts arbitrary colour input into a canonical RGBA object. It supports hex strings (3/4/6/8 digit), mo…
• colour-types — colour-types.ts is the universal type system and Zod schema registry for @suaveplan/colours. It defines TypeSc…
  • colour-types — colour-types.ts is the universal type system and Zod schema registry for @suaveplan/colours. It defines TypeSc…
• utils — utils.ts provides small, pure mathematical utilities used throughout @suaveplan/colours. Every function is determin…
  • utils — utils.ts provides small, pure mathematical utilities used throughout @suaveplan/colours. Every function is determin…

Installation

bun add @suaveplan/colours

Quick Start

import { Colour } from "@suaveplan/colours";

const c = new Colour("#ff9900");
console.log(c.lighten(0.2).toHex()); // "#ffb34d"
console.log(c.isDark()); // false
console.log(c.contrast("#ffffff")); // WCAG contrast ratio

Modules

• src/colour/colour.md — Colour class and instance methods
• src/colour/colour-formatters.md — Output formatters (hex, rgb, hsl, etc.)
• src/colour-factories/colour-factories.md — Random colours, temperature, blend modes, palettes
• src/conversions/conversions.md — Colour-space conversion functions
• src/parser/parser.md — parseColour input parser
• src/types/colour-types/colour-types.md — TypeScript interfaces and Zod schemas
• src/utils/utils.md — Clamping and rounding utilities
• src/errors/errors.md — ColourError hierarchy and typed factories
• src/error-codes/error-codes.md — COLOUR_CODES registry

Subpath Exports

• @suaveplan/colours/colour — Colour class
• @suaveplan/colours/parser — parseColour
• @suaveplan/colours/conversions — colour-space conversion functions
• @suaveplan/colours/types — TypeScript interfaces and Zod schemas
• @suaveplan/colours/utils — clamping and rounding utilities
• @suaveplan/colours/errors — ColourError and factory functions
• @suaveplan/colours/error-codes — COLOUR_CODES registry