suaveplan/openspec/archive/2026-05-22-2026-05-20-colour-plugins/proposal.md

Colour Plugin Ecosystem

Background

@suaveplan/colours (v0.1.0) shipped with core RGB/HSL/HSV/LAB/LCH/OKLAB/OKLCH/XYZ/CMYK support, parsing, mixing, blending, and palette generation. An audit of the ../chromatism/ third-party library revealed several colour-science features that are valuable for design-tool, accessibility, and print-media use cases but were out of scope for the core universal-tier package.

Scope

This change introduces four plugin packages that extend the colour system:

1. @suaveplan/colour-convert-hsluv — Perceptually uniform HSL variant with gamut mapping via HSLuv.org reference algorithm.
2. @suaveplan/colour-convert-cieluv — CIELUV, xyY, LMS cone response, and Bradford chromatic adaptation with CIE standard illuminants.
3. @suaveplan/colour-filter-cmc — CMC l:c Delta-E colour difference metric (configurable luminance and chroma weights).
4. @suaveplan/colour-filter-cct — Correlated Colour Temperature (CCT) in Kelvin via McCamy's formula, plus CCT-to-RGB approximation.

Out of Scope

• ICC profile parsing / embedding (requires WASM or native bindings)
• CVD / colour-blind simulation (Brettel/Viénot models — future change)
• 1D/3D LUT loading and application (future change)

Acceptance Criteria

• Each plugin package follows the genesis scaffold: package.json, tsconfig.lib.json, vitest.config.ts, vite.config.ts, README.md.
• Folder-per-file structure with explicit barrel exports.
• 100% Istanbul coverage on all src/**/*.ts.
• Sibling .md docs for every implementation file (≥200 words, required headings).
• dep-graph.test.ts and tree-shake.test.ts in every package.
• sideEffects: false in every package.json.
• All error codes use defineCodes from @suaveplan/error.
• All packages pass bunx turbo lint typecheck test build test:coverage.