@conductor-by-89soone/tokens 0.6.1 → 0.7.0

package/dist/index.d.ts

@@ -90,4 +90,42 @@ interface TokenGroup {
     readonly order: number;
 }
 
-export { CDT_PREFIX, PACKAGE_NAME, SEVERITY_ICONS, STATUS_ICONS, type SeverityIconName, type StatusIconName, type TokenDefinition, type TokenGroup, type TokenTier, type TokenUsage };
+/**
+ * WCAG 2.1 contrast ratio (1–21) of `foreground` drawn on `background`.
+ *
+ * Accepts `#rgb`, `#rrggbb`, `#rrggbbaa`, `rgb()`/`rgba()` and `hsl()`/`hsla()`, alone or as the single
+ * colour inside a compound value such as a box-shadow. A translucent
+ * foreground is composited over the background first; the background must be opaque, because what
+ * it sits on is unknown here. Throws on anything else rather than returning a ratio that could pass.
+ */
+declare function contrastRatio(foreground: string, background: string): number;
+
+/**
+ * OKLab mixing for derived state colours (CR-050).
+ *
+ * The stylesheet used to tint tone buttons with `color-mix(in srgb, …)` at render time. Mixing in
+ * gamma-encoded sRGB darkens and desaturates the midpoints, and a render-time mix is invisible to
+ * `checkContrast`. These tints are now computed here, at build time, in OKLab — the Cartesian form
+ * of OKLCH, so lightness is perceptually even — and emitted as plain hex. No browser has to support
+ * `oklch()` or relative colour syntax, and every derived background can sit in a contrast pair.
+ *
+ * OKLab rather than polar OKLCH: the surfaces are near-neutral, so their hue is noise, and an OKLCH
+ * mix would swing the tint's hue along that noise (a red mixed toward a blue-grey surface drifts
+ * purple). Mixing a and b linearly keeps the tone's hue and walks its chroma down evenly.
+ *
+ * Refs: CR-050 FR-THM-004 FR-TOK-001
+ */
+/** An OKLab (L, a, b) triple, or an sRGB triple in [0, 1] internally. */
+type OklabColor = readonly [number, number, number];
+/** sRGB → OKLab (Björn Ottosson's reference matrices). */
+declare function toOklab(hex: string): OklabColor;
+/** OKLab → sRGB hex, clipping each out-of-gamut channel. */
+declare function fromOklab([lightness, a, b]: OklabColor): string;
+/** `weight` of `foreground` over `background`, mixed in OKLab. 0 → background, 1 → foreground. */
+declare function mixOklab(foreground: string, background: string, weight: number): string;
+/** The two tones whose state tints are derived (`tone.accent.*`, `tone.danger.*`). */
+type ToneName = "accent" | "danger";
+/** `tone.<tone>.<state>` → hex for one theme, from that theme's tone colours and raised surface. */
+declare function toneValues(tones: Readonly<Record<ToneName, string>>, surfaceRaised: string): Readonly<Record<string, string>>;
+
+export { CDT_PREFIX, type OklabColor, PACKAGE_NAME, SEVERITY_ICONS, STATUS_ICONS, type SeverityIconName, type StatusIconName, type TokenDefinition, type TokenGroup, type TokenTier, type TokenUsage, type ToneName, contrastRatio, fromOklab, mixOklab, toOklab, toneValues };

package/dist/index.js

@@ -476,4 +476,174 @@ var SEVERITY_ICONS = {
   blocked: "shield-x"
 };
 
