feat: release Colour Tools 0.1.0

public/docs/COLOUR-MATH.md

@@ -0,0 +1,94 @@
+# Colour mathematics and terminology
+
+This document records the choices that materially change a result. It is not a
+replacement for CSS Color, Compositing and Blending, or WCAG.
+
+## Parsing and conversion
+
+The parser accepts CSS colour syntax supported by the installed Color.js
+version, including hex and named colours; `rgb()`, `hsl()`, `hwb()`, Lab/LCH
+and OKLab/OKLCH functions; and registered `color()` spaces. Conversion keeps
+finite coordinates outside a target gamut. Hex and ordinary browser sRGB
+previews require mapping; the UI labels when this happened.
+
+The converter exposes device-oriented and mathematical representations, but a
+numeric tuple is meaningful only with its named colour space, white point,
+transfer curve and alpha convention. CMYK output is a convenient mathematical
+conversion, not a printer ICC separation or proof.
+
+## Alpha compositing
+
+For a source colour over a backdrop, with straight alpha `αs` and `αb`, output
+alpha is:
+
+```text
+αo = αs + αb × (1 − αs)
+```
+
+For each premultiplied channel under normal source-over:
+
+```text
+Co = Cs × αs + Cb × αb × (1 − αs)
+co = Co / αo                         when αo > 0
+```
+
+Layers are accumulated from the bottom upward even though the editor displays
+the top layer first. Layer opacity multiplies the colour's own alpha. Blend
+modes are applied before source-over using the model in CSS Compositing and
+Blending.
+
+“Encoded sRGB” applies the operation directly to sRGB-encoded channel values,
+matching many quick web calculators. “Linear-light sRGB” first removes the
+sRGB transfer curve and is generally the physically meaningful choice for
+mixing emitted light. The two results are expected to differ.
+
+## Interpolation
+
+A ramp samples its first and last stop and distributes missing positions like a
+CSS gradient. Each segment is interpolated in the selected space with the
+chosen easing. Cylindrical spaces need an explicit hue route: shorter, longer,
+increasing, decreasing or raw. The default premultiplies colour components by
+alpha before mixing and unpremultiplies afterwards, preventing hidden channels
+inside a transparent endpoint from tinting the ramp. A straight-alpha toggle
+is available for intentionally reproducing that model. OKLCH is the UI default
+because equal numeric progress tends to look more even than encoded RGB; it
+does not guarantee that every intermediate colour lies in a display gamut.
+
+## Gamut mapping
+
+An in-gamut check does not modify the colour. Display mapping uses an OKLCH
+chroma-reduction method by default; channel clipping is available at the engine
+boundary where explicitly selected. The result includes Delta E OK from the
+source so callers can quantify the change. A browser preview is always mapped
+to sRGB because CSS support and physical displays differ.
+
+## Contrast and transparency
+
+Relative luminance and WCAG 2 contrast are evaluated after translucent
+foreground/background colours are composited over the stated canvas (white by
+default). The ratio is:
+
+```text
+(Llighter + 0.05) / (Ldarker + 0.05)
+```
+
+The UI reports 3:1, 4.5:1 and 7:1 thresholds and searches for a nearby lighter
+or darker passing foreground. A mathematical pass is only one part of an
+accessibility review; font size/weight, focus states, disabled controls,
+non-colour cues and actual display conditions remain relevant.
+
+## Perceptual difference and simulations
+
+Delta E 76, CMC, CIEDE2000, Delta E OK, ITP and Jz answer different historical
+or application needs; values from different formulas are not interchangeable.
+The colour-vision previews apply bounded matrices in linear sRGB and expose a
+severity control. They are approximations for interface review, not a model of
+every observer and not medical advice.
+
+## Palette extraction
+
+The raster extractor ignores sufficiently transparent pixels, converts bounded
+samples to OKLab and clusters them deterministically. Reported coverage is the
+share of accepted samples assigned to a cluster, not an exact segmentation of
+every source pixel. Small antialiased regions and colour-managed decoding can
+therefore influence the result.