first commit

docs/media/image/colour-convert-cmyk/README.md

@@ -0,0 +1,32 @@
+# @suaveplan/colour-convert-cmyk - Bidirectional RGB <-> CMYK colour space conversion with black generation for print workflows
+
+Bidirectional conversion between RGB and CMYK colour spaces using the standard Euclidean algorithm with black generation. CMYK is the subtractive model used in professional printing; these conversions are essential for print preview, pre-press workflows, and bridging screen colours with physical output.
+
+<!-- begin:auto-docs -->
+## Documentation tree
+
+- [cmyk](./src/cmyk/cmyk.md) — `cmyk.ts` provides bidirectional conversion between RGB and CMYK colour spaces. CMYK is the subtractive model used in p…
+  - [cmyk](./src/cmyk/cmyk.md) — `cmyk.ts` provides bidirectional conversion between RGB and CMYK colour spaces. CMYK is the subtractive model used in p…
+<!-- end:auto-docs -->
+
+## Installation
+
+```bash
+bun add @suaveplan/colour-convert-cmyk
+```
+
+## Quick Start
+
+```ts
+import { rgbToCmyk, cmykToRgb } from "@suaveplan/colour-convert-cmyk";
+
+const ink = rgbToCmyk({ r: 59, g: 130, b: 246 });
+console.log(ink); // { c: 76, m: 47, y: 0, k: 4 }
+
+const screen = cmykToRgb(ink);
+console.log(screen); // { r: 59, g: 130, b: 246, a: 1 }
+```
+
+## Modules
+
+- [`src/cmyk/cmyk.md`](./src/cmyk/cmyk.md) — RGB↔CMYK conversion implementation and API reference

docs/media/image/colour-convert-cmyk/src/cmyk/cmyk.md

@@ -0,0 +1,47 @@
+# cmyk
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`cmyk.ts` provides bidirectional conversion between RGB and CMYK colour spaces. CMYK is the subtractive model used in professional printing, where colours are created by mixing cyan, magenta, yellow, and black inks. These conversions are essential for print preview, pre-press workflows, and any application that needs to bridge screen colours with physical output. While RGB is additive (light-emitting), CMYK is subtractive (light-absorbing), making direct translation necessary for accurate colour reproduction across media.
+
+## Features
+
+- RGB to CMYK conversion with black generation
+- CMYK to RGB conversion
+- Percentage-based CMYK output (0–100)
+- Handles edge cases like pure black and pure white
+
+## Usage: Basic Example
+
+```ts
+import { rgbToCmyk } from "@suaveplan/colour-convert-cmyk";
+
+const cmyk = rgbToCmyk({ r: 128, g: 64, b: 32 });
+```
+
+## Usage: Advanced Example
+
+```ts
+import { rgbToCmyk, cmykToRgb } from "@suaveplan/colour-convert-cmyk";
+
+const ink = rgbToCmyk({ r: 59, g: 130, b: 246 });
+const screen = cmykToRgb(ink);
+```
+
+## API Reference
+
+### `rgbToCmyk(rgb: RGB): CMYK`
+
+Converts an RGB colour to CMYK percentages. The black channel (`k`) is generated from the maximum of the inverted RGB channels, and the cyan, magenta, and yellow channels are computed relative to this black. This is the standard Euclidean algorithm used in most graphics software.
+
+### `cmykToRgb(cmyk: CMYK): RGBA`
+
+Converts CMYK percentages back to RGB. The formula applies the subtractive model in reverse: each RGB channel is the product of `(1 - ink) × (1 - black)`. The alpha channel is always set to 1 because CMYK has no native alpha channel.
+
+## Implementation Notes
+
+The conversion uses the standard Euclidean algorithm for RGB to CMYK. When the input colour is pure black (`k = 100%`), the cyan, magenta, and yellow channels are defined as zero to avoid division by zero. All CMYK values are rounded to the nearest integer percentage. The inverse conversion always produces alpha 1 because CMYK has no native alpha channel. Round-trip conversion may introduce small quantization errors due to the integer rounding of CMYK percentages.