@luntta/swatch 3.0.0

package/src/data/cvd-matrices.js

@@ -0,0 +1,179 @@
+// CVD (Color Vision Deficiency) simulation matrices.
+//
+// We build dichromat projection matrices in linear sRGB space by
+// lifting the LMS plane projection through standard linear-RGB ↔ LMS
+// transforms:
+//
+//   M_RGB = M_LMS→RGB · M_dichromat_LMS · M_RGB→LMS
+//
+// The LMS plane for each dichromat type is constructed via the
+// Brettel/Viénot anchor-line method: the plane passes through white
+// and a confusion-line anchor (blue for protan/deutan, red for
+// tritan). The missing cone's response is reconstructed as
+// a·X + b·Y in LMS space, solved via Cramer's rule.
+
+import { multiplyMatrices, invertMatrix } from "../util/matrix.js";
+import { appendSuggestion } from "../util/suggest.js";
+
+const CVD_TYPES = [
+	"protan",
+	"protanopia",
+	"protanomaly",
+	"deutan",
+	"deuteranopia",
+	"deuteranomaly",
+	"tritan",
+	"tritanopia",
+	"tritanomaly",
+	"achroma",
+	"achromatopsia",
+	"achromatomaly"
+];
+
+// sRGB→XYZ (D65), ported from src/swatch.js:1737-1743.
+const M_RGB_TO_XYZ = [
+	[0.4124564, 0.3575761, 0.1804375],
+	[0.2126729, 0.7151522, 0.072175],
+	[0.0193339, 0.119192, 0.9503041]
+];
+
+// Hunt-Pointer-Estevez XYZ→LMS (normalized to equal-energy).
+const M_XYZ_TO_LMS = [
+	[0.4002, 0.7076, -0.0808],
+	[-0.2263, 1.1653, 0.0457],
+	[0, 0, 0.9182]
+];
+
+export const M_LINEAR_RGB_TO_LMS = multiplyMatrices(
+	M_XYZ_TO_LMS,
+	M_RGB_TO_XYZ
+);
+export const M_LMS_TO_LINEAR_RGB = invertMatrix(M_LINEAR_RGB_TO_LMS);
+
+function mat3mul3(M, v) {
+	return [
+		M[0][0] * v[0] + M[0][1] * v[1] + M[0][2] * v[2],
+		M[1][0] * v[0] + M[1][1] * v[1] + M[1][2] * v[2],
+		M[2][0] * v[0] + M[2][1] * v[1] + M[2][2] * v[2]
+	];
+}
+
+function linearRgbToLms(rgb) {
+	return mat3mul3(M_LINEAR_RGB_TO_LMS, rgb);
+}
+
+// LMS primaries used as dichromat anchors.
+const blueLms = linearRgbToLms([0, 0, 1]);
+const redLms = linearRgbToLms([1, 0, 0]);
+const whiteLms = linearRgbToLms([1, 1, 1]);
+
+// Protan: L is missing → L = a·M + b·S, anchor = blue.
+function dichromatProtanopia() {
+	const wL = whiteLms[0],
+		wM = whiteLms[1],
+		wS = whiteLms[2];
+	const bL = blueLms[0],
+		bM = blueLms[1],
+		bS = blueLms[2];
+	const det = wM * bS - bM * wS;
+	const a = (wL * bS - bL * wS) / det;
+	const b = (wM * bL - bM * wL) / det;
+	return [
+		[0, a, b],
+		[0, 1, 0],
+		[0, 0, 1]
+	];
+}
+
+// Deutan: M is missing → M = a·L + b·S, anchor = blue.
+function dichromatDeuteranopia() {
+	const wL = whiteLms[0],
+		wM = whiteLms[1],
+		wS = whiteLms[2];
+	const bL = blueLms[0],
+		bM = blueLms[1],
+		bS = blueLms[2];
+	const det = wL * bS - bL * wS;
+	const a = (wM * bS - bM * wS) / det;
+	const b = (wL * bM - bL * wM) / det;
+	return [
+		[1, 0, 0],
+		[a, 0, b],
+		[0, 0, 1]
+	];
+}
+
+// Tritan: S is missing → S = a·L + b·M, anchor = red.
+function dichromatTritanopia() {
+	const wL = whiteLms[0],
+		wM = whiteLms[1];
+	const rL = redLms[0],
+		rM = redLms[1],
+		rS = redLms[2];
+	const det = wL * rM - rL * wM;
+	const a = (whiteLms[2] * rM - rS * wM) / det;
+	const b = (wL * rS - rL * whiteLms[2]) / det;
+	return [
+		[1, 0, 0],
+		[0, 1, 0],
+		[a, b, 0]
+	];
+}
+
+function buildRgbMatrix(dichromatLms) {
+	return multiplyMatrices(
+		M_LMS_TO_LINEAR_RGB,
+		multiplyMatrices(dichromatLms, M_LINEAR_RGB_TO_LMS)
+	);
+}
+
+export const CVD_RGB_MATRICES = {
+	protan: buildRgbMatrix(dichromatProtanopia()),
+	deutan: buildRgbMatrix(dichromatDeuteranopia()),
+	tritan: buildRgbMatrix(dichromatTritanopia())
+};
+
+export function normalizeCVDType(type) {
+	if (typeof type !== "string") {
+		throw new Error("CVD type must be a string");
+	}
+	const t = type.toLowerCase();
+	if (t === "protan" || t === "protanopia" || t === "protanomaly")
+		return "protan";
+	if (t === "deutan" || t === "deuteranopia" || t === "deuteranomaly")
+		return "deutan";
+	if (t === "tritan" || t === "tritanopia" || t === "tritanomaly")
+		return "tritan";
+	if (t === "achroma" || t === "achromatopsia" || t === "achromatomaly")
+		return "achroma";
+	throw new Error(
+		appendSuggestion(`Unknown CVD type: ${type}`, type, CVD_TYPES)
+	);
+}
+
+export const IDENTITY3 = [
+	[1, 0, 0],
+	[0, 1, 0],
+	[0, 0, 1]
+];
+
+// Rec. 709 luminance row, used for the achromatopsia projection.
+export const ACHROMA_MATRIX = [
+	[0.2126, 0.7152, 0.0722],
+	[0.2126, 0.7152, 0.0722],
+	[0.2126, 0.7152, 0.0722]
+];
+
+export function interpolateMatrix3(A, B, t) {
+	const out = [
+		[0, 0, 0],
+		[0, 0, 0],
+		[0, 0, 0]
+	];
+	for (let i = 0; i < 3; i++) {
+		for (let j = 0; j < 3; j++) {
+			out[i][j] = A[i][j] + (B[i][j] - A[i][j]) * t;
+		}
+	}
+	return out;
+}

