@ariaui/color 0.1.3 → 0.1.4

package/dist/index.cjs

@@ -0,0 +1,476 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __defProps = Object.defineProperties;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropDescs = Object.getOwnPropertyDescriptors;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getOwnPropSymbols = Object.getOwnPropertySymbols;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __propIsEnum = Object.prototype.propertyIsEnumerable;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __spreadValues = (a, b) => {
+  for (var prop in b || (b = {}))
+    if (__hasOwnProp.call(b, prop))
+      __defNormalProp(a, prop, b[prop]);
+  if (__getOwnPropSymbols)
+    for (var prop of __getOwnPropSymbols(b)) {
+      if (__propIsEnum.call(b, prop))
+        __defNormalProp(a, prop, b[prop]);
+    }
+  return a;
+};
+var __spreadProps = (a, b) => __defProps(a, __getOwnPropDescs(b));
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// index.ts
+var index_exports = {};
+__export(index_exports, {
+  adjustHue: () => adjustHue,
+  complement: () => complement,
+  contrastRatio: () => contrastRatio,
+  darken: () => darken,
+  desaturate: () => desaturate,
+  grayscale: () => grayscale,
+  hexToOklch: () => hexToOklch,
+  invert: () => invert,
+  lighten: () => lighten,
+  meetsAA: () => meetsAA,
+  meetsAAA: () => meetsAAA,
+  mix: () => mix,
+  oklabToOklch: () => oklabToOklch,
+  oklchToHex: () => oklchToHex,
+  oklchToOklab: () => oklchToOklab,
+  oklchToSrgb: () => oklchToSrgb,
+  parseHex: () => parseHex,
+  parseOklchChannels: () => parseOklchChannels,
+  parseOklchCss: () => parseOklchCss,
+  parseRgb: () => parseRgb,
+  saturate: () => saturate,
+  setAlpha: () => setAlpha,
+  srgbToHex: () => srgbToHex,
+  srgbToOklch: () => srgbToOklch,
+  suggestAccessible: () => suggestAccessible,
+  toCssChannels: () => toCssChannels,
+  toHexString: () => toHexString,
+  toOklchString: () => toOklchString,
+  toRgbString: () => toRgbString
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/parse.ts
+function parseOklchChannels(channels) {
+  const normalised = channels.trim();
+  const [colorPart, alphaPart] = normalised.split("/").map((s) => s.trim());
+  const parts = colorPart.split(/\s+/);
+  if (parts.length !== 3) {
+    throw new Error(
+      `Invalid OKLCH channel string: expected "L C H", got "${channels}"`
+    );
+  }
+  const [rawL, rawC, rawH] = parts;
+  let l;
+  if (rawL.endsWith("%")) {
+    l = parseFloat(rawL) / 100;
+  } else {
+    l = parseFloat(rawL);
+  }
+  const c = parseFloat(rawC);
+  const h = parseFloat(rawH);
+  if (Number.isNaN(l) || Number.isNaN(c) || Number.isNaN(h)) {
+    throw new Error(
+      `Invalid OKLCH channel string: could not parse numbers from "${channels}"`
+    );
+  }
+  let alpha = 1;
+  if (alphaPart !== void 0) {
+    alpha = parseFloat(alphaPart);
+    if (Number.isNaN(alpha)) {
+      throw new Error(
+        `Invalid OKLCH alpha value: could not parse "${alphaPart}"`
+      );
+    }
+  }
+  return { l, c, h, alpha };
+}
+function parseOklchCss(css) {
+  const match = css.match(/oklch\(\s*(.+?)\s*\)/i);
+  if (!match) {
+    throw new Error(`Invalid oklch() CSS string: "${css}"`);
+  }
+  return parseOklchChannels(match[1]);
+}
+function parseHex(hex) {
+  let h = hex.startsWith("#") ? hex.slice(1) : hex;
+  if (h.length === 3) {
+    h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2];
+  } else if (h.length === 4) {
+    h = h[0] + h[0] + h[1] + h[1] + h[2] + h[2] + h[3] + h[3];
+  }
+  if (h.length !== 6 && h.length !== 8) {
+    throw new Error(`Invalid hex color: "${hex}"`);
+  }
+  if (!/^[0-9a-fA-F]+$/.test(h)) {
+    throw new Error(`Invalid hex color: "${hex}"`);
+  }
+  const r = parseInt(h.slice(0, 2), 16) / 255;
+  const g = parseInt(h.slice(2, 4), 16) / 255;
+  const b = parseInt(h.slice(4, 6), 16) / 255;
+  const alpha = h.length === 8 ? parseInt(h.slice(6, 8), 16) / 255 : 1;
+  return { r, g, b, alpha };
+}
+function parseRgb(css) {
+  const match = css.match(/rgba?\(\s*(.+?)\s*\)/i);
+  if (!match) {
+    throw new Error(`Invalid rgb()/rgba() CSS string: "${css}"`);
+  }
+  const inner = match[1];
+  if (inner.includes("/")) {
+    const [colorPart, alphaPart] = inner.split("/").map((s) => s.trim());
+    const [r, g, b] = colorPart.split(/\s+/).map(Number);
+    const alpha = parseFloat(alphaPart);
+    return { r: r / 255, g: g / 255, b: b / 255, alpha };
+  }
+  if (inner.includes(",")) {
+    const parts2 = inner.split(",").map((s) => parseFloat(s.trim()));
+    return {
+      r: parts2[0] / 255,
+      g: parts2[1] / 255,
+      b: parts2[2] / 255,
+      alpha: parts2.length === 4 ? parts2[3] : 1
+    };
+  }
+  const parts = inner.split(/\s+/).map(Number);
+  if (parts.length !== 3) {
+    throw new Error(`Invalid rgb() CSS string: "${css}"`);
+  }
+  return { r: parts[0] / 255, g: parts[1] / 255, b: parts[2] / 255, alpha: 1 };
+}
+
+// src/convert.ts
+function oklchToOklab(c) {
+  const hRad = c.h * Math.PI / 180;
+  return {
+    L: c.l,
+    a: c.c * Math.cos(hRad),
+    b: c.c * Math.sin(hRad),
+    alpha: c.alpha
+  };
+}
+function oklabToOklch(lab) {
+  const c = Math.sqrt(lab.a * lab.a + lab.b * lab.b);
+  let h = Math.atan2(lab.b, lab.a) * 180 / Math.PI;
+  if (h < 0) h += 360;
+  if (c < 1e-8) h = 0;
+  return { l: lab.L, c, h, alpha: lab.alpha };
+}
+function oklabToLinearSrgb(lab) {
+  const l_ = lab.L + 0.3963377774 * lab.a + 0.2158037573 * lab.b;
+  const m_ = lab.L - 0.1055613458 * lab.a - 0.0638541728 * lab.b;
+  const s_ = lab.L - 0.0894841775 * lab.a - 1.291485548 * lab.b;
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+  const r = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+  const g = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+  const b = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+  return [r, g, b];
+}
+function linearSrgbToOklab(r, g, b) {
+  const l = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+  const m = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+  const s = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+  const l_ = Math.cbrt(l);
+  const m_ = Math.cbrt(m);
+  const s_ = Math.cbrt(s);
+  return {
+    L: 0.2104542553 * l_ + 0.793617785 * m_ - 0.0040720468 * s_,
+    a: 1.9779984951 * l_ - 2.428592205 * m_ + 0.4505937099 * s_,
+    b: 0.0259040371 * l_ + 0.7827717662 * m_ - 0.808675766 * s_,
+    alpha: 1
+  };
+}
+function linearToGamma(c) {
+  if (c <= 31308e-7) return 12.92 * c;
+  return 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+}
+function gammaToLinear(c) {
+  if (c <= 0.04045) return c / 12.92;
+  return Math.pow((c + 0.055) / 1.055, 2.4);
+}
+var GAMUT_EPSILON = 1e-6;
+var DELTA_E_TOLERANCE = 0.02;
+var CHROMA_STEP = 0.01;
+function deltaEOK(a, b) {
+  const dL = a.L - b.L;
+  const da = a.a - b.a;
+  const db = a.b - b.b;
+  return Math.sqrt(dL * dL + da * da + db * db);
+}
+function isInGamut(r, g, b) {
+  return r >= -GAMUT_EPSILON && r <= 1 + GAMUT_EPSILON && g >= -GAMUT_EPSILON && g <= 1 + GAMUT_EPSILON && b >= -GAMUT_EPSILON && b <= 1 + GAMUT_EPSILON;
+}
+function clampChannel(v) {
+  return Math.max(0, Math.min(1, v));
+}
+function gamutMapOklchToSrgb(color) {
+  if (color.l <= 0) return { r: 0, g: 0, b: 0, alpha: color.alpha };
+  if (color.l >= 1) return { r: 1, g: 1, b: 1, alpha: color.alpha };
+  const lab = oklchToOklab(color);
+  const [lr, lg, lb] = oklabToLinearSrgb(lab);
+  if (isInGamut(lr, lg, lb)) {
+    return {
+      r: linearToGamma(clampChannel(lr)),
+      g: linearToGamma(clampChannel(lg)),
+      b: linearToGamma(clampChannel(lb)),
+      alpha: color.alpha
+    };
+  }
+  let min = 0;
+  let max = color.c;
+  let mappedChroma = 0;
+  const zeroChromaLab = oklchToOklab(__spreadProps(__spreadValues({}, color), { c: 0 }));
+  const [zr, zg, zb] = oklabToLinearSrgb(zeroChromaLab);
+  if (!isInGamut(zr, zg, zb)) {
+    return {
+      r: linearToGamma(clampChannel(zr)),
+      g: linearToGamma(clampChannel(zg)),
+      b: linearToGamma(clampChannel(zb)),
+      alpha: color.alpha
+    };
+  }
+  while (max - min > CHROMA_STEP) {
+    const mid = (min + max) / 2;
+    const testColor = __spreadProps(__spreadValues({}, color), { c: mid });
+    const testLab = oklchToOklab(testColor);
+    const [tr, tg, tb] = oklabToLinearSrgb(testLab);
+    if (isInGamut(tr, tg, tb)) {
+      min = mid;
+      mappedChroma = mid;
+    } else {
+      const clampedR = clampChannel(tr);
+      const clampedG = clampChannel(tg);
+      const clampedB = clampChannel(tb);
+      const clampedLab = linearSrgbToOklab(clampedR, clampedG, clampedB);
+      const dE = deltaEOK(testLab, clampedLab);
+      if (dE <= DELTA_E_TOLERANCE) {
+        min = mid;
+        mappedChroma = mid;
+      } else {
+        max = mid;
+      }
+    }
+  }
+  const finalLab = oklchToOklab(__spreadProps(__spreadValues({}, color), { c: mappedChroma }));
+  const [fr, fg, fb] = oklabToLinearSrgb(finalLab);
+  return {
+    r: linearToGamma(clampChannel(fr)),
+    g: linearToGamma(clampChannel(fg)),
+    b: linearToGamma(clampChannel(fb)),
+    alpha: color.alpha
+  };
+}
+function oklchToSrgb(color) {
+  return gamutMapOklchToSrgb(color);
+}
+function srgbToOklch(color) {
+  const lr = gammaToLinear(color.r);
+  const lg = gammaToLinear(color.g);
+  const lb = gammaToLinear(color.b);
+  const lab = linearSrgbToOklab(lr, lg, lb);
+  return __spreadValues({}, oklabToOklch(__spreadProps(__spreadValues({}, lab), { alpha: color.alpha })));
+}
+function srgbToHex(color) {
+  const r = Math.round(clampChannel(color.r) * 255);
+  const g = Math.round(clampChannel(color.g) * 255);
+  const b = Math.round(clampChannel(color.b) * 255);
+  const hex = `#${r.toString(16).padStart(2, "0")}${g.toString(16).padStart(2, "0")}${b.toString(16).padStart(2, "0")}`;
+  if (color.alpha < 1) {
+    const a = Math.round(clampChannel(color.alpha) * 255);
+    return `${hex}${a.toString(16).padStart(2, "0")}`;
+  }
+  return hex;
+}
+function oklchToHex(color) {
+  return srgbToHex(oklchToSrgb(color));
+}
+function hexToOklch(hex) {
+  return srgbToOklch(parseHex(hex));
+}
+
+// src/manipulate.ts
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+function normaliseHue(h) {
+  return (h % 360 + 360) % 360;
+}
+function lighten(color, amount) {
+  return __spreadProps(__spreadValues({}, color), { l: clamp(color.l + amount, 0, 1) });
+}
+function darken(color, amount) {
+  return __spreadProps(__spreadValues({}, color), { l: clamp(color.l - amount, 0, 1) });
+}
+function saturate(color, amount) {
+  return __spreadProps(__spreadValues({}, color), { c: Math.max(0, color.c + amount) });
+}
+function desaturate(color, amount) {
+  return __spreadProps(__spreadValues({}, color), { c: Math.max(0, color.c - amount) });
+}
+function setAlpha(color, alpha) {
+  return __spreadProps(__spreadValues({}, color), { alpha: clamp(alpha, 0, 1) });
+}
+function adjustHue(color, degrees) {
+  return __spreadProps(__spreadValues({}, color), { h: normaliseHue(color.h + degrees) });
+}
+function mix(color1, color2, ratio = 0.5) {
+  const t = clamp(ratio, 0, 1);
+  const l = color1.l + (color2.l - color1.l) * t;
+  const c = color1.c + (color2.c - color1.c) * t;
+  const alpha = color1.alpha + (color2.alpha - color1.alpha) * t;
+  let h1 = normaliseHue(color1.h);
+  let h2 = normaliseHue(color2.h);
+  let dh = h2 - h1;
+  if (dh > 180) dh -= 360;
+  if (dh < -180) dh += 360;
+  const h = normaliseHue(h1 + dh * t);
+  return { l, c, h, alpha };
+}
+function complement(color) {
+  return adjustHue(color, 180);
+}
+function invert(color) {
+  return __spreadProps(__spreadValues({}, color), { l: 1 - color.l });
+}
+function grayscale(color) {
+  return __spreadProps(__spreadValues({}, color), { c: 0, h: 0 });
+}
+
+// src/contrast.ts
+function relativeLuminance(color) {
+  const toLinear = (c) => c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  const r = toLinear(color.r);
+  const g = toLinear(color.g);
+  const b = toLinear(color.b);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+function contrastRatio(fg, bg) {
+  const fgSrgb = "l" in fg ? oklchToSrgb(fg) : fg;
+  const bgSrgb = "l" in bg ? oklchToSrgb(bg) : bg;
+  const l1 = relativeLuminance(fgSrgb);
+  const l2 = relativeLuminance(bgSrgb);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function meetsAA(fg, bg, size = "normal") {
+  const ratio = contrastRatio(fg, bg);
+  return size === "large" ? ratio >= 3 : ratio >= 4.5;
+}
+function meetsAAA(fg, bg, size = "normal") {
+  const ratio = contrastRatio(fg, bg);
+  return size === "large" ? ratio >= 4.5 : ratio >= 7;
+}
+function suggestAccessible(fg, bg, target = "AA", size = "normal") {
+  const checker = target === "AAA" ? meetsAAA : meetsAA;
+  if (checker(fg, bg, size)) return fg;
+  const bgSrgb = "l" in bg ? oklchToSrgb(bg) : bg;
+  const bgLum = relativeLuminance(bgSrgb);
+  const directions = bgLum > 0.5 ? [(l, s) => l - s, (l, s) => l + s] : [(l, s) => l + s, (l, s) => l - s];
+  const step = 5e-3;
+  for (const adjust of directions) {
+    let testL = fg.l;
+    for (let i = 0; i < 220; i++) {
+      testL = adjust(testL, step);
+      if (testL < 0 || testL > 1) break;
+      testL = Math.max(0, Math.min(1, testL));
+      const candidate = __spreadProps(__spreadValues({}, fg), { l: testL });
+      if (checker(candidate, bg, size)) {
+        return candidate;
+      }
+    }
+  }
+  const blackRatio = contrastRatio({ l: 0, c: 0, h: 0, alpha: 1 }, bg);
+  const whiteRatio = contrastRatio({ l: 1, c: 0, h: 0, alpha: 1 }, bg);
+  return blackRatio > whiteRatio ? __spreadProps(__spreadValues({}, fg), { l: 0, c: 0 }) : __spreadProps(__spreadValues({}, fg), { l: 1, c: 0 });
+}
+
+// src/format.ts
+function toOklchString(color) {
+  const l = `${roundTo(color.l * 100, 2)}%`;
+  const c = roundTo(color.c, 4);
+  const h = roundTo(color.h, 2);
+  if (color.alpha < 1) {
+    return `oklch(${l} ${c} ${h} / ${roundTo(color.alpha, 3)})`;
+  }
+  return `oklch(${l} ${c} ${h})`;
+}
+function toRgbString(color) {
+  const r = Math.round(clamp01(color.r) * 255);
+  const g = Math.round(clamp01(color.g) * 255);
+  const b = Math.round(clamp01(color.b) * 255);
+  if (color.alpha < 1) {
+    return `rgb(${r} ${g} ${b} / ${roundTo(color.alpha, 3)})`;
+  }
+  return `rgb(${r} ${g} ${b})`;
+}
+function toHexString(color) {
+  const srgb = "l" in color ? oklchToSrgb(color) : color;
+  return srgbToHex(srgb);
+}
+function toCssChannels(color) {
+  const l = `${roundTo(color.l * 100, 2)}%`;
+  const c = roundTo(color.c, 4);
+  const h = roundTo(color.h, 2);
+  return `${l} ${c} ${h}`;
+}
+function roundTo(value, decimals) {
+  const factor = Math.pow(10, decimals);
+  return Math.round(value * factor) / factor;
+}
+function clamp01(v) {
+  return Math.max(0, Math.min(1, v));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  adjustHue,
+  complement,
+  contrastRatio,
+  darken,
+  desaturate,
+  grayscale,
+  hexToOklch,
+  invert,
+  lighten,
+  meetsAA,
+  meetsAAA,
+  mix,
+  oklabToOklch,
+  oklchToHex,
+  oklchToOklab,
+  oklchToSrgb,
+  parseHex,
+  parseOklchChannels,
+  parseOklchCss,
+  parseRgb,
+  saturate,
+  setAlpha,
+  srgbToHex,
+  srgbToOklch,
+  suggestAccessible,
+  toCssChannels,
+  toHexString,
+  toOklchString,
+  toRgbString
+});

package/dist/index.d.cts

@@ -0,0 +1,213 @@
+/**
+ * A color in the OKLCH color space.
+ * - `l`: Lightness, 0–1 (0 = black, 1 = white)
+ * - `c`: Chroma, 0–~0.4 (0 = gray, higher = more saturated)
+ * - `h`: Hue, 0–360 degrees
+ * - `alpha`: Opacity, 0–1
+ */
+interface OklchColor {
+    readonly l: number;
+    readonly c: number;
+    readonly h: number;
+    readonly alpha: number;
+}
+/**
+ * A color in the OKLab color space (intermediate for conversions).
+ */
+interface OklabColor {
+    readonly L: number;
+    readonly a: number;
+    readonly b: number;
+    readonly alpha: number;
+}
+/**
+ * A color in the sRGB color space.
+ * - `r`, `g`, `b`: 0–1 range (not 0–255)
+ * - `alpha`: 0–1
+ */
+interface SrgbColor {
+    readonly r: number;
+    readonly g: number;
+    readonly b: number;
+    readonly alpha: number;
+}
+/** A CSS hex color string. */
+type HexString = `#${string}`;
+/** Semantic color mode. */
+type ColorMode = "light" | "dark";
+
+/**
+ * Parse an OKLCH channel string as used by `@ariaui/tokens` primitives.
+ *
+ * Accepts formats:
+ * - `"55.2% 0.014 286"`  (L with %)
+ * - `"0.552 0.014 286"`  (L as decimal)
+ * - `"55.2% 0.014 286 / 0.5"` (with alpha)
+ *
+ * @throws if the string cannot be parsed.
+ */
+declare function parseOklchChannels(channels: string): OklchColor;
+/**
+ * Parse an `oklch(...)` CSS function string.
+ *
+ * Accepts: `oklch(55.2% 0.014 286)`, `oklch(55.2% 0.014 286 / 0.5)`
+ */
+declare function parseOklchCss(css: string): OklchColor;
+/**
+ * Parse a hex color string.
+ *
+ * Accepts: `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`
+ */
+declare function parseHex(hex: string): SrgbColor;
+/**
+ * Parse an `rgb(...)` or `rgba(...)` CSS function string.
+ *
+ * Accepts modern space-separated (`rgb(139 92 246)`, `rgb(139 92 246 / 0.5)`)
+ * and legacy comma-separated (`rgb(139, 92, 246)`, `rgba(139, 92, 246, 0.5)`).
+ */
+declare function parseRgb(css: string): SrgbColor;
+
+/** Convert OKLCH → OKLab */
+declare function oklchToOklab(c: OklchColor): OklabColor;
+/** Convert OKLab → OKLCH */
+declare function oklabToOklch(lab: OklabColor): OklchColor;
+/**
+ * Convert OKLCH → sRGB with CSS Color Level 4 gamut mapping.
+ * Out-of-gamut colors are mapped by reducing chroma while preserving
+ * lightness and hue, per the spec.
+ */
+declare function oklchToSrgb(color: OklchColor): SrgbColor;
+/**
+ * Convert sRGB → OKLCH.
+ */
+declare function srgbToOklch(color: SrgbColor): OklchColor;
+/**
+ * Convert sRGB → hex string.
+ * Values are clamped to [0, 255]. Alpha is included only if < 1.
+ */
+declare function srgbToHex(color: SrgbColor): HexString;
+/**
+ * Convert OKLCH → hex string (via sRGB with gamut mapping).
+ */
+declare function oklchToHex(color: OklchColor): HexString;
+/**
+ * Convert hex string → OKLCH.
+ */
+declare function hexToOklch(hex: string): OklchColor;
+
+/**
+ * Increase lightness by `amount` (0–1).
+ * `lighten(color, 0.1)` adds 0.1 to lightness (clamped to 1).
+ */
+declare function lighten(color: OklchColor, amount: number): OklchColor;
+/**
+ * Decrease lightness by `amount` (0–1).
+ * `darken(color, 0.1)` subtracts 0.1 from lightness (clamped to 0).
+ */
+declare function darken(color: OklchColor, amount: number): OklchColor;
+/**
+ * Increase chroma by `amount`.
+ * `saturate(color, 0.05)` adds 0.05 to chroma (clamped to 0).
+ */
+declare function saturate(color: OklchColor, amount: number): OklchColor;
+/**
+ * Decrease chroma by `amount`.
+ * `desaturate(color, 0.05)` subtracts 0.05 from chroma (clamped to 0).
+ */
+declare function desaturate(color: OklchColor, amount: number): OklchColor;
+/**
+ * Set the alpha channel.
+ */
+declare function setAlpha(color: OklchColor, alpha: number): OklchColor;
+/**
+ * Rotate the hue by `degrees`.
+ * `adjustHue(color, 30)` rotates hue by +30°.
+ */
+declare function adjustHue(color: OklchColor, degrees: number): OklchColor;
+/**
+ * Mix two OKLCH colors by linear interpolation.
+ *
+ * @param color1 - First color
+ * @param color2 - Second color
+ * @param ratio  - 0 = 100% color1, 1 = 100% color2 (default 0.5)
+ *
+ * Hue interpolation uses the shorter arc.
+ */
+declare function mix(color1: OklchColor, color2: OklchColor, ratio?: number): OklchColor;
+/**
+ * Create a complement (hue + 180°).
+ */
+declare function complement(color: OklchColor): OklchColor;
+/**
+ * Invert a color (flip lightness).
+ */
+declare function invert(color: OklchColor): OklchColor;
+/**
+ * Convert to grayscale (set chroma to 0).
+ */
+declare function grayscale(color: OklchColor): OklchColor;
+
+/**
+ * Calculate WCAG 2.1 contrast ratio between two colors.
+ * Returns a value between 1 and 21.
+ *
+ * Accepts either OKLCH or sRGB colors (OKLCH are converted via gamut mapping).
+ */
+declare function contrastRatio(fg: OklchColor | SrgbColor, bg: OklchColor | SrgbColor): number;
+/**
+ * Check if a fg/bg pair meets WCAG 2.1 AA contrast requirements.
+ *
+ * - Normal text: ratio ≥ 4.5
+ * - Large text (≥18pt or ≥14pt bold): ratio ≥ 3
+ */
+declare function meetsAA(fg: OklchColor | SrgbColor, bg: OklchColor | SrgbColor, size?: "normal" | "large"): boolean;
+/**
+ * Check if a fg/bg pair meets WCAG 2.1 AAA contrast requirements.
+ *
+ * - Normal text: ratio ≥ 7
+ * - Large text: ratio ≥ 4.5
+ */
+declare function meetsAAA(fg: OklchColor | SrgbColor, bg: OklchColor | SrgbColor, size?: "normal" | "large"): boolean;
+/**
+ * Suggest an accessible foreground color by adjusting lightness to meet
+ * the target contrast level against the given background.
+ *
+ * Tries darkening first, then lightening. Returns the closest accessible
+ * OklchColor, or the original if it already passes.
+ *
+ * @param fg - Foreground color to adjust (OKLCH)
+ * @param bg - Background color (OKLCH or sRGB)
+ * @param target - "AA" (4.5:1) or "AAA" (7:1), default "AA"
+ * @param size - "normal" or "large" text
+ */
+declare function suggestAccessible(fg: OklchColor, bg: OklchColor | SrgbColor, target?: "AA" | "AAA", size?: "normal" | "large"): OklchColor;
+
+/**
+ * Format an OKLCH color as a CSS `oklch()` string.
+ *
+ * @example toOklchString({ l: 0.552, c: 0.014, h: 286, alpha: 1 })
+ *          → "oklch(55.2% 0.014 286)"
+ */
+declare function toOklchString(color: OklchColor): string;
+/**
+ * Format an sRGB color as a CSS `rgb()` string (modern syntax).
+ *
+ * @example toRgbString({ r: 0.545, g: 0.361, b: 0.965, alpha: 1 })
+ *          → "rgb(139 92 246)"
+ */
+declare function toRgbString(color: SrgbColor): string;
+/**
+ * Format a color as a hex string.
+ * Accepts OKLCH (converts via gamut mapping) or sRGB.
+ */
+declare function toHexString(color: OklchColor | SrgbColor): HexString;
+/**
+ * Format an OKLCH color back to the bare channel string format
+ * used by `@ariaui/tokens` primitives: `"L% C H"`.
+ *
+ * @example toCssChannels({ l: 0.552, c: 0.014, h: 286, alpha: 1 })
+ *          → "55.2% 0.014 286"
+ */
+declare function toCssChannels(color: OklchColor): string;
+
+export { type ColorMode, type HexString, type OklabColor, type OklchColor, type SrgbColor, adjustHue, complement, contrastRatio, darken, desaturate, grayscale, hexToOklch, invert, lighten, meetsAA, meetsAAA, mix, oklabToOklch, oklchToHex, oklchToOklab, oklchToSrgb, parseHex, parseOklchChannels, parseOklchCss, parseRgb, saturate, setAlpha, srgbToHex, srgbToOklch, suggestAccessible, toCssChannels, toHexString, toOklchString, toRgbString };