@eifi1/ui-kit 0.4.0 → 0.5.0

package/dist/theme/color.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Colour maths for the palette system: sRGB ↔ OKLab ↔ OKLCH, WCAG contrast, gamut
+ * clipping, and colour-vision-deficiency simulation.
+ *
+ * Dependency-free on purpose. This package already ships 48MB of runtime dependencies
+ * for a 1.4MB library, and a colour-space conversion is forty lines of arithmetic that
+ * will not change — importing culori or chroma-js to get it would be the largest
+ * dependency in the kit, paid for by every consumer, to avoid writing down formulas
+ * that were published once and are now fixed.
+ *
+ * **Why OKLCH rather than HSL.** HSL's "lightness" is not lightness: `hsl(60 100% 50%)`
+ * (yellow) and `hsl(240 100% 50%)` (blue) claim the same 50% and differ by a factor of
+ * about twelve in perceived brightness. Any scheme that derives a palette by holding HSL
+ * lightness constant therefore produces a set that looks wildly uneven, and any scheme
+ * that solves for contrast in HSL has to solve separately per hue. OKLab is built so a
+ * given L means the same apparent lightness at every hue, which is what makes "same
+ * lightness, different hue" a usable rule and what makes a contrast solve converge.
+ *
+ * Reference: Björn Ottosson, "A perceptual color space for image processing" (2020).
+ */
+interface Rgb {
+    /** 0–255. */
+    r: number;
+    g: number;
+    b: number;
+}
+interface Oklch {
+    /** Perceptual lightness, 0–1. */
+    l: number;
+    /** Chroma, 0–~0.4 in sRGB. */
+    c: number;
+    /** Hue angle in degrees, 0–360. */
+    h: number;
+}
+/** `#rgb` or `#rrggbb` → components, or null when it is neither. */
+declare function parseHex(hex: string): Rgb | null;
+declare function toHex({ r, g, b }: Rgb): string;
+declare function rgbToOklch(rgb: Rgb): Oklch;
+/**
+ * OKLCH → sRGB, reducing CHROMA until the colour fits.
+ *
+ * Clamping the channels instead — the obvious approach — shifts hue and lightness
+ * together and unpredictably: a saturated blue that overflows clips to a different blue
+ * that is also lighter. Holding L and h and giving up chroma keeps the colour
+ * recognisably the one that was asked for, which matters when the whole point is to
+ * derive a family at a fixed lightness.
+ */
+declare function oklchToRgb(target: Oklch): Rgb;
+declare function hexToOklch(hex: string): Oklch | null;
+declare function oklchToHex(lch: Oklch): string;
+/** WCAG 2.x relative luminance. */
+declare function luminance(rgb: Rgb): number;
+/** WCAG 2.x contrast ratio, 1–21. Order-independent. */
+declare function contrast(a: Rgb | string, b: Rgb | string): number;
+/**
+ * The lightness at hue `h`, chroma `c` that hits `target` contrast against `against`.
+ *
+ * Binary search rather than algebra: OKLab lightness does not map to WCAG luminance in
+ * closed form, and it is not even monotonic in the general case once gamut clipping
+ * starts reducing chroma. It IS monotonic over the half-range we search — away from the
+ * background — which is why the direction is chosen first.
+ *
+ * Returns the best lightness found. If the target is unreachable at this hue and chroma
+ * (a saturated yellow cannot make 7:1 against white at any lightness without going grey)
+ * it returns the extreme end, and the caller should check the contrast it actually got
+ * rather than assuming success — `deriveTokenSet` does exactly that.
+ */
+declare function solveLightness(target: number, against: Rgb, h: number, c: number, direction: "lighter" | "darker"): number;
+type CvdType = "protanopia" | "deuteranopia" | "tritanopia";
+declare function simulateCvd(rgb: Rgb, type: CvdType): Rgb;
+/**
+ * Perceptual distance in OKLab, which is what that space is FOR: a Euclidean distance
+ * in OKLab corresponds far more closely to "how different do these look" than one in
+ * sRGB, where the same numeric gap is obvious among greens and invisible among blues.
+ */
+declare function deltaE(a: Rgb, b: Rgb): number;
+
+export { type CvdType, type Oklch, type Rgb, contrast, deltaE, hexToOklch, luminance, oklchToHex, oklchToRgb, parseHex, rgbToOklch, simulateCvd, solveLightness, toHex };