-export { CDT_PREFIX, PACKAGE_NAME, SEVERITY_ICONS, STATUS_ICONS, breakpoints, tokens };
+// src/contrast/color.ts
+var HEX_SOURCE = "#([0-9a-f]{3,8})\\b";
+var FUNCTIONAL_SOURCE = "\\b(rgba?|hsla?)\\(\\s*([^()]*)\\)";
+var clamp = (value, low, high) => Math.min(Math.max(value, low), high);
+function fromHex(digits) {
+  const byte = (pair) => parseInt(pair.length === 1 ? pair + pair : pair, 16);
+  if (digits.length === 3 || digits.length === 4) {
+    const [r, g, b, a] = [...digits];
+    return { r: byte(r), g: byte(g), b: byte(b), alpha: a === void 0 ? 1 : byte(a) / 255 };
+  }
+  if (digits.length === 6 || digits.length === 8) {
+    const at = (index) => digits.slice(index, index + 2);
+    return {
+      r: byte(at(0)),
+      g: byte(at(2)),
+      b: byte(at(4)),
+      alpha: digits.length === 8 ? byte(at(6)) / 255 : 1
+    };
+  }
+  return void 0;
+}
+function argumentsOf(body) {
+  return body.replace(/\//g, " ").split(/[\s,]+/).filter((part) => part !== "");
+}
+function toAlpha(raw) {
+  if (raw === void 0) return 1;
+  const value = raw.endsWith("%") ? Number(raw.slice(0, -1)) / 100 : Number(raw);
+  return Number.isFinite(value) ? clamp(value, 0, 1) : 1;
+}
+function fromRgb(body) {
+  const parts = argumentsOf(body);
+  if (parts.length < 3) return void 0;
+  const channel = (raw) => {
+    const value = raw.endsWith("%") ? Number(raw.slice(0, -1)) / 100 * 255 : Number(raw);
+    return Number.isFinite(value) ? clamp(Math.round(value), 0, 255) : Number.NaN;
+  };
+  const r = channel(parts[0]);
+  const g = channel(parts[1]);
+  const b = channel(parts[2]);
+  if ([r, g, b].some(Number.isNaN)) return void 0;
+  return { r, g, b, alpha: toAlpha(parts[3]) };
+}
+function fromHsl(body) {
+  const parts = argumentsOf(body);
+  if (parts.length < 3) return void 0;
+  const hue = Number(parts[0].replace(/deg$/i, ""));
+  const saturation = Number(parts[1].replace(/%$/, "")) / 100;
+  const lightness = Number(parts[2].replace(/%$/, "")) / 100;
+  if (![hue, saturation, lightness].every((value) => Number.isFinite(value))) return void 0;
+  const chroma = (1 - Math.abs(2 * clamp(lightness, 0, 1) - 1)) * clamp(saturation, 0, 1);
+  const sextant = (hue % 360 + 360) % 360 / 60;
+  const secondary = chroma * (1 - Math.abs(sextant % 2 - 1));
+  const lift = clamp(lightness, 0, 1) - chroma / 2;
+  const wheel = [
+    [chroma, secondary, 0],
+    [secondary, chroma, 0],
+    [0, chroma, secondary],
+    [0, secondary, chroma],
+    [secondary, 0, chroma],
+    [chroma, 0, secondary]
+  ];
+  const [r, g, b] = wheel[Math.floor(sextant) % 6];
+  const channel = (raw) => clamp(Math.round((raw + lift) * 255), 0, 255);
+  return { r: channel(r), g: channel(g), b: channel(b), alpha: toAlpha(parts[3]) };
+}
+function parseFunctional(name, body) {
+  return name.toLowerCase().startsWith("hsl") ? fromHsl(body) : fromRgb(body);
+}
+function findColors(value) {
+  const found = [];
+  for (const match of value.matchAll(new RegExp(FUNCTIONAL_SOURCE, "gi"))) {
+    const parsed = parseFunctional(match[1], match[2]);
+    if (parsed) found.push(parsed);
+  }
+  for (const match of value.matchAll(new RegExp(HEX_SOURCE, "gi"))) {
+    const parsed = fromHex(match[1]);
+    if (parsed) found.push(parsed);
+  }
+  return found;
+}
+function linearise(channel8) {
+  const channel = channel8 / 255;
+  return channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+}
+function relativeLuminance({ r, g, b }) {
+  return 0.2126 * linearise(r) + 0.7152 * linearise(g) + 0.0722 * linearise(b);
+}
+function contrastRatio(one, other) {
+  const first = relativeLuminance(one);
+  const second = relativeLuminance(other);
+  const lighter = Math.max(first, second);
+  const darker = Math.min(first, second);
+  return (lighter + 0.05) / (darker + 0.05);
+}
+function compositeOver(foreground, background) {
+  if (foreground.alpha >= 1) return foreground;
+  const mix = (front, back) => Math.round(front * foreground.alpha + back * (1 - foreground.alpha));
+  return {
+    r: mix(foreground.r, background.r),
+    g: mix(foreground.g, background.g),
+    b: mix(foreground.b, background.b),
+    alpha: 1
+  };
+}
+
+// src/measure.ts
+function parse(role, value) {
+  const colours = findColors(value);
+  if (colours.length !== 1) throw new Error(`contrastRatio: ${role} "${value}" must hold exactly one #hex, rgb() or hsl() colour, found ${colours.length}`);
+  return colours[0];
+}
+function contrastRatio2(foreground, background) {
+  const back = parse("background", background);
+  if (back.alpha < 1) throw new Error(`contrastRatio: background "${background}" is translucent; composite it onto its surface first`);
+  return contrastRatio(compositeOver(parse("foreground", foreground), back), back);
+}
+
+// src/oklab.ts
+var HEX = /^#([0-9a-f]{6})$/i;
+function parseHex(hex) {
+  const match = HEX.exec(hex);
+  if (match === null) throw new Error(`oklab: expected #rrggbb, got "${hex}"`);
+  const digits = match[1];
+  return [0, 2, 4].map((offset) => Number.parseInt(digits.slice(offset, offset + 2), 16) / 255);
+}
+var toLinear = (channel) => channel <= 0.04045 ? channel / 12.92 : ((channel + 0.055) / 1.055) ** 2.4;
+var toGamma = (channel) => channel <= 31308e-7 ? 12.92 * channel : 1.055 * channel ** (1 / 2.4) - 0.055;
+var clamp2 = (channel) => Math.min(1, Math.max(0, channel));
+function toOklab(hex) {
+  const [r, g, b] = parseHex(hex).map(toLinear);
+  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);
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s
+  ];
+}
+function fromOklab([lightness, a, b]) {
+  const l = (lightness + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+  const m = (lightness - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+  const s = (lightness - 0.0894841775 * a - 1.291485548 * b) ** 3;
+  const linear = [
+    4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s
+  ];
+  return `#${linear.map((channel) => Math.round(clamp2(toGamma(clamp2(channel))) * 255).toString(16).padStart(2, "0")).join("")}`;
+}
+function mixOklab(foreground, background, weight) {
+  if (!(weight >= 0 && weight <= 1)) throw new Error(`oklab: weight must be within [0, 1], got ${weight}`);
+  const front = toOklab(foreground);
+  const back = toOklab(background);
+  return fromOklab(front.map((channel, index) => channel * weight + back[index] * (1 - weight)));
+}
+var TONE_WEIGHTS = {
+  background: 0.04,
+  border: 0.14,
+  backgroundHover: 0.12,
+  borderHover: 0.45
+};
+function toneValues(tones, surfaceRaised) {
+  const out = {};
+  for (const tone of Object.keys(tones)) {
+    for (const [state, weight] of Object.entries(TONE_WEIGHTS)) out[`tone.${tone}.${state}`] = mixOklab(tones[tone], surfaceRaised, weight);
+  }
+  return out;
+}
+
+export { CDT_PREFIX, PACKAGE_NAME, SEVERITY_ICONS, STATUS_ICONS, breakpoints, contrastRatio2 as contrastRatio, fromOklab, mixOklab, toOklab, tokens, toneValues };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conductor-by-89soone/tokens",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Theme-aware design tokens and validation CLIs for Conductor.",
   "license": "MIT",
   "homepage": "https://89sooner.github.io/design-system/",