skills/docs/media/image/colours/src/colour/colour.md

colour

(no submodules)

Purpose

colour.ts implements the Colour class — an immutable, chainable colour value object. It wraps an internal RGBA state and exposes methods for manipulation, analysis, conversion, and output formatting. The class is the primary public API surface for the package and is used by the colour-factories helpers.

Features

• Immutable chainable manipulation (lighten, darken, saturate, desaturate, rotate, alpha, fade, opaquer)
• Colour-space conversion methods (hex, RGB, HSL, HSV, LAB, LCH, OKLAB, OKLCH, CMYK)
• Analysis methods (luminance, perceived brightness, contrast ratio, isDark, isLight, best contrast, distance)
• Utility methods (negate, grayscale, mix, clone, equals, toString)
• Pure functional implementation with no mutation of internal state

Usage: Basic Example

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

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

Usage: Advanced Example

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

const brand = new Colour("#3b82f6");
const text = brand.bestContrast("#ffffff", "#1f2937");
console.log(text.toHex()); // "#ffffff"

API Reference

Constructor

• new Colour(input: ColourInput) — parses any supported colour input into an immutable Colour instance.

Manipulation

• lighten(amount: number): Colour
• darken(amount: number): Colour
• saturate(amount: number): Colour
• desaturate(amount: number): Colour
• rotate(degrees: number): Colour
• alpha(a: number): Colour
• fade(amount: number): Colour
• opaquer(amount: number): Colour
• negate(): Colour
• grayscale(): Colour
• mix(other: ColourInput, amount?: number): Colour

Analysis

• luminance(): number
• perceivedBrightness(): number
• contrast(other: ColourInput): number
• isDark(): boolean
• isLight(): boolean
• bestContrast(...candidates: (Colour | string)[]): Colour
• distance(other: ColourInput, mode?: DistanceMode): number
• equals(other: ColourInput): boolean

Output

• toHex(): string
• toHex3(): string
• toHex8(): string
• toRgb(): RGB
• toRgba(): RGBA
• toHsl(): HSL
• toHsv(): HSV
• toLab(): LAB
• toLch(): LCH
• toOklab(): OKLAB
• toOklch(): OKLCH
• toCmyk(): CMYK
• toString(): string

Implementation Notes

The internal _rgba state is never mutated. Every chainable method returns a new Colour instance. Conversion methods delegate to the conversions module. Analysis methods use the standard WCAG 2.1 luminance formula and sRGB gamma. The bestContrast helper uses the APCA-like perceived brightness for candidate ranking.