package/dist/theme/color.js

@@ -0,0 +1,148 @@
+"use client";
+function parseHex(hex) {
+  const h = hex.trim().replace(/^#/, "");
+  const full = h.length === 3 ? h.split("").map((c) => c + c).join("") : h;
+  if (!/^[0-9a-fA-F]{6}$/.test(full)) return null;
+  return {
+    r: parseInt(full.slice(0, 2), 16),
+    g: parseInt(full.slice(2, 4), 16),
+    b: parseInt(full.slice(4, 6), 16)
+  };
+}
+function toHex({ r, g, b }) {
+  const part = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, "0");
+  return `#${part(r)}${part(g)}${part(b)}`;
+}
+function toLinear(channel) {
+  const c = channel / 255;
+  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+function fromLinear(channel) {
+  const c = channel <= 31308e-7 ? 12.92 * channel : 1.055 * channel ** (1 / 2.4) - 0.055;
+  return c * 255;
+}
+function rgbToOklch(rgb) {
+  const r = toLinear(rgb.r);
+  const g = toLinear(rgb.g);
+  const b = toLinear(rgb.b);
+  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+  const c = Math.sqrt(A * A + B * B);
+  const h = c < 1e-6 ? 0 : (Math.atan2(B, A) * 180 / Math.PI + 360) % 360;
+  return { l: L, c, h };
+}
+function oklchToRgbRaw({ l, c, h }) {
+  const rad = h * Math.PI / 180;
+  const A = c * Math.cos(rad);
+  const B = c * Math.sin(rad);
+  const l_ = (l + 0.3963377774 * A + 0.2158037573 * B) ** 3;
+  const m_ = (l - 0.1055613458 * A - 0.0638541728 * B) ** 3;
+  const s_ = (l - 0.0894841775 * A - 1.291485548 * B) ** 3;
+  return {
+    r: fromLinear(4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_),
+    g: fromLinear(-1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_),
+    b: fromLinear(-0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_)
+  };
+}
+function inGamut({ r, g, b }) {
+  const ok = (v) => v >= -0.5 && v <= 255.5;
+  return ok(r) && ok(g) && ok(b);
+}
+function oklchToRgb(target) {
+  const direct = oklchToRgbRaw(target);
+  if (inGamut(direct)) return direct;
+  let lo = 0;
+  let hi = target.c;
+  for (let i = 0; i < 20; i++) {
+    const mid = (lo + hi) / 2;
+    if (inGamut(oklchToRgbRaw({ ...target, c: mid }))) lo = mid;
+    else hi = mid;
+  }
+  return oklchToRgbRaw({ ...target, c: lo });
+}
+function hexToOklch(hex) {
+  const rgb = parseHex(hex);
+  return rgb ? rgbToOklch(rgb) : null;
+}
+function oklchToHex(lch) {
+  return toHex(oklchToRgb(lch));
+}
+function luminance(rgb) {
+  return 0.2126 * toLinear(rgb.r) + 0.7152 * toLinear(rgb.g) + 0.0722 * toLinear(rgb.b);
+}
+function contrast(a, b) {
+  const ra = typeof a === "string" ? parseHex(a) : a;
+  const rb = typeof b === "string" ? parseHex(b) : b;
+  if (!ra || !rb) return 1;
+  const la = luminance(ra);
+  const lb = luminance(rb);
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+function solveLightness(target, against, h, c, direction) {
+  const bgL = rgbToOklch(against).l;
+  let lo = direction === "darker" ? 0 : bgL;
+  let hi = direction === "darker" ? bgL : 1;
+  for (let i = 0; i < 24; i++) {
+    const mid = (lo + hi) / 2;
+    const got = contrast(oklchToRgb({ l: mid, c, h }), against);
+    if (got < target) {
+      if (direction === "darker") hi = mid;
+      else lo = mid;
+    } else if (direction === "darker") lo = mid;
+    else hi = mid;
+  }
+  return direction === "darker" ? lo : hi;
+}
+const CVD_MATRIX = {
+  protanopia: [
+    [0.1705, 0.8295, 0],
+    [0.1705, 0.8295, 0],
+    [-45e-4, 45e-4, 1]
+  ],
+  deuteranopia: [
+    [0.33066, 0.66934, 0],
+    [0.33066, 0.66934, 0],
+    [-0.02785, 0.02785, 1]
+  ],
+  tritanopia: [
+    [1, 0.1273, -0.1273],
+    [0, 0.8739, 0.1261],
+    [0, 0.8739, 0.1261]
+  ]
+};
+function simulateCvd(rgb, type) {
+  const m = CVD_MATRIX[type];
+  const [r, g, b] = [toLinear(rgb.r), toLinear(rgb.g), toLinear(rgb.b)];
+  return {
+    r: fromLinear(m[0][0] * r + m[0][1] * g + m[0][2] * b),
+    g: fromLinear(m[1][0] * r + m[1][1] * g + m[1][2] * b),
+    b: fromLinear(m[2][0] * r + m[2][1] * g + m[2][2] * b)
+  };
+}
+function deltaE(a, b) {
+  const A = rgbToOklch(a);
+  const B = rgbToOklch(b);
+  const aA = A.c * Math.cos(A.h * Math.PI / 180);
+  const aB = A.c * Math.sin(A.h * Math.PI / 180);
+  const bA = B.c * Math.cos(B.h * Math.PI / 180);
+  const bB = B.c * Math.sin(B.h * Math.PI / 180);
+  return Math.hypot(A.l - B.l, aA - bA, aB - bB);
+}
+export {
+  contrast,
+  deltaE,
+  hexToOklch,
+  luminance,
+  oklchToHex,
+  oklchToRgb,
+  parseHex,
+  rgbToOklch,
+  simulateCvd,
+  solveLightness,
+  toHex
+};
+//# sourceMappingURL=color.js.map

package/dist/theme/color.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/theme/color.ts"],"sourcesContent":["/**\n * Colour maths for the palette system: sRGB ↔ OKLab ↔ OKLCH, WCAG contrast, gamut\n * clipping, and colour-vision-deficiency simulation.\n *\n * Dependency-free on purpose. This package already ships 48MB of runtime dependencies\n * for a 1.4MB library, and a colour-space conversion is forty lines of arithmetic that\n * will not change — importing culori or chroma-js to get it would be the largest\n * dependency in the kit, paid for by every consumer, to avoid writing down formulas\n * that were published once and are now fixed.\n *\n * **Why OKLCH rather than HSL.** HSL's \"lightness\" is not lightness: `hsl(60 100% 50%)`\n * (yellow) and `hsl(240 100% 50%)` (blue) claim the same 50% and differ by a factor of\n * about twelve in perceived brightness. Any scheme that derives a palette by holding HSL\n * lightness constant therefore produces a set that looks wildly uneven, and any scheme\n * that solves for contrast in HSL has to solve separately per hue. OKLab is built so a\n * given L means the same apparent lightness at every hue, which is what makes \"same\n * lightness, different hue\" a usable rule and what makes a contrast solve converge.\n *\n * Reference: Björn Ottosson, \"A perceptual color space for image processing\" (2020).\n */\n\nexport interface Rgb {\n  /** 0–255. */\n  r: number;\n  g: number;\n  b: number;\n}\n\nexport interface Oklch {\n  /** Perceptual lightness, 0–1. */\n  l: number;\n  /** Chroma, 0–~0.4 in sRGB. */\n  c: number;\n  /** Hue angle in degrees, 0–360. */\n  h: number;\n}\n\n/* ── sRGB ─────────────────────────────────────────────────────────────────── */\n\n/** `#rgb` or `#rrggbb` → components, or null when it is neither. */\nexport function parseHex(hex: string): Rgb | null {\n  const h = hex.trim().replace(/^#/, \"\");\n  const full =\n    h.length === 3\n      ? h\n          .split(\"\")\n          .map((c) => c + c)\n          .join(\"\")\n      : h;\n  if (!/^[0-9a-fA-F]{6}$/.test(full)) return null;\n  return {\n    r: parseInt(full.slice(0, 2), 16),\n    g: parseInt(full.slice(2, 4), 16),\n    b: parseInt(full.slice(4, 6), 16),\n  };\n}\n\nexport function toHex({ r, g, b }: Rgb): string {\n  const part = (v: number) =>\n    Math.max(0, Math.min(255, Math.round(v)))\n      .toString(16)\n      .padStart(2, \"0\");\n  return `#${part(r)}${part(g)}${part(b)}`;\n}\n\n/** sRGB 0–255 → linear-light 0–1. The transfer function, not a gamma of 2.2. */\nfunction toLinear(channel: number): number {\n  const c = channel / 255;\n  return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;\n}\n\nfunction fromLinear(channel: number): number {\n  const c = channel <= 0.0031308 ? 12.92 * channel : 1.055 * channel ** (1 / 2.4) - 0.055;\n  return c * 255;\n}\n\n/* ── OKLab / OKLCH ────────────────────────────────────────────────────────── */\n\nexport function rgbToOklch(rgb: Rgb): Oklch {\n  const r = toLinear(rgb.r);\n  const g = toLinear(rgb.g);\n  const b = toLinear(rgb.b);\n\n  const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);\n  const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);\n  const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);\n\n  const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;\n  const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;\n  const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;\n\n  const c = Math.sqrt(A * A + B * B);\n  // Hue is meaningless at zero chroma; 0 keeps it stable rather than NaN-adjacent.\n  const h = c < 1e-6 ? 0 : ((Math.atan2(B, A) * 180) / Math.PI + 360) % 360;\n  return { l: L, c, h };\n}\n\n/** OKLCH → sRGB, WITHOUT gamut clipping. May return components outside 0–255. */\nfunction oklchToRgbRaw({ l, c, h }: Oklch): Rgb {\n  const rad = (h * Math.PI) / 180;\n  const A = c * Math.cos(rad);\n  const B = c * Math.sin(rad);\n\n  const l_ = (l + 0.3963377774 * A + 0.2158037573 * B) ** 3;\n  const m_ = (l - 0.1055613458 * A - 0.0638541728 * B) ** 3;\n  const s_ = (l - 0.0894841775 * A - 1.291485548 * B) ** 3;\n\n  return {\n    r: fromLinear(4.0767416621 * l_ - 3.3077115913 * m_ + 0.2309699292 * s_),\n    g: fromLinear(-1.2684380046 * l_ + 2.6097574011 * m_ - 0.3413193965 * s_),\n    b: fromLinear(-0.0041960863 * l_ - 0.7034186147 * m_ + 1.707614701 * s_),\n  };\n}\n\nfunction inGamut({ r, g, b }: Rgb): boolean {\n  const ok = (v: number) => v >= -0.5 && v <= 255.5;\n  return ok(r) && ok(g) && ok(b);\n}\n\n/**\n * OKLCH → sRGB, reducing CHROMA until the colour fits.\n *\n * Clamping the channels instead — the obvious approach — shifts hue and lightness\n * together and unpredictably: a saturated blue that overflows clips to a different blue\n * that is also lighter. Holding L and h and giving up chroma keeps the colour\n * recognisably the one that was asked for, which matters when the whole point is to\n * derive a family at a fixed lightness.\n */\nexport function oklchToRgb(target: Oklch): Rgb {\n  const direct = oklchToRgbRaw(target);\n  if (inGamut(direct)) return direct;\n\n  let lo = 0;\n  let hi = target.c;\n  // 20 halvings resolves chroma to ~4e-7, far below a perceptible step.\n  for (let i = 0; i < 20; i++) {\n    const mid = (lo + hi) / 2;\n    if (inGamut(oklchToRgbRaw({ ...target, c: mid }))) lo = mid;\n    else hi = mid;\n  }\n  return oklchToRgbRaw({ ...target, c: lo });\n}\n\nexport function hexToOklch(hex: string): Oklch | null {\n  const rgb = parseHex(hex);\n  return rgb ? rgbToOklch(rgb) : null;\n}\n\nexport function oklchToHex(lch: Oklch): string {\n  return toHex(oklchToRgb(lch));\n}\n\n/* ── WCAG contrast ────────────────────────────────────────────────────────── */\n\n/** WCAG 2.x relative luminance. */\nexport function luminance(rgb: Rgb): number {\n  return 0.2126 * toLinear(rgb.r) + 0.7152 * toLinear(rgb.g) + 0.0722 * toLinear(rgb.b);\n}\n\n/** WCAG 2.x contrast ratio, 1–21. Order-independent. */\nexport function contrast(a: Rgb | string, b: Rgb | string): number {\n  const ra = typeof a === \"string\" ? parseHex(a) : a;\n  const rb = typeof b === \"string\" ? parseHex(b) : b;\n  if (!ra || !rb) return 1;\n  const la = luminance(ra);\n  const lb = luminance(rb);\n  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);\n}\n\n/**\n * The lightness at hue `h`, chroma `c` that hits `target` contrast against `against`.\n *\n * Binary search rather than algebra: OKLab lightness does not map to WCAG luminance in\n * closed form, and it is not even monotonic in the general case once gamut clipping\n * starts reducing chroma. It IS monotonic over the half-range we search — away from the\n * background — which is why the direction is chosen first.\n *\n * Returns the best lightness found. If the target is unreachable at this hue and chroma\n * (a saturated yellow cannot make 7:1 against white at any lightness without going grey)\n * it returns the extreme end, and the caller should check the contrast it actually got\n * rather than assuming success — `deriveTokenSet` does exactly that.\n */\nexport function solveLightness(\n  target: number,\n  against: Rgb,\n  h: number,\n  c: number,\n  direction: \"lighter\" | \"darker\",\n): number {\n  // The half-range on the far side of the background from where we are heading.\n  // Going darker, that is [0, backgroundL]; going lighter, [backgroundL, 1]. Contrast is\n  // monotonic across each of those halves, which is what makes a binary search valid —\n  // it is NOT monotonic across the whole 0..1 range, because it turns around at the\n  // background's own lightness.\n  const bgL = rgbToOklch(against).l;\n  let lo = direction === \"darker\" ? 0 : bgL;\n  let hi = direction === \"darker\" ? bgL : 1;\n\n  for (let i = 0; i < 24; i++) {\n    const mid = (lo + hi) / 2;\n    const got = contrast(oklchToRgb({ l: mid, c, h }), against);\n    // Moving AWAY from the background raises contrast; which way that is depends on\n    // whether we are going lighter or darker.\n    if (got < target) {\n      if (direction === \"darker\") hi = mid;\n      else lo = mid;\n    } else if (direction === \"darker\") lo = mid;\n    else hi = mid;\n  }\n  return direction === \"darker\" ? lo : hi;\n}\n\n/* ── Colour-vision deficiency ─────────────────────────────────────────────── */\n\nexport type CvdType = \"protanopia\" | \"deuteranopia\" | \"tritanopia\";\n\n/**\n * Brettel/Viénot-style dichromat simulation in linear RGB.\n *\n * An approximation, and a well-established one. It is here so the kit can FAIL a\n * categorical ramp that two of its series become indistinguishable under, rather than\n * asserting CVD-safety in a comment the way `chart-palette.ts` did — the audit found\n * four of the nine default light chart hues below the 3:1 they were claimed to hold.\n */\nconst CVD_MATRIX: Record<CvdType, number[][]> = {\n  protanopia: [\n    [0.1705, 0.8295, 0],\n    [0.1705, 0.8295, 0],\n    [-0.0045, 0.0045, 1],\n  ],\n  deuteranopia: [\n    [0.33066, 0.66934, 0],\n    [0.33066, 0.66934, 0],\n    [-0.02785, 0.02785, 1],\n  ],\n  tritanopia: [\n    [1, 0.1273, -0.1273],\n    [0, 0.8739, 0.1261],\n    [0, 0.8739, 0.1261],\n  ],\n};\n\nexport function simulateCvd(rgb: Rgb, type: CvdType): Rgb {\n  const m = CVD_MATRIX[type];\n  const [r, g, b] = [toLinear(rgb.r), toLinear(rgb.g), toLinear(rgb.b)];\n  return {\n    r: fromLinear(m[0][0] * r + m[0][1] * g + m[0][2] * b),\n    g: fromLinear(m[1][0] * r + m[1][1] * g + m[1][2] * b),\n    b: fromLinear(m[2][0] * r + m[2][1] * g + m[2][2] * b),\n  };\n}\n\n/**\n * Perceptual distance in OKLab, which is what that space is FOR: a Euclidean distance\n * in OKLab corresponds far more closely to \"how different do these look\" than one in\n * sRGB, where the same numeric gap is obvious among greens and invisible among blues.\n */\nexport function deltaE(a: Rgb, b: Rgb): number {\n  const A = rgbToOklch(a);\n  const B = rgbToOklch(b);\n  const aA = A.c * Math.cos((A.h * Math.PI) / 180);\n  const aB = A.c * Math.sin((A.h * Math.PI) / 180);\n  const bA = B.c * Math.cos((B.h * Math.PI) / 180);\n  const bB = B.c * Math.sin((B.h * Math.PI) / 180);\n  return Math.hypot(A.l - B.l, aA - bA, aB - bB);\n}\n"],"mappings":"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","names":[]}

package/dist/theme/palette-derive.d.ts

@@ -0,0 +1,140 @@
+import { ThemeMode } from './theme-store.js';
+import { TokenSet } from './palette-presets.js';
+import { CvdType, Oklch } from './color.js';
+import 'zustand/middleware';
+import 'zustand';
+import './chart-palette.js';
+
+/**
+ * Build a whole palette from one brand colour, plus any number of colours pinned by
+ * hand, with every contrast ratio SOLVED rather than chosen and then hoped for.
+ *
+ * The presets this package shipped were assembled by eye and annotated with the ratios
+ * they were believed to hold — `tokens.css` records "7.0:1 and 4.8:1", and
+ * `palette-presets.ts` records "2.67:1 … lifted they clear it at 3.30:1". Nothing
+ * computed any of them, and the audit found four of the nine default light chart hues
+ * below the 3:1 that WCAG 1.4.11 requires of a graphical object. A comment is not a
+ * test. Everything here is derived to a target and then measured, and
+ * {@link auditPalette} returns the measurements so a caller can refuse a palette that
+ * does not hold up.
+ *
+ * WHAT IS DERIVED AND WHAT IS NOT. The UI palette and the CATEGORICAL CHART RAMP solve
+ * different problems and are deliberately kept apart. A UI colour needs contrast against
+ * one known surface and carries a fixed meaning; a chart colour needs to stay separable
+ * from eight unknown siblings, at roughly equal salience, with no implied order.
+ * Optimising a set for one makes it worse at the other, which is why `deriveTokenSet`
+ * leaves `chart` alone unless you explicitly ask for {@link deriveChartRamp}.
+ */
+/** A role whose hue may be pinned by the caller instead of chosen by the deriver. */
+type AnchorRole = "brand" | "accent" | "danger" | "warning" | "success" | "info";
+type PaletteAnchors = {
+    brand: string;
+} & Partial<Record<Exclude<AnchorRole, "brand">, string>>;
+interface DeriveOptions {
+    anchors: PaletteAnchors;
+    mode: ThemeMode;
+    /**
+     * How strongly the surfaces carry the brand's hue, 0–1 of the maximum useful tint.
+     * 0 gives neutral greys; the shipped default is a visible warmth, because a page that
+     * is very slightly the brand's hue reads as considered where a pure grey reads as
+     * unstyled. Above ~0.5 the surfaces start competing with the content.
+     */
+    surfaceTint?: number;
+    /** Contrast targets for the three text roles against the WORST surface. */
+    textContrast?: {
+        primary?: number;
+        secondary?: number;
+        muted?: number;
+    };
+}
+/** The semantic layer, which lives in tokens.css rather than in `TokenSet`. */
+interface SemanticTokens {
+    danger: string;
+    dangerHover: string;
+    dangerContrast: string;
+    dangerBorder: string;
+    dangerBg: string;
+    warning: string;
+    warningBorder: string;
+    warningBg: string;
+    info: string;
+    infoBorder: string;
+    infoBg: string;
+    success: string;
+    successBorder: string;
+    successBg: string;
+    /** Present only when a `accent` (secondary brand) anchor was supplied. */
+    accent?: string;
+    accentContrast?: string;
+    accentBg?: string;
+}
+interface ContrastCheck {
+    /** e.g. "textMuted on bgPage". */
+    pair: string;
+    ratio: number;
+    /** What WCAG asks of this pair. */
+    required: number;
+    /** Which rule the requirement comes from, for a reader who wants to argue with it. */
+    rule: string;
+    passes: boolean;
+}
+interface ContrastReport {
+    checks: ContrastCheck[];
+    failures: ContrastCheck[];
+    passes: boolean;
+}
+interface DerivedPalette {
+    tokens: TokenSet;
+    semantic: SemanticTokens;
+    audit: ContrastReport;
+    /** Compromises the deriver had to make, in plain words. Never silent. */
+    warnings: string[];
+}
+declare function derivePalette({ anchors, mode, surfaceTint, textContrast, }: DeriveOptions): DerivedPalette;
+/**
+ * Measure every pair that has a requirement, and say which ones fail.
+ *
+ * This is the part the shipped presets were missing. `derivePalette` runs it on the way
+ * out, and the preset test runs it over everything the package ships, so a palette that
+ * does not hold up cannot be merged with a comment claiming that it does.
+ */
+declare function auditPalette(t: TokenSet, semantic?: SemanticTokens): ContrastReport;
+interface ChartRampReport {
+    colors: string[];
+    /** Series pairs that are too close under normal vision or any simulated CVD. */
+    collisions: Array<{
+        a: number;
+        b: number;
+        under: "normal" | CvdType;
+        distance: number;
+    }>;
+    /** Series that do not clear 3:1 against a surface they may be drawn on. */
+    lowContrast: Array<{
+        index: number;
+        surface: string;
+        ratio: number;
+    }>;
+    /** The worst pairwise separation, across normal vision and all three dichromacies. */
+    minSeparation: number;
+    /** The worst contrast any series reaches against any surface it was measured on. */
+    minContrast: number;
+    passes: boolean;
+}
+/**
+ * A categorical ramp of `count` hues, evenly spaced and equal in perceived lightness,
+ * then MEASURED for separability — including under each dichromacy.
+ *
+ * Offered but not used by default, and the distinction matters. Evenly spaced hues at
+ * one lightness are a reasonable generic answer; Paul Tol's "Muted" set, which this
+ * package ships, is a better specific one, because it was optimised against real
+ * confusion lines rather than derived from a formula. So this exists for a consumer who
+ * wants their charts to follow their brand and is willing to read the report — not as
+ * a silent upgrade to the default.
+ */
+declare function deriveChartRamp(brandHex: string, mode: ThemeMode, surfaces: string[], count?: number): ChartRampReport;
+/** Audit a ramp somebody else chose — the shipped Paul Tol set, say. */
+declare function auditChartRamp(colors: string[], surfaces: string[]): ChartRampReport;
+/** Convenience: the OKLCH of a hex, for a caller inspecting an anchor. */
+declare function describe(hex: string): Oklch | null;
+
+export { type AnchorRole, type ChartRampReport, type ContrastCheck, type ContrastReport, type DeriveOptions, type DerivedPalette, type PaletteAnchors, type SemanticTokens, auditChartRamp, auditPalette, deriveChartRamp, derivePalette, describe };