package/src/data/named-colors.js

@@ -0,0 +1,157 @@
+// CSS Color Module Level 4 named-color list. Lowercase keys → 6-digit
+// hex (without leading "#"). Includes the legacy `transparent` keyword
+// (mapped to fully transparent black) and the British/American
+// `grey`/`gray` synonyms.
+
+const namedColors = {
+	aliceblue: "f0f8ff",
+	antiquewhite: "faebd7",
+	aqua: "00ffff",
+	aquamarine: "7fffd4",
+	azure: "f0ffff",
+	beige: "f5f5dc",
+	bisque: "ffe4c4",
+	black: "000000",
+	blanchedalmond: "ffebcd",
+	blue: "0000ff",
+	blueviolet: "8a2be2",
+	brown: "a52a2a",
+	burlywood: "deb887",
+	cadetblue: "5f9ea0",
+	chartreuse: "7fff00",
+	chocolate: "d2691e",
+	coral: "ff7f50",
+	cornflowerblue: "6495ed",
+	cornsilk: "fff8dc",
+	crimson: "dc143c",
+	cyan: "00ffff",
+	darkblue: "00008b",
+	darkcyan: "008b8b",
+	darkgoldenrod: "b8860b",
+	darkgray: "a9a9a9",
+	darkgreen: "006400",
+	darkgrey: "a9a9a9",
+	darkkhaki: "bdb76b",
+	darkmagenta: "8b008b",
+	darkolivegreen: "556b2f",
+	darkorange: "ff8c00",
+	darkorchid: "9932cc",
+	darkred: "8b0000",
+	darksalmon: "e9967a",
+	darkseagreen: "8fbc8f",
+	darkslateblue: "483d8b",
+	darkslategray: "2f4f4f",
+	darkslategrey: "2f4f4f",
+	darkturquoise: "00ced1",
+	darkviolet: "9400d3",
+	deeppink: "ff1493",
+	deepskyblue: "00bfff",
+	dimgray: "696969",
+	dimgrey: "696969",
+	dodgerblue: "1e90ff",
+	firebrick: "b22222",
+	floralwhite: "fffaf0",
+	forestgreen: "228b22",
+	fuchsia: "ff00ff",
+	gainsboro: "dcdcdc",
+	ghostwhite: "f8f8ff",
+	gold: "ffd700",
+	goldenrod: "daa520",
+	gray: "808080",
+	green: "008000",
+	greenyellow: "adff2f",
+	grey: "808080",
+	honeydew: "f0fff0",
+	hotpink: "ff69b4",
+	indianred: "cd5c5c",
+	indigo: "4b0082",
+	ivory: "fffff0",
+	khaki: "f0e68c",
+	lavender: "e6e6fa",
+	lavenderblush: "fff0f5",
+	lawngreen: "7cfc00",
+	lemonchiffon: "fffacd",
+	lightblue: "add8e6",
+	lightcoral: "f08080",
+	lightcyan: "e0ffff",
+	lightgoldenrodyellow: "fafad2",
+	lightgray: "d3d3d3",
+	lightgreen: "90ee90",
+	lightgrey: "d3d3d3",
+	lightpink: "ffb6c1",
+	lightsalmon: "ffa07a",
+	lightseagreen: "20b2aa",
+	lightskyblue: "87cefa",
+	lightslategray: "778899",
+	lightslategrey: "778899",
+	lightsteelblue: "b0c4de",
+	lightyellow: "ffffe0",
+	lime: "00ff00",
+	limegreen: "32cd32",
+	linen: "faf0e6",
+	magenta: "ff00ff",
+	maroon: "800000",
+	mediumaquamarine: "66cdaa",
+	mediumblue: "0000cd",
+	mediumorchid: "ba55d3",
+	mediumpurple: "9370db",
+	mediumseagreen: "3cb371",
+	mediumslateblue: "7b68ee",
+	mediumspringgreen: "00fa9a",
+	mediumturquoise: "48d1cc",
+	mediumvioletred: "c71585",
+	midnightblue: "191970",
+	mintcream: "f5fffa",
+	mistyrose: "ffe4e1",
+	moccasin: "ffe4b5",
+	navajowhite: "ffdead",
+	navy: "000080",
+	oldlace: "fdf5e6",
+	olive: "808000",
+	olivedrab: "6b8e23",
+	orange: "ffa500",
+	orangered: "ff4500",
+	orchid: "da70d6",
+	palegoldenrod: "eee8aa",
+	palegreen: "98fb98",
+	paleturquoise: "afeeee",
+	palevioletred: "db7093",
+	papayawhip: "ffefd5",
+	peachpuff: "ffdab9",
+	peru: "cd853f",
+	pink: "ffc0cb",
+	plum: "dda0dd",
+	powderblue: "b0e0e6",
+	purple: "800080",
+	rebeccapurple: "663399",
+	red: "ff0000",
+	rosybrown: "bc8f8f",
+	royalblue: "4169e1",
+	saddlebrown: "8b4513",
+	salmon: "fa8072",
+	sandybrown: "f4a460",
+	seagreen: "2e8b57",
+	seashell: "fff5ee",
+	sienna: "a0522d",
+	silver: "c0c0c0",
+	skyblue: "87ceeb",
+	slateblue: "6a5acd",
+	slategray: "708090",
+	slategrey: "708090",
+	snow: "fffafa",
+	springgreen: "00ff7f",
+	steelblue: "4682b4",
+	tan: "d2b48c",
+	teal: "008080",
+	thistle: "d8bfd8",
+	tomato: "ff6347",
+	turquoise: "40e0d0",
+	violet: "ee82ee",
+	wheat: "f5deb3",
+	white: "ffffff",
+	whitesmoke: "f5f5f5",
+	yellow: "ffff00",
+	yellowgreen: "9acd32"
+};
+
+export default namedColors;

