@riverbankcms/sdk 0.130.0 → 0.132.0

package/dist/server/theme.mjs

@@ -312,6 +312,25 @@ const nonShadeablePaletteRoleNames = /* @__PURE__ */ new Set([
 	"warning",
 	"destructive"
 ]);
+/**
+* Status role aliases the persisted palette does not carry itself.
+*
+* Generators reference `--tb-error` (the site-style-owned input error border)
+* and `--tb-info` (`.alert-info`, `.status-info`, the field-note rule), but the
+* palette schema only defines `destructive` and has no `info` role at all.
+* Without these aliases those declarations name variables that are never
+* defined and browsers drop them. The SDK bridge resolves the same pair via
+* TOKEN_ALIASES, so both runtimes agree on what a status token means.
+*
+* Runs after the danger → destructive promotion above, so `destructive` is
+* already the single source of truth for the error colour.
+*/
+function statusAliasTokens(expanded) {
+	const aliases = {};
+	if (expanded.destructive) aliases.error = expanded.destructive;
+	if (expanded.accent) aliases.info = expanded.accent;
+	return aliases;
+}
 function expandPalette(palette) {
 	const base = colorsToMap(palette);
 	const expanded = { ...base };
@@ -330,6 +349,7 @@ function expandPalette(palette) {
 	}
 	if (base.text) expanded.body = base.text;
 	if (base.danger && !base.destructive) expanded.destructive = base.danger;
+	Object.assign(expanded, statusAliasTokens(expanded));
 	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 })) {
@@ -763,6 +783,12 @@ const opaqueButtonColourTokenSchema = themeColorTokenSchema.refine((value) => pa
 	if (token === null) throw new Error("Invariant: opaque button token passed its schema");
 	return token;
 });
