@riverbankcms/sdk 0.111.0 → 0.119.0

package/dist/server/theme.mjs

@@ -1,6 +1,346 @@
 import z, { z as z$1 } from "zod";
 import * as fs from "fs/promises";
 import * as path from "path";
+//#region ../theme-core/src/palette/utils/colorConversion.ts
+const clamp01 = (x) => Math.max(0, Math.min(1, x));
+const mod = (a, n) => (a % n + n) % n;
+const deg = (x) => mod(x, 360);
+function hexToRgb(hex) {
+	const h = hex.replace(/^#/, "");
+	const m = h.length === 3 ? h.split("").map((c) => c + c).join("") : h;
+	if (m.length !== 6) throw new Error("Bad hex");
+	const int = parseInt(m, 16);
+	return {
+		r: int >> 16 & 255,
+		g: int >> 8 & 255,
+		b: int & 255
+	};
+}
+function rgbToHex(r, g, b) {
+	const to = (n) => Math.round(n).toString(16).padStart(2, "0");
+	return `#${to(r)}${to(g)}${to(b)}`;
+}
+function srgbToLinear(u) {
+	const x = u / 255;
+	return x <= .04045 ? x / 12.92 : Math.pow((x + .055) / 1.055, 2.4);
+}
+function linearToSrgb(x) {
+	return clamp01(x <= .0031308 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - .055) * 255;
+}
+function rgbToHsl(r, g, b) {
+	const R = r / 255, G = g / 255, B = b / 255;
+	const max = Math.max(R, G, B), min = Math.min(R, G, B);
+	const d = max - min;
+	let h = 0;
+	if (d !== 0) {
+		switch (max) {
+			case R:
+				h = (G - B) / d + (G < B ? 6 : 0);
+				break;
+			case G:
+				h = (B - R) / d + 2;
+				break;
+			case B:
+				h = (R - G) / d + 4;
+				break;
+		}
+		h *= 60;
+	}
+	const l = (max + min) / 2;
+	const s = d === 0 ? 0 : d / (1 - Math.abs(2 * l - 1));
+	return {
+		h,
+		s,
+		l
+	};
+}
+function srgbToOklab(r, g, b) {
+	const R = srgbToLinear(r), G = srgbToLinear(g), B = srgbToLinear(b);
+	const l = .4122214708 * R + .5363325363 * G + .0514459929 * B;
+	const m = .2119034982 * R + .6806995451 * G + .1073969566 * B;
+	const s = .0883024619 * R + .2817188376 * G + .6299787005 * B;
+	const l_ = Math.cbrt(l), m_ = Math.cbrt(m), s_ = Math.cbrt(s);
+	return {
+		L: .2104542553 * l_ + .793617785 * m_ - .0040720468 * s_,
+		a: 1.9779984951 * l_ - 2.428592205 * m_ + .4505937099 * s_,
+		b: .0259040371 * l_ + .7827717662 * m_ - .808675766 * s_
+	};
+}
+function oklabToSrgb(L, a, b) {
+	const l_ = Math.pow(L + .3963377774 * a + .2158037573 * b, 3);
+	const m_ = Math.pow(L - .1055613458 * a - .0638541728 * b, 3);
+	const s_ = Math.pow(L - .0894841775 * a - 1.291485548 * b, 3);
+	const R = 4.0767416621 * l_ - 3.3077115913 * m_ + .2309699292 * s_;
+	const G = -1.2684380046 * l_ + 2.6097574011 * m_ - .3413193965 * s_;
+	const B = -.0041960863 * l_ - .7034186147 * m_ + 1.707614701 * s_;
+	return {
+		r: linearToSrgb(R),
+		g: linearToSrgb(G),
+		b: linearToSrgb(B)
+	};
+}
+function oklabToOklch(L, a, b) {
+	const C = Math.sqrt(a * a + b * b);
+	return {
+		L,
+		C,
+		h: C < 1e-7 ? 0 : deg(Math.atan2(b, a) * 180 / Math.PI)
+	};
+}
+function oklchToOklab(L, C, h) {
+	const hr = h * Math.PI / 180;
+	return {
+		L,
+		a: C * Math.cos(hr),
+		b: C * Math.sin(hr)
+	};
+}
+function inSRGB(r, g, b) {
+	return r >= 0 && r <= 255 && g >= 0 && g <= 255 && b >= 0 && b <= 255;
+}
+function oklchToHexGamut(L, C, h) {
+	let lo = 0, hi = C, best = 0;
+	for (let i = 0; i < 18; i++) {
+		const mid = (lo + hi) / 2;
+		const { a, b } = oklchToOklab(L, mid, h);
+		const { r, g, b: bb } = oklabToSrgb(L, a, b);
+		if (inSRGB(r, g, bb)) {
+			best = mid;
+			lo = mid;
+		} else hi = mid;
+	}
+	const { a, b } = oklchToOklab(L, best, h);
+	const { r, g, b: bb } = oklabToSrgb(L, a, b);
+	return rgbToHex(r, g, bb);
+}
+function featuresFromHex(hex) {
+	const { r, g, b } = hexToRgb(hex);
+	const { h, s, l } = rgbToHsl(r, g, b);
+	const { L, a, b: b2 } = srgbToOklab(r, g, b);
+	const { L: okL, C: okC, h: okH } = oklabToOklch(L, a, b2);
+	return {
+		r,
+		g,
+		b,
+		h,
+		s,
+		l,
+		v: Math.max(r, g, b) / 255,
+		Y: .2126 * srgbToLinear(r) + .7152 * srgbToLinear(g) + .0722 * srgbToLinear(b),
+		chroma: s,
+		okL,
+		okC,
+		okH,
+		hex
+	};
+}
+//#endregion
+//#region ../theme-core/src/palette/neutralScale.ts
+function generateNeutralScale({ background, steps = 11, warm = false }) {
+	const isDark = background === "#000000" || background.startsWith("#0") || background.startsWith("#1");
+	const shadeNames = [
+		50,
+		100,
+		200,
+		300,
+		400,
+		500,
+		600,
+		700,
+		800,
+		900,
+		950
+	];
+	const count = Math.min(steps, shadeNames.length);
+	const scale = [];
+	for (let i = 0; i < count; i++) {
+		const shadeName = shadeNames[i] ?? shadeNames[shadeNames.length - 1] ?? 950;
+		const t = i / (count - 1);
+		const hex = oklchToHexGamut(isDark ? mix(.06, .92, t) : mix(.98, .1, t), .02, warm ? 85 : 250);
+		const name = `neutral-${shadeName}`;
+		scale.push({
+			name,
+			hex
+		});
+	}
+	return scale;
+}
+function mix(a, b, t) {
+	return a + (b - a) * Math.max(0, Math.min(1, t));
+}
+//#endregion
+//#region ../theme-core/src/palette/utils/contrast.ts
+function relativeLuminance(r, g, b) {
+	const R = srgbToLinear(r), G = srgbToLinear(g), B = srgbToLinear(b);
+	return .2126 * R + .7152 * G + .0722 * B;
+}
+function contrastRatio(hex1, hex2) {
+	const { r: r1, g: g1, b: b1 } = hexToRgb(hex1);
+	const { r: r2, g: g2, b: b2 } = hexToRgb(hex2);
+	const L1 = relativeLuminance(r1, g1, b1);
+	const L2 = relativeLuminance(r2, g2, b2);
+	const [hi, lo] = L1 >= L2 ? [L1, L2] : [L2, L1];
+	return (hi + .05) / (lo + .05);
+}
+//#endregion
+//#region ../theme-core/src/palette/utils/textColor.ts
+/**
+* Pick the better of black/white text for a given background using actual
+* contrast ratios, not a simple luminance cutoff.
+*
+* @param background - Background color in hex or rgb/rgba format (e.g., '#FFFFFF' or 'rgb(255, 255, 255)')
+* @param minContrast - Preferred minimum contrast ratio for body-sized text
+* @returns '#000000' for light backgrounds, '#FFFFFF' for dark backgrounds
+*/
+function pickBlackOrWhiteTextColor(background, minContrast = 4.5) {
+	const { r, g, b } = parseColorToRgb(background);
+	const luminance = relativeLuminance(r, g, b);
+	const blackContrast = (luminance + .05) / .05;
+	const whiteContrast = 1.05 / (luminance + .05);
+	if (blackContrast >= minContrast && whiteContrast < minContrast) return "#000000";
+	if (whiteContrast >= minContrast && blackContrast < minContrast) return "#FFFFFF";
+	return blackContrast >= whiteContrast ? "#000000" : "#FFFFFF";
+}
+/**
+* Backwards-compatible alias for callers that want the best black/white text
+* color for a background.
+*/
+function getTextColorForBackground(background) {
+	return pickBlackOrWhiteTextColor(background);
+}
+function parseColorToRgb(input) {
+	const trimmed = input.trim();
+	if (trimmed.startsWith("#")) return hexToRgb(trimmed);
+	const rgbMatch = trimmed.match(/^rgba?\(\s*(\d{1,3})\s*,\s*(\d{1,3})\s*,\s*(\d{1,3})(?:\s*,\s*(?:0|1|0?\.\d+))?\s*\)$/i);
+	if (rgbMatch?.[1] && rgbMatch[2] && rgbMatch[3]) return {
+		r: clamp255(Number(rgbMatch[1])),
+		g: clamp255(Number(rgbMatch[2])),
+		b: clamp255(Number(rgbMatch[3]))
+	};
+	throw new Error("Unsupported color format");
+}
+function clamp255(value) {
+	if (Number.isNaN(value)) return 0;
+	return Math.max(0, Math.min(255, value));
+}
+//#endregion
+//#region ../theme-core/src/palette/utils/onColor.ts
+const BACKGROUND_ROLE_NAMES = /* @__PURE__ */ new Set([
+	"primary",
+	"secondary",
+	"accent",
+	"success",
+	"warning",
+	"destructive",
+	"info",
+	"background",
+	"surface",
+	"surfaceAlt",
+	"muted",
+	"neutral"
+]);
+function onColorTokenName(backgroundToken) {
+	return `on${backgroundToken.split("-").filter((part) => part.length > 0).map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("")}`;
+}
+function isOnColorBackgroundCandidateToken(token) {
+	const role = token.match(/^(.*?)(?:-\d{2,3})?$/)?.[1] ?? token;
+	return BACKGROUND_ROLE_NAMES.has(role);
+}
+//#endregion
+//#region ../theme-core/src/palette/generateShades.ts
+function generateShades(hexColor, name) {
+	const shadeSteps = [
+		50,
+		100,
+		200,
+		300,
+		400,
+		500,
+		600,
+		700,
+		800,
+		900,
+		950
+	];
+	const base = featuresFromHex(hexColor);
+	const hue = base.okH;
+	const baseChroma = base.okC;
+	const toneMap = {
+		50: .975,
+		100: .945,
+		200: .89,
+		300: .82,
+		400: .74,
+		500: .66,
+		600: .58,
+		700: .49,
+		800: .4,
+		900: .28,
+		950: .16
+	};
+	const shadeDefs = shadeSteps.map((step, idx) => {
+		const t = idx / (shadeSteps.length - 1);
+		const L = toneMap[step];
+		const C = baseChroma * (.06 + .94 * Math.sin(Math.PI * t));
+		return {
+			name: `${name}-${step}`,
+			hex: oklchToHexGamut(L, C, hue)
+		};
+	});
+	shadeDefs.push({
+		name,
+		hex: hexColor
+	});
+	return shadeDefs;
+}
+//#endregion
+//#region ../theme-core/src/palette/expandPalette.ts
+function colorsToMap(palette) {
+	const map = {};
+	for (const c of palette.colors) map[c.name] = c.hex;
+	return map;
+}
+function isBackgroundDark(hex) {
+	try {
+		return featuresFromHex(hex).Y < .5;
+	} catch {
+		return false;
+	}
+}
+const nonShadeablePaletteRoleNames = /* @__PURE__ */ new Set([
+	"success",
+	"warning",
+	"destructive"
+]);
+function expandPalette(palette) {
+	const base = colorsToMap(palette);
+	const expanded = { ...base };
+	generateNeutralScale({
+		background: base.background || base.surface || "#ffffff",
+		steps: 11,
+		warm: false
+	}).forEach((n) => {
+		expanded[n.name] = n.hex;
+	});
+	for (const [name, hex] of Object.entries(base)) {
+		if (nonShadeablePaletteRoleNames.has(name)) continue;
+		if (hex) generateShades(hex, name).forEach((shade) => {
+			expanded[shade.name] = shade.hex;
+		});
+	}
+	if (base.text) expanded.body = base.text;
+	if (base.danger && !base.destructive) expanded.destructive = base.danger;
+	const isDark = base.background ? isBackgroundDark(base.background) : false;
+	expanded.mutedText = palette.meta?.mode === "dark" || isDark ? expanded["neutral-600"] ?? "#666" : expanded["neutral-500"] ?? "#888";
+	for (const [token, hex] of Object.entries({ ...expanded })) {
+		if (!hex || !isOnColorBackgroundCandidateToken(token)) continue;
+		const onToken = onColorTokenName(token);
+		if (expanded[onToken]) continue;
+		expanded[onToken] = getTextColorForBackground(hex);
+	}
+	return expanded;
+}
+//#endregion
 //#region ../theme-core/src/tokens/colorTokenParts.ts
 function parseOpacityPercent(source) {
 	const trimmed = source.trim();
@@ -195,111 +535,6 @@ const mediaSchema = z.object({
 	transform: transformSchema.optional()
 });
 //#endregion
-//#region ../theme-core/src/buttons/effectClassification.ts
-/**
-* Exhaustive live policy for every registered effect id.
-*
-* The resolver consumes the transition payload directly, so adding an effect
-* cannot update classification without also defining its runtime behavior.
-*/
-const BUTTON_EFFECT_POLICIES = {
-	"darken-background": {
-		classification: "colour-transition",
-		transition: {
-			kind: "adjust-shade",
-			direction: "darker"
-		}
-	},
-	"lighten-background": {
-		classification: "colour-transition",
-		transition: {
-			kind: "adjust-shade",
-			direction: "lighter"
-		}
-	},
-	"background-on-hover": {
-		classification: "colour-transition",
-		transition: { kind: "replace-background" }
-	},
-	"background-on-hover-alpha": {
-		classification: "unsupported-colour",
-		reason: "alpha_requires_surface"
-	},
-	"fade-background": {
-		classification: "unsupported-colour",
-		reason: "changes_element_opacity"
-	},
-	"opacity-reduce": {
-		classification: "unsupported-colour",
-		reason: "changes_element_opacity"
-	},
-	"gradient-text": {
-		classification: "unsupported-colour",
-		reason: "changes_foreground"
-	},
-	"text-color-change": {
-		classification: "unsupported-colour",
-		reason: "changes_foreground"
-	},
-	"border-color-change": {
-		classification: "unsupported-colour",
-		reason: "changes_border"
-	},
-	"aurora-glow": {
-		classification: "unsupported-background-overlay",
-		reason: "unresolved_background_overlay"
-	},
-	"cosmic-stardust": {
-		classification: "unsupported-background-overlay",
-		reason: "unresolved_background_overlay"
-	},
-	"gradient-border-fill": {
-		classification: "unsupported-background-overlay",
-		reason: "unresolved_background_overlay"
-	},
-	"animated-gradient-border-fill": {
-		classification: "unsupported-background-overlay",
-		reason: "unresolved_background_overlay"
-	},
-	"nav-underline": {
-		classification: "not-button",
-		reason: "not_button_effect"
-	},
-	"nav-frosted-base": {
-		classification: "not-button",
-		reason: "not_button_effect"
-	},
-	"nav-frosted-hover": {
-		classification: "not-button",
-		reason: "not_button_effect"
-	},
-	"nav-frosted-active": {
-		classification: "not-button",
-		reason: "not_button_effect"
-	},
-	"animated-gradient": { classification: "non-colour" },
-	"border-glow": { classification: "non-colour" },
-	"drop-shadow": { classification: "non-colour" },
-	"inner-shadow": { classification: "non-colour" },
-	"neumorphic-shadow": { classification: "non-colour" },
-	"outer-glow": { classification: "non-colour" },
-	"retro-3d-shadow": { classification: "non-colour" },
-	"scale-up": { classification: "non-colour" },
-	"scale-down": { classification: "non-colour" },
-	lift: { classification: "non-colour" },
-	"press-down": { classification: "non-colour" },
-	pop: { classification: "non-colour" },
-	"border-bottom-grow": { classification: "non-colour" },
-	"sketchy-border": { classification: "non-colour" },
-	"pulse-animation": { classification: "non-colour" }
-};
-function getButtonEffectPolicy(effectId) {
-	return Object.prototype.hasOwnProperty.call(BUTTON_EFFECT_POLICIES, effectId) ? BUTTON_EFFECT_POLICIES[effectId] : null;
-}
-function classifyButtonEffectId(effectId) {
-	return getButtonEffectPolicy(effectId)?.classification ?? "unknown";
-}
-//#endregion
 //#region ../theme-core/src/buttons/types.ts
 /**
 * Standard semantic variant roles a theme exposes.
@@ -316,6 +551,13 @@ const VARIANT_ROLES = [
 	"tertiary",
 	"accent"
 ];
+/**
+* Canonical persisted/CSS-safe button variant identifier.
+*
+* IDs become class selectors, so keep the contract deliberately narrower than
+* an arbitrary string and shared with every authoring/runtime boundary.
+*/
+const buttonVariantIdSchema = z$1.string().min(1).max(50).regex(/^[a-z0-9-]+$/, "Button variant IDs may contain lowercase letters, numbers, and hyphens only");
 function parseOpaqueButtonColourToken(value) {
 	const token = parseThemeColorToken(value);
 	if (token === null) return null;
@@ -330,6 +572,109 @@ const opaqueButtonColourTokenSchema = themeColorTokenSchema.refine((value) => pa
 	if (token === null) throw new Error("Invariant: opaque button token passed its schema");
 	return token;
 });
+const buttonShadeAmountSchema = z$1.number().finite().min(0).max(900).multipleOf(100);
+const buttonShadowIntensitySchema = z$1.enum([
+	"subtle",
+	"medium",
+	"strong"
+]);
+/**
+* The complete persisted button-effect contract.
+*
+* Navigation has its own generic interactive-effect model. Button variants use
+* this closed union so unsupported effect IDs, unknown option keys, and unsafe
+* CSS values cannot become representable after the schema boundary.
+*/
+const buttonEffectApplicationSchema = z$1.discriminatedUnion("effectId", [
+	z$1.strictObject({
+		effectId: z$1.literal("darken-background"),
+		options: z$1.strictObject({ amount: buttonShadeAmountSchema.optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("lighten-background"),
+		options: z$1.strictObject({ amount: buttonShadeAmountSchema.optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("background-on-hover"),
+		options: z$1.strictObject({ colorToken: opaqueButtonColourTokenSchema.optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("animated-gradient"),
+		options: z$1.strictObject({ direction: z$1.enum(["horizontal", "vertical"]).optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("drop-shadow"),
+		options: z$1.strictObject({ intensity: buttonShadowIntensitySchema.optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("inner-shadow"),
+		options: z$1.strictObject({}).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("neumorphic-shadow"),
+		options: z$1.strictObject({
+			mode: z$1.enum(["raised", "pressed"]).optional(),
+			intensity: buttonShadowIntensitySchema.optional()
+		}).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("retro-3d-shadow"),
+		options: z$1.strictObject({}).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("scale-up"),
+		options: z$1.strictObject({ scale: z$1.enum([
+			"1.02",
+			"1.03",
+			"1.05",
+			"1.10"
+		]).optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("scale-down"),
+		options: z$1.strictObject({ scale: z$1.enum([
+			"0.90",
+			"0.95",
+			"0.97",
+			"0.98"
+		]).optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("lift"),
+		options: z$1.strictObject({ amount: z$1.enum([
+			"0.25",
+			"0.5",
+			"1"
+		]).optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("press-down"),
+		options: z$1.strictObject({}).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("pop"),
+		options: z$1.strictObject({ intensity: z$1.enum([
+			"subtle",
+			"medium",
+			"dramatic"
+		]).optional() }).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("border-bottom-grow"),
+		options: z$1.strictObject({
+			height: z$1.union([z$1.literal(1), z$1.literal(2)]).optional(),
+			origin: z$1.enum([
+				"left",
+				"center",
+				"right"
+			]).optional()
+		}).optional()
+	}),
+	z$1.strictObject({
+		effectId: z$1.literal("sketchy-border"),
+		options: z$1.strictObject({ intensity: buttonShadowIntensitySchema.optional() }).optional()
+	})
+]);
 const cornerStyleSchema = z$1.enum([
 	"square",
 	"rounded",
@@ -364,13 +709,7 @@ const hoverTransformSchema = z$1.enum([
 	"scale",
 	"press"
 ]);
-const hoverColorSchema = z$1.enum([
-	"none",
-	"brighten",
-	"darken",
-	"saturate",
-	"token"
-]);
+z$1.enum(["none", "token"]);
 const buttonPaddingPresetSchema = z$1.enum([
 	"compact",
 	"default",
@@ -431,7 +770,7 @@ const buttonSizesSchema = z$1.object({
 	lg,
 	xl: xl ?? lg
 }));
-const canonicalButtonGlobalSettingsSchema = z$1.object({
+const buttonGlobalSettingsBaseSchema = z$1.strictObject({
 	cornerStyle: cornerStyleSchema,
 	cornerRadius: z$1.number().min(0).max(24).optional(),
 	/**
@@ -444,30 +783,23 @@ const canonicalButtonGlobalSettingsSchema = z$1.object({
 	shadow: shadowSizeSchema.optional(),
 	textTransform: textTransformSchema,
 	fontWeight: fontWeightSchema,
-	/**
-	* @deprecated Set per-variant via `variant.border.widthClass` instead.
-	* Schema field is preserved so existing presets parse; the value is unread
-	* by the current generator and will be removed once the legacy
-	* `primitives/content/components/Button.tsx` slot exports are deleted.
-	*/
-	borderWidth: z$1.union([
-		z$1.literal(1),
-		z$1.literal(2),
-		z$1.literal(3)
-	]),
 	typography: buttonTypographySchema.optional(),
 	fontSize: z$1.string().optional(),
 	letterSpacing: letterSpacingSchema.optional(),
 	italic: z$1.boolean().optional(),
 	paddingPreset: buttonPaddingPresetSchema.optional(),
 	hoverTransform: hoverTransformSchema,
-	hoverColor: hoverColorSchema,
-	hoverColorToken: opaqueButtonColourTokenSchema.optional(),
 	gradientStyle: gradientStyleSchema.optional(),
 	gradientAngle: z$1.number().min(0).max(360).optional(),
 	gradientSharpness: gradientSharpnessSchema.optional()
 });
-const buttonGlobalSettingsSchema = z$1.preprocess(normalizeLegacyButtonGlobalInput, canonicalButtonGlobalSettingsSchema);
+const buttonGlobalSettingsSchema = z$1.discriminatedUnion("hoverColor", [buttonGlobalSettingsBaseSchema.extend({
+	hoverColor: z$1.literal("none"),
+	hoverColorToken: z$1.never().optional()
+}), buttonGlobalSettingsBaseSchema.extend({
+	hoverColor: z$1.literal("token"),
+	hoverColorToken: opaqueButtonColourTokenSchema
+})]);
 const gradientDirectionSchema$1 = z$1.enum([
 	"to-r",
 	"to-l",
@@ -479,11 +811,11 @@ const gradientDirectionSchema$1 = z$1.enum([
 	"to-bl"
 ]);
 const buttonColourTreatmentSchema = z$1.discriminatedUnion("type", [
-	z$1.object({
+	z$1.strictObject({
 		type: z$1.literal("solid"),
 		colorToken: opaqueButtonColourTokenSchema
 	}),
-	z$1.object({
+	z$1.strictObject({
 		type: z$1.literal("gradient"),
 		stops: z$1.array(opaqueButtonColourTokenSchema).min(2).transform((stops) => {
 			const [first, second, ...rest] = stops;
@@ -497,19 +829,15 @@ const buttonColourTreatmentSchema = z$1.discriminatedUnion("type", [
 		direction: gradientDirectionSchema$1,
 		foregroundToken: opaqueButtonColourTokenSchema
 	}),
-	z$1.object({
+	z$1.strictObject({
 		type: z$1.literal("surface"),
 		role: z$1.literal("link")
 	})
 ]);
 const buttonBackgroundSchema = buttonColourTreatmentSchema;
-const effectApplicationSchema$1 = z$1.object({
-	effectId: z$1.string(),
-	options: z$1.record(z$1.string(), z$1.json()).optional()
-});
-const buttonBorderSchema = z$1.object({ widthClass: z$1.string() });
-const buttonVariantAffordanceSchema = z$1.object({ iconId: z$1.string().min(1) });
-const variantShadowSchema = z$1.object({
+const buttonBorderSchema = z$1.strictObject({ widthClass: z$1.string() });
+const buttonVariantAffordanceSchema = z$1.strictObject({ iconId: z$1.string().min(1) });
+const variantShadowSchema = z$1.strictObject({
 	elevation: z$1.enum([
 		"none",
 		"low",
@@ -522,13 +850,13 @@ const variantShadowSchema = z$1.object({
 		"hard"
 	]).nullable(),
 	position: z$1.enum(["bottom", "bottom-right"]).default("bottom"),
-	colorToken: themeColorTokenSchema.optional()
+	colorToken: opaqueButtonColourTokenSchema.optional()
 });
-const variantEffectsSchema = z$1.object({
-	base: z$1.array(effectApplicationSchema$1).optional(),
-	hover: z$1.array(effectApplicationSchema$1).optional(),
-	active: z$1.array(effectApplicationSchema$1).optional(),
-	focus: z$1.array(effectApplicationSchema$1).optional()
+const variantEffectsSchema = z$1.strictObject({
+	base: z$1.array(buttonEffectApplicationSchema).optional(),
+	hover: z$1.array(buttonEffectApplicationSchema).optional(),
+	active: z$1.array(buttonEffectApplicationSchema).optional(),
+	focus: z$1.array(buttonEffectApplicationSchema).optional()
 });
 /**
 * Per-variant size overrides schema — every entry is optional.
@@ -549,8 +877,8 @@ const variantSizeOverridesSchema = z$1.object({
 * default (e.g. link-style variants declaring zero horizontal padding at
 * every size).
 */
-const canonicalButtonVariantSchema = z$1.object({
-	id: z$1.string(),
+const buttonVariantSchema = z$1.strictObject({
+	id: buttonVariantIdSchema,
 	name: z$1.string().min(1).max(20),
 	enabled: z$1.boolean(),
 	priority: prioritySchema,
@@ -564,154 +892,585 @@ const canonicalButtonVariantSchema = z$1.object({
 	sizes: variantSizeOverridesSchema.optional(),
 	affordance: buttonVariantAffordanceSchema.optional()
 });
-/**
-* Temporary persisted-theme admission boundary for issue #1206.
-*
-* Production inventory on 2026-07-22 found 22 rows using the old independent
-* `textColorToken`/border colour shape. New source and all downstream code use
-* only the canonical relationship. Delete this preprocessor after the reviewed
-* production rewrite reports zero legacy rows.
-*/
-const buttonVariantSchema = z$1.preprocess(normalizeLegacyButtonVariantInput, canonicalButtonVariantSchema);
-const buttonSystemSchema = z$1.object({
+const buttonSystemSchema = z$1.strictObject({
 	global: buttonGlobalSettingsSchema,
 	variants: z$1.array(buttonVariantSchema).min(1).max(6),
 	sizes: buttonSizesSchema.optional()
+}).superRefine((system, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	system.variants.forEach((variant, index) => {
+		if (seen.has(variant.id)) ctx.addIssue({
+			code: "custom",
+			path: [
+				"variants",
+				index,
+				"id"
+			],
+			message: `Duplicate button variant ID: ${variant.id}`
+		});
+		seen.add(variant.id);
+	});
 });
-function normalizeLegacyButtonVariantInput(input) {
-	if (!isUnknownRecord(input)) return input;
-	const background = input.background;
-	if (!isUnknownRecord(background)) return input;
-	if (!(background.type === "transparent" || Object.prototype.hasOwnProperty.call(input, "textColorToken") || isUnknownRecord(input.border) && Object.prototype.hasOwnProperty.call(input.border, "colorToken") || hasLegacyButtonEffects(input.effects) || hasLegacyAlphaToken(input, background))) return input;
-	const { textColorToken, ...withoutLegacyText } = input;
-	const normalizedBorder = isUnknownRecord(input.border) && typeof input.border.widthClass === "string" ? { widthClass: input.border.widthClass } : input.border;
-	const normalizedAffordance = isUnknownRecord(input.affordance) && typeof input.affordance.iconId === "string" ? { iconId: input.affordance.iconId } : input.affordance;
-	const normalizedEffects = normalizeLegacyButtonEffects(input.effects, background.type);
-	const hoverBackgroundToken = stripLegacyTokenAlpha(input.hoverBackgroundToken);
-	if (background.type === "transparent") return {
-		...withoutLegacyText,
-		background: {
-			type: "surface",
-			role: "link"
-		},
-		border: normalizedBorder,
-		affordance: normalizedAffordance,
-		effects: normalizedEffects,
-		hoverBackgroundToken
-	};
-	if (background.type === "gradient") {
-		const stops = Array.isArray(background.stops) ? background.stops.map(stripLegacyTokenAlpha) : background.stops;
-		return {
-			...withoutLegacyText,
-			background: {
-				...background,
-				stops,
-				foregroundToken: stripLegacyTokenAlpha(background.foregroundToken ?? textColorToken)
-			},
-			border: normalizedBorder,
-			affordance: normalizedAffordance,
-			effects: normalizedEffects,
-			hoverBackgroundToken
-		};
+//#endregion
+//#region ../theme-core/src/surfaces/foregroundContract.ts
+const SURFACE_FOREGROUND_CSS_VARS = {
+	text: "--rb-surface-text-color",
+	heading: "--rb-surface-heading-color",
+	link: "--rb-surface-link-color",
+	supporting: "--rb-surface-supporting-color"
+};
+const DEFAULT_SURFACE_TEXT_COLOR = "rgb(var(--tb-text, 17 24 39))";
+const DEFAULT_ROLE_FALLBACKS = {
+	text: DEFAULT_SURFACE_TEXT_COLOR,
+	heading: DEFAULT_SURFACE_TEXT_COLOR,
+	link: "rgb(var(--tb-primary, var(--tb-text, 17 24 39)))",
+	supporting: "rgb(var(--tb-mutedText, 100 116 139))"
+};
+function requireSurfaceColorValue(role, value) {
+	const normalized = value.trim();
+	if (normalized.length === 0) throw new RangeError(`Surface foreground ${role} must be a non-empty CSS color.`);
+	return normalized;
+}
+function surfaceForegroundValue(role, outsideProviderFallback = DEFAULT_ROLE_FALLBACKS[role]) {
+	const roleVariable = SURFACE_FOREGROUND_CSS_VARS[role];
+	const fallback = requireSurfaceColorValue("fallback", outsideProviderFallback);
+	if (role === "text") return `var(${roleVariable}, ${fallback})`;
+	return `var(${roleVariable}, var(${SURFACE_FOREGROUND_CSS_VARS.text}, ${fallback}))`;
+}
+//#endregion
+//#region ../theme-core/src/buttons/constants.ts
+/**
+* Shared constants for button CSS generation
+*
+* These mappings convert Tailwind-style tokens to actual CSS values.
+* Centralized here to eliminate duplication across multiple files.
+*/
+/**
+* Map Tailwind-style gradient direction tokens to CSS gradient directions
+*/
+const GRADIENT_DIRECTION_MAP = {
+	"to-r": "to right",
+	"to-l": "to left",
+	"to-t": "to top",
+	"to-b": "to bottom",
+	"to-br": "to bottom right",
+	"to-bl": "to bottom left",
+	"to-tr": "to top right",
+	"to-tl": "to top left"
+};
+//#endregion
+//#region ../theme-core/src/buttons/effectClassification.ts
+/**
+* Exhaustive live policy for every registered effect id.
+*
+* The resolver consumes the transition payload directly, so adding an effect
+* cannot update classification without also defining its runtime behavior.
+*/
+const BUTTON_EFFECT_POLICIES = {
+	"darken-background": {
+		classification: "colour-transition",
+		transition: {
+			kind: "adjust-shade",
+			direction: "darker"
+		}
+	},
+	"lighten-background": {
+		classification: "colour-transition",
+		transition: {
+			kind: "adjust-shade",
+			direction: "lighter"
+		}
+	},
+	"background-on-hover": {
+		classification: "colour-transition",
+		transition: { kind: "replace-background" }
+	},
+	"background-on-hover-alpha": {
+		classification: "unsupported-colour",
+		reason: "alpha_requires_surface"
+	},
+	"fade-background": {
+		classification: "unsupported-colour",
+		reason: "changes_element_opacity"
+	},
+	"opacity-reduce": {
+		classification: "unsupported-colour",
+		reason: "changes_element_opacity"
+	},
+	"gradient-text": {
+		classification: "unsupported-colour",
+		reason: "changes_foreground"
+	},
+	"text-color-change": {
+		classification: "unsupported-colour",
+		reason: "changes_foreground"
+	},
+	"border-color-change": {
+		classification: "unsupported-colour",
+		reason: "changes_border"
+	},
+	"aurora-glow": {
+		classification: "unsupported-background-overlay",
+		reason: "unresolved_background_overlay"
+	},
+	"cosmic-stardust": {
+		classification: "unsupported-background-overlay",
+		reason: "unresolved_background_overlay"
+	},
+	"gradient-border-fill": {
+		classification: "unsupported-background-overlay",
+		reason: "unresolved_background_overlay"
+	},
+	"animated-gradient-border-fill": {
+		classification: "unsupported-background-overlay",
+		reason: "unresolved_background_overlay"
+	},
+	"nav-underline": {
+		classification: "not-button",
+		reason: "not_button_effect"
+	},
+	"nav-frosted-base": {
+		classification: "not-button",
+		reason: "not_button_effect"
+	},
+	"nav-frosted-hover": {
+		classification: "not-button",
+		reason: "not_button_effect"
+	},
+	"nav-frosted-active": {
+		classification: "not-button",
+		reason: "not_button_effect"
+	},
+	"animated-gradient": { classification: "non-colour" },
+	"border-glow": {
+		classification: "unsupported-colour",
+		reason: "changes_shadow_colour"
+	},
+	"drop-shadow": { classification: "decorative-colour" },
+	"inner-shadow": { classification: "decorative-colour" },
+	"neumorphic-shadow": { classification: "decorative-colour" },
+	"outer-glow": {
+		classification: "unsupported-colour",
+		reason: "changes_shadow_colour"
+	},
+	"retro-3d-shadow": { classification: "decorative-colour" },
+	"scale-up": { classification: "non-colour" },
+	"scale-down": { classification: "non-colour" },
+	lift: { classification: "non-colour" },
+	"press-down": { classification: "non-colour" },
+	pop: { classification: "non-colour" },
+	"border-bottom-grow": { classification: "non-colour" },
+	"sketchy-border": { classification: "decorative-colour" },
+	"pulse-animation": {
+		classification: "unsupported-colour",
+		reason: "changes_element_opacity"
 	}
+};
+function validateButtonEffectOptions(effect) {
+	const parsed = buttonEffectApplicationSchema.safeParse(effect);
+	if (parsed.success) return { ok: true };
+	const firstIssue = parsed.error.issues[0];
+	const firstPathPart = firstIssue?.path[firstIssue.path.length - 1];
 	return {
-		...withoutLegacyText,
-		background: background.type === "solid" ? {
-			...background,
-			colorToken: stripLegacyTokenAlpha(background.colorToken)
-		} : background,
-		border: normalizedBorder,
-		affordance: normalizedAffordance,
-		effects: normalizedEffects,
-		hoverBackgroundToken
+		ok: false,
+		option: (firstIssue?.code === "unrecognized_keys" ? firstIssue.keys[0] : void 0) ?? (typeof firstPathPart === "string" ? firstPathPart : "options")
 	};
 }
-function normalizeLegacyButtonGlobalInput(input) {
-	if (!isUnknownRecord(input)) return input;
-	const hoverColorToken = stripLegacyTokenAlpha(input.hoverColorToken);
-	return hoverColorToken === input.hoverColorToken ? input : {
-		...input,
-		hoverColorToken
-	};
-}
-function hasLegacyAlphaToken(input, background) {
-	const stops = isUnknownArray(background.stops) ? background.stops : [];
-	return [
-		input.hoverBackgroundToken,
-		background.colorToken,
-		background.foregroundToken,
-		...stops
-	].some((token) => stripLegacyTokenAlpha(token) !== token);
-}
-function stripLegacyTokenAlpha(value) {
-	if (typeof value !== "string") return value;
-	const slashIndex = value.indexOf("/");
-	return slashIndex < 0 ? value : value.slice(0, slashIndex);
+function getButtonEffectPolicy(effectId) {
+	return Object.prototype.hasOwnProperty.call(BUTTON_EFFECT_POLICIES, effectId) ? BUTTON_EFFECT_POLICIES[effectId] : null;
 }
-function hasLegacyButtonEffects(input) {
-	if (!isUnknownRecord(input)) return false;
-	return [
-		"base",
-		"hover",
-		"active",
-		"focus"
-	].some((state) => {
-		const effects = input[state];
-		return Array.isArray(effects) && effects.some((effect) => {
-			if (!isUnknownRecord(effect) || typeof effect.effectId !== "string") return true;
-			const classification = classifyButtonEffectId(effect.effectId);
-			if (classification !== "colour-transition" && classification !== "non-colour") return true;
-			return effect.effectId === "background-on-hover" && isUnknownRecord(effect.options) && stripLegacyTokenAlpha(effect.options.colorToken) !== effect.options.colorToken;
-		});
+//#endregion
+//#region ../theme-core/src/buttons/resolveButtonColourStates.ts
+const BUTTON_VISUAL_STATES = [
+	"base",
+	"hover",
+	"focus",
+	"active",
+	"disabled"
+];
+const BUTTON_CONTRAST_POLICY = {
+	textMinimumRatio: 4.5,
+	nonTextMinimumRatio: 3,
+	gradientSamplesPerSegment: 20,
+	alphaBackgrounds: "reject-without-known-surface",
+	disabled: "retain-full-colour-contract"
+};
+function compileButtonColourStates(input) {
+	const baseTransition = applyColourEffects({
+		variantId: input.variant.id,
+		state: "base",
+		treatment: input.variant.background,
+		effects: input.variant.effects?.base,
+		palette: input.palette
 	});
-}
-function normalizeLegacyButtonEffects(input, backgroundType) {
-	if (!isUnknownRecord(input)) return input;
-	const normalized = {};
+	if (!baseTransition.ok) return baseTransition;
+	const stateTreatments = {
+		base: baseTransition.treatment,
+		hover: hoverTreatment(input.variant, input.global, baseTransition.treatment),
+		focus: baseTransition.treatment,
+		active: baseTransition.treatment,
+		disabled: baseTransition.treatment
+	};
+	const nonColourEffects = { ...baseTransition.nonColourEffects.length > 0 ? { base: [...baseTransition.nonColourEffects] } : {} };
 	for (const state of [
-		"base",
 		"hover",
-		"active",
-		"focus"
+		"focus",
+		"active"
 	]) {
-		const effects = input[state];
-		if (!Array.isArray(effects)) continue;
-		const safeEffects = effects.flatMap((effect) => {
-			if (!isUnknownRecord(effect) || typeof effect.effectId !== "string") return [];
-			const classification = classifyButtonEffectId(effect.effectId);
-			if (classification === "non-colour") return [effect];
-			if (classification !== "colour-transition") return [];
-			if (effect.effectId === "background-on-hover") {
-				const options = isUnknownRecord(effect.options) ? effect.options : null;
-				const colorToken = options === null ? null : parseOpaqueButtonColourToken(stripLegacyTokenAlpha(options.colorToken));
-				return colorToken === null ? [] : [{
-					...effect,
-					options: {
-						...options,
+		const transition = applyColourEffects({
+			variantId: input.variant.id,
+			state,
+			treatment: stateTreatments[state],
+			effects: input.variant.effects?.[state],
+			palette: input.palette
+		});
+		if (!transition.ok) return transition;
+		stateTreatments[state] = transition.treatment;
+		if (transition.nonColourEffects.length > 0) nonColourEffects[state] = [...transition.nonColourEffects];
+	}
+	const resolved = {};
+	for (const state of BUTTON_VISUAL_STATES) {
+		const result = resolveTreatment({
+			variantId: input.variant.id,
+			state,
+			treatment: stateTreatments[state],
+			palette: input.palette
+		});
+		if (!result.ok) return result;
+		resolved[state] = result.colour;
+	}
+	return {
+		ok: true,
+		states: resolved,
+		focusIndicator: resolveFocusIndicator(resolved.focus),
+		nonColourEffects
+	};
+}
+function hoverTreatment(variant, global, fallback) {
+	const token = variant.hoverBackgroundToken ?? (global.hoverColor === "token" ? global.hoverColorToken : void 0);
+	return token === void 0 ? fallback : {
+		type: "solid",
+		colorToken: token
+	};
+}
+function applyColourEffects(input) {
+	let treatment = input.treatment;
+	const nonColourEffects = [];
+	for (const effect of input.effects ?? []) {
+		const policy = getButtonEffectPolicy(effect.effectId);
+		if (policy === null) return unknownEffect(input, effect);
+		if (policy.classification === "unsupported-colour" || policy.classification === "unsupported-background-overlay" || policy.classification === "not-button") return unsupportedEffect(input, effect, policy.reason);
+		const options = validateButtonEffectOptions(effect);
+		if (!options.ok) return invalidEffectOption(input, effect, options.option);
+		switch (policy.classification) {
+			case "non-colour":
+			case "decorative-colour":
+				nonColourEffects.push(effect);
+				break;
+			case "colour-transition":
+				if (policy.transition.kind === "adjust-shade") {
+					if (effect.effectId !== "darken-background" && effect.effectId !== "lighten-background") return unknownEffect(input, effect);
+					if (treatment.type !== "solid") return inapplicableEffect(input, effect, treatment);
+					const amount = readShadeAmount(effect);
+					if (amount === null) return invalidEffectOption(input, effect, "amount");
+					const signedAmount = policy.transition.direction === "darker" ? amount : -amount;
+					treatment = {
+						type: "solid",
+						colorToken: adjustShade(treatment.colorToken, signedAmount, input.palette)
+					};
+					break;
+				}
+				if (policy.transition.kind === "replace-background") {
+					if (effect.effectId !== "background-on-hover") return unknownEffect(input, effect);
+					const colorToken = readOpaqueToken(effect);
+					if (colorToken === null) return invalidEffectOption(input, effect, "colorToken");
+					treatment = {
+						type: "solid",
 						colorToken
-					}
-				}];
-			}
-			if (backgroundType !== "solid") return [];
-			const rawAmount = isUnknownRecord(effect.options) ? effect.options.amount : void 0;
-			const amount = typeof rawAmount === "number" && rawAmount > 0 ? Math.max(100, Math.round(rawAmount / 100) * 100) : 100;
-			return [{
-				...effect,
-				options: {
-					...isUnknownRecord(effect.options) ? effect.options : {},
-					amount
+					};
+					break;
 				}
-			}];
-		});
-		if (safeEffects.length > 0) normalized[state] = safeEffects;
+				return unknownEffect(input, effect);
+		}
 	}
-	return Object.keys(normalized).length === 0 ? void 0 : normalized;
+	return {
+		ok: true,
+		treatment,
+		nonColourEffects
+	};
+}
+function resolveTreatment(input) {
+	const treatment = input.treatment;
+	switch (treatment.type) {
+		case "surface": return {
+			ok: true,
+			colour: {
+				kind: "surface",
+				role: treatment.role,
+				backgroundCss: "transparent",
+				foregroundCss: surfaceForegroundValue(treatment.role)
+			}
+		};
+		case "solid": return resolveSolid(input, treatment.colorToken);
+		case "gradient": return resolveGradient(input, treatment);
+	}
+}
+function resolveFocusIndicator(colour) {
+	switch (colour.kind) {
+		case "solid": return {
+			kind: "two-tone",
+			innerCss: colour.foregroundCss,
+			outerCss: colour.backgroundCss,
+			minimumPairContrast: BUTTON_CONTRAST_POLICY.textMinimumRatio
+		};
+		case "gradient": return {
+			kind: "two-tone",
+			innerCss: colour.foregroundCss,
+			outerCss: tokenCss(colour.backgroundTokens[0]),
+			minimumPairContrast: BUTTON_CONTRAST_POLICY.textMinimumRatio
+		};
+		case "surface": return {
+			kind: "surface-role",
+			colorCss: colour.foregroundCss,
+			minimumSurfaceContrast: BUTTON_CONTRAST_POLICY.nonTextMinimumRatio
+		};
+	}
+}
+function resolveSolid(input, backgroundToken) {
+	const backgroundHex = paletteHex(input, backgroundToken);
+	if (!backgroundHex.ok) return backgroundHex;
+	const foregroundToken = unsafeAsOpaqueButtonColourToken(onColorTokenName(backgroundToken));
+	const foregroundHex = input.palette[foregroundToken];
+	if (typeof foregroundHex !== "string") return {
+		ok: false,
+		error: {
+			tag: "missing_on_colour",
+			variantId: input.variantId,
+			state: input.state,
+			backgroundToken,
+			foregroundToken
+		}
+	};
+	const contrast = validateContrast({
+		...input,
+		background: backgroundToken,
+		backgroundHex: backgroundHex.hex,
+		foreground: foregroundToken,
+		foregroundHex
+	});
+	if (!contrast.ok) return contrast;
+	return {
+		ok: true,
+		colour: {
+			kind: "solid",
+			backgroundToken,
+			foregroundToken,
+			backgroundCss: tokenCss(backgroundToken),
+			foregroundCss: tokenCss(foregroundToken)
+		}
+	};
+}
+function resolveGradient(input, treatment) {
+	const foregroundHex = paletteHex(input, treatment.foregroundToken);
+	if (!foregroundHex.ok) return foregroundHex;
+	const stopHexes = [];
+	for (const token of treatment.stops) {
+		const stop = paletteHex(input, token);
+		if (!stop.ok) return stop;
+		stopHexes.push(stop.hex);
+	}
+	for (let segment = 0; segment < stopHexes.length - 1; segment += 1) {
+		const start = stopHexes[segment];
+		const end = stopHexes[segment + 1];
+		const startToken = treatment.stops[segment];
+		const endToken = treatment.stops[segment + 1];
+		if (start === void 0 || end === void 0 || startToken === void 0 || endToken === void 0) continue;
+		for (let sample = 0; sample <= BUTTON_CONTRAST_POLICY.gradientSamplesPerSegment; sample += 1) {
+			const position = sample / BUTTON_CONTRAST_POLICY.gradientSamplesPerSegment;
+			const sampleHex = interpolateHex(start, end, position);
+			const contrast = validateContrast({
+				...input,
+				background: `${startToken}→${endToken}@${position.toFixed(2)}`,
+				backgroundHex: sampleHex,
+				foreground: treatment.foregroundToken,
+				foregroundHex: foregroundHex.hex
+			});
+			if (!contrast.ok) return contrast;
+		}
+	}
+	const direction = GRADIENT_DIRECTION_MAP[treatment.direction] ?? "to right";
+	return {
+		ok: true,
+		colour: {
+			kind: "gradient",
+			backgroundTokens: treatment.stops,
+			foregroundToken: treatment.foregroundToken,
+			backgroundCss: `linear-gradient(${direction}, ${treatment.stops.map(tokenCss).join(", ")})`,
+			foregroundCss: tokenCss(treatment.foregroundToken)
+		}
+	};
+}
+function paletteHex(input, token) {
+	const hex = input.palette[token];
+	return typeof hex === "string" ? {
+		ok: true,
+		hex
+	} : {
+		ok: false,
+		error: {
+			tag: "unknown_palette_token",
+			variantId: input.variantId,
+			state: input.state,
+			token
+		}
+	};
+}
+function validateContrast(input) {
+	const ratio = contrastRatio(input.backgroundHex, input.foregroundHex);
+	return ratio >= BUTTON_CONTRAST_POLICY.textMinimumRatio ? { ok: true } : {
+		ok: false,
+		error: {
+			tag: "insufficient_contrast",
+			variantId: input.variantId,
+			state: input.state,
+			background: input.background,
+			foreground: input.foreground,
+			ratio,
+			requiredRatio: BUTTON_CONTRAST_POLICY.textMinimumRatio
+		}
+	};
+}
+function tokenCss(token) {
+	return `rgb(var(--tb-${token}))`;
+}
+function adjustShade(token, amount, palette) {
+	const match = token.match(/^(.*)-(\d{2,3})$/);
+	const base = match?.[1] ?? token;
+	const currentShade = match?.[2] === void 0 ? 500 : Number(match[2]);
+	const availableShades = [
+		50,
+		100,
+		200,
+		300,
+		400,
+		500,
+		600,
+		700,
+		800,
+		900,
+		950
+	].filter((shade) => typeof palette[`${base}-${shade}`] === "string");
+	if (availableShades.length === 0) return token;
+	const firstShade = availableShades[0];
+	if (firstShade === void 0) return token;
+	const exactIndex = availableShades.indexOf(currentShade);
+	const startingIndex = exactIndex >= 0 ? exactIndex : availableShades.indexOf(availableShades.reduce((closestShade, shade) => Math.abs(shade - currentShade) < Math.abs(closestShade - currentShade) ? shade : closestShade, firstShade));
+	const stepCount = Math.abs(amount) / 100;
+	const direction = amount < 0 ? -1 : 1;
+	const targetShade = availableShades[Math.max(0, Math.min(availableShades.length - 1, startingIndex + direction * stepCount))];
+	return targetShade === void 0 ? token : unsafeAsOpaqueButtonColourToken(`${base}-${targetShade}`);
+}
+function readShadeAmount(effect) {
+	const value = effect.options?.amount ?? 100;
+	return typeof value === "number" && Number.isFinite(value) && value >= 0 && value % 100 === 0 ? value : null;
+}
+function readOpaqueToken(effect) {
+	return parseOpaqueButtonColourToken(effect.options?.colorToken ?? "neutral-800");
+}
+function unsupportedEffect(input, effect, reason) {
+	return {
+		ok: false,
+		error: {
+			tag: "unsupported_colour_effect",
+			variantId: input.variantId,
+			state: input.state,
+			effectId: effect.effectId,
+			reason
+		}
+	};
+}
+function invalidEffectOption(input, effect, option) {
+	return {
+		ok: false,
+		error: {
+			tag: "invalid_colour_effect_options",
+			variantId: input.variantId,
+			state: input.state,
+			effectId: effect.effectId,
+			option
+		}
+	};
 }
-function isUnknownRecord(value) {
-	return typeof value === "object" && value !== null && !Array.isArray(value);
+function inapplicableEffect(input, effect, treatment) {
+	return {
+		ok: false,
+		error: {
+			tag: "inapplicable_colour_effect",
+			variantId: input.variantId,
+			state: input.state,
+			effectId: effect.effectId,
+			treatment: treatment.type
+		}
+	};
+}
+function unknownEffect(input, effect) {
+	return {
+		ok: false,
+		error: {
+			tag: "unknown_button_effect",
+			variantId: input.variantId,
+			state: input.state,
+			effectId: effect.effectId
+		}
+	};
 }
-function isUnknownArray(value) {
-	return Array.isArray(value);
+function interpolateHex(startHex, endHex, position) {
+	const start = hexToRgb(startHex);
+	const end = hexToRgb(endHex);
+	const channel = (from, to) => Math.round(from + (to - from) * position).toString(16).padStart(2, "0");
+	return `#${channel(start.r, end.r)}${channel(start.g, end.g)}${channel(start.b, end.b)}`;
+}
+//#endregion
+//#region ../theme-core/src/buttons/parseThemeForPersistence.ts
+/**
+* Proves that every persisted button variant compiles against the theme's
+* concrete palette. Public rendering may still recover from malformed
+* external/runtime input, but persistence boundaries must reject it.
+*/
+function parseThemeForPersistence(value) {
+	const parsed = themeSchema$1.safeParse(value);
+	if (!parsed.success) return {
+		ok: false,
+		error: {
+			kind: "invalid-theme-schema",
+			issues: parsed.error.issues
+		}
+	};
+	const theme = parsed.data;
+	if (!theme.buttons) return {
+		ok: true,
+		value: theme
+	};
+	const palette = expandPalette(theme.palette);
+	for (const variant of theme.buttons.variants) {
+		const result = compileButtonColourStates({
+			variant,
+			global: theme.buttons.global,
+			palette
+		});
+		if (!result.ok) return {
+			ok: false,
+			error: {
+				kind: "invalid-button-colour-contract",
+				variantId: variant.id,
+				cause: result.error
+			}
+		};
+	}
+	return {
+		ok: true,
+		value: theme
+	};
 }
 buttonSizeNameSchema.options;
 //#endregion
@@ -868,7 +1627,6 @@ const quietArrowRecipe = defineButtonStyleRecipe({
 			cornerStyle: "rounded",
 			textTransform: "uppercase",
 			fontWeight: 500,
-			borderWidth: 1,
 			typography: "body",
 			fontSize: "text-sm",
 			letterSpacing: "loose",
@@ -932,7 +1690,7 @@ const quietArrowRecipe = defineButtonStyleRecipe({
 					affordance: { iconId: "ArrowRight" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surfaceAlt" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
 					}] }
 				}
 			},
@@ -1043,7 +1801,6 @@ const softPillRecipe = defineStaticButtonStyleRecipe({
 			shadow: "low",
 			textTransform: "none",
 			fontWeight: 500,
-			borderWidth: 2,
 			hoverTransform: "lift",
 			hoverColor: "none"
 		},
@@ -1062,10 +1819,7 @@ const softPillRecipe = defineStaticButtonStyleRecipe({
 						position: "bottom"
 					},
 					effects: {
-						hover: [{
-							effectId: "lift",
-							options: { translateY: "-1px" }
-						}],
+						hover: [{ effectId: "lift" }],
 						active: [{
 							effectId: "scale-down",
 							options: { scale: "0.98" }
@@ -1084,7 +1838,7 @@ const softPillRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border-2" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -1099,7 +1853,7 @@ const softPillRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -1113,7 +1867,7 @@ const softPillRecipe = defineStaticButtonStyleRecipe({
 					borderRadius: "rounded-full",
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -1143,7 +1897,6 @@ const earthPillRecipe = defineStaticButtonStyleRecipe({
 			shadow: "low",
 			textTransform: "none",
 			fontWeight: 500,
-			borderWidth: 1,
 			hoverTransform: "lift",
 			hoverColor: "none",
 			typography: "body",
@@ -1179,12 +1932,9 @@ const earthPillRecipe = defineStaticButtonStyleRecipe({
 						position: "bottom"
 					},
 					effects: {
-						hover: [{
-							effectId: "lift",
-							options: { translateY: "-1px" }
-						}, {
+						hover: [{ effectId: "lift" }, {
 							effectId: "background-on-hover",
-							options: { colorToken: "accent" }
+							options: { colorToken: unsafeAsOpaqueButtonColourToken("accent") }
 						}],
 						active: [{
 							effectId: "scale-down",
@@ -1204,7 +1954,7 @@ const earthPillRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "muted" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("muted") }
 					}] }
 				}
 			},
@@ -1219,7 +1969,7 @@ const earthPillRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surfaceAlt" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
 					}] }
 				}
 			},
@@ -1279,7 +2029,6 @@ const confidentChipRecipe = defineStaticButtonStyleRecipe({
 			shadow: "medium",
 			textTransform: "none",
 			fontWeight: 600,
-			borderWidth: 1,
 			hoverTransform: "none",
 			hoverColor: "none"
 		},
@@ -1320,7 +2069,7 @@ const confidentChipRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "background" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("background") }
 					}] }
 				}
 			},
@@ -1335,7 +2084,7 @@ const confidentChipRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -1349,7 +2098,7 @@ const confidentChipRecipe = defineStaticButtonStyleRecipe({
 					borderRadius: "rounded-md",
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -1384,7 +2133,6 @@ const editorialLinkRecipe = defineStaticButtonStyleRecipe({
 			cornerStyle: "square",
 			textTransform: "none",
 			fontWeight: 500,
-			borderWidth: 1,
 			hoverTransform: "none",
 			hoverColor: "none"
 		},
@@ -1402,7 +2150,6 @@ const editorialLinkRecipe = defineStaticButtonStyleRecipe({
 						effectId: "border-bottom-grow",
 						options: {
 							height: 2,
-							colorToken: "text",
 							origin: "left"
 						}
 					}] }
@@ -1421,7 +2168,6 @@ const editorialLinkRecipe = defineStaticButtonStyleRecipe({
 						effectId: "border-bottom-grow",
 						options: {
 							height: 1,
-							colorToken: "mutedText",
 							origin: "left"
 						}
 					}] }
@@ -1440,7 +2186,6 @@ const editorialLinkRecipe = defineStaticButtonStyleRecipe({
 						effectId: "border-bottom-grow",
 						options: {
 							height: 1,
-							colorToken: "accent",
 							origin: "left"
 						}
 					}] }
@@ -1464,7 +2209,6 @@ const editorialLinkRecipe = defineStaticButtonStyleRecipe({
 					effectId: "border-bottom-grow",
 					options: {
 						height: 2,
-						colorToken: "accent",
 						origin: "left"
 					}
 				}] } }
@@ -1486,7 +2230,6 @@ const pebbleRecipe = defineStaticButtonStyleRecipe({
 			cornerStyle: "pill",
 			textTransform: "none",
 			fontWeight: 500,
-			borderWidth: 2,
 			hoverTransform: "none",
 			hoverColor: "none"
 		},
@@ -1531,7 +2274,7 @@ const pebbleRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border-2" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "accent" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("accent") }
 					}] }
 				}
 			},
@@ -1546,7 +2289,7 @@ const pebbleRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -1601,7 +2344,6 @@ const brushedWashRecipe = defineStaticButtonStyleRecipe({
 			shadow: "low",
 			textTransform: "none",
 			fontWeight: 500,
-			borderWidth: 1,
 			hoverTransform: "none",
 			hoverColor: "none"
 		},
@@ -1666,7 +2408,7 @@ const brushedWashRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -1680,7 +2422,7 @@ const brushedWashRecipe = defineStaticButtonStyleRecipe({
 					borderRadius: "rounded-lg",
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -1709,7 +2451,6 @@ const inkStampRecipe = defineStaticButtonStyleRecipe({
 			cornerStyle: "rounded",
 			textTransform: "uppercase",
 			fontWeight: 600,
-			borderWidth: 1,
 			hoverTransform: "none",
 			hoverColor: "none",
 			letterSpacing: "loose"
@@ -1767,7 +2508,7 @@ const inkStampRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border-2" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -1782,7 +2523,7 @@ const inkStampRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border-2" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -1816,7 +2557,6 @@ const inkStampRecipe = defineStaticButtonStyleRecipe({
 						effectId: "border-bottom-grow",
 						options: {
 							height: 1,
-							colorToken: "accent",
 							origin: "left"
 						}
 					}] }
@@ -1847,7 +2587,6 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 			cornerStyle: "rounded",
 			textTransform: "none",
 			fontWeight: 600,
-			borderWidth: 1,
 			typography: "body",
 			letterSpacing: "tight",
 			paddingPreset: "default",
@@ -1879,12 +2618,9 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 					},
 					borderRadius: "rounded-lg",
 					affordance: { iconId: "ArrowRight" },
-					effects: { hover: [{
-						effectId: "lift",
-						options: { translateY: "-2px" }
-					}, {
+					effects: { hover: [{ effectId: "lift" }, {
 						effectId: "background-on-hover",
-						options: { colorToken: "secondary" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("secondary") }
 					}] }
 				}
 			},
@@ -1897,12 +2633,9 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 					},
 					borderRadius: "rounded-lg",
 					border: { widthClass: "border" },
-					effects: { hover: [{
-						effectId: "lift",
-						options: { translateY: "-2px" }
-					}, {
+					effects: { hover: [{ effectId: "lift" }, {
 						effectId: "background-on-hover",
-						options: { colorToken: "surfaceAlt" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
 					}] }
 				}
 			},
@@ -1915,12 +2648,9 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 					},
 					borderRadius: "rounded-lg",
 					border: { widthClass: "border" },
-					effects: { hover: [{
-						effectId: "lift",
-						options: { translateY: "-2px" }
-					}, {
+					effects: { hover: [{ effectId: "lift" }, {
 						effectId: "background-on-hover",
-						options: { colorToken: "surfaceAlt" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
 					}] }
 				}
 			},
@@ -1932,10 +2662,7 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 						role: "link"
 					},
 					borderRadius: "rounded-lg",
-					effects: { hover: [{
-						effectId: "lift",
-						options: { translateY: "-2px" }
-					}] }
+					effects: { hover: [{ effectId: "lift" }] }
 				}
 			},
 			accent: {
@@ -1947,10 +2674,7 @@ const flatInkRecipe = defineStaticButtonStyleRecipe({
 					},
 					borderRadius: "rounded-lg",
 					affordance: { iconId: "ArrowRight" },
-					effects: { hover: [{
-						effectId: "lift",
-						options: { translateY: "-2px" }
-					}] }
+					effects: { hover: [{ effectId: "lift" }] }
 				}
 			}
 		}
@@ -1971,9 +2695,8 @@ const showtimePillRecipe = defineStaticButtonStyleRecipe({
 			shadow: "low",
 			textTransform: "uppercase",
 			fontWeight: 700,
-			borderWidth: 2,
 			hoverTransform: "lift",
-			hoverColor: "darken",
+			hoverColor: "none",
 			typography: "body",
 			paddingPreset: "spacious",
 			italic: false
@@ -2031,7 +2754,7 @@ const showtimePillRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border-2" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "background" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("background") }
 					}] }
 				}
 			},
@@ -2045,7 +2768,7 @@ const showtimePillRecipe = defineStaticButtonStyleRecipe({
 					borderRadius: "rounded-full",
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -2080,7 +2803,6 @@ const joyStampRecipe = defineStaticButtonStyleRecipe({
 			typography: "heading",
 			fontWeight: 700,
 			fontSize: "text-lg",
-			borderWidth: 2,
 			hoverTransform: "none",
 			hoverColor: "none"
 		},
@@ -2115,7 +2837,7 @@ const joyStampRecipe = defineStaticButtonStyleRecipe({
 						elevation: "high",
 						softness: "hard",
 						position: "bottom-right",
-						colorToken: "text"
+						colorToken: unsafeAsOpaqueButtonColourToken("text")
 					},
 					effects: { hover: [{ effectId: "press-down" }] }
 				}
@@ -2133,7 +2855,7 @@ const joyStampRecipe = defineStaticButtonStyleRecipe({
 						elevation: "high",
 						softness: "hard",
 						position: "bottom-right",
-						colorToken: "secondary"
+						colorToken: unsafeAsOpaqueButtonColourToken("secondary")
 					},
 					effects: { hover: [{ effectId: "press-down" }] }
 				}
@@ -2178,7 +2900,6 @@ const ornateRitualRecipe = defineStaticButtonStyleRecipe({
 			cornerStyle: "rounded",
 			textTransform: "uppercase",
 			fontWeight: 600,
-			borderWidth: 1,
 			hoverTransform: "none",
 			hoverColor: "none",
 			letterSpacing: "loose"
@@ -2214,7 +2935,7 @@ const ornateRitualRecipe = defineStaticButtonStyleRecipe({
 					effects: {
 						hover: [{
 							effectId: "background-on-hover",
-							options: { colorToken: "primary-100" }
+							options: { colorToken: unsafeAsOpaqueButtonColourToken("primary-100") }
 						}],
 						active: [{
 							effectId: "scale-down",
@@ -2234,7 +2955,7 @@ const ornateRitualRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surface") }
 					}] }
 				}
 			},
@@ -2249,7 +2970,7 @@ const ornateRitualRecipe = defineStaticButtonStyleRecipe({
 					border: { widthClass: "border" },
 					effects: { hover: [{
 						effectId: "background-on-hover",
-						options: { colorToken: "muted" }
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("muted") }
 					}] }
 				}
 			},
@@ -2283,7 +3004,6 @@ const ornateRitualRecipe = defineStaticButtonStyleRecipe({
 						effectId: "border-bottom-grow",
 						options: {
 							height: 1,
-							colorToken: "accent",
 							origin: "left"
 						}
 					}] }
@@ -4224,13 +4944,13 @@ async function loadLocalTheme(contentDir, themeName = "current") {
 	} catch (error) {
 		throw new Error(`Invalid JSON in theme file: ${filePath}\n${error instanceof Error ? error.message : String(error)}`);
 	}
-	const result = themeSchema$1.safeParse(parsedContent);
-	if (!result.success) {
-		const issues = result.error.issues.map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`).join("\n");
-		throw new Error(`Invalid theme at ${filePath}\n${issues}`);
+	const result = parseThemeForPersistence(parsedContent);
+	if (!result.ok) {
+		const detail = result.error.kind === "invalid-theme-schema" ? result.error.issues.map((issue) => `  - ${issue.path.join(".")}: ${issue.message}`).join("\n") : `  - buttons.${result.error.variantId}: ${result.error.cause.tag}`;
+		throw new Error(`Invalid theme at ${filePath}\n${detail}`);
 	}
 	return {
-		theme: result.data,
+		theme: result.value,
 		name: themeName,
 		filePath: path.resolve(filePath)
 	};
@@ -4263,43 +4983,5 @@ async function listLocalThemes(contentDir) {
 * These utilities help you work with Builder themes in your application.
 */
 const themeSchema = themeSchema$1;
-/**
-* Apply a Builder theme to the DOM by injecting CSS variables
-*
-* @param theme - The theme object from Riverbank CMS
-* @param element - The element to apply the theme to (default: document.documentElement)
-*
-* @example
-* ```ts
-* const site = await client.getSite({ slug: 'my-site' });
-* applyTheme(site.theme);
-* ```
-*/
-function applyTheme(theme, element) {
-	const targetElement = element ?? (typeof document !== "undefined" ? document.documentElement : null);
-	if (!targetElement) {
-		console.warn("[Builder SDK] Cannot apply theme: no document available");
-		return;
-	}
-	targetElement.setAttribute("data-builder-theme", JSON.stringify(theme));
-}
-/**
-* Create a theme object with type-safe defaults
-*
-* @param partial - Partial theme configuration
-* @returns Complete theme object
-*
-* @example
-* ```ts
-* const customTheme = createTheme({
-*   colors: {
-*     primary: '#007bff',
-*   },
-* });
-* ```
-*/
-function createTheme(partial = {}) {
-	return { ...partial };
-}
 //#endregion
-export { applyTheme, createTheme, listLocalThemes, loadLocalTheme, themeSchema };
+export { listLocalThemes, loadLocalTheme, themeSchema };