package/src/format/css.js

@@ -0,0 +1,256 @@
+// CSS Color 4 serializer.
+//
+// `formatCss(swatch, opts)` returns a CSS string. `opts.format` picks
+// the form; if omitted we pick the best default for the swatch's source
+// space (preserving it losslessly where possible).
+//
+// Supported formats:
+//   'hex'          — #rrggbb (drops alpha)
+//   'hex-alpha'    — #rrggbbaa
+//   'rgb'          — rgb(r g b) or rgb(r g b / a)   (modern slash syntax)
+//   'rgb-legacy'   — rgb(r, g, b) or rgba(r, g, b, a)
+//   'hsl'          — hsl(h s% l%) modern
+//   'hsl-legacy'   — hsl(h, s%, l%) / hsla(...)
+//   'hwb'          — hwb(h w% b%)
+//   'lab'          — lab(L a b)  (D50, CSS spec)
+//   'lch'          — lch(L C H)
+//   'oklab'        — oklab(L a b)
+//   'oklch'        — oklch(L C H)
+//   'color'        — color(<space> r g b [/ a])  — uses the source space
+//
+// Precision: numbers are serialized with up to 6 significant digits by
+// default to keep strings short; pass `{ precision }` to override.
+
+const DEFAULT_PRECISION = 6;
+
+function fmtNum(n, precision = DEFAULT_PRECISION) {
+	if (!Number.isFinite(n)) return "0";
+	if (n === 0) return "0";
+	// Strip trailing zeros after toPrecision.
+	const s = n.toPrecision(precision);
+	// toPrecision may return scientific notation for very small/large; for
+	// color values we'd rather see fixed form within a sane range.
+	if (s.indexOf("e") < 0) {
+		return parseFloat(s).toString();
+	}
+	return parseFloat(n.toFixed(precision)).toString();
+}
+
+function fmtInt(n) {
+	return Math.round(n).toString();
+}
+
+function fmtAlpha(a, precision = DEFAULT_PRECISION) {
+	if (a >= 1) return "1";
+	if (a <= 0) return "0";
+	return fmtNum(a, precision);
+}
+
+function hex2(n) {
+	const v = Math.max(0, Math.min(255, Math.round(n * 255)));
+	return v.toString(16).padStart(2, "0");
+}
+
+function toHex(swatch, withAlpha) {
+	const { r, g, b } = swatch.srgb;
+	const base = "#" + hex2(r) + hex2(g) + hex2(b);
+	if (withAlpha) return base + hex2(swatch.alpha);
+	return base;
+}
+
+function toRgbModern(swatch, precision) {
+	const { r, g, b } = swatch.srgb;
+	const R = fmtInt(r * 255);
+	const G = fmtInt(g * 255);
+	const B = fmtInt(b * 255);
+	if (swatch.alpha < 1) {
+		return `rgb(${R} ${G} ${B} / ${fmtAlpha(swatch.alpha, precision)})`;
+	}
+	return `rgb(${R} ${G} ${B})`;
+}
+
+function toRgbLegacy(swatch, precision) {
+	const { r, g, b } = swatch.srgb;
+	const R = fmtInt(r * 255);
+	const G = fmtInt(g * 255);
+	const B = fmtInt(b * 255);
+	if (swatch.alpha < 1) {
+		return `rgba(${R}, ${G}, ${B}, ${fmtAlpha(swatch.alpha, precision)})`;
+	}
+	return `rgb(${R}, ${G}, ${B})`;
+}
+
+function toHslModern(swatch, precision) {
+	const { h, s, l } = swatch.hsl;
+	const H = fmtNum(h, precision);
+	const S = fmtNum(s, precision);
+	const L = fmtNum(l, precision);
+	if (swatch.alpha < 1) {
+		return `hsl(${H} ${S}% ${L}% / ${fmtAlpha(swatch.alpha, precision)})`;
+	}
+	return `hsl(${H} ${S}% ${L}%)`;
+}
+
+function toHslLegacy(swatch, precision) {
+	const { h, s, l } = swatch.hsl;
+	const H = fmtNum(h, precision);
+	const S = fmtNum(s, precision);
+	const L = fmtNum(l, precision);
+	if (swatch.alpha < 1) {
+		return `hsla(${H}, ${S}%, ${L}%, ${fmtAlpha(swatch.alpha, precision)})`;
+	}
+	return `hsl(${H}, ${S}%, ${L}%)`;
+}
+
+function toHwb(swatch, precision) {
+	const { h, w, b } = swatch.hwb;
+	const H = fmtNum(h, precision);
+	const W = fmtNum(w, precision);
+	const B = fmtNum(b, precision);
+	if (swatch.alpha < 1) {
+		return `hwb(${H} ${W}% ${B}% / ${fmtAlpha(swatch.alpha, precision)})`;
+	}
+	return `hwb(${H} ${W}% ${B}%)`;
+}
+
+function toLab(swatch, precision) {
+	// CSS lab() is D50.
+	const coords = swatch._getCoordsIn("lab-d50");
+	const L = fmtNum(coords[0], precision);
+	const a = fmtNum(coords[1], precision);
+	const b = fmtNum(coords[2], precision);
+	if (swatch.alpha < 1) {
+		return `lab(${L} ${a} ${b} / ${fmtAlpha(swatch.alpha, precision)})`;
+	}
+	return `lab(${L} ${a} ${b})`;
+}
+
+function toLch(swatch, precision) {
+	const coords = swatch._getCoordsIn("lch-d50");
+	const L = fmtNum(coords[0], precision);
+	const C = fmtNum(coords[1], precision);
+	const H = fmtNum(coords[2], precision);
+	if (swatch.alpha < 1) {
+		return `lch(${L} ${C} ${H} / ${fmtAlpha(swatch.alpha, precision)})`;
+	}
+	return `lch(${L} ${C} ${H})`;
+}
+
+function toOklab(swatch, precision) {
+	const { l, a, b } = swatch.oklab;
+	const L = fmtNum(l, precision);
+	const A = fmtNum(a, precision);
+	const B = fmtNum(b, precision);
+	if (swatch.alpha < 1) {
+		return `oklab(${L} ${A} ${B} / ${fmtAlpha(swatch.alpha, precision)})`;
+	}
+	return `oklab(${L} ${A} ${B})`;
+}
+
+function toOklch(swatch, precision) {
+	const { l, c, h } = swatch.oklch;
+	const L = fmtNum(l, precision);
+	const C = fmtNum(c, precision);
+	const H = fmtNum(h, precision);
+	if (swatch.alpha < 1) {
+		return `oklch(${L} ${C} ${H} / ${fmtAlpha(swatch.alpha, precision)})`;
+	}
+	return `oklch(${L} ${C} ${H})`;
+}
+
+// Map registry ids back to CSS color() space tokens.
+const SPACE_TO_COLOR_FN = {
+	srgb: "srgb",
+	"srgb-linear": "srgb-linear",
+	"display-p3": "display-p3",
+	rec2020: "rec2020",
+	a98: "a98-rgb",
+	prophoto: "prophoto-rgb",
+	xyz: "xyz-d65",
+	"xyz-d65": "xyz-d65",
+	"xyz-d50": "xyz-d50"
+};
+
+function toColorFn(swatch, precision, spaceOverride) {
+	const spaceId = spaceOverride || swatch.space;
+	const token = SPACE_TO_COLOR_FN[spaceId];
+	if (!token) {
+		throw new Error(
+			`formatCss: space "${spaceId}" has no color() serialization`
+		);
+	}
+	const coords = swatch._getCoordsIn(spaceId);
+	const c1 = fmtNum(coords[0], precision);
+	const c2 = fmtNum(coords[1], precision);
+	const c3 = fmtNum(coords[2], precision);
+	if (swatch.alpha < 1) {
+		return `color(${token} ${c1} ${c2} ${c3} / ${fmtAlpha(swatch.alpha, precision)})`;
+	}
+	return `color(${token} ${c1} ${c2} ${c3})`;
+}
+
+// Pick a default format for a swatch based on its source space.
+function defaultFormat(swatch) {
+	switch (swatch.space) {
+		case "srgb":
+			return swatch.alpha < 1 ? "rgb" : "hex";
+		case "hsl":
+			return "hsl";
+		case "hwb":
+			return "hwb";
+		case "lab":
+		case "lab-d50":
+			return "lab";
+		case "lch":
+		case "lch-d50":
+			return "lch";
+		case "oklab":
+			return "oklab";
+		case "oklch":
+			return "oklch";
+		case "display-p3":
+		case "rec2020":
+		case "a98":
+		case "prophoto":
+		case "srgb-linear":
+		case "xyz":
+		case "xyz-d65":
+		case "xyz-d50":
+			return "color";
+		default:
+			return "hex";
+	}
+}
+
+export function formatCss(swatch, opts = {}) {
+	const precision = opts.precision ?? DEFAULT_PRECISION;
+	const format = opts.format ?? defaultFormat(swatch);
+	switch (format) {
+		case "hex":
+			return toHex(swatch, false);
+		case "hex-alpha":
+			return toHex(swatch, true);
+		case "rgb":
+			return toRgbModern(swatch, precision);
+		case "rgb-legacy":
+			return toRgbLegacy(swatch, precision);
+		case "hsl":
+			return toHslModern(swatch, precision);
+		case "hsl-legacy":
+			return toHslLegacy(swatch, precision);
+		case "hwb":
+			return toHwb(swatch, precision);
+		case "lab":
+			return toLab(swatch, precision);
+		case "lch":
+			return toLch(swatch, precision);
+		case "oklab":
+			return toOklab(swatch, precision);
+		case "oklch":
+			return toOklch(swatch, precision);
+		case "color":
+			return toColorFn(swatch, precision, opts.space);
+		default:
+			throw new Error(`formatCss: unknown format "${format}"`);
+	}
+}