+const contextualButtonHoverSchema = z.strictObject({
+	kind: z.literal("shade-shift"),
+	seedToken: opaqueButtonColourTokenSchema,
+	fallbackDirection: z.enum(["lighter", "darker"]),
+	preferredToken: opaqueButtonColourTokenSchema.optional()
+});
 const buttonShadeAmountSchema = z.number().finite().min(0).max(900).multipleOf(100);
 const buttonShadowIntensitySchema = z.enum([
 	"subtle",
@@ -1102,6 +1128,7 @@ const buttonVariantSchema = z.strictObject({
 	shadow: variantShadowSchema.optional(),
 	border: buttonBorderSchema.optional(),
 	hoverBackgroundToken: opaqueButtonColourTokenSchema.optional(),
+	contextualHover: contextualButtonHoverSchema.optional(),
 	effects: variantEffectsSchema.optional(),
 	sizes: variantSizeOverridesSchema.optional(),
 	affordance: buttonVariantAffordanceSchema.optional()
@@ -1341,6 +1368,139 @@ function validateButtonTextContrast(input) {
 	};
 }
 //#endregion
+//#region ../theme-core/src/buttons/contextualHover.ts
+function resolveContextualHoverPreference(input) {
+	const preferred = input.instruction.preferredToken;
+	if (preferred && isSafeCandidate(preferred, input.palette, input.surface)) return {
+		kind: "resolved",
+		token: preferred,
+		repair: null
+	};
+	const contextual = resolveContextualHover(input);
+	return contextual.kind === "resolved" ? {
+		kind: "resolved",
+		token: contextual.token,
+		repair: preferred ? {
+			kind: "preferred-token-replaced",
+			preferredToken: preferred,
+			contextualToken: contextual.token
+		} : null
+	} : contextual;
+}
+/**
+* Resolves semantic shade movement from real palette steps. The persisted
+* instruction owns the colour family and deterministic unknown-surface
+* fallback; a proven surface may select the opposite direction when it gives
+* the button stronger separation while retaining the shared contrast contract.
+*/
+function resolveContextualHover(input) {
+	const candidates = shadeCandidates(input.instruction.seedToken, input.palette);
+	if (candidates.length === 0) return {
+		kind: "unavailable",
+		reason: "no-distinct-shade"
+	};
+	const textSafe = candidates.filter((candidate) => hasSafeTextContrast(candidate.token, input.palette));
+	if (textSafe.length === 0) return {
+		kind: "unavailable",
+		reason: "no-text-safe-candidate"
+	};
+	if (!input.surface) {
+		const selected = textSafe.find((candidate) => candidate.direction === input.instruction.fallbackDirection) ?? textSafe[0];
+		return selected ? {
+			kind: "resolved",
+			token: selected.token,
+			direction: selected.direction,
+			evidence: "fallback-direction"
+		} : {
+			kind: "unavailable",
+			reason: "no-text-safe-candidate"
+		};
+	}
+	const selected = textSafe.map((candidate) => ({
+		...candidate,
+		surfaceContrast: contrastRatio(input.palette[candidate.token] ?? "", input.surface?.backgroundHex ?? "")
+	})).filter((candidate) => candidate.surfaceContrast !== null && candidate.surfaceContrast >= BUTTON_CONTRAST_POLICY.nonTextMinimumRatio).sort((left, right) => {
+		const distanceDifference = left.distance - right.distance;
+		if (distanceDifference !== 0) return distanceDifference;
+		const contrastDifference = (right.surfaceContrast ?? 0) - (left.surfaceContrast ?? 0);
+		if (contrastDifference !== 0) return contrastDifference;
+		if (left.direction === right.direction) return left.token.localeCompare(right.token);
+		return left.direction === input.instruction.fallbackDirection ? -1 : 1;
+	})[0];
+	return selected ? {
+		kind: "resolved",
+		token: selected.token,
+		direction: selected.direction,
+		evidence: "known-surface"
+	} : {
+		kind: "unavailable",
+		reason: "no-surface-safe-candidate"
+	};
+}
+function shadeCandidates(seedToken, palette) {
+	const match = String(seedToken).match(/^(.*?)(?:-(\d{2,3}))?$/);
+	const family = match?.[1] ?? String(seedToken);
+	const currentShade = match?.[2] ? Number(match[2]) : 500;
+	const seedHex = palette[seedToken];
+	const shades = Object.keys(palette).flatMap((token) => {
+		const shade = token.match(new RegExp(`^${escapeRegExp(family)}-(\\d{2,3})$`));
+		return shade?.[1] ? [Number(shade[1])] : [];
+	}).filter((shade) => Number.isFinite(shade)).sort((left, right) => left - right);
+	const lower = [...shades].filter((shade) => shade < currentShade).sort((left, right) => right - left);
+	const higher = shades.filter((shade) => shade > currentShade);
+	return [...lower.map((shade) => candidate(family, shade, currentShade, "lighter", seedHex, palette)), ...higher.map((shade) => candidate(family, shade, currentShade, "darker", seedHex, palette))].filter((value) => value !== null);
+}
+function candidate(family, shade, currentShade, direction, seedHex, palette) {
+	const token = parseOpaqueButtonColourToken(`${family}-${shade}`);
+	if (token === null) return null;
+	const candidateHex = palette[token];
+	if (!candidateHex || candidateHex === seedHex) return null;
+	return {
+		token,
+		direction,
+		distance: Math.abs(shade - currentShade),
+		surfaceContrast: null
+	};
+}
+function hasSafeTextContrast(token, palette) {
+	const background = palette[token];
+	const foreground = palette[onColorTokenName(token)];
+	return typeof background === "string" && typeof foreground === "string" && contrastRatio(background, foreground) >= BUTTON_CONTRAST_POLICY.textMinimumRatio;
+}
+function isSafeCandidate(token, palette, surface) {
+	if (!hasSafeTextContrast(token, palette)) return false;
+	return surface ? contrastRatio(palette[token] ?? "", surface.backgroundHex) >= BUTTON_CONTRAST_POLICY.nonTextMinimumRatio : true;
+}
+function escapeRegExp(value) {
+	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+//#endregion
+//#region ../theme-core/src/buttons/resolveButtonHoverTreatment.ts
+function resolveButtonHoverTreatment(input) {
+	if (input.variant.contextualHover) {
+		const contextual = resolveContextualHoverPreference({
+			instruction: input.variant.contextualHover,
+			palette: input.palette,
+			surface: input.surface
+		});
+		if (contextual.kind === "resolved") return {
+			treatment: {
+				type: "solid",
+				colorToken: contextual.token
+			},
+			repair: contextual.repair
+		};
+	}
+	const token = input.variant.hoverBackgroundToken ?? (input.global.hoverColor === "token" ? input.global.hoverColorToken : void 0);
+	return {
+		treatment: token === void 0 ? input.fallback : {
+			type: "solid",
+			colorToken: token
+		},
+		repair: null
+	};
+}
+//#endregion
 //#region ../theme-core/src/buttons/resolveButtonColourStates.ts
 function compileButtonColourStates(input) {
 	const baseTransition = applyColourEffects({
@@ -1351,9 +1511,16 @@ function compileButtonColourStates(input) {
 		palette: input.palette
 	});
 	if (!baseTransition.ok) return baseTransition;
+	const hover = resolveButtonHoverTreatment({
+		variant: input.variant,
+		global: input.global,
+		fallback: baseTransition.treatment,
+		palette: input.palette,
+		surface: input.surface
+	});
 	const stateTreatments = {
 		base: baseTransition.treatment,
-		hover: hoverTreatment(input.variant, input.global, baseTransition.treatment),
+		hover: hover.treatment,
 		focus: baseTransition.treatment,
 		active: baseTransition.treatment,
 		disabled: baseTransition.treatment
@@ -1392,14 +1559,8 @@ function compileButtonColourStates(input) {
 		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
+		nonColourEffects,
+		contextualHoverRepair: hover.repair
 	};
 }
 function applyColourEffects(input) {
@@ -1813,13 +1974,7 @@ const tokenOrCssColorValueSchema = z.string();
 buttonSizeNameSchema.options;
 //#endregion
 //#region ../theme-core/src/buttons/styles/domain.ts
-const PUBLIC_BUTTON_ROLES = [
-	"primary",
-	"secondary",
-	"outline",
-	"ghost",
-	"accent"
-];
+const PUBLIC_BUTTON_ROLES = VARIANT_ROLES;
 function defineButtonStyleRecipe(recipe) {
 	return recipe;
 }
@@ -1915,6 +2070,14 @@ const BUTTON_STYLE_IDS = [
 	"quiet-arrow"
 ];
 const quietArrowParametersSchema = z.object({ secondaryTreatment: z.enum(["outlined", "solid-accent"]) }).strict();
+const flatInkHoverTreatmentSchema = z.enum([
+	"contextual",
+	"secondary",
+	"accent"
+]);
+const flatInkHoverPreferencesShape = Object.fromEntries(VARIANT_ROLES.map((role) => [role, flatInkHoverTreatmentSchema.optional()]));
+const flatInkHoverPreferencesSchema = z.strictObject(flatInkHoverPreferencesShape);
+const flatInkParametersSchema = z.strictObject({ hoverPreferences: flatInkHoverPreferencesSchema.optional() });
 const emptyParametersSchema$1 = z.object({}).strict();
 function selectionBranch(styleId, parameters) {
 	return z.object({
@@ -1929,7 +2092,7 @@ z.discriminatedUnion("styleId", [
 	selectionBranch("editorial-link", emptyParametersSchema$1),
 	selectionBranch("pebble", emptyParametersSchema$1),
 	selectionBranch("ink-stamp", emptyParametersSchema$1),
-	selectionBranch("flat-ink", emptyParametersSchema$1),
+	selectionBranch("flat-ink", flatInkParametersSchema),
 	selectionBranch("brushed-wash", emptyParametersSchema$1),
 	selectionBranch("showtime-pill", emptyParametersSchema$1),
 	selectionBranch("joy-stamp", emptyParametersSchema$1),
@@ -2066,6 +2229,189 @@ const quietArrowRecipe = defineButtonStyleRecipe({
 	})
 });
 //#endregion
+//#region ../theme-core/src/buttons/styles/recipes/flatInk.ts
+const contextualRoleConfig = {
+	primary: {
+		contextualSeedToken: unsafeAsOpaqueButtonColourToken("primary"),
+		fallbackDirection: "darker"
+	},
+	secondary: {
+		contextualSeedToken: unsafeAsOpaqueButtonColourToken("surfaceAlt"),
+		fallbackDirection: "darker"
+	},
+	outline: {
+		contextualSeedToken: unsafeAsOpaqueButtonColourToken("surfaceAlt"),
+		fallbackDirection: "darker"
+	},
+	ghost: {
+		contextualSeedToken: unsafeAsOpaqueButtonColourToken("surfaceAlt"),
+		fallbackDirection: "darker"
+	},
+	accent: {
+		contextualSeedToken: unsafeAsOpaqueButtonColourToken("accent"),
+		fallbackDirection: "darker"
+	}
+};
+const hoverControl = {
+	kind: "button-hover-by-role",
+	parameter: "hoverPreferences",
+	label: "Button hover",
+	roles: contextualRoleConfig,
+	options: [
+		{
+			value: "contextual",
+			label: "Contextual shade shift"
+		},
+		{
+			value: "secondary",
+			label: "Secondary button colour"
+		},
+		{
+			value: "accent",
+			label: "Accent button colour"
+		}
+	]
+};
+const lift = { effectId: "lift" };
+const flatInkRecipe = defineButtonStyleRecipe({
+	id: "flat-ink",
+	accessibilityLabel: "Flat rounded buttons with arrow affordances",
+	tags: {
+		tone: "classic",
+		energy: "calm",
+		motion: "subtle",
+		era: "editorial"
+	},
+	parameterSchema: flatInkParametersSchema,
+	defaultParameters: {},
+	controls: [hoverControl],
+	defineSystem: (parameters) => ({
+		global: {
+			cornerStyle: "rounded",
+			textTransform: "none",
+			fontWeight: 600,
+			typography: "body",
+			letterSpacing: "tight",
+			paddingPreset: "default",
+			hoverTransform: "lift",
+			hoverColor: "none"
+		},
+		sizes: {
+			sm: {
+				padding: "0.625rem 1.125rem",
+				fontSize: "text-sm"
+			},
+			md: { padding: "0.8125rem 1.375rem" },
+			lg: {
+				padding: "0.9375rem 1.625rem",
+				fontSize: "text-lg"
+			},
+			xl: {
+				padding: "1.0625rem 2rem",
+				fontSize: "text-xl"
+			}
+		},
+		roles: {
+			primary: {
+				kind: "complete",
+				appearance: {
+					background: {
+						type: "solid",
+						colorToken: unsafeAsOpaqueButtonColourToken("primary")
+					},
+					borderRadius: "rounded-lg",
+					affordance: { iconId: "ArrowRight" },
+					...hoverAppearance("primary", parameters, [lift, {
+						effectId: "background-on-hover",
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("secondary") }
+					}])
+				}
+			},
+			secondary: {
+				kind: "complete",
+				appearance: {
+					background: {
+						type: "surface",
+						role: "link"
+					},
+					borderRadius: "rounded-lg",
+					border: { widthClass: "border" },
+					...hoverAppearance("secondary", parameters, [lift, {
+						effectId: "background-on-hover",
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
+					}])
+				}
+			},
+			outline: {
+				kind: "complete",
+				appearance: {
+					background: {
+						type: "surface",
+						role: "link"
+					},
+					borderRadius: "rounded-lg",
+					border: { widthClass: "border" },
+					...hoverAppearance("outline", parameters, [lift, {
+						effectId: "background-on-hover",
+						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
+					}])
+				}
+			},
+			ghost: {
+				kind: "complete",
+				appearance: {
+					background: {
+						type: "surface",
+						role: "link"
+					},
+					borderRadius: "rounded-lg",
+					...hoverAppearance("ghost", parameters, [lift])
+				}
+			},
+			accent: {
+				kind: "complete",
+				appearance: {
+					background: {
+						type: "solid",
+						colorToken: unsafeAsOpaqueButtonColourToken("accent")
+					},
+					borderRadius: "rounded-lg",
+					affordance: { iconId: "ArrowRight" },
+					...hoverAppearance("accent", parameters, [lift])
+				}
+			}
+		}
+	})
+});
+function hoverAppearance(role, parameters, recommended) {
+	const preference = parameters.hoverPreferences?.[role];
+	if (preference === void 0) return { effects: { hover: [...recommended] } };
+	if (preference === "contextual") {
+		const config = contextualRoleConfig[role];
+		return {
+			effects: { hover: [lift] },
+			contextualHover: {
+				kind: "shade-shift",
+				seedToken: config.contextualSeedToken,
+				fallbackDirection: config.fallbackDirection
+			}
+		};
+	}
+	const config = contextualRoleConfig[role];
+	return {
+		effects: { hover: [lift] },
+		contextualHover: {
+			kind: "shade-shift",
+			seedToken: config.contextualSeedToken,
+			fallbackDirection: config.fallbackDirection,
+			preferredToken: unsafeAsOpaqueButtonColourToken(paletteRole(preference))
+		}
+	};
+}
+function paletteRole(preference) {
+	return preference;
+}
+//#endregion
 //#region ../theme-core/src/buttons/styles/recipes/defineStaticButtonStyleRecipe.ts
 const emptyParametersSchema = z.object({}).strict();
 function defineStaticButtonStyleRecipe(input) {
@@ -2912,113 +3258,6 @@ const inkStampRecipe = defineStaticButtonStyleRecipe({
 		}
 	}
 });
-const flatInkRecipe = defineStaticButtonStyleRecipe({
-	id: "flat-ink",
-	accessibilityLabel: "Flat rounded buttons with arrow affordances",
-	tags: {
-		tone: "classic",
-		energy: "calm",
-		motion: "subtle",
-		era: "editorial"
-	},
-	system: {
-		global: {
-			cornerStyle: "rounded",
-			textTransform: "none",
-			fontWeight: 600,
-			typography: "body",
-			letterSpacing: "tight",
-			paddingPreset: "default",
-			hoverTransform: "lift",
-			hoverColor: "none"
-		},
-		sizes: {
-			sm: {
-				padding: "0.625rem 1.125rem",
-				fontSize: "text-sm"
-			},
-			md: { padding: "0.8125rem 1.375rem" },
-			lg: {
-				padding: "0.9375rem 1.625rem",
-				fontSize: "text-lg"
-			},
-			xl: {
-				padding: "1.0625rem 2rem",
-				fontSize: "text-xl"
-			}
-		},
-		roles: {
-			primary: {
-				kind: "complete",
-				appearance: {
-					background: {
-						type: "solid",
-						colorToken: "primary"
-					},
-					borderRadius: "rounded-lg",
-					affordance: { iconId: "ArrowRight" },
-					effects: { hover: [{ effectId: "lift" }, {
-						effectId: "background-on-hover",
-						options: { colorToken: unsafeAsOpaqueButtonColourToken("secondary") }
-					}] }
-				}
-			},
-			secondary: {
-				kind: "complete",
-				appearance: {
-					background: {
-						type: "surface",
-						role: "link"
-					},
-					borderRadius: "rounded-lg",
-					border: { widthClass: "border" },
-					effects: { hover: [{ effectId: "lift" }, {
-						effectId: "background-on-hover",
-						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
-					}] }
-				}
-			},
-			outline: {
-				kind: "complete",
-				appearance: {
-					background: {
-						type: "surface",
-						role: "link"
-					},
-					borderRadius: "rounded-lg",
-					border: { widthClass: "border" },
-					effects: { hover: [{ effectId: "lift" }, {
-						effectId: "background-on-hover",
-						options: { colorToken: unsafeAsOpaqueButtonColourToken("surfaceAlt") }
-					}] }
-				}
-			},
-			ghost: {
-				kind: "complete",
-				appearance: {
-					background: {
-						type: "surface",
-						role: "link"
-					},
-					borderRadius: "rounded-lg",
-					effects: { hover: [{ effectId: "lift" }] }
-				}
-			},
-			accent: {
-				kind: "complete",
-				appearance: {
-					background: {
-						type: "solid",
-						colorToken: "accent"
-					},
-					borderRadius: "rounded-lg",
-					affordance: { iconId: "ArrowRight" },
-					effects: { hover: [{ effectId: "lift" }] }
-				}
-			}
-		}
-	}
-});
 const showtimePillRecipe = defineStaticButtonStyleRecipe({
 	id: "showtime-pill",
 	accessibilityLabel: "Bold uppercase pill buttons with playful movement",
@@ -3433,6 +3672,26 @@ function presetCategory(recipe) {
 //#region ../theme-core/src/cards/types.ts
 const cardVariantRoleValues = ["default", "alternative"];
 const boxlessCardVariantValue = "none";
+const openCardRoleValue = "open";
+/**
+* The roles a site style implements with an actual card variant. `none` is
+* deliberately absent: it is a role value only, never a variant.
+*/
+const surfaceCardRoleValues = [...cardVariantRoleValues, openCardRoleValue];
+/**
+* The closed role vocabulary Looks and blocks use for surfaced and boxless
+* card choices.
+*
+* - `none`        — no site-style card surface; the block's own composition and
+*                   the author's own card fields govern the item. This is *not*
+*                   a promise of visible boxlessness: a block whose base class
+*                   draws a border still draws one. It says the Look is not
+*                   asking the site style for a card.
+* - `open`        — boxless but marked (a rule or accent edge, no enclosing box)
+* - `default`     — the site's quiet everyday card
+* - `alternative` — the statement card carrying the site's personality
+*/
+const cardRoleValues = [...surfaceCardRoleValues, boxlessCardVariantValue];
 const cardSpacingSchema = z.enum([
 	"none",
 	"compact",
@@ -3441,6 +3700,17 @@ const cardSpacingSchema = z.enum([
 	"comfortable",
 	"spacious"
 ]);
+/** Per-axis padding, for boxless cards whose inline padding differs from block. */
+const cardSpacingAxesSchema = z.object({
+	block: cardSpacingSchema,
+	inline: cardSpacingSchema
+});
+/**
+* A card's content padding: one value for both axes, or one per axis. Two
+* fields would let a variant say both and leave the reader to guess, so this is
+* a union — the legacy `spacingAxes` key is lifted into it on parse.
+*/
+const cardSpacingValueSchema = z.union([cardSpacingSchema, cardSpacingAxesSchema]);
 const gradientDirectionSchema = z.enum([
 	"to-r",
 	"to-l",
@@ -3452,7 +3722,21 @@ const gradientDirectionSchema = z.enum([
 	"to-bl"
 ]);
 z.enum(cardVariantRoleValues);
-const boxStylesCardVariantSchema = z.enum([...cardVariantRoleValues, boxlessCardVariantValue]);
+const surfaceCardRoleSchema = z.enum(surfaceCardRoleValues);
+const cardRoleSchema = z.enum(cardRoleValues);
+const PRIORITY_ROLE_INFERENCE = {
+	1: "default",
+	2: "alternative"
+};
+/**
+* Role inference for legacy card systems authored before variants carried a
+* `role`. Priority 1 is the everyday card, priority 2 the statement card —
+* which is how variants are surfaced today. `open` is never inferred: a site
+* style has to opt into it.
+*/
+function inferCardVariantRoleFromPriority(priority) {
+	return PRIORITY_ROLE_INFERENCE[priority] ?? null;
+}
 const cardBackgroundSchema = z.discriminatedUnion("type", [
 	z.object({
 		type: z.literal("solid"),
@@ -3478,17 +3762,19 @@ const cardCornerValueSchema = z.enum([
 	"pill",
 	"expressive"
 ]);
+const cardEdgeSchema = z.enum([
+	"left",
+	"top",
+	"right",
+	"bottom"
+]);
 /**
-* A single accented card edge (e.g. a left accent bar). When set, it replaces
-* the full `border` so the card reads as edge-accented rather than outlined.
+* Legacy single accented card edge (e.g. a left accent bar). Persisted and
+* curated data may still carry it; it lifts into a one-element `decorations`
+* list at the parse boundary and has no representation after that.
 */
 const cardAccentEdgeSchema = z.object({
-	edge: z.enum([
-		"left",
-		"top",
-		"right",
-		"bottom"
-	]),
+	edge: cardEdgeSchema,
 	colorToken: themeColorTokenSchema,
 	width: z.enum([
 		"thin",
@@ -3497,13 +3783,43 @@ const cardAccentEdgeSchema = z.object({
 		"heavy"
 	])
 });
+/** `hairline` (1px) is the widening the boxless `open` role needs. */
+const cardEdgeRuleWidthSchema = z.enum([
+	"hairline",
+	"thin",
+	"medium",
+	"thick",
+	"heavy"
+]);
+const cardEdgeRuleLengthSchema = z.enum(["full", "short"]);
+const cardEdgeRuleAlignSchema = z.enum([
+	"start",
+	"center",
+	"end"
+]);
+/**
+* Decorations are edge rules today. The alias exists so the list can grow into
+* a discriminated union without every call site changing.
+*/
+const cardDecorationSchema = z.object({
+	edge: cardEdgeSchema,
+	colorToken: themeColorTokenSchema,
+	width: cardEdgeRuleWidthSchema,
+	/** Defaults to `full`. */
+	length: cardEdgeRuleLengthSchema.optional(),
+	/** Where a `short` rule sits along its edge. Defaults to `start`. */
+	align: cardEdgeRuleAlignSchema.optional(),
+	/** Opacity applied to `colorToken`, 0–1. Scoped here, not on the token. */
+	alpha: z.number().min(0).max(1).optional()
+});
+const cardDecorationsSchema = z.array(cardDecorationSchema).max(2);
 const cardCornerRadiiSchema = z.object({
 	topLeft: cardCornerValueSchema.optional(),
 	topRight: cardCornerValueSchema.optional(),
 	bottomLeft: cardCornerValueSchema.optional(),
 	bottomRight: cardCornerValueSchema.optional()
 });
-const cardVariantSchema = z.object({
+const cardVariantInputSchema = z.object({
 	id: z.string(),
 	name: z.string().min(1).max(20),
 	enabled: z.boolean(),
@@ -3512,8 +3828,10 @@ const cardVariantSchema = z.object({
 		z.literal(2),
 		z.literal(3)
 	]),
+	role: surfaceCardRoleSchema.optional(),
 	background: cardBackgroundSchema,
-	spacing: cardSpacingSchema,
+	spacing: cardSpacingValueSchema,
+	spacingAxes: cardSpacingAxesSchema.optional(),
 	foregroundToken: themeColorTokenSchema.optional(),
 	shadow: z.object({
 		elevation: z.enum([
@@ -3537,9 +3855,91 @@ const cardVariantSchema = z.object({
 	]).optional(),
 	cornerRadii: cardCornerRadiiSchema.optional(),
 	border: cardBorderSchema.optional(),
+	decorations: cardDecorationsSchema.optional(),
 	accentEdge: cardAccentEdgeSchema.optional()
 });
-const cardSystemSchema = z.object({ variants: z.array(cardVariantSchema).min(1).max(3) });
+/**
+* Lift a legacy `accentEdge` into the decoration list. The old emitter reset
+* `border: 0` implicitly whenever an accent edge was present; conversion drops
+* the border instead, so the output is unchanged and the data says so.
+*/
+function normalizeLegacyAccentEdge(variant) {
+	const { accentEdge, ...rest } = normalizeLegacySpacingAxes(variant);
+	if (!accentEdge) return rest;
+	const { border: _droppedByAccentEdgeReset, ...withoutBorder } = rest;
+	return {
+		...withoutBorder,
+		decorations: [{
+			...accentEdge,
+			length: "full"
+		}]
+	};
+}
+/**
+* Lift a legacy `spacingAxes` into `spacing`. It always won over the flat value
+* when both were set, so the lift preserves the emitted padding exactly.
+*/
+function normalizeLegacySpacingAxes(variant) {
+	const { spacingAxes, ...rest } = variant;
+	return spacingAxes ? {
+		...rest,
+		spacing: spacingAxes
+	} : variant;
+}
+function validateSingleDecorationSource(variant, ctx) {
+	if (!variant.accentEdge || !variant.decorations) return;
+	ctx.addIssue({
+		code: "custom",
+		path: ["decorations"],
+		message: "A card variant carries either the legacy `accentEdge` or `decorations`, never both."
+	});
+}
+const cardVariantSchema = cardVariantInputSchema.superRefine(validateSingleDecorationSource).transform(normalizeLegacyAccentEdge);
+/**
+* Fill in roles for legacy systems whose variants declare none. Inference is
+* collision-tolerant on purpose: first claimant wins and a later variant that
+* would infer a taken role simply gets no role. Legacy data is not obliged to
+* be well-formed, and a card system that fails to parse takes the whole theme
+* down with it.
+*/
+function withInferredRoles(variants) {
+	const claimed = new Set(variants.flatMap((variant) => variant.role ? [variant.role] : []));
+	return variants.map((variant) => {
+		if (variant.role) return variant;
+		const inferred = inferCardVariantRoleFromPriority(variant.priority);
+		if (!inferred || claimed.has(inferred)) return variant;
+		claimed.add(inferred);
+		return {
+			...variant,
+			role: inferred
+		};
+	});
+}
+/**
+* Only *declared* roles are validated — a site style saying "these two
+* variants are both the default card" is an authoring error worth rejecting.
+*/
+function validateUniqueDeclaredCardVariantRoles(system, ctx) {
+	const declared = /* @__PURE__ */ new Set();
+	system.variants.forEach((variant, index) => {
+		const role = variant.role;
+		if (!role) return;
+		if (declared.has(role)) {
+			ctx.addIssue({
+				code: "custom",
+				path: [
+					"variants",
+					index,
+					"role"
+				],
+				message: `Card role "${role}" is already implemented by another variant.`
+			});
+			return;
+		}
+		declared.add(role);
+	});
+}
+const cardSystemSchema = z.object({ variants: z.array(cardVariantSchema).min(1).max(3) }).superRefine(validateUniqueDeclaredCardVariantRoles).transform((system) => ({ variants: withInferredRoles(system.variants) }));
 //#endregion
 //#region ../theme-core/src/accordions/types.ts
 /**
@@ -4352,6 +4752,58 @@ new Set(themeV2NormalEditorRawStyleFieldNames);
 [...themeV2RuntimeStyleFieldNames, ...themeV2BlockSpecificRawStyleFieldNames];
 const pageDesignEditorBackgroundOverrideOwner = "page-design-editor";
 const siteChromeBackgroundOverrideOwner = "site-chrome-editor";
+//#endregion
+//#region ../theme-core/src/header/legacyHeaderVariant.ts
+/**
+* The header variants the system actually renders.
+*
+* Each one has a layout row in the site-header block and a paint target in
+* `paintTargets.ts`. This is the canonical list: the block transform's variant
+* class allowlist and the AI theme generator's enum both derive from it, so
+* they cannot drift.
+*/
+const headerVariantValues = [
+	"classic",
+	"centered",
+	"floating"
+];
+z.enum(headerVariantValues);
+/**
+* Header variant spellings that were once authorable but no longer name a
+* layout of their own, and the variant they read as now.
+*
+* `transparent` was an overlay header with no CSS of its own: everything it
+* did (transparent root background, overlay content flow) is what `floating`
+* already does, and it had zero persisted usage in production or locally when
+* it was retired. It survives here as a one-boundary alias so a theme authored
+* against the old vocabulary still parses.
+*
+* This matters because the theme schema is strict and has no per-field
+* `.catch()`: an out-of-enum variant fails `themeSchema.safeParse` for the
+* *whole* theme, which silently swaps the site's theme for
+* `modernMinimalTheme`. Aliasing here keeps that from happening.
+*/
+const legacyHeaderVariants = { transparent: "floating" };
+const legacyHeaderVariantValues = Object.keys(legacyHeaderVariants);
+/**
+* The header variant boundary for themes that go through `themeSchema`:
+* canonical variants pass through, legacy spellings normalize to the variant
+* they meant, everything else fails the parse.
+*
+* Deliberately an enum plus a transform rather than a `z.preprocess`, so the
+* schema's *input* type stays an accurate union (the legacy spelling is still
+* accepted on the wire) instead of widening to `unknown`. `SdkThemeWire` in
+* `@riverbankcms/api` is `z.input<typeof themeSchema>`, so a widened input here
+* would leak straight into a public type.
+*
+* Not every read of a persisted theme goes through the schema:
+* `resolveRuntimeTheme` in
+* `apps/dashboard/src/server/services/sites/runtimeSiteResponse.ts` returns the
+* raw database JSON asserted as `Theme` with no parse, so a theme still
+* carrying a legacy spelling reaches the theme editor un-aliased. That gap
+* predates this alias and is harmless while persisted usage is zero.
+*/
+const headerVariantWithLegacyAliasSchema = z.enum([...headerVariantValues, ...legacyHeaderVariantValues]).transform((value) => value in legacyHeaderVariants ? legacyHeaderVariants[value] : value);
 const BREAKPOINT_LG = 1024;
 const BREAKPOINT_XL = 1280;
 const BREAKPOINT_LG_DOWN = BREAKPOINT_LG - 1;
@@ -4668,15 +5120,7 @@ const cardStylesOverrideSchema = z.object({
 	spacing: semanticSpacingSchema.nullable().optional(),
 	raised: z.boolean().nullable().optional(),
 	rounded: boxRoundedSchema.nullable().optional(),
-	treatment: z.enum([
-		"accent-quote",
-		"editorial-rule",
-		"soft-panel",
-		"editorial-serif-quote",
-		"editorial-open",
-		"color-blocked"
-	]).nullable().optional(),
-	cardVariant: boxStylesCardVariantSchema.nullable().optional()
+	role: cardRoleSchema.nullable().optional()
 });
 const blockStyleOverridesSchema = z.object({
 	sectionStyles: sectionStylesOverrideSchema.nullable().optional(),
@@ -4781,30 +5225,6 @@ const motion = z.object({
 	]).nullable()
 });
 z.object({ shape: corners });
-z.object({
-	elevation: z.enum([
-		"none",
-		"low",
-		"medium",
-		"high"
-	]),
-	border: z.enum([
-		"none",
-		"subtle",
-		"defined"
-	]),
-	shape: corners,
-	headerStyle: z.enum([
-		"plain",
-		"accentBar",
-		"subtleBg"
-	]).nullable(),
-	mediaTreatment: z.enum([
-		"square",
-		"rounded",
-		"bleed"
-	]).nullable()
-});
 const inputStyle = z.object({
 	shape: corners,
 	border: z.enum([
@@ -4819,12 +5239,6 @@ const inputStyle = z.object({
 	]),
 	label: z.enum(["inside", "above"])
 });
-const headerVariant = z.enum([
-	"classic",
-	"centered",
-	"transparent",
-	"floating"
-]);
 const headerPositioning = z.enum([
 	"static",
 	"sticky",
@@ -4968,7 +5382,7 @@ const headerBackgroundSchema = z.object({
 	textColor: tokenOrCssColorValueSchema.nullable().optional()
 });
 const headerSchema = z.object({
-	variant: headerVariant,
+	variant: headerVariantWithLegacyAliasSchema,
 	positioning: headerPositioning,
 	shrinkOnScroll: z.boolean(),
 	maxWidth: headerMaxWidth,