first commit

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

@@ -0,0 +1,88 @@
+# colour
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## 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
+
+```ts
+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
+
+```ts
+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.