@nationaldesignstudio/react 0.0.15 → 0.0.16

package/src/lib/theme.ts

@@ -0,0 +1,1000 @@
+/**
+ * Component-level theming interface
+ *
+ * This interface defines all the customizable design tokens that can be
+ * overridden at the component level. Components accepting a `theme` prop
+ * will apply these values as CSS custom properties, allowing fine-grained
+ * control over appearance without creating new variants.
+ *
+ * All values use primitive token names (e.g., "gray-100", "spacing-40")
+ * which are converted to CSS variable references internally.
+ */
+
+// =============================================================================
+// Token Name Types
+// =============================================================================
+
+/**
+ * Color token names - maps to `--color-{name}` CSS variables
+ * @example "gray-100", "ember-v300", "alpha-black-10"
+ */
+export type ColorToken =
+	// Grayscale
+	| "gray-50"
+	| "gray-100"
+	| "gray-200"
+	| "gray-300"
+	| "gray-400"
+	| "gray-500"
+	| "gray-600"
+	| "gray-700"
+	| "gray-800"
+	| "gray-900"
+	| "gray-1000"
+	| "gray-1100"
+	| "gray-1200"
+	// Steel
+	| "steel-50"
+	| "steel-100"
+	| "steel-200"
+	| "steel-300"
+	| "steel-400"
+	| "steel-500"
+	| "steel-600"
+	| "steel-700"
+	| "steel-800"
+	| "steel-900"
+	| "steel-1000"
+	| "steel-1100"
+	| "steel-1200"
+	// Brown
+	| "brown-50"
+	| "brown-100"
+	| "brown-200"
+	| "brown-300"
+	| "brown-400"
+	| "brown-500"
+	| "brown-600"
+	| "brown-700"
+	| "brown-800"
+	| "brown-900"
+	| "brown-1000"
+	| "brown-1100"
+	| "brown-1200"
+	// Ember
+	| "ember-50"
+	| "ember-100"
+	| "ember-200"
+	| "ember-300"
+	| "ember-400"
+	| "ember-500"
+	| "ember-600"
+	| "ember-700"
+	| "ember-800"
+	| "ember-900"
+	| "ember-v100"
+	| "ember-v200"
+	| "ember-v300"
+	| "ember-v400"
+	// Orange
+	| "orange-50"
+	| "orange-100"
+	| "orange-200"
+	| "orange-300"
+	| "orange-400"
+	| "orange-500"
+	| "orange-600"
+	| "orange-700"
+	| "orange-800"
+	| "orange-900"
+	| "orange-v100"
+	| "orange-v200"
+	| "orange-v300"
+	| "orange-v400"
+	// Amber
+	| "amber-50"
+	| "amber-100"
+	| "amber-200"
+	| "amber-300"
+	| "amber-400"
+	| "amber-500"
+	| "amber-600"
+	| "amber-700"
+	| "amber-800"
+	| "amber-900"
+	| "amber-v100"
+	| "amber-v200"
+	| "amber-v300"
+	| "amber-v400"
+	// Yellow
+	| "yellow-50"
+	| "yellow-100"
+	| "yellow-200"
+	| "yellow-300"
+	| "yellow-400"
+	| "yellow-500"
+	| "yellow-600"
+	| "yellow-700"
+	| "yellow-800"
+	| "yellow-900"
+	| "yellow-v100"
+	| "yellow-v200"
+	| "yellow-v300"
+	| "yellow-v400"
+	// Lime
+	| "lime-50"
+	| "lime-100"
+	| "lime-200"
+	| "lime-300"
+	| "lime-400"
+	| "lime-500"
+	| "lime-600"
+	| "lime-700"
+	| "lime-800"
+	| "lime-900"
+	| "lime-v100"
+	| "lime-v200"
+	| "lime-v300"
+	| "lime-v400"
+	// Green
+	| "green-50"
+	| "green-100"
+	| "green-200"
+	| "green-300"
+	| "green-400"
+	| "green-500"
+	| "green-600"
+	| "green-700"
+	| "green-800"
+	| "green-900"
+	| "green-v100"
+	| "green-v200"
+	| "green-v300"
+	| "green-v400"
+	// Sage
+	| "sage-50"
+	| "sage-100"
+	| "sage-200"
+	| "sage-300"
+	| "sage-400"
+	| "sage-500"
+	| "sage-600"
+	| "sage-700"
+	| "sage-800"
+	| "sage-900"
+	| "sage-v100"
+	| "sage-v200"
+	| "sage-v300"
+	| "sage-v400"
+	// Teal
+	| "teal-50"
+	| "teal-100"
+	| "teal-200"
+	| "teal-300"
+	| "teal-400"
+	| "teal-500"
+	| "teal-600"
+	| "teal-700"
+	| "teal-800"
+	| "teal-900"
+	| "teal-v100"
+	| "teal-v200"
+	| "teal-v300"
+	| "teal-v400"
+	// Cyan
+	| "cyan-50"
+	| "cyan-100"
+	| "cyan-200"
+	| "cyan-300"
+	| "cyan-400"
+	| "cyan-500"
+	| "cyan-600"
+	| "cyan-700"
+	| "cyan-800"
+	| "cyan-900"
+	| "cyan-v100"
+	| "cyan-v200"
+	| "cyan-v300"
+	| "cyan-v400"
+	// Ice
+	| "ice-50"
+	| "ice-100"
+	| "ice-200"
+	| "ice-300"
+	| "ice-400"
+	| "ice-500"
+	| "ice-600"
+	| "ice-700"
+	| "ice-800"
+	| "ice-900"
+	| "ice-v100"
+	| "ice-v200"
+	| "ice-v300"
+	| "ice-v400"
+	// Blue
+	| "blue-50"
+	| "blue-100"
+	| "blue-200"
+	| "blue-300"
+	| "blue-400"
+	| "blue-500"
+	| "blue-600"
+	| "blue-700"
+	| "blue-800"
+	| "blue-900"
+	| "blue-v100"
+	| "blue-v200"
+	| "blue-v300"
+	| "blue-v400"
+	// Indigo
+	| "indigo-50"
+	| "indigo-100"
+	| "indigo-200"
+	| "indigo-300"
+	| "indigo-400"
+	| "indigo-500"
+	| "indigo-600"
+	| "indigo-700"
+	| "indigo-800"
+	| "indigo-900"
+	| "indigo-v100"
+	| "indigo-v200"
+	| "indigo-v300"
+	| "indigo-v400"
+	// Iris
+	| "iris-50"
+	| "iris-100"
+	| "iris-200"
+	| "iris-300"
+	| "iris-400"
+	| "iris-500"
+	| "iris-600"
+	| "iris-700"
+	| "iris-800"
+	| "iris-900"
+	| "iris-v100"
+	| "iris-v200"
+	| "iris-v300"
+	| "iris-v400"
+	// Purple
+	| "purple-50"
+	| "purple-100"
+	| "purple-200"
+	| "purple-300"
+	| "purple-400"
+	| "purple-500"
+	| "purple-600"
+	| "purple-700"
+	| "purple-800"
+	| "purple-900"
+	| "purple-v100"
+	| "purple-v200"
+	| "purple-v300"
+	| "purple-v400"
+	// Pink
+	| "pink-50"
+	| "pink-100"
+	| "pink-200"
+	| "pink-300"
+	| "pink-400"
+	| "pink-500"
+	| "pink-600"
+	| "pink-700"
+	| "pink-800"
+	| "pink-900"
+	| "pink-v100"
+	| "pink-v200"
+	| "pink-v300"
+	| "pink-v400"
+	// Red
+	| "red-50"
+	| "red-100"
+	| "red-200"
+	| "red-300"
+	| "red-400"
+	| "red-500"
+	| "red-600"
+	| "red-700"
+	| "red-800"
+	| "red-900"
+	| "red-v100"
+	| "red-v200"
+	| "red-v300"
+	| "red-v400"
+	// Alpha
+	| "alpha-black-5"
+	| "alpha-black-10"
+	| "alpha-black-20"
+	| "alpha-black-30"
+	| "alpha-black-40"
+	| "alpha-black-50"
+	| "alpha-black-60"
+	| "alpha-black-70"
+	| "alpha-black-80"
+	| "alpha-black-90"
+	| "alpha-black-95"
+	| "alpha-white-5"
+	| "alpha-white-10"
+	| "alpha-white-20"
+	| "alpha-white-30"
+	| "alpha-white-40"
+	| "alpha-white-50"
+	| "alpha-white-60"
+	| "alpha-white-70"
+	| "alpha-white-80"
+	| "alpha-white-90"
+	| "alpha-white-95"
+	// Special
+	| "white"
+	| "black";
+
+/**
+ * Spacing token names - maps to `--spacing-{name}` CSS variables
+ * @example "spacing-40", "spacing-72"
+ */
+export type SpacingToken =
+	| "spacing-0"
+	| "spacing-2"
+	| "spacing-4"
+	| "spacing-6"
+	| "spacing-8"
+	| "spacing-10"
+	| "spacing-11"
+	| "spacing-12"
+	| "spacing-16"
+	| "spacing-20"
+	| "spacing-24"
+	| "spacing-28"
+	| "spacing-32"
+	| "spacing-36"
+	| "spacing-40"
+	| "spacing-48"
+	| "spacing-56"
+	| "spacing-64"
+	| "spacing-72"
+	| "spacing-80"
+	| "spacing-96"
+	| "spacing-112"
+	| "spacing-128"
+	| "spacing-144"
+	| "spacing-160"
+	| "spacing-176"
+	| "spacing-192"
+	| "spacing-208"
+	| "spacing-224"
+	| "spacing-240"
+	| "spacing-256"
+	| "spacing-288"
+	| "spacing-320"
+	| "spacing-352"
+	| "spacing-384"
+	| "spacing-400";
+
+/**
+ * Radius token names - maps to `--radii-{name}` CSS variables
+ * @example "radii-4", "radii-6"
+ */
+export type RadiusToken =
+	| "radii-0"
+	| "radii-2"
+	| "radii-4"
+	| "radii-6"
+	| "radii-8"
+	| "radii-10"
+	| "radii-11"
+	| "radii-12"
+	| "radii-16"
+	| "radii-20"
+	| "radii-24"
+	| "radii-28"
+	| "radii-32"
+	| "radii-36"
+	| "radii-40"
+	| "radii-48"
+	| "radii-56"
+	| "radii-64"
+	| "radii-72"
+	| "radii-80"
+	| "radii-96"
+	| "radii-112"
+	| "radii-128"
+	| "radii-144"
+	| "radii-160"
+	| "radii-176"
+	| "radii-192"
+	| "radii-208"
+	| "radii-224"
+	| "radii-240"
+	| "radii-256"
+	| "radii-288"
+	| "radii-320"
+	| "radii-352"
+	| "radii-384"
+	| "radii-400";
+
+/**
+ * Font size token values - primitive font sizes available in the design system
+ * These correspond to Tailwind classes like `text-64`, `text-128`, etc.
+ * @example 64, 128, 192
+ */
+export type FontSizeToken =
+	| 9
+	| 11
+	| 12
+	| 14
+	| 16
+	| 18
+	| 21
+	| 24
+	| 28
+	| 32
+	| 36
+	| 42
+	| 48
+	| 56
+	| 64
+	| 72
+	| 84
+	| 88
+	| 96
+	| 112
+	| 128
+	| 148
+	| 168
+	| 192
+	| 224
+	| 256
+	| 280;
+
+/**
+ * Array of all available font sizes for use in UI selectors/dropdowns
+ */
+export const FONT_SIZES: FontSizeToken[] = [
+	9, 11, 12, 14, 16, 18, 21, 24, 28, 32, 36, 42, 48, 56, 64, 72, 84, 88, 96,
+	112, 128, 148, 168, 192, 224, 256, 280,
+];
+
+/**
+ * Helper to generate typography class string from font size
+ * @example fontSizeToClass(128) => "text-128 leading-128 tracking-128"
+ */
+export function fontSizeToClass(size: FontSizeToken): string {
+	return `text-${size} leading-${size} tracking-${size}`;
+}
+
+/**
+ * Helper to generate responsive typography class string
+ * @example responsiveTypographyClass(64, 128, 192) => "text-64 leading-64 tracking-64 md:text-128 md:leading-128 md:tracking-128 xl:text-192 xl:leading-192 xl:tracking-192"
+ */
+export function responsiveTypographyClass(
+	mobile: FontSizeToken,
+	tablet: FontSizeToken,
+	desktop: FontSizeToken,
+): string {
+	return [
+		fontSizeToClass(mobile),
+		`md:${fontSizeToClass(tablet).split(" ").join(" md:")}`,
+		`xl:${fontSizeToClass(desktop).split(" ").join(" xl:")}`,
+	].join(" ");
+}
+
+// =============================================================================
+// Color Tokens
+// =============================================================================
+
+export interface ComponentThemeColors {
+	/**
+	 * Background color for sections
+	 * @example "gray-100"
+	 */
+	bgSection?: ColorToken;
+
+	/**
+	 * Background color for cards
+	 * @example "white"
+	 */
+	cardBackground?: ColorToken;
+
+	/**
+	 * Muted background color
+	 * @example "gray-50"
+	 */
+	bgMuted?: ColorToken;
+
+	/**
+	 * Primary text color
+	 * @example "gray-1100"
+	 */
+	textPrimary?: ColorToken;
+
+	/**
+	 * Secondary text color
+	 * @example "gray-800"
+	 */
+	textSecondary?: ColorToken;
+
+	/**
+	 * Muted text color
+	 * @example "gray-600"
+	 */
+	textMuted?: ColorToken;
+
+	/**
+	 * Inverted text color (for dark backgrounds)
+	 * @example "gray-100"
+	 */
+	textInverted?: ColorToken;
+
+	/**
+	 * Link text color
+	 * @example "gray-1100"
+	 */
+	textLink?: ColorToken;
+
+	/**
+	 * Link hover text color
+	 * @example "gray-700"
+	 */
+	textLinkHover?: ColorToken;
+
+	/**
+	 * Brand accent color
+	 * @example "ember-v300"
+	 */
+	accentBrand?: ColorToken;
+
+	/**
+	 * Soft brand accent color
+	 * @example "ember-100"
+	 */
+	accentBrandSoft?: ColorToken;
+
+	/**
+	 * Subtle border color
+	 * @example "alpha-black-10"
+	 */
+	borderSubtle?: ColorToken;
+
+	/**
+	 * Strong border color
+	 * @example "alpha-black-20"
+	 */
+	borderStrong?: ColorToken;
+
+	/**
+	 * Focus border color (uses accentBrand by default)
+	 * @example "ember-v300"
+	 */
+	borderFocus?: ColorToken;
+
+	/**
+	 * Divider border color
+	 * @example "alpha-black-10"
+	 */
+	borderDivider?: ColorToken;
+
+	/**
+	 * Primary button background color
+	 * @example "gray-1100"
+	 */
+	buttonPrimaryBg?: ColorToken;
+
+	/**
+	 * Primary button hover background color
+	 * @example "gray-600"
+	 */
+	buttonPrimaryBgHover?: ColorToken;
+
+	/**
+	 * Secondary button background color
+	 * @example "white"
+	 */
+	buttonSecondaryBg?: ColorToken;
+
+	/**
+	 * Secondary button hover background color
+	 * @example "gray-100"
+	 */
+	buttonSecondaryBgHover?: ColorToken;
+}
+
+// =============================================================================
+// Spatial Tokens
+// =============================================================================
+
+export interface ComponentThemeSpatial {
+	/**
+	 * Grid margin for large breakpoint
+	 * @example "spacing-72"
+	 */
+	gridLargeMargin?: SpacingToken;
+
+	/**
+	 * Grid gutter for large breakpoint
+	 * @example "spacing-24"
+	 */
+	gridLargeGutter?: SpacingToken;
+
+	/**
+	 * Number of grid columns for large breakpoint
+	 */
+	gridLargeColumns?: number;
+
+	/**
+	 * Grid margin for medium breakpoint
+	 * @example "spacing-56"
+	 */
+	gridMediumMargin?: SpacingToken;
+
+	/**
+	 * Grid gutter for medium breakpoint
+	 * @example "spacing-20"
+	 */
+	gridMediumGutter?: SpacingToken;
+
+	/**
+	 * Number of grid columns for medium breakpoint
+	 */
+	gridMediumColumns?: number;
+
+	/**
+	 * Grid margin for small breakpoint
+	 * @example "spacing-24"
+	 */
+	gridSmallMargin?: SpacingToken;
+
+	/**
+	 * Grid gutter for small breakpoint
+	 * @example "spacing-12"
+	 */
+	gridSmallGutter?: SpacingToken;
+
+	/**
+	 * Number of grid columns for small breakpoint
+	 */
+	gridSmallColumns?: number;
+
+	/**
+	 * Section gap for large breakpoint
+	 * @example "spacing-64"
+	 */
+	sectionLargeGap?: SpacingToken;
+
+	/**
+	 * Section padding for large breakpoint
+	 * @example "spacing-128"
+	 */
+	sectionLargePadding?: SpacingToken;
+
+	/**
+	 * Section gap for medium breakpoint
+	 * @example "spacing-56"
+	 */
+	sectionMediumGap?: SpacingToken;
+
+	/**
+	 * Section padding for medium breakpoint
+	 * @example "spacing-96"
+	 */
+	sectionMediumPadding?: SpacingToken;
+
+	/**
+	 * Section gap for small breakpoint
+	 * @example "spacing-32"
+	 */
+	sectionSmallGap?: SpacingToken;
+
+	/**
+	 * Section padding for small breakpoint
+	 * @example "spacing-64"
+	 */
+	sectionSmallPadding?: SpacingToken;
+
+	/**
+	 * Card gap for large size
+	 * @example "spacing-10"
+	 */
+	cardLargeGap?: SpacingToken;
+
+	/**
+	 * Card padding for large size
+	 * @example "spacing-24"
+	 */
+	cardLargePadding?: SpacingToken;
+
+	/**
+	 * Card gap for small size
+	 * @example "spacing-12"
+	 */
+	cardSmallGap?: SpacingToken;
+
+	/**
+	 * Card padding for small size
+	 * @example "spacing-16"
+	 */
+	cardSmallPadding?: SpacingToken;
+}
+
+// =============================================================================
+// Surface Tokens
+// =============================================================================
+
+export interface ComponentThemeSurface {
+	/**
+	 * Card border radius
+	 * @example "radii-4"
+	 */
+	cardRadius?: RadiusToken;
+
+	/**
+	 * Card stroke/border width in pixels
+	 * @example 1
+	 */
+	cardStroke?: number;
+
+	/**
+	 * Button border radius
+	 * @example "radii-6"
+	 */
+	buttonRadius?: RadiusToken;
+
+	/**
+	 * Button stroke/border weight in pixels
+	 * @example 1
+	 */
+	buttonStrokeWeight?: number;
+}
+
+// =============================================================================
+// Combined Theme Interface
+// =============================================================================
+
+/**
+ * Complete component theme interface combining colors, spatial, and surface tokens.
+ *
+ * @example
+ * ```tsx
+ * const customTheme: ComponentTheme = {
+ *   colors: {
+ *     textPrimary: "gray-100",
+ *     accentBrand: "ember-500",
+ *   },
+ *   spatial: {
+ *     sectionLargePadding: "spacing-96",
+ *   },
+ *   surface: {
+ *     cardRadius: "radii-8",
+ *   },
+ * };
+ *
+ * <Tout theme={customTheme} ... />
+ * ```
+ */
+export interface ComponentTheme {
+	colors?: ComponentThemeColors;
+	spatial?: ComponentThemeSpatial;
+	surface?: ComponentThemeSurface;
+}
+
+// =============================================================================
+// Button Theme Interface
+// =============================================================================
+
+/**
+ * Button-specific theme interface for customizing individual button appearance.
+ *
+ * @example
+ * ```tsx
+ * const buttonTheme: ButtonTheme = {
+ *   bg: "ember-500",
+ *   bgHover: "ember-600",
+ *   text: "white",
+ *   radius: "radii-8",
+ * };
+ *
+ * <Button theme={buttonTheme}>Themed Button</Button>
+ * ```
+ */
+export interface ButtonTheme {
+	/** Background color */
+	bg?: ColorToken;
+	/** Background color on hover */
+	bgHover?: ColorToken;
+	/** Background color on active/press */
+	bgActive?: ColorToken;
+	/** Text color */
+	text?: ColorToken;
+	/** Border color (if using border) */
+	borderColor?: ColorToken;
+	/** Border width in pixels (0 for no border) */
+	borderWidth?: number;
+	/** Border radius */
+	radius?: RadiusToken;
+}
+
+// =============================================================================
+// Utility Functions
+// =============================================================================
+
+/**
+ * Converts a color token name to a CSS variable reference
+ */
+function colorToVar(token: ColorToken): string {
+	return `var(--color-${token})`;
+}
+
+/**
+ * Converts a spacing token name to a CSS variable reference
+ */
+function spacingToVar(token: SpacingToken): string {
+	return `var(--${token})`;
+}
+
+/**
+ * Converts a radius token name to a CSS variable reference
+ */
+function radiusToVar(token: RadiusToken): string {
+	return `var(--${token})`;
+}
+
+/**
+ * Converts a ComponentTheme object to CSS custom properties (inline style object)
+ *
+ * @param theme - The theme object to convert
+ * @returns An object suitable for use as React inline styles
+ */
+export function themeToStyleVars(
+	theme: ComponentTheme | undefined,
+): React.CSSProperties {
+	if (!theme) return {};
+
+	const vars: Record<string, string> = {};
+
+	// Colors
+	if (theme.colors) {
+		const { colors } = theme;
+		if (colors.bgSection)
+			vars["--theme-bg-section"] = colorToVar(colors.bgSection);
+		if (colors.cardBackground)
+			vars["--theme-card-background"] = colorToVar(colors.cardBackground);
+		if (colors.bgMuted) vars["--theme-bg-muted"] = colorToVar(colors.bgMuted);
+		if (colors.textPrimary)
+			vars["--theme-text-primary"] = colorToVar(colors.textPrimary);
+		if (colors.textSecondary)
+			vars["--theme-text-secondary"] = colorToVar(colors.textSecondary);
+		if (colors.textMuted)
+			vars["--theme-text-muted"] = colorToVar(colors.textMuted);
+		if (colors.textInverted)
+			vars["--theme-text-inverted"] = colorToVar(colors.textInverted);
+		if (colors.textLink)
+			vars["--theme-text-link"] = colorToVar(colors.textLink);
+		if (colors.textLinkHover)
+			vars["--theme-text-link-hover"] = colorToVar(colors.textLinkHover);
+		if (colors.accentBrand)
+			vars["--theme-accent-brand"] = colorToVar(colors.accentBrand);
+		if (colors.accentBrandSoft)
+			vars["--theme-accent-brand-soft"] = colorToVar(colors.accentBrandSoft);
+		if (colors.borderSubtle)
+			vars["--theme-border-subtle"] = colorToVar(colors.borderSubtle);
+		if (colors.borderStrong)
+			vars["--theme-border-strong"] = colorToVar(colors.borderStrong);
+		if (colors.borderFocus)
+			vars["--theme-border-focus"] = colorToVar(colors.borderFocus);
+		if (colors.borderDivider)
+			vars["--theme-border-divider"] = colorToVar(colors.borderDivider);
+		if (colors.buttonPrimaryBg)
+			vars["--theme-button-primary-bg"] = colorToVar(colors.buttonPrimaryBg);
+		if (colors.buttonPrimaryBgHover)
+			vars["--theme-button-primary-bg-hover"] = colorToVar(
+				colors.buttonPrimaryBgHover,
+			);
+		if (colors.buttonSecondaryBg)
+			vars["--theme-button-secondary-bg"] = colorToVar(
+				colors.buttonSecondaryBg,
+			);
+		if (colors.buttonSecondaryBgHover)
+			vars["--theme-button-secondary-bg-hover"] = colorToVar(
+				colors.buttonSecondaryBgHover,
+			);
+	}
+
+	// Spatial
+	if (theme.spatial) {
+		const { spatial } = theme;
+		if (spatial.gridLargeMargin)
+			vars["--theme-grid-large-margin"] = spacingToVar(spatial.gridLargeMargin);
+		if (spatial.gridLargeGutter)
+			vars["--theme-grid-large-gutter"] = spacingToVar(spatial.gridLargeGutter);
+		if (spatial.gridLargeColumns)
+			vars["--theme-grid-large-columns"] = String(spatial.gridLargeColumns);
+		if (spatial.gridMediumMargin)
+			vars["--theme-grid-medium-margin"] = spacingToVar(
+				spatial.gridMediumMargin,
+			);
+		if (spatial.gridMediumGutter)
+			vars["--theme-grid-medium-gutter"] = spacingToVar(
+				spatial.gridMediumGutter,
+			);
+		if (spatial.gridMediumColumns)
+			vars["--theme-grid-medium-columns"] = String(spatial.gridMediumColumns);
+		if (spatial.gridSmallMargin)
+			vars["--theme-grid-small-margin"] = spacingToVar(spatial.gridSmallMargin);
+		if (spatial.gridSmallGutter)
+			vars["--theme-grid-small-gutter"] = spacingToVar(spatial.gridSmallGutter);
+		if (spatial.gridSmallColumns)
+			vars["--theme-grid-small-columns"] = String(spatial.gridSmallColumns);
+		if (spatial.sectionLargeGap)
+			vars["--theme-section-large-gap"] = spacingToVar(spatial.sectionLargeGap);
+		if (spatial.sectionLargePadding)
+			vars["--theme-section-large-padding"] = spacingToVar(
+				spatial.sectionLargePadding,
+			);
+		if (spatial.sectionMediumGap)
+			vars["--theme-section-medium-gap"] = spacingToVar(
+				spatial.sectionMediumGap,
+			);
+		if (spatial.sectionMediumPadding)
+			vars["--theme-section-medium-padding"] = spacingToVar(
+				spatial.sectionMediumPadding,
+			);
+		if (spatial.sectionSmallGap)
+			vars["--theme-section-small-gap"] = spacingToVar(spatial.sectionSmallGap);
+		if (spatial.sectionSmallPadding)
+			vars["--theme-section-small-padding"] = spacingToVar(
+				spatial.sectionSmallPadding,
+			);
+		if (spatial.cardLargeGap)
+			vars["--theme-card-large-gap"] = spacingToVar(spatial.cardLargeGap);
+		if (spatial.cardLargePadding)
+			vars["--theme-card-large-padding"] = spacingToVar(
+				spatial.cardLargePadding,
+			);
+		if (spatial.cardSmallGap)
+			vars["--theme-card-small-gap"] = spacingToVar(spatial.cardSmallGap);
+		if (spatial.cardSmallPadding)
+			vars["--theme-card-small-padding"] = spacingToVar(
+				spatial.cardSmallPadding,
+			);
+	}
+
+	// Surface
+	if (theme.surface) {
+		const { surface } = theme;
+		if (surface.cardRadius)
+			vars["--theme-card-radius"] = radiusToVar(surface.cardRadius);
+		if (surface.cardStroke)
+			vars["--theme-card-stroke"] = `${surface.cardStroke}px`;
+		if (surface.buttonRadius)
+			vars["--theme-button-radius"] = radiusToVar(surface.buttonRadius);
+		if (surface.buttonStrokeWeight)
+			vars["--theme-button-stroke-weight"] = `${surface.buttonStrokeWeight}px`;
+	}
+
+	return vars as React.CSSProperties;
+}
+
+/**
+ * Converts a ButtonTheme object to CSS custom properties (inline style object)
+ *
+ * @param theme - The button theme object to convert
+ * @returns An object suitable for use as React inline styles
+ */
+export function buttonThemeToStyleVars(
+	theme: ButtonTheme | undefined,
+): React.CSSProperties {
+	if (!theme) return {};
+
+	const vars: Record<string, string> = {};
+
+	if (theme.bg) vars["--btn-bg"] = colorToVar(theme.bg);
+	if (theme.bgHover) vars["--btn-bg-hover"] = colorToVar(theme.bgHover);
+	if (theme.bgActive) vars["--btn-bg-active"] = colorToVar(theme.bgActive);
+	if (theme.text) vars["--btn-text"] = colorToVar(theme.text);
+	if (theme.borderColor)
+		vars["--btn-border-color"] = colorToVar(theme.borderColor);
+	if (theme.borderWidth !== undefined)
+		vars["--btn-border-width"] = `${theme.borderWidth}px`;
+	if (theme.radius) vars["--btn-radius"] = radiusToVar(theme.radius);
+
+	return vars as React.CSSProperties;
+}