@riverbankcms/sdk 0.107.0 → 0.109.0

package/dist/server/theme-bridge.mjs

@@ -58,6 +58,111 @@ 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/tokens/colorTokenParts.ts
 function parseOpacityPercent(source) {
 	const trimmed = source.trim();
@@ -189,6 +294,10 @@ function isThemeColorToken(value) {
 	const parts = parseColorTokenParts(value);
 	return parts.kind === "token" && isThemeColorTokenBase(parts.token);
 }
+function parseThemeColorToken(value) {
+	if (!isThemeColorToken(value)) return null;
+	return value.trim();
+}
 const themeColorTokenSchema = z$1.string().min(1).refine((value) => Boolean(isThemeColorToken(value)), "Expected a known Theme V2 color token");
 //#endregion
 //#region ../theme-core/src/buttons/types.ts
@@ -207,6 +316,20 @@ const VARIANT_ROLES = [
 	"tertiary",
 	"accent"
 ];
+function parseOpaqueButtonColourToken(value) {
+	const token = parseThemeColorToken(value);
+	if (token === null) return null;
+	const parts = parseColorTokenParts(token);
+	return parts.kind === "token" && parts.opacityPercent === null ? token : null;
+}
+function unsafeAsOpaqueButtonColourToken(value) {
+	return value;
+}
+const opaqueButtonColourTokenSchema = themeColorTokenSchema.refine((value) => parseOpaqueButtonColourToken(value) !== null, "Button colour tokens must be opaque").transform((value) => {
+	const token = parseOpaqueButtonColourToken(value);
+	if (token === null) throw new Error("Invariant: opaque button token passed its schema");
+	return token;
+});
 const cornerStyleSchema = z$1.enum([
 	"square",
 	"rounded",
@@ -308,7 +431,7 @@ const buttonSizesSchema = z$1.object({
 	lg,
 	xl: xl ?? lg
 }));
-const buttonGlobalSettingsSchema = z$1.object({
+const canonicalButtonGlobalSettingsSchema = z$1.object({
 	cornerStyle: cornerStyleSchema,
 	cornerRadius: z$1.number().min(0).max(24).optional(),
 	/**
@@ -339,11 +462,12 @@ const buttonGlobalSettingsSchema = z$1.object({
 	paddingPreset: buttonPaddingPresetSchema.optional(),
 	hoverTransform: hoverTransformSchema,
 	hoverColor: hoverColorSchema,
-	hoverColorToken: themeColorTokenSchema.optional(),
+	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 gradientDirectionSchema$1 = z$1.enum([
 	"to-r",
 	"to-l",
@@ -357,27 +481,33 @@ const gradientDirectionSchema$1 = z$1.enum([
 const buttonBackgroundSchema = z$1.discriminatedUnion("type", [
 	z$1.object({
 		type: z$1.literal("solid"),
-		colorToken: themeColorTokenSchema
+		colorToken: opaqueButtonColourTokenSchema
 	}),
 	z$1.object({
 		type: z$1.literal("gradient"),
-		stops: z$1.array(themeColorTokenSchema).min(2),
-		direction: gradientDirectionSchema$1
+		stops: z$1.array(opaqueButtonColourTokenSchema).min(2).transform((stops) => {
+			const [first, second, ...rest] = stops;
+			if (first === void 0 || second === void 0) throw new Error("Invariant: gradient stops passed the minimum length schema");
+			return [
+				first,
+				second,
+				...rest
+			];
+		}),
+		direction: gradientDirectionSchema$1,
+		foregroundToken: opaqueButtonColourTokenSchema
 	}),
-	z$1.object({ type: z$1.literal("transparent") })
+	z$1.object({
+		type: z$1.literal("surface"),
+		role: z$1.literal("link")
+	})
 ]);
 const effectApplicationSchema$1 = z$1.object({
 	effectId: z$1.string(),
-	options: z$1.record(z$1.string(), z$1.any()).optional()
-});
-const buttonBorderSchema = z$1.object({
-	widthClass: z$1.string(),
-	colorToken: themeColorTokenSchema
-});
-const buttonVariantAffordanceSchema = z$1.object({
-	iconId: z$1.string().min(1),
-	colorToken: themeColorTokenSchema.optional()
+	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({
 	elevation: z$1.enum([
 		"none",
@@ -418,27 +548,738 @@ const variantSizeOverridesSchema = z$1.object({
 * default (e.g. link-style variants declaring zero horizontal padding at
 * every size).
 */
-const buttonVariantSchema = z$1.object({
+const canonicalButtonVariantSchema = z$1.object({
 	id: z$1.string(),
 	name: z$1.string().min(1).max(20),
 	enabled: z$1.boolean(),
 	priority: prioritySchema,
 	background: buttonBackgroundSchema,
-	textColorToken: themeColorTokenSchema,
 	/** Tailwind radius token (e.g. `'rounded-md'`). Omit to inherit from `global.cornerStyle`. */
 	borderRadius: z$1.string().optional(),
 	shadow: variantShadowSchema.optional(),
 	border: buttonBorderSchema.optional(),
-	hoverBackgroundToken: z$1.string().optional(),
+	hoverBackgroundToken: opaqueButtonColourTokenSchema.optional(),
 	effects: variantEffectsSchema.optional(),
 	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({
 	global: buttonGlobalSettingsSchema,
 	variants: z$1.array(buttonVariantSchema).min(1).max(6),
 	sizes: buttonSizesSchema.optional()
 });
+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
+		};
+	}
+	return {
+		...withoutLegacyText,
+		background: background.type === "solid" ? {
+			...background,
+			colorToken: stripLegacyTokenAlpha(background.colorToken)
+		} : background,
+		border: normalizedBorder,
+		affordance: normalizedAffordance,
+		effects: normalizedEffects,
+		hoverBackgroundToken
+	};
+}
+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 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;
+		});
+	});
+}
+function normalizeLegacyButtonEffects(input, backgroundType) {
+	if (!isUnknownRecord(input)) return input;
+	const normalized = {};
+	for (const state of [
+		"base",
+		"hover",
+		"active",
+		"focus"
+	]) {
+		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,
+						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
+				}
+			}];
+		});
+		if (safeEffects.length > 0) normalized[state] = safeEffects;
+	}
+	return Object.keys(normalized).length === 0 ? void 0 : normalized;
+}
+function isUnknownRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isUnknownArray(value) {
+	return Array.isArray(value);
+}
+//#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$1 = {
+	"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/palette/utils/colorConversion.ts
+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 srgbToLinear(u) {
+	const x = u / 255;
+	return x <= .04045 ? x / 12.92 : Math.pow((x + .055) / 1.055, 2.4);
+}
+//#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/surfaces/foregroundRoles.ts
+const SURFACE_FOREGROUND_ROLES = [
+	"text",
+	"heading",
+	"link",
+	"supporting"
+];
+//#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 completeSurfaceForegrounds(input) {
+	const text = requireSurfaceColorValue("text", input.text);
+	return {
+		text,
+		heading: input.heading === void 0 ? text : requireSurfaceColorValue("heading", input.heading),
+		link: input.link === void 0 ? text : requireSurfaceColorValue("link", input.link),
+		supporting: input.supporting === void 0 ? text : requireSurfaceColorValue("supporting", input.supporting)
+	};
+}
+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}))`;
+}
+function surfaceForegroundDeclarations(input) {
+	const foregrounds = completeSurfaceForegrounds(input);
+	return [`color: ${foregrounds.text}`, ...SURFACE_FOREGROUND_ROLES.map((role) => `${SURFACE_FOREGROUND_CSS_VARS[role]}: ${foregrounds[role]}`)];
+}
+//#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
+	});
+	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 [
+		"hover",
+		"focus",
+		"active"
+	]) {
+		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 formatButtonColourContractError(error) {
+	switch (error.tag) {
+		case "unknown_palette_token": return `Button "${error.variantId}" ${error.state} state uses unknown palette token "${error.token}".`;
+		case "missing_on_colour": return `Button "${error.variantId}" ${error.state} state cannot derive ${error.foregroundToken} from ${error.backgroundToken}.`;
+		case "insufficient_contrast": return `Button "${error.variantId}" ${error.state} state has ${error.ratio.toFixed(2)}:1 contrast (${error.requiredRatio}:1 required).`;
+		case "unsupported_colour_effect": return `Button "${error.variantId}" ${error.state} effect "${error.effectId}" is not contrast-safe (${error.reason}).`;
+		case "invalid_colour_effect_options": return `Button "${error.variantId}" ${error.state} effect "${error.effectId}" has an invalid ${error.option} option.`;
+		case "inapplicable_colour_effect": return `Button "${error.variantId}" ${error.state} effect "${error.effectId}" cannot apply to a ${error.treatment} treatment.`;
+		case "unknown_button_effect": return `Button "${error.variantId}" ${error.state} uses unknown effect "${error.effectId}".`;
+	}
+}
+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);
+		switch (policy.classification) {
+			case "non-colour":
+				nonColourEffects.push(effect);
+				break;
+			case "unsupported-colour":
+			case "unsupported-background-overlay":
+			case "not-button": return unsupportedEffect(input, effect, policy.reason);
+			case "colour-transition":
+				if (policy.transition.kind === "adjust-shade") {
+					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") {
+					const colorToken = readOpaqueToken(effect, "colorToken", "neutral-800");
+					if (colorToken === null) return invalidEffectOption(input, effect, "colorToken");
+					treatment = {
+						type: "solid",
+						colorToken
+					};
+					break;
+				}
+				return unknownEffect(input, effect);
+		}
+	}
+	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$1[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, key, fallback) {
+	return parseOpaqueButtonColourToken(effect.options?.[key] ?? fallback);
+}
+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 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 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/resolvedButtonCss.ts
+/**
+* Canonical colour declaration mapping shared by full themes and ThemeBridge.
+* Both background properties are always emitted so transitions cannot retain
+* a stale gradient or solid layer.
+*/
+function resolvedButtonColourDeclarations(colour) {
+	switch (colour.kind) {
+		case "solid": return [
+			["background-color", colour.backgroundCss],
+			["background-image", "none"],
+			["color", colour.foregroundCss]
+		];
+		case "gradient": return [
+			["background-color", "transparent"],
+			["background-image", colour.backgroundCss],
+			["color", colour.foregroundCss]
+		];
+		case "surface": return [
+			["background-color", colour.backgroundCss],
+			["background-image", "none"],
+			["color", colour.foregroundCss]
+		];
+	}
+}
+function resolvedButtonFocusDeclarations(indicator) {
+	return indicator.kind === "two-tone" ? [
+		["outline", `2px solid ${indicator.innerCss}`],
+		["outline-offset", "2px"],
+		["box-shadow", `0 0 0 4px ${indicator.outerCss}`]
+	] : [["outline", `3px solid ${indicator.colorCss}`], ["outline-offset", "3px"]];
+}
+/**
+* Disabled buttons retain their validated colour pair and add a non-layout
+* visual affordance. `currentColor` keeps the cue inside the same contrast
+* relationship, while retaining pointer events lets the not-allowed cursor
+* remain observable.
+*/
+const RESOLVED_BUTTON_DISABLED_DECLARATIONS = [
+	["cursor", "not-allowed"],
+	["transform", "none"],
+	["box-shadow", "none"],
+	["outline", "2px dashed currentColor"],
+	["outline-offset", "-4px"]
+];
 buttonSizeNameSchema.options;
 //#endregion
 //#region ../theme-core/src/site-styles/styleTags.ts
@@ -498,7 +1339,7 @@ function defineButtonPersonality(input) {
 		name: input.name,
 		description: input.description,
 		tags: input.tags,
-		buttonSystem: input.buttonSystem
+		buttonSystem: buttonSystemSchema.parse(input.buttonSystem)
 	};
 }
 //#endregion
@@ -551,19 +1392,15 @@ const brushedWash = defineButtonPersonality({
 				background: {
 					type: "gradient",
 					stops: ["primary", "accent"],
-					direction: "to-r"
+					direction: "to-r",
+					foregroundToken: "primaryForeground"
 				},
-				textColorToken: "primaryForeground",
 				borderRadius: "rounded-lg",
 				shadow: {
 					elevation: "low",
 					softness: "soft",
 					position: "bottom"
-				},
-				effects: { hover: [{
-					effectId: "opacity-reduce",
-					options: { reduction: -15 }
-				}] }
+				}
 			},
 			{
 				id: "secondary",
@@ -573,32 +1410,27 @@ const brushedWash = defineButtonPersonality({
 				background: {
 					type: "gradient",
 					stops: ["secondary", "accent"],
-					direction: "to-br"
+					direction: "to-br",
+					foregroundToken: "primaryForeground"
 				},
-				textColorToken: "primaryForeground",
 				borderRadius: "rounded-lg",
 				shadow: {
 					elevation: "low",
 					softness: "soft",
 					position: "bottom"
-				},
-				effects: { hover: [{
-					effectId: "opacity-reduce",
-					options: { reduction: -15 }
-				}] }
+				}
 			},
 			{
 				id: "outline",
 				name: "Outline",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "primary",
-				borderRadius: "rounded-lg",
-				border: {
-					widthClass: "border",
-					colorToken: "primary"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-lg",
+				border: { widthClass: "border" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "surface" }
@@ -609,8 +1441,10 @@ const brushedWash = defineButtonPersonality({
 				name: "Ghost",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "text",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-lg",
 				effects: { hover: [{
 					effectId: "background-on-hover",
@@ -656,7 +1490,6 @@ const confidentChip = defineButtonPersonality({
 					type: "solid",
 					colorToken: "primary"
 				},
-				textColorToken: "primaryForeground",
 				borderRadius: "rounded-md",
 				shadow: {
 					elevation: "medium",
@@ -666,7 +1499,7 @@ const confidentChip = defineButtonPersonality({
 				effects: {
 					hover: [{
 						effectId: "darken-background",
-						options: { amount: 60 }
+						options: { amount: 100 }
 					}],
 					active: [{
 						effectId: "scale-down",
@@ -683,12 +1516,8 @@ const confidentChip = defineButtonPersonality({
 					type: "solid",
 					colorToken: "surface"
 				},
-				textColorToken: "text",
 				borderRadius: "rounded-md",
-				border: {
-					widthClass: "border",
-					colorToken: "border"
-				},
+				border: { widthClass: "border" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "background" }
@@ -699,13 +1528,12 @@ const confidentChip = defineButtonPersonality({
 				name: "Outline",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "primary",
-				borderRadius: "rounded-md",
-				border: {
-					widthClass: "border",
-					colorToken: "primary"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-md",
+				border: { widthClass: "border" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "surface" }
@@ -716,8 +1544,10 @@ const confidentChip = defineButtonPersonality({
 				name: "Ghost",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "primary",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-md",
 				effects: { hover: [{
 					effectId: "background-on-hover",
@@ -780,7 +1610,6 @@ const earthPill = defineButtonPersonality({
 					type: "solid",
 					colorToken: "primary"
 				},
-				textColorToken: "primaryForeground",
 				borderRadius: "rounded-full",
 				shadow: {
 					elevation: "low",
@@ -806,13 +1635,12 @@ const earthPill = defineButtonPersonality({
 				name: "Secondary",
 				enabled: true,
 				priority: 2,
-				background: { type: "transparent" },
-				textColorToken: "primary",
-				borderRadius: "rounded-full",
-				border: {
-					widthClass: "border",
-					colorToken: "primary"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-full",
+				border: { widthClass: "border" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "muted" }
@@ -823,13 +1651,12 @@ const earthPill = defineButtonPersonality({
 				name: "Outline",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "text",
-				borderRadius: "rounded-full",
-				border: {
-					widthClass: "border",
-					colorToken: "border"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-full",
+				border: { widthClass: "border" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "surfaceAlt" }
@@ -840,8 +1667,10 @@ const earthPill = defineButtonPersonality({
 				name: "Ghost",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "primary",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-full",
 				shadow: {
 					elevation: "none",
@@ -862,11 +1691,7 @@ const earthPill = defineButtonPersonality({
 						padding: "0.625rem 0",
 						fontSize: "text-xl"
 					}
-				},
-				effects: { hover: [{
-					effectId: "opacity-reduce",
-					options: { reduction: 25 }
-				}] }
+				}
 			}
 		]
 	}
@@ -902,8 +1727,10 @@ const editorialLink = defineButtonPersonality({
 				name: "Primary",
 				enabled: true,
 				priority: 1,
-				background: { type: "transparent" },
-				textColorToken: "text",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-none",
 				sizes: {
 					sm: { padding: "0.25rem 0" },
@@ -925,8 +1752,10 @@ const editorialLink = defineButtonPersonality({
 				name: "Secondary",
 				enabled: true,
 				priority: 2,
-				background: { type: "transparent" },
-				textColorToken: "mutedText",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-none",
 				sizes: {
 					sm: { padding: "0.25rem 0" },
@@ -948,8 +1777,10 @@ const editorialLink = defineButtonPersonality({
 				name: "Outline",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "accent",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-none",
 				sizes: {
 					sm: { padding: "0.25rem 0" },
@@ -971,19 +1802,17 @@ const editorialLink = defineButtonPersonality({
 				name: "Ghost",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "mutedText",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-none",
 				sizes: {
 					sm: { padding: "0.25rem 0" },
 					md: { padding: "0.5rem 0" },
 					lg: { padding: "0.625rem 0" },
 					xl: { padding: "0.75rem 0" }
-				},
-				effects: { hover: [{
-					effectId: "opacity-reduce",
-					options: { reduction: -20 }
-				}] }
+				}
 			}
 		]
 	}
@@ -1045,12 +1874,8 @@ const flatInk = defineButtonPersonality({
 					type: "solid",
 					colorToken: "primary"
 				},
-				textColorToken: "primaryForeground",
 				borderRadius: "rounded-lg",
-				affordance: {
-					iconId: "ArrowRight",
-					colorToken: "accent"
-				},
+				affordance: { iconId: "ArrowRight" },
 				effects: { hover: [{
 					effectId: "lift",
 					options: { translateY: "-2px" }
@@ -1064,13 +1889,12 @@ const flatInk = defineButtonPersonality({
 				name: "Secondary",
 				enabled: true,
 				priority: 2,
-				background: { type: "transparent" },
-				textColorToken: "primary",
-				borderRadius: "rounded-lg",
-				border: {
-					widthClass: "border",
-					colorToken: "border"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-lg",
+				border: { widthClass: "border" },
 				effects: { hover: [{
 					effectId: "lift",
 					options: { translateY: "-2px" }
@@ -1088,12 +1912,8 @@ const flatInk = defineButtonPersonality({
 					type: "solid",
 					colorToken: "accent"
 				},
-				textColorToken: "accentForeground",
 				borderRadius: "rounded-lg",
-				affordance: {
-					iconId: "ArrowRight",
-					colorToken: "accentForeground"
-				},
+				affordance: { iconId: "ArrowRight" },
 				effects: { hover: [{
 					effectId: "lift",
 					options: { translateY: "-2px" }
@@ -1156,7 +1976,6 @@ const inkStamp = defineButtonPersonality({
 					type: "solid",
 					colorToken: "primary"
 				},
-				textColorToken: "primaryForeground",
 				borderRadius: "rounded-md",
 				effects: {
 					hover: [{
@@ -1177,13 +1996,12 @@ const inkStamp = defineButtonPersonality({
 				name: "Secondary",
 				enabled: true,
 				priority: 2,
-				background: { type: "transparent" },
-				textColorToken: "primary",
-				borderRadius: "rounded-md",
-				border: {
-					widthClass: "border-2",
-					colorToken: "primary"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-md",
+				border: { widthClass: "border-2" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "surface" }
@@ -1194,13 +2012,12 @@ const inkStamp = defineButtonPersonality({
 				name: "Outline",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "text",
-				borderRadius: "rounded-md",
-				border: {
-					widthClass: "border-2",
-					colorToken: "border"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-md",
+				border: { widthClass: "border-2" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "surface" }
@@ -1211,8 +2028,10 @@ const inkStamp = defineButtonPersonality({
 				name: "Ghost",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "accent",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-none",
 				sizes: {
 					sm: {
@@ -1305,7 +2124,6 @@ const joyStamp = defineButtonPersonality({
 				type: "solid",
 				colorToken: "primary"
 			},
-			textColorToken: "primaryForeground",
 			borderRadius: "rounded-full",
 			shadow: {
 				elevation: "high",
@@ -1319,13 +2137,12 @@ const joyStamp = defineButtonPersonality({
 			name: "Secondary",
 			enabled: true,
 			priority: 2,
-			background: { type: "transparent" },
-			textColorToken: "text",
-			borderRadius: "rounded-full",
-			border: {
-				widthClass: "border-2",
-				colorToken: "text"
+			background: {
+				type: "surface",
+				role: "link"
 			},
+			borderRadius: "rounded-full",
+			border: { widthClass: "border-2" },
 			shadow: {
 				elevation: "high",
 				softness: "hard",
@@ -1390,12 +2207,8 @@ const ornateRitual = defineButtonPersonality({
 					type: "solid",
 					colorToken: "primary"
 				},
-				textColorToken: "primaryForeground",
 				borderRadius: "rounded-md",
-				border: {
-					widthClass: "border",
-					colorToken: "primary"
-				},
+				border: { widthClass: "border" },
 				effects: {
 					hover: [{
 						effectId: "background-on-hover",
@@ -1416,12 +2229,8 @@ const ornateRitual = defineButtonPersonality({
 					type: "solid",
 					colorToken: "secondary"
 				},
-				textColorToken: "primaryForeground",
 				borderRadius: "rounded-md",
-				border: {
-					widthClass: "border",
-					colorToken: "primary"
-				},
+				border: { widthClass: "border" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "surface" }
@@ -1432,13 +2241,12 @@ const ornateRitual = defineButtonPersonality({
 				name: "Outline",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "primary",
-				borderRadius: "rounded-md",
-				border: {
-					widthClass: "border",
-					colorToken: "primary"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-md",
+				border: { widthClass: "border" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "muted" }
@@ -1449,8 +2257,10 @@ const ornateRitual = defineButtonPersonality({
 				name: "Ghost",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "accent",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-none",
 				sizes: {
 					sm: {
@@ -1532,14 +2342,10 @@ const pebble = defineButtonPersonality({
 					type: "solid",
 					colorToken: "primary"
 				},
-				textColorToken: "primaryForeground",
 				borderRadius: "rounded-full",
 				effects: { hover: [{
-					effectId: "background-on-hover-alpha",
-					options: {
-						colorToken: "primary",
-						opacity: 88
-					}
+					effectId: "darken-background",
+					options: { amount: 100 }
 				}] }
 			},
 			{
@@ -1547,13 +2353,12 @@ const pebble = defineButtonPersonality({
 				name: "Secondary",
 				enabled: true,
 				priority: 2,
-				background: { type: "transparent" },
-				textColorToken: "primary",
-				borderRadius: "rounded-full",
-				border: {
-					widthClass: "border-2",
-					colorToken: "accent"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-full",
+				border: { widthClass: "border-2" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "accent" }
@@ -1564,13 +2369,12 @@ const pebble = defineButtonPersonality({
 				name: "Outline",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "text",
-				borderRadius: "rounded-full",
-				border: {
-					widthClass: "border",
-					colorToken: "border"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-full",
+				border: { widthClass: "border" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "surface" }
@@ -1581,8 +2385,10 @@ const pebble = defineButtonPersonality({
 				name: "Ghost",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "primary",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-full",
 				sizes: {
 					sm: {
@@ -1598,11 +2404,7 @@ const pebble = defineButtonPersonality({
 						padding: "0.75rem 1.5rem",
 						fontSize: "text-xl"
 					}
-				},
-				effects: { hover: [{
-					effectId: "opacity-reduce",
-					options: { reduction: 30 }
-				}] }
+				}
 			}
 		]
 	}
@@ -1664,15 +2466,11 @@ const quietArrow = defineButtonPersonality({
 					type: "solid",
 					colorToken: "primary"
 				},
-				textColorToken: "primaryForeground",
 				borderRadius: "rounded-xl",
 				affordance: { iconId: "ArrowRight" },
 				effects: { hover: [{
-					effectId: "background-on-hover-alpha",
-					options: {
-						colorToken: "primary",
-						opacity: 90
-					}
+					effectId: "darken-background",
+					options: { amount: 100 }
 				}] }
 			},
 			{
@@ -1680,13 +2478,12 @@ const quietArrow = defineButtonPersonality({
 				name: "Secondary",
 				enabled: true,
 				priority: 2,
-				background: { type: "transparent" },
-				textColorToken: "primary",
-				borderRadius: "rounded-xl",
-				border: {
-					widthClass: "border",
-					colorToken: "primary"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-xl",
+				border: { widthClass: "border" },
 				affordance: { iconId: "ArrowRight" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
@@ -1698,21 +2495,22 @@ const quietArrow = defineButtonPersonality({
 				name: "Outline",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "primary",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-xl",
-				border: {
-					widthClass: "border",
-					colorToken: "primary"
-				}
+				border: { widthClass: "border" }
 			},
 			{
 				id: "ghost",
 				name: "Ghost",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "primary",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-xl"
 			}
 		]
@@ -1776,7 +2574,6 @@ const showtimePill = defineButtonPersonality({
 					type: "solid",
 					colorToken: "primary"
 				},
-				textColorToken: "background",
 				borderRadius: "rounded-full",
 				effects: { hover: [{ effectId: "pop" }] }
 			},
@@ -1785,13 +2582,12 @@ const showtimePill = defineButtonPersonality({
 				name: "Secondary",
 				enabled: true,
 				priority: 2,
-				background: { type: "transparent" },
-				textColorToken: "primary",
-				borderRadius: "rounded-full",
-				border: {
-					widthClass: "border-2",
-					colorToken: "primary"
+				background: {
+					type: "surface",
+					role: "link"
 				},
+				borderRadius: "rounded-full",
+				border: { widthClass: "border-2" },
 				effects: { hover: [{ effectId: "pop" }] }
 			},
 			{
@@ -1803,7 +2599,6 @@ const showtimePill = defineButtonPersonality({
 					type: "solid",
 					colorToken: "secondary"
 				},
-				textColorToken: "primary",
 				borderRadius: "rounded-full",
 				effects: { hover: [{ effectId: "pop" }] }
 			},
@@ -1816,12 +2611,8 @@ const showtimePill = defineButtonPersonality({
 					type: "solid",
 					colorToken: "background"
 				},
-				textColorToken: "primary",
 				borderRadius: "rounded-full",
-				border: {
-					widthClass: "border-2",
-					colorToken: "primary"
-				},
+				border: { widthClass: "border-2" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "surface" }
@@ -1832,16 +2623,118 @@ const showtimePill = defineButtonPersonality({
 				name: "Outline",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "primary",
+				background: {
+					type: "surface",
+					role: "link"
+				},
+				borderRadius: "rounded-full",
+				border: { widthClass: "border-2" },
+				effects: { hover: [{
+					effectId: "background-on-hover",
+					options: { colorToken: "background" }
+				}] }
+			},
+			{
+				id: "ghost",
+				name: "Ghost",
+				enabled: true,
+				priority: 3,
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-full",
-				border: {
-					widthClass: "border-2",
+				effects: { hover: [{
+					effectId: "background-on-hover",
+					options: { colorToken: "surface" }
+				}] }
+			}
+		]
+	}
+});
+//#endregion
+//#region ../theme-core/src/buttons/personalities/soft-pill.ts
+/**
+* Soft Pill — rounded-full pill buttons with a hover lift. The default for
+* Calm Studio and Modern Wellness; reads as quietly modern and welcoming.
+*/
+const softPill = defineButtonPersonality({
+	id: "soft-pill",
+	name: "Soft Pill",
+	description: "Rounded pills with a gentle lift on hover. Quietly modern.",
+	tags: {
+		tone: "classic",
+		energy: "calm",
+		motion: "subtle",
+		era: "organic"
+	},
+	buttonSystem: {
+		global: {
+			cornerStyle: "pill",
+			shadow: "low",
+			textTransform: "none",
+			fontWeight: 500,
+			borderWidth: 2,
+			hoverTransform: "lift",
+			hoverColor: "none"
+		},
+		variants: [
+			{
+				id: "primary",
+				name: "Primary",
+				enabled: true,
+				priority: 1,
+				background: {
+					type: "solid",
 					colorToken: "primary"
 				},
+				borderRadius: "rounded-full",
+				shadow: {
+					elevation: "low",
+					softness: "soft",
+					position: "bottom"
+				},
+				effects: {
+					hover: [{
+						effectId: "lift",
+						options: { translateY: "-1px" }
+					}],
+					active: [{
+						effectId: "scale-down",
+						options: { scale: "0.98" }
+					}]
+				}
+			},
+			{
+				id: "secondary",
+				name: "Secondary",
+				enabled: true,
+				priority: 2,
+				background: {
+					type: "surface",
+					role: "link"
+				},
+				borderRadius: "rounded-full",
+				border: { widthClass: "border-2" },
 				effects: { hover: [{
 					effectId: "background-on-hover",
-					options: { colorToken: "background" }
+					options: { colorToken: "surface" }
+				}] }
+			},
+			{
+				id: "outline",
+				name: "Outline",
+				enabled: true,
+				priority: 3,
+				background: {
+					type: "surface",
+					role: "link"
+				},
+				borderRadius: "rounded-full",
+				border: { widthClass: "border" },
+				effects: { hover: [{
+					effectId: "background-on-hover",
+					options: { colorToken: "surface" }
 				}] }
 			},
 			{
@@ -1849,116 +2742,62 @@ const showtimePill = defineButtonPersonality({
 				name: "Ghost",
 				enabled: true,
 				priority: 3,
-				background: { type: "transparent" },
-				textColorToken: "primary",
+				background: {
+					type: "surface",
+					role: "link"
+				},
 				borderRadius: "rounded-full",
 				effects: { hover: [{
 					effectId: "background-on-hover",
 					options: { colorToken: "surface" }
 				}] }
 			}
-		]
+		]
+	}
+});
+//#endregion
+//#region ../theme-core/src/buttons/personalities/two-tone-pill.ts
+const solidSecondary = {
+	id: "secondary",
+	name: "Secondary",
+	enabled: true,
+	priority: 2,
+	background: {
+		type: "solid",
+		colorToken: unsafeAsOpaqueButtonColourToken("secondary")
+	},
+	borderRadius: "rounded-full",
+	shadow: {
+		elevation: "none",
+		softness: null,
+		position: "bottom"
+	},
+	effects: {
+		hover: [{
+			effectId: "background-on-hover-alpha",
+			options: {
+				colorToken: "secondary",
+				opacity: 88
+			}
+		}],
+		active: [{
+			effectId: "scale-down",
+			options: { scale: "0.98" }
+		}]
 	}
-});
+};
 //#endregion
 //#region ../theme-core/src/buttons/personalities/index.ts
 const buttonPersonalities = [
+	softPill,
 	defineButtonPersonality({
-		id: "soft-pill",
-		name: "Soft Pill",
-		description: "Rounded pills with a gentle lift on hover. Quietly modern.",
-		tags: {
-			tone: "classic",
-			energy: "calm",
-			motion: "subtle",
-			era: "organic"
-		},
+		id: "two-tone-pill",
+		name: "Two-tone Pill",
+		description: "Rounded pills with distinct solid primary and secondary brand colours.",
+		tags: softPill.tags,
 		buttonSystem: {
-			global: {
-				cornerStyle: "pill",
-				shadow: "low",
-				textTransform: "none",
-				fontWeight: 500,
-				borderWidth: 2,
-				hoverTransform: "lift",
-				hoverColor: "none"
-			},
-			variants: [
-				{
-					id: "primary",
-					name: "Primary",
-					enabled: true,
-					priority: 1,
-					background: {
-						type: "solid",
-						colorToken: "primary"
-					},
-					textColorToken: "primaryForeground",
-					borderRadius: "rounded-full",
-					shadow: {
-						elevation: "low",
-						softness: "soft",
-						position: "bottom"
-					},
-					effects: {
-						hover: [{
-							effectId: "lift",
-							options: { translateY: "-1px" }
-						}],
-						active: [{
-							effectId: "scale-down",
-							options: { scale: "0.98" }
-						}]
-					}
-				},
-				{
-					id: "secondary",
-					name: "Secondary",
-					enabled: true,
-					priority: 2,
-					background: { type: "transparent" },
-					textColorToken: "primary",
-					borderRadius: "rounded-full",
-					border: {
-						widthClass: "border-2",
-						colorToken: "primary"
-					},
-					effects: { hover: [{
-						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
-					}] }
-				},
-				{
-					id: "outline",
-					name: "Outline",
-					enabled: true,
-					priority: 3,
-					background: { type: "transparent" },
-					textColorToken: "text",
-					borderRadius: "rounded-full",
-					border: {
-						widthClass: "border",
-						colorToken: "border"
-					},
-					effects: { hover: [{
-						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
-					}] }
-				},
-				{
-					id: "ghost",
-					name: "Ghost",
-					enabled: true,
-					priority: 3,
-					background: { type: "transparent" },
-					textColorToken: "text",
-					borderRadius: "rounded-full",
-					effects: { hover: [{
-						effectId: "background-on-hover",
-						options: { colorToken: "surface" }
-					}] }
-				}
-			]
+			...softPill.buttonSystem,
+			variants: softPill.buttonSystem.variants.map((variant) => variant.id === "secondary" ? solidSecondary : variant)
 		}
 	}),
 	earthPill,
@@ -1974,6 +2813,27 @@ const buttonPersonalities = [
 	quietArrow
 ];
 new Map(buttonPersonalities.map((p) => [p.id, p]));
+buttonPersonalities.map((personality) => ({
+	id: personality.id,
+	name: personality.name,
+	description: personality.description,
+	category: presetCategory(personality),
+	buttonSystem: personality.buttonSystem,
+	compatibility: {
+		...personality.tags.tone ? { tones: [personality.tags.tone] } : {},
+		...personality.tags.energy ? { energies: [personality.tags.energy] } : {}
+	}
+}));
+function presetCategory(personality) {
+	switch (personality.tags.era) {
+		case "retro": return "retro";
+		case "editorial": return "minimal";
+		case "organic": return "artistic";
+		case "modern": return personality.tags.tone === "bold" ? "modern" : "technical";
+		case "technical": return "technical";
+		case void 0: return "modern";
+	}
+}
 //#endregion
 //#region ../theme-core/src/buttons/core.ts
 const CORNER_RADIUS_MAP$2 = {
@@ -1988,125 +2848,101 @@ const BORDER_WIDTH_MAP$2 = {
 	medium: "2px",
 	thick: "4px"
 };
-const GRADIENT_DIRECTION_MAP$1 = {
-	"to-r": "to right",
-	"to-l": "to left",
-	"to-t": "to top",
-	"to-b": "to bottom",
-	"to-tr": "to top right",
-	"to-tl": "to top left",
-	"to-br": "to bottom right",
-	"to-bl": "to bottom left"
-};
 const SHADOW_VALUES$2 = {
 	none: "none",
 	low: "0 1px 2px rgba(0,0,0,0.06)",
 	medium: "0 4px 6px -1px rgba(0,0,0,0.1), 0 2px 4px -2px rgba(0,0,0,0.1)",
 	high: "0 10px 15px -3px rgba(0,0,0,0.1), 0 4px 6px -4px rgba(0,0,0,0.1)"
 };
-/**
-* Generate button CSS from core variant definitions.
-*
-* This is a pure function with no dependencies on Theme type.
-* It generates CSS that uses rgb(var(--tb-{token})) for colors.
-*
-* @param scopeId - Theme scope ID for selector (e.g., 'sdk' -> [data-theme-scope="sdk"])
-* @param variants - Button variant definitions
-* @param settings - Global button settings
-* @returns CSS string
-*/
-function generateButtonCoreCss(scopeId, variants, settings) {
-	const cssChunks = [];
-	for (const variant of variants) {
-		const css = generateVariantCss$1(scopeId, variant, settings);
-		cssChunks.push(css);
-	}
-	return cssChunks.join("\n\n");
-}
-/**
-* Generate CSS for a single button variant
-*
-* Selectors use :where() for zero specificity, allowing site styles to override easily.
-*/
-function generateVariantCss$1(scopeId, variant, settings) {
+const RESOLVER_GLOBAL = {
+	cornerStyle: "rounded",
+	textTransform: "none",
+	fontWeight: 500,
+	borderWidth: 1,
+	hoverTransform: "none",
+	hoverColor: "none"
+};
+function generateButtonCoreCss(scopeId, variants, settings, palette) {
+	return variants.map((variant) => generateVariantCss$1(scopeId, variant, settings, palette)).join("\n\n");
+}
+function generateVariantCss$1(scopeId, variant, settings, palette) {
+	const borderWidth = BORDER_WIDTH_MAP$2[variant.borderWidth ?? "none"];
+	const result = compileButtonColourStates({
+		variant: {
+			id: variant.id,
+			name: variant.id,
+			enabled: true,
+			priority: 1,
+			background: variant.treatment,
+			...borderWidth === "0" ? {} : { border: { widthClass: borderWidth } }
+		},
+		global: RESOLVER_GLOBAL,
+		palette
+	});
+	if (!result.ok) throw new Error(`[ThemeBridge] ${formatButtonColourContractError(result.error)}`);
 	const selector = `:where([data-theme-scope="${scopeId}"]) .button-${variant.id}`;
-	const rules = [];
-	const borderWidthValue = variant.borderWidth ? BORDER_WIDTH_MAP$2[variant.borderWidth] : variant.borderToken ? BORDER_WIDTH_MAP$2[settings.borderWidth] : "0";
-	const hasBorder = borderWidthValue !== "0";
-	const basePadding = {
-		vertical: "0.5rem",
-		horizontal: "1rem"
-	};
-	if (hasBorder) {
-		rules.push(`padding-top: calc(${basePadding.vertical} - ${borderWidthValue});`);
-		rules.push(`padding-bottom: calc(${basePadding.vertical} - ${borderWidthValue});`);
-		rules.push(`padding-left: calc(${basePadding.horizontal} - ${borderWidthValue});`);
-		rules.push(`padding-right: calc(${basePadding.horizontal} - ${borderWidthValue});`);
-	} else rules.push(`padding: ${basePadding.vertical} ${basePadding.horizontal};`);
-	rules.push(`font-weight: ${settings.fontWeight ?? 500};`);
-	if (settings.textTransform && settings.textTransform !== "none") rules.push(`text-transform: ${settings.textTransform};`);
-	rules.push("cursor: pointer;");
-	rules.push("transition: all 200ms ease-in-out;");
-	rules.push("display: inline-flex;");
-	rules.push("align-items: center;");
-	rules.push("justify-content: center;");
-	rules.push(`border-radius: ${CORNER_RADIUS_MAP$2[settings.corners]};`);
-	rules.push(`box-shadow: ${SHADOW_VALUES$2[settings.shadow]};`);
-	if (variant.background === "solid" && variant.backgroundToken) rules.push(`background-color: rgb(var(--tb-${variant.backgroundToken}));`);
-	else if (variant.background === "gradient" && variant.gradientStops) {
-		const colors = variant.gradientStops.map((token) => `rgb(var(--tb-${token}))`).join(", ");
-		const direction = GRADIENT_DIRECTION_MAP$1[variant.gradientDirection ?? "to-r"];
-		rules.push(`background-image: linear-gradient(${direction}, ${colors});`);
-	} else rules.push("background-color: transparent;");
-	const textColor = variant.background === "transparent" ? `var(--rb-surface-link-color, rgb(var(--tb-${variant.textToken})))` : `rgb(var(--tb-${variant.textToken}))`;
-	rules.push(`color: ${textColor};`);
-	if (variant.borderToken) {
-		const borderColor = variant.background === "transparent" ? `var(--rb-surface-link-color, rgb(var(--tb-${variant.borderToken})))` : `rgb(var(--tb-${variant.borderToken}))`;
-		rules.push(`border: ${borderWidthValue} solid ${borderColor};`);
-	} else rules.push("border: none;");
 	return [
-		`${selector} {\n  ${rules.join("\n  ")}\n}`,
-		`${selector}:hover {\n  opacity: 0.9;\n}`,
-		`${selector}:active {\n  opacity: 0.8;\n  transform: scale(0.98);\n}`,
-		`${selector}:disabled,
-${selector}:disabled:hover,
-${selector}:disabled:active {
-  opacity: 0.5;
-  cursor: not-allowed;
-  pointer-events: none;
-  transform: none;
-}`
+		rule(selector, [
+			...borderWidth === "0" ? ["padding: 0.5rem 1rem;"] : [
+				`padding-top: calc(0.5rem - ${borderWidth});`,
+				`padding-bottom: calc(0.5rem - ${borderWidth});`,
+				`padding-left: calc(1rem - ${borderWidth});`,
+				`padding-right: calc(1rem - ${borderWidth});`
+			],
+			`font-weight: ${settings.fontWeight ?? 500};`,
+			...settings.textTransform && settings.textTransform !== "none" ? [`text-transform: ${settings.textTransform};`] : [],
+			"cursor: pointer;",
+			"transition: all 200ms ease-in-out;",
+			"display: inline-flex;",
+			"align-items: center;",
+			"justify-content: center;",
+			`border-radius: ${CORNER_RADIUS_MAP$2[settings.corners]};`,
+			`box-shadow: ${SHADOW_VALUES$2[settings.shadow]};`,
+			...declarationStrings(resolvedButtonColourDeclarations(result.states.base)),
+			borderWidth === "0" ? "border: none;" : `border: ${borderWidth} solid currentColor;`
+		]),
+		rule(`${selector}:hover`, declarationStrings(resolvedButtonColourDeclarations(result.states.hover))),
+		rule(`${selector}:active`, [...declarationStrings(resolvedButtonColourDeclarations(result.states.active)), "transform: scale(0.98);"]),
+		rule(`${selector}:focus-visible`, declarationStrings(resolvedButtonFocusDeclarations(result.focusIndicator))),
+		rule(`${selector}:disabled,\n${selector}:disabled:hover,\n${selector}:disabled:active`, [...declarationStrings(resolvedButtonColourDeclarations(result.states.disabled)), ...declarationStrings(RESOLVED_BUTTON_DISABLED_DECLARATIONS)])
 	].join("\n\n");
 }
-/**
-* Get default button variants for SDK usage.
-* These create primary, secondary, outline, and ghost buttons.
-*/
+function declarationStrings(declarations) {
+	return declarations.map(([property, value]) => `${property}: ${value};`);
+}
+function rule(selector, declarations) {
+	return `${selector} {\n  ${declarations.join("\n  ")}\n}`;
+}
 function getDefaultButtonVariants() {
 	return [
 		{
 			id: "primary",
-			background: "solid",
-			backgroundToken: "primary",
-			textToken: "white"
+			treatment: {
+				type: "solid",
+				colorToken: unsafeAsOpaqueButtonColourToken("primary")
+			}
 		},
 		{
 			id: "secondary",
-			background: "solid",
-			backgroundToken: "secondary",
-			textToken: "white"
+			treatment: {
+				type: "solid",
+				colorToken: unsafeAsOpaqueButtonColourToken("secondary")
+			}
 		},
 		{
 			id: "outline",
-			background: "transparent",
-			borderToken: "primary",
-			textToken: "primary",
+			treatment: {
+				type: "surface",
+				role: "link"
+			},
 			borderWidth: "thin"
 		},
 		{
 			id: "ghost",
-			background: "transparent",
-			textToken: "primary"
+			treatment: {
+				type: "surface",
+				role: "link"
+			}
 		}
 	];
 }
@@ -2222,53 +3058,6 @@ const cardVariantSchema = z$1.object({
 });
 const cardSystemSchema = z$1.object({ variants: z$1.array(cardVariantSchema).min(1).max(3) });
 //#endregion
-//#region ../theme-core/src/surfaces/foregroundRoles.ts
-const SURFACE_FOREGROUND_ROLES = [
-	"text",
-	"heading",
-	"link",
-	"supporting"
-];
-//#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 completeSurfaceForegrounds(input) {
-	const text = requireSurfaceColorValue("text", input.text);
-	return {
-		text,
-		heading: input.heading === void 0 ? text : requireSurfaceColorValue("heading", input.heading),
-		link: input.link === void 0 ? text : requireSurfaceColorValue("link", input.link),
-		supporting: input.supporting === void 0 ? text : requireSurfaceColorValue("supporting", input.supporting)
-	};
-}
-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}))`;
-}
-function surfaceForegroundDeclarations(input) {
-	const foregrounds = completeSurfaceForegrounds(input);
-	return [`color: ${foregrounds.text}`, ...SURFACE_FOREGROUND_ROLES.map((role) => `${SURFACE_FOREGROUND_CSS_VARS[role]}: ${foregrounds[role]}`)];
-}
-//#endregion
 //#region ../theme-core/src/cards/core.ts
 /**
 * Core Card CSS Generator
@@ -2398,7 +3187,7 @@ function generateVariantCss(scopeId, variant, settings) {
 	containerRules.push("display: flex");
 	containerRules.push("flex-direction: column");
 	containerRules.push("position: relative");
-	containerRules.push("overflow: hidden");
+	containerRules.push("overflow: visible");
 	const mediaRadius = CORNER_RADIUS_MAP$1[settings.corners];
 	const mediaRules = [`border-top-left-radius: ${mediaRadius}`, `border-top-right-radius: ${mediaRadius}`];
 	const contentRules = [`padding: ${SPACING_MAP[variant.spacing]}`];
@@ -3780,6 +4569,7 @@ const navFontWeight = z$1.enum([
 	"bold"
 ]);
 const headerMaxWidth = z$1.enum(["container", "full"]);
+const headerBarFrame = z$1.enum(["full-bleed", "inset-shell"]);
 const headerContainerSchema = z$1.object({
 	rounded: z$1.enum([
 		"none",
@@ -3924,6 +4714,7 @@ const headerSchema = z$1.object({
 	positioning: headerPositioning,
 	shrinkOnScroll: z$1.boolean(),
 	maxWidth: headerMaxWidth,
+	barFrame: headerBarFrame.optional(),
 	logoOverride: mediaSchema.nullable().optional(),
 	background: headerBackgroundSchema.default({
 		type: "color",
@@ -3933,6 +4724,7 @@ const headerSchema = z$1.object({
 	navStyle: headerNavStyle,
 	navColor: themeColorTokenSchema.nullable().optional(),
 	navWeight: navFontWeight.default("medium"),
+	navFontRole: z$1.enum(["body", "heading"]).optional(),
 	navTypography: z$1.enum(["body", "heading"]).optional(),
 	navTextSize: navLinkStyleSchema.shape.textSize,
 	navPlacement: z$1.enum(["end", "center"]).optional(),
@@ -3948,7 +4740,21 @@ const headerSchema = z$1.object({
 	ctaTreatment: headerCtaTreatmentSchema.optional(),
 	ctaVariant: z$1.string().min(1).optional(),
 	dropdownStyle: dropdownStyleSchema
-});
+}).transform(normaliseHeaderNavFontRole);
+/**
+* Normalises the legacy `navTypography` font-role alias into the canonical
+* `navFontRole` field so persisted themes migrate at the parse boundary without
+* a data migration. `navFontRole` always wins when both are present; the legacy
+* field is dropped so we never carry a dual write forward.
+*/
+function normaliseHeaderNavFontRole(header) {
+	if (header.navTypography === void 0) return header;
+	const { navTypography, ...rest } = header;
+	return header.navFontRole === void 0 ? {
+		...rest,
+		navFontRole: navTypography
+	} : rest;
+}
 const footerVariant = z$1.enum([
 	"simple",
 	"columns",
@@ -4213,19 +5019,6 @@ z$1.object({
 	themes: z$1.array(themeSchema).length(3)
 });
 //#endregion
-//#region ../theme-core/src/palette/utils/colorConversion.ts
-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
-	};
-}
-//#endregion
 //#region ../theme-core/src/styles/shadow.ts
 function generateShadowCssVars(theme) {
 	const level = theme.shadow.elevation;
@@ -6131,6 +6924,214 @@ const originalJoyCardSystem = { variants: [{
 const serifDisplayQuote = { style: "serif-display" };
 /** Punchy quotation mark in the secondary accent colour. Bold / accent styles. */
 const accentGlyphQuote = { style: "accent-glyph" };
+/**
+* Curated library of gradient presets.
+* All gradients use theme color tokens, so they adapt to the site's palette.
+*/
+const GRADIENT_PRESETS = [
+	{
+		id: "primary-secondary",
+		name: "Primary to Secondary",
+		description: "Blend your primary and secondary brand colors",
+		type: "linear",
+		angle: 135,
+		stops: [{
+			color: "primary-500",
+			position: 0
+		}, {
+			color: "secondary-500",
+			position: 100
+		}]
+	},
+	{
+		id: "primary-accent",
+		name: "Primary to Accent",
+		description: "Energetic gradient from primary to accent",
+		type: "linear",
+		angle: 135,
+		stops: [{
+			color: "primary-500",
+			position: 0
+		}, {
+			color: "accent-500",
+			position: 100
+		}]
+	},
+	{
+		id: "secondary-accent",
+		name: "Secondary to Accent",
+		description: "Vibrant secondary to accent blend",
+		type: "linear",
+		angle: 135,
+		stops: [{
+			color: "secondary-500",
+			position: 0
+		}, {
+			color: "accent-500",
+			position: 100
+		}]
+	},
+	{
+		id: "primary-light-dark",
+		name: "Primary Light to Dark",
+		description: "Subtle primary color fade",
+		type: "linear",
+		angle: 180,
+		stops: [{
+			color: "primary-500",
+			position: 0
+		}, {
+			color: "primary-900",
+			position: 100
+		}]
+	},
+	{
+		id: "primary-dark-light",
+		name: "Primary Dark to Light",
+		description: "Reverse primary fade",
+		type: "linear",
+		angle: 180,
+		stops: [{
+			color: "primary-900",
+			position: 0
+		}, {
+			color: "primary-50",
+			position: 100
+		}]
+	},
+	{
+		id: "secondary-light-dark",
+		name: "Secondary Light to Dark",
+		description: "Subtle secondary color fade",
+		type: "linear",
+		angle: 180,
+		stops: [{
+			color: "secondary-500",
+			position: 0
+		}, {
+			color: "secondary-900",
+			position: 100
+		}]
+	},
+	{
+		id: "accent-light-dark",
+		name: "Accent Light to Dark",
+		description: "Accent color depth fade",
+		type: "linear",
+		angle: 180,
+		stops: [{
+			color: "accent-500",
+			position: 0
+		}, {
+			color: "accent-900",
+			position: 100
+		}]
+	},
+	{
+		id: "background-surface",
+		name: "Background to Surface",
+		description: "Subtle depth using base colors",
+		type: "linear",
+		angle: 180,
+		stops: [{
+			color: "background",
+			position: 0
+		}, {
+			color: "surface",
+			position: 100
+		}]
+	},
+	{
+		id: "neutral-fade",
+		name: "Neutral Gradient",
+		description: "Elegant neutral color fade",
+		type: "linear",
+		angle: 180,
+		stops: [{
+			color: "neutral-900",
+			position: 0
+		}, {
+			color: "neutral-50",
+			position: 100
+		}]
+	},
+	{
+		id: "primary-glow",
+		name: "Primary glow",
+		description: "A soft top-centred glow using your primary palette",
+		type: "radial",
+		shape: "ellipse",
+		position: "top center",
+		stops: [{
+			color: "primary-900",
+			position: 0
+		}, {
+			color: "primary-950",
+			position: 100
+		}],
+		foreground: {
+			textColor: "onPrimary900",
+			headingColor: "onPrimary900",
+			linkColor: "onPrimary900",
+			supportingColor: "onPrimary900"
+		}
+	},
+	{
+		id: "accent-glow",
+		name: "Accent glow",
+		description: "A soft top-centred glow using your accent palette",
+		type: "radial",
+		shape: "ellipse",
+		position: "top center",
+		stops: [{
+			color: "accent-900",
+			position: 0
+		}, {
+			color: "accent-950",
+			position: 100
+		}],
+		foreground: {
+			textColor: "onAccent900",
+			headingColor: "onAccent900",
+			linkColor: "onAccent900",
+			supportingColor: "onAccent900"
+		}
+	},
+	{
+		id: "primary-secondary-accent",
+		name: "Brand Trio",
+		description: "All three brand colors in harmony",
+		type: "linear",
+		angle: 135,
+		stops: [
+			{
+				color: "primary-500",
+				position: 0
+			},
+			{
+				color: "secondary-500",
+				position: 50
+			},
+			{
+				color: "accent-500",
+				position: 100
+			}
+		]
+	}
+].map((preset) => ({
+	...preset,
+	id: preset.id,
+	stops: preset.stops
+}));
+const GRADIENT_PRESET_IDS = GRADIENT_PRESETS.map((preset) => preset.id);
+const gradientPresetIdSet = new Set(GRADIENT_PRESET_IDS);
+Object.fromEntries(GRADIENT_PRESETS.map((preset) => [preset.id, preset]));
+function parseGradientPresetId(value) {
+	if (typeof value !== "string") return null;
+	const normalized = value.trim();
+	if (!gradientPresetIdSet.has(normalized)) return null;
+	return normalized;
+}
 //#endregion
 //#region ../theme-core/src/site-styles/headerCtaVariants.ts
 function hasButtonVariant(theme, variantId) {
@@ -6284,7 +7285,7 @@ const overlayLogoAccommodations = [
 * optional nested styling fields that would otherwise leak from another Look.
 */
 function baseHeader(theme) {
-	const { navLinkStyle: _navLinkStyle, navTypography: _navTypography, navTextSize: _navTextSize, dropdownStyle: _dropdownStyle, ctaVariant: _ctaVariant, navContainer: _navContainer, container: _container, shadow: _shadow, logo: _logo, logoText: _logoText, border: _border, ...header } = theme.header;
+	const { navLinkStyle: _navLinkStyle, navFontRole: _navFontRole, navTypography: _navTypography, navTextSize: _navTextSize, dropdownStyle: _dropdownStyle, ctaVariant: _ctaVariant, navContainer: _navContainer, container: _container, shadow: _shadow, logo: _logo, logoText: _logoText, border: _border, ...header } = theme.header;
 	return {
 		...header,
 		navContainer: {
@@ -6433,6 +7434,17 @@ const headerStyleCatalog = defineExactCatalog()([
 		navTypography: "brand-caps",
 		moods: ["expressive"]
 	},
+	{
+		id: asHeaderStyleId("brand-capsule"),
+		label: "Brand Capsule",
+		description: "Solid brand chrome designed as a floating capsule, with quiet-caps nav, a soft pill active state, and an inverted CTA pill.",
+		supportedLayoutIds: supportedLayouts(["classic"]),
+		navInteraction: "pill-background",
+		surface: "brand-solid",
+		defaultDepth: "shadow",
+		navTypography: "quiet-caps",
+		moods: ["expressive", "professional"]
+	},
 	{
 		id: asHeaderStyleId("serif-line"),
 		label: "Serif Line",
@@ -6526,6 +7538,7 @@ const headerStyleCompatibilityOrder = /* @__PURE__ */ new Map([
 		"brand-bar",
 		"brand-underline",
 		"brand-pill",
+		"brand-capsule",
 		"serif-line",
 		"flat-tabs"
 	])],
@@ -6563,6 +7576,11 @@ headerStyleRepairChain([
 	"brand-pill",
 	"brand-bar",
 	"minimal"
+]), headerStyleRepairChain([
+	"brand-capsule",
+	"brand-pill",
+	"brand-bar",
+	"minimal"
 ]), headerStyleRepairChain([
 	"pill-nav",
 	"soft-bar",
@@ -8199,6 +9217,19 @@ asBoundaryOptionId("break:angle-balanced");
 asBoundaryOptionId("break:angle-steep");
 //#endregion
 //#region ../theme-core/src/site-styles/runtimeCompiler.ts
+function defineSectionForegroundRuntimeTokens(input) {
+	return {
+		textColor: requireThemeColorToken(input.textColor),
+		headingColor: requireThemeColorToken(input.headingColor),
+		linkColor: requireThemeColorToken(input.linkColor),
+		supportingColor: requireThemeColorToken(input.supportingColor)
+	};
+}
+function requireThemeColorToken(value) {
+	const token = parseThemeColorToken(value);
+	if (!token) throw new Error(`Invalid section foreground Theme color token: ${String(value)}`);
+	return token;
+}
 function defineDesignRuntimeRules(rules) {
 	return rules;
 }
@@ -8446,24 +9477,24 @@ const kirtanOrnateDesignRuntimeRules = defineDesignRuntimeRules({
 				type: "color",
 				color: "muted"
 			},
-			foreground: {
+			foreground: defineSectionForegroundRuntimeTokens({
 				textColor: "text",
 				headingColor: "primary",
 				linkColor: "primary",
 				supportingColor: "text"
-			}
+			})
 		},
 		"brand-depth-band": {
 			background: {
 				type: "color",
 				color: "primary-800"
 			},
-			foreground: {
+			foreground: defineSectionForegroundRuntimeTokens({
 				textColor: "text",
 				headingColor: "primary",
 				linkColor: "primary",
 				supportingColor: "text"
-			}
+			})
 		},
 		"hero-image": {
 			background: {
@@ -8471,12 +9502,32 @@ const kirtanOrnateDesignRuntimeRules = defineDesignRuntimeRules({
 				opacity: 1,
 				position: "center center"
 			},
-			foreground: {
+			foreground: defineSectionForegroundRuntimeTokens({
 				textColor: "text",
 				headingColor: "primary",
 				linkColor: "primary",
 				supportingColor: "text"
-			}
+			})
+		}
+	}
+});
+const primaryGlowGradientPresetId = parseGradientPresetId("primary-glow");
+if (!primaryGlowGradientPresetId) throw new Error("Expected primary-glow in the Theme Core gradient catalog");
+const fulcrumDesignRuntimeRules = defineDesignRuntimeRules({
+	...defaultDesignRuntimeRules,
+	sectionSurfaces: {
+		...defaultDesignRuntimeRules.sectionSurfaces,
+		"accent-band": {
+			background: {
+				type: "gradient",
+				gradientPresetId: primaryGlowGradientPresetId
+			},
+			foreground: defineSectionForegroundRuntimeTokens({
+				textColor: "primaryForeground",
+				headingColor: "primaryForeground",
+				linkColor: "primaryForeground",
+				supportingColor: "primaryForeground"
+			})
 		}
 	}
 });
@@ -8800,6 +9851,7 @@ const curatedSiteStyles = [
 		],
 		buttonPersonalityChoices: [
 			buttonChoice("soft-pill"),
+			buttonChoice("two-tone-pill"),
 			buttonChoice("pebble"),
 			buttonChoice("editorial-link"),
 			buttonChoice("brushed-wash")
@@ -9863,6 +10915,8 @@ const curatedSiteStyles = [
 		},
 		compositionBudget: quietBudget,
 		typography: fulcrumTypography,
+		designRuntimeRules: fulcrumDesignRuntimeRules,
+		recommendedAppearancePresetIds: ["cta-accent-band"],
 		themeOverrides: {
 			shadow: { colorToken: "primary" },
 			accordions: {
@@ -9979,6 +11033,7 @@ const curatedSiteStyles = [
 		],
 		buttonPersonalityChoices: [
 			buttonChoice("quiet-arrow"),
+			buttonChoice("two-tone-pill"),
 			buttonChoice("flat-ink"),
 			buttonChoice("editorial-link")
 		],
@@ -11938,6 +12993,12 @@ const containerResponsiveThemeCss = `/*
       .rb-lg-hidden {
         display: none;
       }
+      .rb-lg-flex-row {
+        flex-direction: row;
+      }
+      .rb-lg-items-center {
+        align-items: center;
+      }
     }
 
 }
@@ -18447,6 +19508,11 @@ const containerResponsiveThemeCss = `/*
   flex-wrap: wrap;
 }
 
+/* Text-style CTA actions belong to the section foreground contract. */
+:where(.theme-scope) [data-block="cta-full"] .cta-row .button-link {
+  color: var(--rb-surface-link-color, var(--rb-surface-text-color, rgb(var(--tb-primary))));
+}
+
 /* =============================================================================
  * Block: Body Text (content block, Phase 2)
  *
@@ -23374,7 +24440,7 @@ const containerResponsiveThemeCss = `/*
   [data-block="feature-cards"][data-block-composition="asymmetric-emphasis"]
   .rb-feature-card {
   height: auto;
-  overflow: hidden;
+  overflow: visible;
   border: 0;
   border-radius: 0;
   background: transparent;
@@ -24280,8 +25346,12 @@ function buildThemeBridgeRuntime(config) {
 	};
 }
 function buildBridgeCssVars(config) {
+	const tokens = resolveBridgeTokens(config.tokens);
 	return {
-		...buildColorCssVars(resolveBridgeTokens(config.tokens)),
+		...buildColorCssVars({
+			...tokens,
+			...deriveConcreteBridgeOnTokens(tokens)
+		}),
 		...buildTypographyCssVars(config.typography),
 		...buildFontSizeCssVars(),
 		...buildTextRhythmCssVars(),
@@ -24418,6 +25488,41 @@ function resolveBridgeTokens(tokens) {
 	for (const [name, value] of Object.entries(BRIDGE_DEFAULT_TOKENS)) if (!isPresentTokenValue(resolved[name])) resolved[name] = value;
 	return resolved;
 }
+function deriveConcreteBridgeOnTokens(tokens) {
+	const derived = {};
+	for (const [name, value] of Object.entries(tokens)) {
+		if (!isOnColorBackgroundCandidateToken(name)) continue;
+		const hex = rgbChannelsToOpaqueHex(value);
+		if (hex === null) continue;
+		const onToken = onColorTokenName(name);
+		if (tokens[onToken] === void 0) derived[onToken] = hexToRgbChannels(getTextColorForBackground(hex));
+	}
+	return derived;
+}
+function buildBridgeButtonPalette(tokens) {
+	const palette = {};
+	for (const [name, value] of Object.entries(tokens)) {
+		const hex = rgbChannelsToOpaqueHex(value);
+		if (hex !== null) palette[name] = hex;
+	}
+	for (const [name, value] of Object.entries(deriveConcreteBridgeOnTokens(tokens))) {
+		const hex = rgbChannelsToOpaqueHex(value);
+		if (hex !== null) palette[name] = hex;
+	}
+	return {
+		...palette,
+		meta: { mode: "light" }
+	};
+}
+function rgbChannelsToOpaqueHex(value) {
+	const match = value.match(RGB_CHANNELS_PATTERN);
+	if (!match || match[4] !== void 0) return null;
+	return `#${[
+		Number(match[1]),
+		Number(match[2]),
+		Number(match[3])
+	].map((channel) => channel.toString(16).padStart(2, "0")).join("")}`;
+}
 function isPresentTokenValue(value) {
 	return typeof value === "string" && value.trim().length > 0;
 }
@@ -24495,13 +25600,15 @@ function generateButtonsCss(config, corners, shadows) {
 		const requestedIds = new Set(buttonConfig.variants);
 		variants = variants.filter((variant) => requestedIds.has(variant.id));
 	}
-	return generateButtonCoreCss("sdk", variants, {
+	const settings = {
 		corners,
 		shadow: shadows,
 		borderWidth: "thin",
 		fontWeight: 500,
 		textTransform: "none"
-	});
+	};
+	const tokens = resolveBridgeTokens(config.tokens);
+	return generateButtonCoreCss("sdk", variants, settings, buildBridgeButtonPalette(tokens));
 }
 function generateCardsCss(config, corners, shadows) {
 	let variants = getDefaultCardVariants();