package/src/operations/accessibility.js

@@ -0,0 +1,103 @@
+// WCAG 2.1 accessibility helpers.
+//
+//   luminance(c)     — relative luminance (Y) per WCAG 2.1
+//   contrast(a, b)   — WCAG contrast ratio, symmetric, clamped ≥ 1
+//   isReadable(a, b, { level, size }) — checks WCAG AA/AAA thresholds
+//   ensureContrast(a, b, { minRatio, direction, step }) —
+//     walks HSL L (preserving hue/saturation) until the ratio meets
+//     the target. Future: add { space: 'oklch' } to walk OKLCh L.
+//
+// These operate on displayable sRGB values. Wide-gamut inputs are
+// first gamut-mapped into sRGB before the metric is computed.
+
+import { Swatch, swatch } from "../core/swatch-class.js";
+import { inGamut, toGamut } from "./gamut.js";
+
+function toSwatch(input) {
+	return input instanceof Swatch ? input : swatch(input);
+}
+
+function toAccessibleSrgb(input) {
+	const s = toSwatch(input);
+	if (inGamut(s, "srgb")) return s.to("srgb");
+	return toGamut(s, { space: "srgb" });
+}
+
+// WCAG 2.1 relative luminance from gamma-encoded sRGB in [0,1].
+export function luminance(input) {
+	const s = toAccessibleSrgb(input);
+	const { r, g, b } = s.srgb;
+	const rl =
+		r <= 0.03928 ? r / 12.92 : Math.pow((r + 0.055) / 1.055, 2.4);
+	const gl =
+		g <= 0.03928 ? g / 12.92 : Math.pow((g + 0.055) / 1.055, 2.4);
+	const bl =
+		b <= 0.03928 ? b / 12.92 : Math.pow((b + 0.055) / 1.055, 2.4);
+	return 0.2126 * rl + 0.7152 * gl + 0.0722 * bl;
+}
+
+export function contrast(a, b) {
+	const la = luminance(a);
+	const lb = luminance(b);
+	const ratio = (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+	return ratio;
+}
+
+// Thresholds:
+//   normal AA = 4.5, normal AAA = 7
+//   large  AA = 3,   large  AAA = 4.5
+//   ui       = 3 (AA only per WCAG 2.1)
+export function isReadable(a, b, { level = "AA", size = "normal" } = {}) {
+	let threshold;
+	if (size === "large") {
+		threshold = level === "AAA" ? 4.5 : 3;
+	} else if (size === "ui") {
+		threshold = 3;
+	} else {
+		threshold = level === "AAA" ? 7 : 4.5;
+	}
+	return contrast(a, b) >= threshold;
+}
+
+// Walk the HSL L of `color` until contrast against `other` meets
+// `minRatio`. If one direction fails, try the other; if neither
+// succeeds, fall back to pure white or black.
+export function ensureContrast(
+	color,
+	other,
+	{ minRatio = 4.5, direction = "auto", step = 1 } = {}
+) {
+	const original = toSwatch(color);
+	const cs = toAccessibleSrgb(color);
+	const os = toAccessibleSrgb(other);
+
+	if (contrast(cs, os) >= minRatio) return original;
+
+	let dir = direction;
+	if (dir === "auto") {
+		dir = luminance(os) > 0.5 ? "darker" : "lighter";
+	}
+
+	const baseHsl = cs.hsl;
+
+	function tryWalk(sign) {
+		let l = baseHsl.l;
+		while (true) {
+			l += sign * step;
+			if (l < 0 || l > 100) return null;
+			const candidate = swatch({
+				space: "hsl",
+				coords: [baseHsl.h, baseHsl.s, l],
+				alpha: cs.alpha
+			});
+			if (contrast(candidate, os) >= minRatio) return candidate;
+		}
+	}
+
+	const primary = tryWalk(dir === "lighter" ? 1 : -1);
+	if (primary) return primary;
+	const fallback = tryWalk(dir === "lighter" ? -1 : 1);
+	if (fallback) return fallback;
+
+	return swatch(luminance(os) > 0.5 ? "#000000" : "#ffffff");
+}