@rhombuskit/theme-builder 1.15.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doug Williamson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @rhombuskit/theme-builder
+
+Generate WCAG-AA-validated [RhombusKit](https://rhombuskit.online) themes from a few seed
+colours. Framework-agnostic (no Angular peer) — usable from a build script, a CLI, or the
+interactive [`/theme-builder`](https://rhombuskit.online/theme-builder) page.
+
+You give it a brand accent (and, optionally, a neutral); it emits **both** a light and a dark
+theme covering the full 60-token RhombusKit CONTRACT, then re-validates every text/background
+pair for WCAG 2.1 AA and either returns an AA-clean theme or throws — it never returns sub-AA
+output.
+
+## Install
+
+```sh
+npm i @rhombuskit/theme-builder @rhombuskit/tokens
+```
+
+## Usage
+
+```ts
+import { generateTheme, serializeThemeCss, toRegisteredThemes } from '@rhombuskit/theme-builder';
+
+const theme = generateTheme({ accent: '#0f766e', name: 'teal' });
+
+// Paste-ready [data-theme] CSS over all 60 CONTRACT tokens (light + dark):
+console.log(serializeThemeCss(theme));
+
+// Metadata for the theme registry (pair with the CSS above):
+const registered = toRegisteredThemes(theme); // RegisteredTheme[]
+```
+
+The emitted CSS + registration follow the sanctioned custom-theme path in
+[the theming guide](https://rhombuskit.online/theming). A bare `generateTheme()` reproduces the
+built-in `rhombus-light`/`rhombus-dark` packs byte-for-byte.
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,113 @@
+import { SemanticTokenName } from '@rhombuskit/tokens';
+
+declare const RUNGS: readonly [50, 100, 200, 300, 400, 500, 600, 700, 800, 900, 950];
+type Rung = (typeof RUNGS)[number];
+type FullRamp = Record<Rung, string>;
+
+/** A few seed colours in. See the spec for the derivation. */
+interface ThemeSeed {
+    /** Brand accent hex. Omitted OR === #7c3aed → shipped violet verbatim. */
+    accent?: string;
+    /** Neutral/surface base hex. Omitted OR === #64748b (slate-500) → shipped slate verbatim. */
+    neutral?: string;
+    /** Registry id (default: the OKLCH hue name of the accent, e.g. "indigo"). */
+    name?: string;
+    /** Human label (default: Title-Case of name). */
+    label?: string;
+    /** Chroma-envelope multiplier for generated ramps (default 1, clamped [0.5, 1.5]). */
+    vividness?: number;
+}
+/** A complete light + dark theme over the 60-token CONTRACT, plus a fidelity report. */
+interface GeneratedTheme {
+    name: string;
+    label: string;
+    light: Record<SemanticTokenName, string>;
+    dark: Record<SemanticTokenName, string>;
+    report: {
+        warnings: string[];
+    };
+}
+interface BuildOptions {
+    /** Disable the AA-rescue nudge. Only for the red-gate test — a green seed then throws. */
+    nudge?: boolean;
+}
+/**
+ * Structural match for `@rhombuskit/theme-engine`'s `RegisteredTheme` — declared locally so this
+ * package stays free of an Angular/theme-engine dependency. Assignable to `provideRhombusThemes()`.
+ */
+interface RegisteredThemeMeta {
+    name: string;
+    label: string;
+    mode: 'light' | 'dark';
+    palette: string;
+}
+
+/** A dark, hue-preserving tint for the one dark background no ramp step can supply. */
+declare function deepTint(hex: string): string;
+/** Synthesize an 11-rung ramp from a seed: fixed lightness ladder, seed hue + scaled chroma. */
+declare function buildRamp(seedHex: string, Lcurve: readonly number[], Cenv: readonly number[], cap?: readonly number[], vividness?: number): FullRamp;
+/** Generate a complete, AA-clean light + dark theme from a few seed colours. */
+declare function build(seed?: ThemeSeed, opts?: BuildOptions): GeneratedTheme;
+
+interface ThemeAAFailure {
+    fg: SemanticTokenName;
+    bg: SemanticTokenName;
+    ratio: number;
+    min: number;
+}
+interface ThemeAAResult {
+    ok: boolean;
+    failures: ThemeAAFailure[];
+}
+type ThemeRecord = Partial<Record<SemanticTokenName, string>>;
+declare function validateThemeAA(record: ThemeRecord): ThemeAAResult;
+
+/** Two `[data-theme="<name>"]{…}` blocks (light + `-dark`) over every CONTRACT token. */
+declare function serializeThemeCss(theme: GeneratedTheme): string;
+/** Light + dark `RegisteredTheme` metadata sharing one palette (pair with the CSS above). */
+declare function toRegisteredThemes(theme: GeneratedTheme): RegisteredThemeMeta[];
+/** The `declare module '@rhombuskit/theme-engine'` snippet so `setTheme('<name>')` type-checks. */
+declare function toAugmentation(theme: GeneratedTheme): string;
+
+/** [r, g, b] in 0–255, a in 0–1. */
+type Rgba = [number, number, number, number];
+/**
+ * Parse `#rgb` / `#rrggbb` / `#rrggbbaa` / `rgb()` / `rgba()` (space- or comma-separated,
+ * optional slash or 4th-value alpha). Returns null for var()/color-mix/named/anything else —
+ * such values are not contrast-checkable and are skipped by callers.
+ */
+declare function parseColor(css: string): Rgba | null;
+/** Normalise any parseable colour to lowercase `#rrggbb` (alpha stripped); null if unparseable. */
+declare function normalizeHex(css: string): string | null;
+/** WCAG 2.1 relative luminance (sRGB linearisation, 0.2126/0.7152/0.0722). */
+declare function relativeLuminance([r, g, b]: readonly [number, number, number]): number;
+/** WCAG contrast ratio (Lhi+0.05)/(Llo+0.05); null if either side is non-concrete. */
+declare function contrastRatio(fg: string, bg: string): number | null;
+/**
+ * Composite a (possibly translucent) foreground over a solid background, returning the opaque
+ * hex the viewer actually sees. Used before measuring contrast so alpha can never pass vacuously.
+ * An opaque foreground is returned unchanged (as hex).
+ */
+declare function alphaComposite(fg: string, bg: string): string;
+interface Oklch {
+    L: number;
+    C: number;
+    H: number;
+}
+declare function toOKLCH(hex: string): Oklch;
+/** OKLCH → hex (channels clamped to 0–255; use gamutClampToSrgb first for faithful hues). */
+declare function fromOKLCH(L: number, C: number, H: number): string;
+/**
+ * Reduce chroma (holding L and H) until the colour fits inside sRGB, then convert to hex.
+ * An already-in-gamut colour is returned exactly. CSS Color 4 chroma reduction by bisection.
+ */
+declare function gamutClampToSrgb(L: number, C: number, H: number): string;
+
+/** Thrown when a generated theme cannot be made AA-clean — the generator never returns sub-AA. */
+declare class ThemeAAError extends Error {
+    readonly mode: 'light' | 'dark';
+    readonly failures: ThemeAAFailure[];
+    constructor(mode: 'light' | 'dark', failures: ThemeAAFailure[]);
+}
+
+export { type BuildOptions, type GeneratedTheme, type Oklch, type RegisteredThemeMeta, type Rgba, ThemeAAError, type ThemeAAFailure, type ThemeAAResult, type ThemeSeed, alphaComposite, buildRamp, contrastRatio, deepTint, fromOKLCH, gamutClampToSrgb, build as generateTheme, normalizeHex, parseColor, relativeLuminance, serializeThemeCss, toAugmentation, toOKLCH, toRegisteredThemes, validateThemeAA };

package/dist/index.mjs

@@ -0,0 +1,833 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/color-math.ts
+var clampByte = /* @__PURE__ */ __name((n) => Math.min(255, Math.max(0, Math.round(n))), "clampByte");
+var toHex = /* @__PURE__ */ __name((r, g, b) => "#" + [
+  r,
+  g,
+  b
+].map((c) => clampByte(c).toString(16).padStart(2, "0")).join(""), "toHex");
+function parseColor(css) {
+  const s = css.trim();
+  let m = /^#([0-9a-f]{3})$/i.exec(s);
+  if (m) {
+    const h = m[1];
+    return [
+      parseInt(h[0] + h[0], 16),
+      parseInt(h[1] + h[1], 16),
+      parseInt(h[2] + h[2], 16),
+      1
+    ];
+  }
+  m = /^#([0-9a-f]{6})([0-9a-f]{2})?$/i.exec(s);
+  if (m) {
+    const h = m[1];
+    return [
+      parseInt(h.slice(0, 2), 16),
+      parseInt(h.slice(2, 4), 16),
+      parseInt(h.slice(4, 6), 16),
+      m[2] === void 0 ? 1 : parseInt(m[2], 16) / 255
+    ];
+  }
+  m = /^rgba?\(\s*([0-9.]+)[\s,]+([0-9.]+)[\s,]+([0-9.]+)(?:\s*[,/]\s*([0-9.]+))?\s*\)$/i.exec(s);
+  if (m) {
+    return [
+      Number(m[1]),
+      Number(m[2]),
+      Number(m[3]),
+      m[4] === void 0 ? 1 : Number(m[4])
+    ];
+  }
+  return null;
+}
+__name(parseColor, "parseColor");
+function normalizeHex(css) {
+  const p = parseColor(css);
+  return p ? toHex(p[0], p[1], p[2]) : null;
+}
+__name(normalizeHex, "normalizeHex");
+function relativeLuminance([r, g, b]) {
+  const channel = /* @__PURE__ */ __name((v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+  }, "channel");
+  return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+__name(relativeLuminance, "relativeLuminance");
+function contrastRatio(fg, bg) {
+  const a = parseColor(fg);
+  const b = parseColor(bg);
+  if (!a || !b) return null;
+  const l1 = relativeLuminance([
+    a[0],
+    a[1],
+    a[2]
+  ]);
+  const l2 = relativeLuminance([
+    b[0],
+    b[1],
+    b[2]
+  ]);
+  return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05);
+}
+__name(contrastRatio, "contrastRatio");
+function alphaComposite(fg, bg) {
+  const f = parseColor(fg);
+  const b = parseColor(bg);
+  if (!f || !b) return fg;
+  const a = f[3];
+  return toHex(f[0] * a + b[0] * (1 - a), f[1] * a + b[1] * (1 - a), f[2] * a + b[2] * (1 - a));
+}
+__name(alphaComposite, "alphaComposite");
+var linearize = /* @__PURE__ */ __name((c) => c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4), "linearize");
+var delinearize = /* @__PURE__ */ __name((c) => c <= 31308e-7 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055, "delinearize");
+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 [
+    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_
+  ];
+}
+__name(linearSrgbToOklab, "linearSrgbToOklab");
+function oklabToLinearSrgb(L, a, b) {
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+  const l = l_ * l_ * l_;
+  const m = m_ * m_ * m_;
+  const s = s_ * s_ * s_;
+  return [
+    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
+  ];
+}
+__name(oklabToLinearSrgb, "oklabToLinearSrgb");
+function toOKLCH(hex) {
+  const p = parseColor(hex);
+  if (!p) throw new Error(`toOKLCH: unparseable colour "${hex}"`);
+  const [L, a, b] = linearSrgbToOklab(linearize(p[0] / 255), linearize(p[1] / 255), linearize(p[2] / 255));
+  const C = Math.hypot(a, b);
+  let H = Math.atan2(b, a) * 180 / Math.PI;
+  if (H < 0) H += 360;
+  return {
+    L,
+    C,
+    H
+  };
+}
+__name(toOKLCH, "toOKLCH");
+function fromOKLCH(L, C, H) {
+  const rad = H * Math.PI / 180;
+  const [r, g, b] = oklabToLinearSrgb(L, C * Math.cos(rad), C * Math.sin(rad));
+  return toHex(delinearize(r) * 255, delinearize(g) * 255, delinearize(b) * 255);
+}
+__name(fromOKLCH, "fromOKLCH");
+function inGamut(L, C, H) {
+  const rad = H * Math.PI / 180;
+  const lin = oklabToLinearSrgb(L, C * Math.cos(rad), C * Math.sin(rad));
+  const eps = 1e-4;
+  return lin.every((c) => c >= -eps && c <= 1 + eps);
+}
+__name(inGamut, "inGamut");
+function gamutClampToSrgb(L, C, H) {
+  if (inGamut(L, C, H)) return fromOKLCH(L, C, H);
+  let lo = 0;
+  let hi = C;
+  for (let i = 0; i < 28; i++) {
+    const mid = (lo + hi) / 2;
+    if (inGamut(L, mid, H)) lo = mid;
+    else hi = mid;
+  }
+  return fromOKLCH(L, lo, H);
+}
+__name(gamutClampToSrgb, "gamutClampToSrgb");
+
+// src/constants.ts
+import { tokens } from "@rhombuskit/tokens";
+var RUNGS = [
+  50,
+  100,
+  200,
+  300,
+  400,
+  500,
+  600,
+  700,
+  800,
+  900,
+  950
+];
+var prim = tokens.primitives;
+function sourceRamp(family) {
+  const ramp = {};
+  for (const step of RUNGS) {
+    const value = prim[`${family}-${step}`];
+    if (value) ramp[step] = value;
+  }
+  return ramp;
+}
+__name(sourceRamp, "sourceRamp");
+var RAMPS = {
+  violet: sourceRamp("violet"),
+  slate: sourceRamp("slate"),
+  green: sourceRamp("green"),
+  amber: sourceRamp("amber"),
+  red: sourceRamp("red")
+};
+var L_ACCENT_CURVE = RUNGS.map((r) => toOKLCH(RAMPS.violet[r]).L);
+var CHROMA_ENV = RUNGS.map((r) => toOKLCH(RAMPS.violet[r]).C);
+var L_NEUTRAL_CURVE = RUNGS.map((r) => toOKLCH(RAMPS.slate[r]).L);
+var C_NEUTRAL_CAP = RUNGS.map((r) => toOKLCH(RAMPS.slate[r]).C);
+var BASE = {
+  light: tokens.themes["rhombus-light"],
+  dark: tokens.themes["rhombus-dark"]
+};
+var CONTRACT_KEYS = Object.keys(BASE.light);
+var TEXT_PAIRS = [
+  [
+    "--text-primary",
+    "--bg"
+  ],
+  [
+    "--text-primary",
+    "--surface-0"
+  ],
+  [
+    "--text-primary",
+    "--surface-1"
+  ],
+  [
+    "--text-primary",
+    "--surface-2"
+  ],
+  [
+    "--text-secondary",
+    "--bg"
+  ],
+  [
+    "--text-secondary",
+    "--surface-0"
+  ],
+  [
+    "--text-muted",
+    "--bg"
+  ],
+  [
+    "--text-muted",
+    "--surface-0"
+  ],
+  [
+    "--text-accent",
+    "--bg"
+  ],
+  [
+    "--text-accent",
+    "--surface-0"
+  ],
+  [
+    "--btn-primary-text",
+    "--btn-primary-bg"
+  ],
+  [
+    "--text-on-accent",
+    "--btn-primary-bg"
+  ],
+  [
+    "--nav-active-text",
+    "--nav-active-bg"
+  ],
+  [
+    "--tooltip-text",
+    "--tooltip-bg"
+  ],
+  [
+    "--toast-info-text",
+    "--toast-info-bg"
+  ],
+  [
+    "--toast-success-text",
+    "--toast-success-bg"
+  ],
+  [
+    "--toast-warning-text",
+    "--toast-warning-bg"
+  ],
+  [
+    "--toast-error-text",
+    "--toast-error-bg"
+  ],
+  [
+    "--code-keyword",
+    "--surface-0"
+  ],
+  [
+    "--code-string",
+    "--surface-0"
+  ],
+  [
+    "--code-function",
+    "--surface-0"
+  ],
+  [
+    "--code-number",
+    "--surface-0"
+  ],
+  [
+    "--code-comment",
+    "--surface-0"
+  ],
+  [
+    "--code-punctuation",
+    "--surface-0"
+  ]
+];
+var BADGE_PAIRS = [
+  [
+    "--status-draft-text",
+    "--status-draft-bg"
+  ],
+  [
+    "--status-published-text",
+    "--status-published-bg"
+  ],
+  [
+    "--status-scheduled-text",
+    "--status-scheduled-bg"
+  ],
+  [
+    "--status-archived-text",
+    "--status-archived-bg"
+  ]
+];
+
+// src/validate.ts
+function solidify(value, bg) {
+  if (value === void 0) return void 0;
+  const parsed = parseColor(value);
+  if (parsed && parsed[3] < 1) return alphaComposite(value, bg);
+  return value;
+}
+__name(solidify, "solidify");
+function validateThemeAA(record) {
+  const bg = record["--bg"] ?? "#ffffff";
+  const failures = [];
+  const check = /* @__PURE__ */ __name((pairs, min) => {
+    for (const [fgTok, bgTok] of pairs) {
+      const fg = solidify(record[fgTok], bg);
+      const bgVal = solidify(record[bgTok], bg);
+      if (fg === void 0 || bgVal === void 0) continue;
+      const ratio = contrastRatio(fg, bgVal);
+      if (ratio === null) continue;
+      if (ratio < min) failures.push({
+        fg: fgTok,
+        bg: bgTok,
+        ratio,
+        min
+      });
+    }
+  }, "check");
+  check(TEXT_PAIRS, 4.5);
+  check(BADGE_PAIRS, 3);
+  return {
+    ok: failures.length === 0,
+    failures
+  };
+}
+__name(validateThemeAA, "validateThemeAA");
+
+// src/errors.ts
+var ThemeAAError = class extends Error {
+  static {
+    __name(this, "ThemeAAError");
+  }
+  mode;
+  failures;
+  constructor(mode, failures) {
+    super(`Generated ${mode} theme failed WCAG AA on ${failures.length} pair(s): ` + failures.map((f) => `${f.fg} on ${f.bg} = ${f.ratio.toFixed(2)}:1 (needs ${f.min}:1)`).join("; ")), this.mode = mode, this.failures = failures;
+    this.name = "ThemeAAError";
+  }
+};
+
+// src/generate.ts
+var CANON_ACCENT = "#7c3aed";
+var CANON_NEUTRAL = "#64748b";
+var alpha = /* @__PURE__ */ __name((hex, a) => {
+  const p = parseColor(hex);
+  return `rgb(${p[0]} ${p[1]} ${p[2]} / ${a})`;
+}, "alpha");
+function deepTint(hex) {
+  return gamutClampToSrgb(0.2, 0.07, toOKLCH(hex).H);
+}
+__name(deepTint, "deepTint");
+var ACCENT = {
+  light: {
+    "--text-accent": {
+      rung: 600
+    },
+    "--border-accent": {
+      rung: 200
+    },
+    "--focus-ring": {
+      fn: /* @__PURE__ */ __name((r) => alpha(r[600], "0.22"), "fn")
+    },
+    "--focus-border": {
+      rung: 600
+    },
+    "--btn-primary-bg": {
+      rung: 600
+    },
+    "--btn-primary-hover": {
+      rung: 700
+    },
+    "--nav-active-bg": {
+      rung: 50
+    },
+    "--nav-active-text": {
+      rung: 700
+    },
+    "--switch-track-on": {
+      rung: 600
+    },
+    "--shadow-btn-primary": {
+      fn: /* @__PURE__ */ __name((r) => `0 1px 2px 0 ${alpha(r[600], "0.25")}`, "fn")
+    },
+    "--status-scheduled-bg": {
+      rung: 50
+    },
+    "--status-scheduled-text": {
+      rung: 600
+    },
+    "--code-keyword": {
+      rung: 700
+    }
+  },
+  dark: {
+    "--text-accent": {
+      rung: 400
+    },
+    "--border-accent": {
+      fn: /* @__PURE__ */ __name((r) => alpha(r[400], "0.40"), "fn")
+    },
+    "--focus-ring": {
+      fn: /* @__PURE__ */ __name((r) => alpha(r[400], "0.28"), "fn")
+    },
+    "--focus-border": {
+      rung: 400
+    },
+    "--btn-primary-bg": {
+      rung: 600
+    },
+    "--btn-primary-hover": {
+      rung: 700
+    },
+    // Solid deep-tint (not the built-in's translucent alpha) so the generated theme also
+    // clears a raw-channel contrast guard — matching the shipped community themes, which use a
+    // solid dark nav-active-bg for exactly this reason (community-themes.ts). See validate.ts.
+    "--nav-active-bg": {
+      fn: /* @__PURE__ */ __name((r) => deepTint(r[600]), "fn")
+    },
+    "--switch-track-on": {
+      rung: 500
+    },
+    "--status-scheduled-bg": {
+      fn: /* @__PURE__ */ __name((r) => deepTint(r[600]), "fn")
+    },
+    "--status-scheduled-text": {
+      rung: 400
+    },
+    "--code-keyword": {
+      rung: 300
+    }
+  }
+};
+var NEUTRAL = {
+  light: {
+    "--bg": {
+      rung: 50
+    },
+    "--bg-subtle": {
+      rung: 100
+    },
+    "--surface-1": {
+      rung: 100
+    },
+    "--surface-2": {
+      rung: 200
+    },
+    "--surface-3": {
+      rung: 300
+    },
+    "--text-primary": {
+      rung: 900
+    },
+    "--text-secondary": {
+      rung: 600
+    },
+    "--text-muted": {
+      rung: 500
+    },
+    "--text-disabled": {
+      rung: 300
+    },
+    "--border": {
+      rung: 200
+    },
+    "--border-strong": {
+      rung: 400
+    },
+    "--switch-track-off": {
+      rung: 300
+    },
+    "--tooltip-bg": {
+      rung: 900
+    },
+    "--toast-info-bg": {
+      rung: 100
+    },
+    "--toast-info-text": {
+      rung: 700
+    },
+    "--status-archived-bg": {
+      rung: 100
+    },
+    "--status-archived-text": {
+      rung: 600
+    },
+    "--code-comment": {
+      rung: 500
+    },
+    "--code-punctuation": {
+      rung: 600
+    }
+  },
+  dark: {
+    "--bg": {
+      rung: 950
+    },
+    "--bg-subtle": {
+      rung: 900
+    },
+    "--surface-0": {
+      rung: 900
+    },
+    "--surface-1": {
+      rung: 800
+    },
+    "--surface-2": {
+      rung: 700
+    },
+    "--surface-3": {
+      rung: 600
+    },
+    "--text-primary": {
+      rung: 50
+    },
+    "--text-secondary": {
+      rung: 300
+    },
+    "--text-muted": {
+      rung: 400
+    },
+    "--text-disabled": {
+      rung: 600
+    },
+    "--border": {
+      rung: 700
+    },
+    "--border-strong": {
+      rung: 500
+    },
+    "--switch-track-off": {
+      rung: 600
+    },
+    "--tooltip-bg": {
+      rung: 700
+    },
+    "--toast-info-bg": {
+      rung: 800
+    },
+    "--toast-info-text": {
+      rung: 200
+    },
+    "--status-archived-bg": {
+      rung: 800
+    },
+    "--status-archived-text": {
+      rung: 400
+    },
+    "--code-comment": {
+      rung: 400
+    },
+    "--code-punctuation": {
+      rung: 300
+    },
+    "--nav-active-text": {
+      rung: 50
+    }
+  }
+};
+function applyTable(rec, ramp, table, prov) {
+  for (const key of Object.keys(table)) {
+    const recipe = table[key];
+    if ("rung" in recipe) {
+      rec[key] = ramp[recipe.rung];
+      if (prov) prov[key] = {
+        ramp,
+        idx: RUNGS.indexOf(recipe.rung)
+      };
+    } else {
+      rec[key] = recipe.fn(ramp);
+    }
+  }
+}
+__name(applyTable, "applyTable");
+function overrideAccent(rec, ramp, mode, prov) {
+  applyTable(rec, ramp, ACCENT[mode], prov);
+}
+__name(overrideAccent, "overrideAccent");
+function overrideNeutral(rec, ramp, mode, prov) {
+  applyTable(rec, ramp, NEUTRAL[mode], prov);
+}
+__name(overrideNeutral, "overrideNeutral");
+function anchorOf(curve, L) {
+  let best = 0;
+  for (let i = 1; i < curve.length; i++) {
+    if (Math.abs(curve[i] - L) < Math.abs(curve[best] - L)) best = i;
+  }
+  return best;
+}
+__name(anchorOf, "anchorOf");
+function buildRamp(seedHex, Lcurve, Cenv, cap, vividness = 1) {
+  const { L: Ls, C: Cs, H: Hs } = toOKLCH(seedHex);
+  const anchor = anchorOf(Lcurve, Ls);
+  const kC = Cs / (Cenv[anchor] || 1e-6);
+  const ramp = {};
+  for (let i = 0; i < RUNGS.length; i++) {
+    const Li = Lcurve[i];
+    let Ci = Cenv[i] * kC * vividness;
+    if (cap) Ci = Math.min(Ci, cap[i]);
+    ramp[RUNGS[i]] = i === anchor && Math.abs(Li - Ls) < 0.02 ? seedHex : gamutClampToSrgb(Li, Ci, Hs);
+  }
+  return ramp;
+}
+__name(buildRamp, "buildRamp");
+function nudgeFailing(rec, mode, prov, budget) {
+  const dir = mode === "light" ? 1 : -1;
+  const bg = rec["--bg"];
+  for (const [pairs, min] of [
+    [
+      TEXT_PAIRS,
+      4.5
+    ],
+    [
+      BADGE_PAIRS,
+      3
+    ]
+  ]) {
+    for (const [fgTok, bgTok] of pairs) {
+      const p = prov[fgTok];
+      if (!p) continue;
+      for (let k = 0; k < budget; k++) {
+        const fg = solidify(rec[fgTok], bg);
+        const bgVal = solidify(rec[bgTok], bg);
+        const ratio = fg && bgVal ? contrastRatio(fg, bgVal) : null;
+        if (ratio === null || ratio >= min) break;
+        const idx = p.idx + dir;
+        if (idx < 0 || idx >= RUNGS.length) break;
+        p.idx = idx;
+        rec[fgTok] = p.ramp[RUNGS[idx]];
+      }
+    }
+  }
+}
+__name(nudgeFailing, "nudgeFailing");
+var HUE_NAMES = [
+  [
+    15,
+    "red"
+  ],
+  [
+    45,
+    "orange"
+  ],
+  [
+    70,
+    "amber"
+  ],
+  [
+    95,
+    "yellow"
+  ],
+  [
+    135,
+    "lime"
+  ],
+  [
+    165,
+    "green"
+  ],
+  [
+    195,
+    "teal"
+  ],
+  [
+    225,
+    "cyan"
+  ],
+  [
+    265,
+    "blue"
+  ],
+  [
+    295,
+    "indigo"
+  ],
+  [
+    330,
+    "violet"
+  ],
+  [
+    350,
+    "magenta"
+  ],
+  [
+    360,
+    "red"
+  ]
+];
+var hueName = /* @__PURE__ */ __name((h) => HUE_NAMES.find(([max]) => h < max)?.[1] ?? "custom", "hueName");
+var clampVividness = /* @__PURE__ */ __name((v) => v === void 0 ? 1 : Math.min(1.5, Math.max(0.5, v)), "clampVividness");
+function build(seed = {}, opts = {}) {
+  const nudge = opts.nudge !== false;
+  const vividness = clampVividness(seed.vividness);
+  const warnings = [];
+  const accentHex = seed.accent === void 0 ? CANON_ACCENT : normalizeHex(seed.accent);
+  if (accentHex === null) throw new Error(`Invalid accent colour: "${seed.accent}"`);
+  const neutralHex = seed.neutral === void 0 ? CANON_NEUTRAL : normalizeHex(seed.neutral);
+  if (neutralHex === null) throw new Error(`Invalid neutral colour: "${seed.neutral}"`);
+  const accentCustom = accentHex !== CANON_ACCENT;
+  const neutralCustom = neutralHex !== CANON_NEUTRAL;
+  const light = {
+    ...BASE.light
+  };
+  const dark = {
+    ...BASE.dark
+  };
+  const provLight = {};
+  const provDark = {};
+  if (accentCustom) {
+    const A = buildRamp(accentHex, L_ACCENT_CURVE, CHROMA_ENV, void 0, vividness);
+    overrideAccent(light, A, "light", provLight);
+    overrideAccent(dark, A, "dark", provDark);
+    const { L: Ls, C: Cs } = toOKLCH(accentHex);
+    const drift = Math.abs(RUNGS.indexOf(600) - anchorOf(L_ACCENT_CURVE, Ls));
+    if (drift > 2) {
+      warnings.push(`Accent ${accentHex} sits ${drift} rungs from the accessible accent lightness; it was adjusted to meet contrast, so the rendered accent is darker/lighter than the seed.`);
+    }
+    if (Cs < 0.04) {
+      warnings.push(`Accent ${accentHex} has very low chroma and will read close to neutral.`);
+    }
+  }
+  if (neutralCustom) {
+    const N = buildRamp(neutralHex, L_NEUTRAL_CURVE, C_NEUTRAL_CAP, C_NEUTRAL_CAP, vividness);
+    overrideNeutral(light, N, "light", provLight);
+    overrideNeutral(dark, N, "dark", provDark);
+  }
+  for (const [rec, mode, prov] of [
+    [
+      light,
+      "light",
+      provLight
+    ],
+    [
+      dark,
+      "dark",
+      provDark
+    ]
+  ]) {
+    if (nudge) nudgeFailing(rec, mode, prov, 2);
+    const result = validateThemeAA(rec);
+    if (!result.ok) throw new ThemeAAError(mode, result.failures);
+  }
+  const name = seed.name ?? (accentCustom ? hueName(toOKLCH(accentHex).H) : "rhombus");
+  const label = seed.label ?? name.charAt(0).toUpperCase() + name.slice(1);
+  return {
+    name,
+    label,
+    light,
+    dark,
+    report: {
+      warnings
+    }
+  };
+}
+__name(build, "build");
+
+// src/serialize.ts
+function block(name, values) {
+  const lines = CONTRACT_KEYS.map((key) => `  ${key}: ${values[key]};`).join("\n");
+  return `[data-theme="${name}"] {
+${lines}
+}`;
+}
+__name(block, "block");
+function serializeThemeCss(theme) {
+  return `${block(theme.name, theme.light)}
+
+${block(`${theme.name}-dark`, theme.dark)}
+`;
+}
+__name(serializeThemeCss, "serializeThemeCss");
+function toRegisteredThemes(theme) {
+  return [
+    {
+      name: theme.name,
+      label: theme.label,
+      mode: "light",
+      palette: theme.name
+    },
+    {
+      name: `${theme.name}-dark`,
+      label: theme.label,
+      mode: "dark",
+      palette: theme.name
+    }
+  ];
+}
+__name(toRegisteredThemes, "toRegisteredThemes");
+function toAugmentation(theme) {
+  return `declare module '@rhombuskit/theme-engine' {
+  interface ThemeRegistry {
+    '${theme.name}': true;
+    '${theme.name}-dark': true;
+  }
+}
+`;
+}
+__name(toAugmentation, "toAugmentation");
+export {
+  ThemeAAError,
+  alphaComposite,
+  buildRamp,
+  contrastRatio,
+  deepTint,
+  fromOKLCH,
+  gamutClampToSrgb,
+  build as generateTheme,
+  normalizeHex,
+  parseColor,
+  relativeLuminance,
+  serializeThemeCss,
+  toAugmentation,
+  toOKLCH,
+  toRegisteredThemes,
+  validateThemeAA
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@rhombuskit/theme-builder",
+  "version": "1.15.0",
+  "license": "MIT",
+  "description": "Generate WCAG-AA-validated RhombusKit token-override themes from a few seed colours — a framework-agnostic seed→theme generator that emits both light and dark packs over the full 60-token CONTRACT.",
+  "keywords": [
+    "design-tokens",
+    "theming",
+    "color",
+    "oklch",
+    "wcag",
+    "accessibility",
+    "design-system",
+    "rhombuskit"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doug-williamson/RhombusKit.git",
+    "directory": "packages/theme-builder"
+  },
+  "homepage": "https://rhombuskit.online",
+  "funding": "https://github.com/sponsors/doug-williamson",
+  "bugs": {
+    "url": "https://github.com/doug-williamson/RhombusKit/issues"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@rhombuskit/tokens": "1.15.0"
+  },
+  "scripts": {
+    "build": "tsup"
+  }
+}