@praxiis/ui 0.0.1

package/src/core/restyle/restyleTheme.ts

@@ -0,0 +1,1352 @@
+/**
+ * El Sendero Design System - Restyle Theme Configuration
+ *
+ * Maps all design system tokens to Restyle theme format.
+ * Restyle enables type-safe, prop-based styling for React Native components.
+ */
+
+import { createTheme } from "@shopify/restyle";
+import {
+  baseColors,
+  darkSemanticColors,
+  fontFamily,
+  lightSemanticColors,
+  radii,
+  spacing,
+  typographyPresets,
+  zIndex,
+} from "../../tokens";
+
+// =============================================================================
+// PRESET RESTYLE THEME BUILDER
+// =============================================================================
+
+import type { ThemeColors, DeepPartial } from "../../providers/ThemeProvider/types";
+
+export type SemanticColorsInput = {
+  [K in keyof typeof lightSemanticColors]: {
+    [P in keyof (typeof lightSemanticColors)[K]]: string;
+  };
+};
+
+export const flattenColors = (semanticColors: SemanticColorsInput) =>
+  ({
+    // Backgrounds
+    backgroundPrimary: semanticColors.background.primary,
+    backgroundSecondary: semanticColors.background.secondary,
+    backgroundTertiary: semanticColors.background.tertiary,
+    backgroundInverse: semanticColors.background.inverse,
+
+    // Surfaces
+    surfacePrimary: semanticColors.surface.primary,
+    surfaceSecondary: semanticColors.surface.secondary,
+    surfaceElevated: semanticColors.surface.elevated,
+    surfaceOverlay: semanticColors.surface.overlay,
+
+    // Text
+    textPrimary: semanticColors.text.primary,
+    textSecondary: semanticColors.text.secondary,
+    textTertiary: semanticColors.text.tertiary,
+    textDisabled: semanticColors.text.disabled,
+    textInverse: semanticColors.text.inverse,
+    textLink: semanticColors.text.link,
+
+    // Borders
+    borderDefault: semanticColors.border.default,
+    borderSubtle: semanticColors.border.subtle,
+    borderStrong: semanticColors.border.strong,
+    borderFocus: semanticColors.border.focus,
+
+    // Accents
+    accentPrimary: semanticColors.accent.primary,
+    accentPrimaryHover: semanticColors.accent.primaryHover,
+    accentPrimaryPressed: semanticColors.accent.primaryPressed,
+    accentSecondary: semanticColors.accent.secondary,
+    accentSecondaryHover: semanticColors.accent.secondaryHover,
+    accentSecondaryPressed: semanticColors.accent.secondaryPressed,
+
+    // Interactive
+    interactiveDefault: semanticColors.interactive.default,
+    interactiveHover: semanticColors.interactive.hover,
+    interactivePressed: semanticColors.interactive.pressed,
+    interactiveDisabled: semanticColors.interactive.disabled,
+
+    // Feedback
+    feedbackSuccess: semanticColors.feedback.success,
+    feedbackSuccessLight: semanticColors.feedback.successLight,
+    feedbackSuccessDark: semanticColors.feedback.successDark,
+    feedbackWarning: semanticColors.feedback.warning,
+    feedbackWarningLight: semanticColors.feedback.warningLight,
+    feedbackWarningDark: semanticColors.feedback.warningDark,
+    feedbackError: semanticColors.feedback.error,
+    feedbackErrorLight: semanticColors.feedback.errorLight,
+    feedbackErrorDark: semanticColors.feedback.errorDark,
+    feedbackInfo: semanticColors.feedback.info,
+    feedbackInfoLight: semanticColors.feedback.infoLight,
+    feedbackInfoDark: semanticColors.feedback.infoDark,
+
+    // Danger (for buttons)
+    dangerPrimary: semanticColors.feedback.error,
+    dangerPrimaryHover: semanticColors.feedback.errorDark,
+    dangerPrimaryPressed: semanticColors.feedback.errorDark,
+
+    // Special
+    specialSkeleton: semanticColors.special.skeleton,
+    specialDivider: semanticColors.special.divider,
+    specialScrim: semanticColors.special.scrim,
+
+    // Emotion colors
+    emotionHappy: semanticColors.emotion.happy,
+    emotionCalm: semanticColors.emotion.calm,
+    emotionNeutral: semanticColors.emotion.neutral,
+    emotionSad: semanticColors.emotion.sad,
+    emotionAnxious: semanticColors.emotion.anxious,
+    emotionAngry: semanticColors.emotion.angry,
+    emotionOverwhelmed: semanticColors.emotion.overwhelmed,
+
+    // Transparent
+    transparent: "transparent",
+
+    // Base Colors - Blue (Primary)
+    blue50: baseColors.blue[50],
+    blue100: baseColors.blue[100],
+    blue200: baseColors.blue[200],
+    blue300: baseColors.blue[300],
+    blue400: baseColors.blue[400],
+    blue500: baseColors.blue[500],
+    blue600: baseColors.blue[600],
+    blue700: baseColors.blue[700],
+    blue800: baseColors.blue[800],
+    blue900: baseColors.blue[900],
+
+    // Base Colors - Pink (Accent)
+    pink50: baseColors.pink[50],
+    pink100: baseColors.pink[100],
+    pink200: baseColors.pink[200],
+    pink300: baseColors.pink[300],
+    pink400: baseColors.pink[400],
+    pink500: baseColors.pink[500],
+    pink600: baseColors.pink[600],
+    pink700: baseColors.pink[700],
+    pink800: baseColors.pink[800],
+    pink900: baseColors.pink[900],
+
+    // Base Colors - Yellow (Warning/Accent)
+    yellow50: baseColors.yellow[50],
+    yellow100: baseColors.yellow[100],
+    yellow200: baseColors.yellow[200],
+    yellow300: baseColors.yellow[300],
+    yellow400: baseColors.yellow[400],
+    yellow500: baseColors.yellow[500],
+    yellow600: baseColors.yellow[600],
+    yellow700: baseColors.yellow[700],
+    yellow800: baseColors.yellow[800],
+    yellow900: baseColors.yellow[900],
+
+    // Base Colors - Green (Success)
+    green50: baseColors.green[50],
+    green100: baseColors.green[100],
+    green200: baseColors.green[200],
+    green300: baseColors.green[300],
+    green400: baseColors.green[400],
+    green500: baseColors.green[500],
+    green600: baseColors.green[600],
+    green700: baseColors.green[700],
+    green800: baseColors.green[800],
+    green900: baseColors.green[900],
+
+    // Base Colors - Orange (Secondary accent)
+    orange50: baseColors.orange[50],
+    orange100: baseColors.orange[100],
+    orange200: baseColors.orange[200],
+    orange300: baseColors.orange[300],
+    orange400: baseColors.orange[400],
+    orange500: baseColors.orange[500],
+    orange600: baseColors.orange[600],
+    orange700: baseColors.orange[700],
+    orange800: baseColors.orange[800],
+    orange900: baseColors.orange[900],
+
+    // Base Colors - Amber (Alternative warning)
+    amber50: baseColors.amber[50],
+    amber100: baseColors.amber[100],
+    amber200: baseColors.amber[200],
+    amber300: baseColors.amber[300],
+    amber400: baseColors.amber[400],
+    amber500: baseColors.amber[500],
+    amber600: baseColors.amber[600],
+    amber700: baseColors.amber[700],
+    amber800: baseColors.amber[800],
+    amber900: baseColors.amber[900],
+
+    // Base Colors - Red (Error)
+    red50: baseColors.red[50],
+    red100: baseColors.red[100],
+    red200: baseColors.red[200],
+    red300: baseColors.red[300],
+    red400: baseColors.red[400],
+    red500: baseColors.red[500],
+    red600: baseColors.red[600],
+    red700: baseColors.red[700],
+    red800: baseColors.red[800],
+    red900: baseColors.red[900],
+
+    // Base Colors - Purple (Decorative)
+    purple50: baseColors.purple[50],
+    purple100: baseColors.purple[100],
+    purple200: baseColors.purple[200],
+    purple300: baseColors.purple[300],
+    purple400: baseColors.purple[400],
+    purple500: baseColors.purple[500],
+    purple600: baseColors.purple[600],
+    purple700: baseColors.purple[700],
+    purple800: baseColors.purple[800],
+    purple900: baseColors.purple[900],
+
+    // Base Colors - Cyan (Info/Accent)
+    cyan50: baseColors.cyan[50],
+    cyan100: baseColors.cyan[100],
+    cyan200: baseColors.cyan[200],
+    cyan300: baseColors.cyan[300],
+    cyan400: baseColors.cyan[400],
+    cyan500: baseColors.cyan[500],
+    cyan600: baseColors.cyan[600],
+    cyan700: baseColors.cyan[700],
+    cyan800: baseColors.cyan[800],
+    cyan900: baseColors.cyan[900],
+
+    // Base Colors - Deep Purple (Special)
+    deepPurple50: baseColors.deepPurple[50],
+    deepPurple100: baseColors.deepPurple[100],
+    deepPurple200: baseColors.deepPurple[200],
+    deepPurple300: baseColors.deepPurple[300],
+    deepPurple400: baseColors.deepPurple[400],
+    deepPurple500: baseColors.deepPurple[500],
+    deepPurple600: baseColors.deepPurple[600],
+    deepPurple700: baseColors.deepPurple[700],
+    deepPurple800: baseColors.deepPurple[800],
+    deepPurple900: baseColors.deepPurple[900],
+
+    // Base Colors - Gray
+    gray50: baseColors.gray[50],
+    gray100: baseColors.gray[100],
+    gray200: baseColors.gray[200],
+    gray300: baseColors.gray[300],
+    gray400: baseColors.gray[400],
+    gray500: baseColors.gray[500],
+    gray600: baseColors.gray[600],
+    gray700: baseColors.gray[700],
+    gray800: baseColors.gray[800],
+    gray900: baseColors.gray[900],
+
+    // Base Colors - Pure
+    white: baseColors.white,
+    black: baseColors.black,
+
+    // Text Color Aliases (for semantic usage like color="primary")
+    // These map to the flattened text colors for convenience
+    primary: semanticColors.text.primary,
+    secondary: semanticColors.text.secondary,
+    tertiary: semanticColors.text.tertiary,
+    disabled: semanticColors.text.disabled,
+    inverse: semanticColors.text.inverse,
+    link: semanticColors.text.link,
+    success: semanticColors.feedback.success,
+    warning: semanticColors.feedback.warning,
+    error: semanticColors.feedback.error,
+    info: semanticColors.feedback.info,
+  }) as const;
+
+// =============================================================================
+// COLOR PALETTES
+// =============================================================================
+
+const lightColors = flattenColors(lightSemanticColors);
+const darkColors = flattenColors(darkSemanticColors);
+
+// =============================================================================
+// RESTYLE THEME DEFINITION
+// =============================================================================
+
+// =============================================================================
+// HELPER: CREATE BASE THEME CONFIG
+// Shared configuration for both light and dark themes
+// =============================================================================
+
+export const createBaseThemeConfig = (
+  colors: ReturnType<typeof flattenColors>,
+) => ({
+  colors,
+  spacing,
+  borderRadii: radii,
+  textVariants: {
+    defaults: {
+      color: "textPrimary",
+    },
+    // Display variants
+    displayLarge: {
+      fontSize: typographyPresets.displayLarge.fontSize,
+      lineHeight: typographyPresets.displayLarge.lineHeight,
+      fontWeight: typographyPresets.displayLarge.fontWeight,
+      letterSpacing: typographyPresets.displayLarge.letterSpacing,
+      fontFamily: fontFamily.bold,
+    },
+    displayMedium: {
+      fontSize: typographyPresets.displayMedium.fontSize,
+      lineHeight: typographyPresets.displayMedium.lineHeight,
+      fontWeight: typographyPresets.displayMedium.fontWeight,
+      letterSpacing: typographyPresets.displayMedium.letterSpacing,
+      fontFamily: fontFamily.bold,
+    },
+    displaySmall: {
+      fontSize: typographyPresets.displaySmall.fontSize,
+      lineHeight: typographyPresets.displaySmall.lineHeight,
+      fontWeight: typographyPresets.displaySmall.fontWeight,
+      letterSpacing: typographyPresets.displaySmall.letterSpacing,
+      fontFamily: fontFamily.bold,
+    },
+    // Heading variants
+    headingLarge: {
+      fontSize: typographyPresets.headingLarge.fontSize,
+      lineHeight: typographyPresets.headingLarge.lineHeight,
+      fontWeight: typographyPresets.headingLarge.fontWeight,
+      letterSpacing: typographyPresets.headingLarge.letterSpacing,
+      fontFamily: fontFamily.semibold,
+    },
+    headingMedium: {
+      fontSize: typographyPresets.headingMedium.fontSize,
+      lineHeight: typographyPresets.headingMedium.lineHeight,
+      fontWeight: typographyPresets.headingMedium.fontWeight,
+      letterSpacing: typographyPresets.headingMedium.letterSpacing,
+      fontFamily: fontFamily.semibold,
+    },
+    headingSmall: {
+      fontSize: typographyPresets.headingSmall.fontSize,
+      lineHeight: typographyPresets.headingSmall.lineHeight,
+      fontWeight: typographyPresets.headingSmall.fontWeight,
+      letterSpacing: typographyPresets.headingSmall.letterSpacing,
+      fontFamily: fontFamily.semibold,
+    },
+    // Body variants
+    bodyLarge: {
+      fontSize: typographyPresets.bodyLarge.fontSize,
+      lineHeight: typographyPresets.bodyLarge.lineHeight,
+      fontWeight: typographyPresets.bodyLarge.fontWeight,
+      letterSpacing: typographyPresets.bodyLarge.letterSpacing,
+      fontFamily: fontFamily.regular,
+    },
+    bodyMedium: {
+      fontSize: typographyPresets.bodyMedium.fontSize,
+      lineHeight: typographyPresets.bodyMedium.lineHeight,
+      fontWeight: typographyPresets.bodyMedium.fontWeight,
+      letterSpacing: typographyPresets.bodyMedium.letterSpacing,
+      fontFamily: fontFamily.regular,
+    },
+    bodySmall: {
+      fontSize: typographyPresets.bodySmall.fontSize,
+      lineHeight: typographyPresets.bodySmall.lineHeight,
+      fontWeight: typographyPresets.bodySmall.fontWeight,
+      letterSpacing: typographyPresets.bodySmall.letterSpacing,
+      fontFamily: fontFamily.regular,
+    },
+    // Label variants
+    labelLarge: {
+      fontSize: typographyPresets.labelLarge.fontSize,
+      lineHeight: typographyPresets.labelLarge.lineHeight,
+      fontWeight: typographyPresets.labelLarge.fontWeight,
+      letterSpacing: typographyPresets.labelLarge.letterSpacing,
+      fontFamily: fontFamily.medium,
+    },
+    labelMedium: {
+      fontSize: typographyPresets.labelMedium.fontSize,
+      lineHeight: typographyPresets.labelMedium.lineHeight,
+      fontWeight: typographyPresets.labelMedium.fontWeight,
+      letterSpacing: typographyPresets.labelMedium.letterSpacing,
+      fontFamily: fontFamily.medium,
+    },
+    labelSmall: {
+      fontSize: typographyPresets.labelSmall.fontSize,
+      lineHeight: typographyPresets.labelSmall.lineHeight,
+      fontWeight: typographyPresets.labelSmall.fontWeight,
+      letterSpacing: typographyPresets.labelSmall.letterSpacing,
+      fontFamily: fontFamily.medium,
+    },
+    // Caption variants
+    caption: {
+      fontSize: typographyPresets.caption.fontSize,
+      lineHeight: typographyPresets.caption.lineHeight,
+      fontWeight: typographyPresets.caption.fontWeight,
+      letterSpacing: typographyPresets.caption.letterSpacing,
+      fontFamily: fontFamily.regular,
+    },
+    captionSmall: {
+      fontSize: typographyPresets.captionSmall.fontSize,
+      lineHeight: typographyPresets.captionSmall.lineHeight,
+      fontWeight: typographyPresets.captionSmall.fontWeight,
+      letterSpacing: typographyPresets.captionSmall.letterSpacing,
+      fontFamily: fontFamily.regular,
+    },
+    // Overline variant
+    overline: {
+      fontSize: typographyPresets.overline.fontSize,
+      lineHeight: typographyPresets.overline.lineHeight,
+      fontWeight: typographyPresets.overline.fontWeight,
+      letterSpacing: typographyPresets.overline.letterSpacing,
+      textTransform: typographyPresets.overline.textTransform,
+      fontFamily: fontFamily.semibold,
+    },
+    // Code variant
+    code: {
+      fontSize: typographyPresets.code.fontSize,
+      lineHeight: typographyPresets.code.lineHeight,
+      fontWeight: typographyPresets.code.fontWeight,
+      letterSpacing: typographyPresets.code.letterSpacing,
+      fontFamily: fontFamily.mono,
+    },
+  },
+  breakpoints: {
+    phone: 0,
+    tablet: 768,
+  },
+  zIndices: {
+    behind: zIndex.behind,
+    base: zIndex.base,
+    raised: zIndex.raised,
+    dropdown: zIndex.dropdown,
+    sticky: zIndex.sticky,
+    overlay: zIndex.overlay,
+    modal: zIndex.modal,
+    popover: zIndex.popover,
+    toast: zIndex.toast,
+    max: zIndex.max,
+  },
+  // ==========================================================================
+  // BUTTON SIZES
+  // ==========================================================================
+  // Mathematical relationship: Icon matches text visual weight (1:1)
+  //
+  // | Size | Height | Icon | Text Variant | Touch Target |
+  // |------|--------|------|--------------|--------------|
+  // | sm   | 36px   | 16px | labelSmall   | 36px (native)|
+  // | md   | 44px   | 20px | labelMedium  | 44px (native)|
+  // | lg   | 52px   | 24px | labelLarge   | 52px (native)|
+  //
+  // See: tokens/scales.ts BUTTON_ICON_SIZE, BUTTON_TEXT_VARIANT
+  buttonSizes: {
+    defaults: {
+      height: 44,
+      paddingHorizontal: "md",
+      borderRadius: "md",
+    },
+    sm: {
+      height: 36,
+      paddingHorizontal: "sm",
+    },
+    md: {
+      height: 44,
+      paddingHorizontal: "md",
+    },
+    lg: {
+      height: 52,
+      paddingHorizontal: "lg",
+    },
+  },
+  // Button variants - visual styles only
+  buttonVariants: {
+    defaults: {
+      borderWidth: 0,
+    },
+    solid: {
+      borderWidth: 0,
+    },
+    outline: {
+      backgroundColor: "transparent",
+      borderWidth: 1.5,
+    },
+    ghost: {
+      backgroundColor: "transparent",
+      borderWidth: 0,
+    },
+    disabled: {
+      borderWidth: 0,
+    },
+  },
+  // ==========================================================================
+  // CHECKBOX SIZES
+  // ==========================================================================
+  // Mathematical relationship: Icon = Container × ~75% (toggleControl ratio)
+  //
+  // | Size | Container | Icon | Ratio | hitSlop | Touch Target |
+  // |------|-----------|------|-------|---------|--------------|
+  // | sm   | 20px      | 16px | 80%   | 12px    | 44px         |
+  // | md   | 24px      | 20px | 83%   | 10px    | 44px         |
+  // | lg   | 32px      | 24px | 75%   | 6px     | 44px         |
+  //
+  // See: tokens/scales.ts CHECKBOX_ICON_SIZE, CHECKBOX_HIT_SLOP
+  checkboxSizes: {
+    defaults: {
+      width: 24,
+      height: 24,
+      borderRadius: "xs",
+      borderWidth: 2,
+    },
+    sm: {
+      width: 20,
+      height: 20,
+    },
+    md: {
+      width: 24,
+      height: 24,
+    },
+    lg: {
+      width: 32,
+      height: 32,
+      borderRadius: "sm",
+    },
+  },
+  // ==========================================================================
+  // RADIO BUTTON SIZES
+  // ==========================================================================
+  // Uses same container sizes as Checkbox but with circular shape (full radius).
+  // Inner dot size: ~40% of container for visual balance.
+  //
+  // | Size | Container | Inner Dot | hitSlop | Touch |
+  // |------|-----------|-----------|---------|-------|
+  // | sm   | 20px      | 8px       | 12px    | 44px  |
+  // | md   | 24px      | 10px      | 10px    | 44px  |
+  // | lg   | 32px      | 14px      | 6px     | 44px  |
+  //
+  // See: tokens/scales.ts TOGGLE_CONTAINER_SIZES, RADIO_BUTTON_INNER_SIZE
+  radioButtonSizes: {
+    defaults: {
+      width: 24,
+      height: 24,
+      borderRadius: "full",
+      borderWidth: 2,
+    },
+    sm: {
+      width: 20,
+      height: 20,
+    },
+    md: {
+      width: 24,
+      height: 24,
+    },
+    lg: {
+      width: 32,
+      height: 32,
+    },
+  },
+  // ==========================================================================
+  // SWITCH SIZES
+  // ==========================================================================
+  // Mathematical relationship: Thumb = TrackHeight - (THUMB_INSET × 2)
+  // THUMB_INSET = 2px (from tokens/scales.ts)
+  //
+  // | Size | Track W | Track H | Thumb | W:H Ratio | hitSlop | Touch |
+  // |------|---------|---------|-------|-----------|---------|-------|
+  // | sm   | 40px    | 24px    | 20px  | 1.67:1    | 10px    | 44px  |
+  // | md   | 48px    | 28px    | 24px  | 1.71:1    | 8px     | 44px  |
+  // | lg   | 56px    | 32px    | 28px  | 1.75:1    | 6px     | 44px  |
+  //
+  // See: tokens/scales.ts SWITCH_DIMENSIONS, SWITCH_THUMB_INSET
+  switchSizes: {
+    defaults: {
+      // Track dimensions
+      width: 48,
+      height: 28,
+      borderRadius: "full",
+    },
+    sm: {
+      width: 40,
+      height: 24,
+    },
+    md: {
+      width: 48,
+      height: 28,
+    },
+    lg: {
+      width: 56,
+      height: 32,
+    },
+  },
+  // ==========================================================================
+  // TEXT INPUT VARIANTS
+  // ==========================================================================
+  // Visual style variants for TextInput. Actual border/background styling
+  // is resolved in TextInput.helpers.ts; keys here establish the type
+  // contract so TextInputVariant derives from the theme.
+  //
+  // | Variant  | Background     | Border      | Use Case |
+  // |----------|----------------|-------------|----------|
+  // | outlined | transparent    | 1.5px solid | Default, most forms |
+  // | filled   | backgroundSecondary | subtle  | Dense/compact UIs |
+  // | textarea | transparent    | 1.5px solid | Multi-line text input |
+  textInputVariants: {
+    defaults: {},
+    outlined: {},
+    filled: {},
+    textarea: {},
+  },
+  // ==========================================================================
+  // TEXT INPUT SIZES
+  // ==========================================================================
+  // Height/padding presets for TextInput. Actual dimensions are
+  // resolved in TextInput.helpers.ts; keys establish the type contract.
+  //
+  // | Size | Height | Padding H | Font Size | Use Case |
+  // |------|--------|-----------|-----------|----------|
+  // | sm   | 40px   | 12px      | 14px      | Compact forms |
+  // | md   | 48px   | 16px      | 16px      | Default mobile |
+  // | lg   | 56px   | 20px      | 18px      | Tablets, emphasis |
+  textInputSizes: {
+    defaults: {},
+    sm: {},
+    md: {},
+    lg: {},
+  },
+  // ==========================================================================
+  // SELECT SHEET VARIANTS
+  // ==========================================================================
+  // Industry-standard dimensions based on Material Design 3 and iOS HIG.
+  //
+  // Variant Positioning:
+  // - center: Centered modal dialog with max-width constraint
+  // - bottom: Bottom sheet anchored to screen bottom
+  //
+  // Size Scale:
+  // | Size | Max Width | List Height | Header | Use Case |
+  // |------|-----------|-------------|--------|----------|
+  // | sm   | 320px     | 200px       | 48px   | Few options |
+  // | md   | 400px     | 300px       | 56px   | Default |
+  // SelectSheet - Simplified consistent width like Modal
+  // Phone: Full width - 16px margins
+  // Tablet (≥768px): Capped at 480px max-width for phone-like experience
+  //
+  // See: tokens/scales.ts SELECT_SHEET_LAYOUT
+  selectSheetVariants: {
+    defaults: {
+      backgroundColor: "surfaceElevated",
+      borderRadius: "xl",
+      overflow: "hidden",
+    },
+  },
+  // SelectSheet header - Consistent height
+  selectSheetHeader: {
+    height: 56,
+    paddingHorizontal: "lg",
+    borderBottomWidth: 1,
+    borderBottomColor: "borderSubtle",
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "space-between",
+  },
+  // SelectSheet option row - Consistent height with touch targets
+  selectSheetOptionRow: {
+    height: 52,
+    paddingHorizontal: "lg",
+    paddingVertical: "md",
+    flexDirection: "row",
+    alignItems: "center",
+    gap: "md",
+  },
+  // Card variants - visual styles
+  cardVariants: {
+    defaults: {
+      borderWidth: 0,
+      borderRadius: "lg",
+    },
+    flat: {
+      backgroundColor: "backgroundSecondary",
+      borderWidth: 0,
+      borderRadius: "lg",
+    },
+    outlined: {
+      backgroundColor: "backgroundSecondary",
+      borderWidth: 1,
+      borderColor: "borderDefault",
+      borderRadius: "lg",
+    },
+  },
+  // Header variants
+  headerVariants: {
+    defaults: {
+      backgroundColor: "surfacePrimary",
+      borderBottomWidth: 1,
+      borderBottomColor: "borderSubtle",
+      flexDirection: "row",
+      alignItems: "center",
+      gap: "xs",
+      paddingHorizontal: "lg", // 16px from spacing tokens
+    },
+    primary: {
+      backgroundColor: "surfacePrimary",
+      borderBottomWidth: 1,
+      borderBottomColor: "borderSubtle",
+    },
+    transparent: {
+      backgroundColor: "transparent",
+      borderBottomWidth: 0,
+    },
+    elevated: {
+      backgroundColor: "surfaceElevated",
+      borderBottomWidth: 0,
+    },
+  },
+  // Header sizes
+  // Content height only - safe area inset is added at runtime
+  // - sm (44px): Compact headers, modals - matches iOS minimum touch target
+  // - md (56px): Standard navigation, phone default
+  // - lg (64px): Prominent headers, tablet default
+  headerSizes: {
+    defaults: {
+      height: 56,
+    },
+    sm: {
+      height: 44,
+    },
+    md: {
+      height: 56,
+    },
+    lg: {
+      height: 64,
+    },
+  },
+  // Icon sizes
+  // Scale: 12 → 16 → 20 → 24 (+4px) → 32 → 40 → 48 (+8px)
+  // Smaller icons need finer control; larger icons can have bigger jumps
+  // - xs (12px): Badges, inline text indicators, status dots
+  // - sm (16px): Compact buttons, dense lists, checkbox icons (sm)
+  // - md (20px): Phone default, standard buttons, checkbox icons (md)
+  // - lg (24px): Primary actions, phone headers, checkbox icons (lg)
+  // - xl (32px): Tablet headers, emphasized actions
+  // - 2xl (40px): Empty states, onboarding illustrations
+  // - 3xl (48px): Hero sections, large feature illustrations
+  iconSizes: {
+    defaults: {
+      width: 20,
+      height: 20,
+    },
+    xs: {
+      width: 12,
+      height: 12,
+    },
+    sm: {
+      width: 16,
+      height: 16,
+    },
+    md: {
+      width: 20,
+      height: 20,
+    },
+    lg: {
+      width: 24,
+      height: 24,
+    },
+    xl: {
+      width: 32,
+      height: 32,
+    },
+    "2xl": {
+      width: 40,
+      height: 40,
+    },
+    "3xl": {
+      width: 48,
+      height: 48,
+    },
+  },
+  // IconButton variants (visual styles)
+  iconButtonVariants: {
+    defaults: {
+      borderRadius: "full",
+      borderWidth: 0,
+      backgroundColor: "accentPrimary", // Default to contained style
+      borderColor: "transparent",
+    },
+    contained: {
+      borderRadius: "full",
+      borderWidth: 0,
+      backgroundColor: "accentPrimary", // Default background, can be overridden via style prop
+      borderColor: "transparent",
+    },
+    outlined: {
+      borderRadius: "full",
+      borderWidth: 2,
+      backgroundColor: "transparent",
+      borderColor: "accentPrimary", // Default border color, can be overridden via style prop
+    },
+    ghost: {
+      borderRadius: "full",
+      borderWidth: 0,
+      backgroundColor: "transparent",
+      borderColor: "transparent",
+    },
+  },
+  // ==========================================================================
+  // ICON BUTTON SIZES
+  // ==========================================================================
+  // Mathematical relationship: Icon = Container × ~45% (circularButton ratio)
+  //
+  // | Size | Container | Icon | Ratio | hitSlop | Touch Target |
+  // |------|-----------|------|-------|---------|--------------|
+  // | sm   | 36px      | 16px | 44%   | 4px     | 44px         |
+  // | md   | 44px      | 20px | 45%   | 0px     | 44px         |
+  // | lg   | 56px      | 24px | 43%   | 0px     | 56px         |
+  //
+  // Ghost variant uses icon size for hitSlop calculation:
+  // | Size | Icon | hitSlop | Touch Target |
+  // |------|------|---------|--------------|
+  // | sm   | 16px | 14px    | 44px         |
+  // | md   | 20px | 12px    | 44px         |
+  // | lg   | 24px | 10px    | 44px         |
+  //
+  // See: tokens/scales.ts ICON_BUTTON_ICON_SIZE, ICON_BUTTON_HIT_SLOP
+  iconButtonSizes: {
+    defaults: {
+      width: 44,
+      height: 44,
+      alignItems: "center",
+      justifyContent: "center",
+    },
+    sm: {
+      width: 36,
+      height: 36,
+    },
+    md: {
+      width: 44,
+      height: 44,
+    },
+    lg: {
+      width: 56,
+      height: 56,
+    },
+  },
+  // ==========================================================================
+  // PROGRESS BAR SIZES
+  // ==========================================================================
+  // Height scales for progress bar track
+  //
+  // | Size | Height | Border Radius | Use Case |
+  // |------|--------|---------------|----------|
+  // | sm   | 4px    | 2px           | Inline, compact indicators |
+  // | md   | 8px    | 4px           | Standard progress bars |
+  // | lg   | 12px   | 6px           | Prominent indicators |
+  //
+  // See: ProgressBar.helpers.ts PROGRESS_BAR_HEIGHTS
+  progressBarSizes: {
+    defaults: {
+      height: 8,
+      width: "100%",
+    },
+    sm: {
+      height: 4,
+    },
+    md: {
+      height: 8,
+    },
+    lg: {
+      height: 12,
+    },
+  },
+  // NOTE: progressBarVariants removed — ProgressBar now accepts a `color` prop
+  // (RestyleColor) instead of a variant key. Track background is always "borderSubtle".
+  // ==========================================================================
+  // SPINNER SIZES
+  // ==========================================================================
+  // Maps to React Native ActivityIndicator sizes
+  //
+  // | Size | ActivityIndicator | Use Case |
+  // |------|-------------------|----------|
+  // | sm   | "small"           | Inline loading, buttons |
+  // | lg   | "large"           | Full-screen loading, cards |
+  spinnerSizes: {
+    defaults: {},
+    sm: {},
+    lg: {},
+  },
+  // ==========================================================================
+  // AVATAR SIZES
+  // ==========================================================================
+  // Profile images with fallback initials following 8px grid
+  //
+  // | Size | Dimensions | Font | Use Case |
+  // |------|------------|------|----------|
+  // | sm   | 32×32      | 12px | Compact lists, comments |
+  // | md   | 40×40      | 14px | Standard avatar (default) |
+  // | lg   | 56×56      | 20px | Profile headers, featured |
+  avatarSizes: {
+    defaults: {
+      borderRadius: "full",
+      alignItems: "center",
+      justifyContent: "center",
+    },
+    sm: {
+      width: 32,
+      height: 32,
+    },
+    md: {
+      width: 40,
+      height: 40,
+    },
+    lg: {
+      width: 56,
+      height: 56,
+    },
+  },
+  // ==========================================================================
+  // SKELETON VARIANTS
+  // ==========================================================================
+  // Shape variants for Skeleton. Actual border-radius/dimension logic
+  // is resolved in Skeleton.helpers.ts; keys establish the type contract.
+  //
+  // | Variant      | Shape             | Use Case |
+  // |--------------|-------------------|----------|
+  // | text         | Rounded rectangle | Text placeholders |
+  // | circular     | Circle            | Avatar/icon placeholders |
+  // | rectangular  | Sharp corners     | Image/card placeholders |
+  skeletonVariants: {
+    defaults: {},
+    text: {},
+    circular: {},
+    rectangular: {},
+  },
+  // ==========================================================================
+  // SKELETON SIZES
+  // ==========================================================================
+  // Size presets for Skeleton. Actual dimensions vary by variant
+  // and are resolved in Skeleton.helpers.ts.
+  //
+  // | Size | Text Height | Circular | Rectangular | Use Case |
+  // |------|-------------|----------|-------------|----------|
+  // | sm   | 16px        | 32px     | 80px        | Compact elements |
+  // | md   | 20px        | 48px     | 120px       | Standard content |
+  // | lg   | 28px        | 64px     | 160px       | Headings/prominent |
+  skeletonSizes: {
+    defaults: {},
+    sm: {},
+    md: {},
+    lg: {},
+  },
+  // ==========================================================================
+  // CHIP SIZES
+  // ==========================================================================
+  // Compact elements for tags, filters, and selections
+  // Professional sizing: 28/32/40px with optimal density-to-usability ratio
+  //
+  // | Size | Height | Padding H | Icon | Text Variant | Use Case |
+  // |------|--------|-----------|------|--------------|----------|
+  // | sm   | 28px   | sm (8px)  | xs   | captionSmall | Dense UIs, compact tags |
+  // | md   | 32px   | md (12px) | sm   | labelSmall   | Standard (default) |
+  // | lg   | 40px   | lg (16px) | md   | labelMedium  | Prominent filters |
+  chipSizes: {
+    defaults: {
+      borderRadius: "full",
+      alignItems: "center",
+      justifyContent: "center",
+      flexDirection: "row",
+      gap: "xs",
+    },
+    sm: {
+      height: 28,
+      paddingHorizontal: "sm",
+    },
+    md: {
+      height: 32,
+      paddingHorizontal: "md",
+    },
+    lg: {
+      height: 40,
+      paddingHorizontal: "lg",
+    },
+  },
+  // Chip variants - visual styles (colors handled dynamically via logic hook)
+  chipVariants: {
+    defaults: {
+      borderRadius: "full",
+      borderWidth: 0,
+    },
+    filled: {
+      borderWidth: 0,
+    },
+    outlined: {
+      borderWidth: 1.5,
+      backgroundColor: "transparent",
+    },
+  },
+  // ==========================================================================
+  // BADGE SIZES
+  // ==========================================================================
+  // Compact status indicators, counts, and labels
+  // Heights follow 4px grid: 16/20/24px for visual consistency
+  //
+  // | Size | Height | Min Width | Dot Size | Padding H | Use Case |
+  // |------|--------|-----------|----------|-----------|----------|
+  // | sm   | 16px   | 16px      | 6px      | 2xs (2px) | Inline indicators |
+  // | md   | 20px   | 20px      | 8px      | xs (4px)  | Standard (default) |
+  // | lg   | 24px   | 24px      | 10px     | sm (8px)  | Prominent badges |
+  badgeSizes: {
+    defaults: {
+      borderRadius: "full",
+      alignItems: "center",
+      justifyContent: "center",
+    },
+    sm: {
+      height: 16,
+      minWidth: 16,
+      paddingHorizontal: "2xs",
+    },
+    md: {
+      height: 20,
+      minWidth: 20,
+      paddingHorizontal: "xs",
+    },
+    lg: {
+      height: 24,
+      minWidth: 24,
+      paddingHorizontal: "sm",
+    },
+  },
+  // Badge variants - visual styles (colors handled dynamically via logic hook)
+  badgeVariants: {
+    defaults: {
+      borderRadius: "full",
+      borderWidth: 0,
+    },
+    filled: {
+      borderWidth: 0,
+    },
+    outlined: {
+      borderWidth: 1.5,
+      backgroundColor: "transparent",
+    },
+  },
+  // ==========================================================================
+  // LIST ITEM SIZES
+  // ==========================================================================
+  // Flexible list item with leading/trailing content slots
+  //
+  // | Size | Min Height | Padding V | Padding H | Use Case |
+  // |------|------------|-----------|-----------|----------|
+  // | sm   | 44px       | xs (4px)  | md (12px) | Compact lists, dense UIs |
+  // | md   | 56px       | sm (8px)  | md (12px) | Standard (default) |
+  // | lg   | 72px       | md (12px) | lg (16px) | Prominent items, settings |
+  listItemSizes: {
+    defaults: {
+      minHeight: 56,
+      paddingHorizontal: "md",
+      paddingVertical: "sm",
+    },
+    sm: {
+      minHeight: 44,
+      paddingHorizontal: "md",
+      paddingVertical: "xs",
+    },
+    md: {
+      minHeight: 56,
+      paddingHorizontal: "md",
+      paddingVertical: "sm",
+    },
+    lg: {
+      minHeight: 72,
+      paddingHorizontal: "lg",
+      paddingVertical: "md",
+    },
+  },
+  // ==========================================================================
+  // TOAST VARIANTS
+  // ==========================================================================
+  // Toast notifications for user feedback
+  // Consistent 48px min-height for comfortable reading and touch dismissal
+  //
+  // | Variant | Use Case |
+  // |---------|----------|
+  // | success | Positive feedback, operation completed |
+  // | error   | Error state, operation failed |
+  // | warning | Caution, potential issue |
+  // | info    | Informational message |
+  //
+  // Colors are applied dynamically via component logic for theme awareness
+  toastVariants: {
+    defaults: {
+      borderRadius: "md",
+      borderWidth: 1,
+      padding: "sm",
+      flexDirection: "row",
+      alignItems: "center",
+      gap: "sm",
+      minHeight: 48,
+    },
+    success: {},
+    error: {},
+    warning: {},
+    info: {},
+  },
+  // ==========================================================================
+  // DIVIDER VARIANTS
+  // ==========================================================================
+  // Visual separators for content sections
+  //
+  // | Variant | Color | Use Case |
+  // |---------|-------|----------|
+  // | subtle  | borderSubtle | Light separation (default) |
+  // | default | borderDefault | Standard separation |
+  // | strong  | borderStrong | Prominent separation |
+  dividerVariants: {
+    defaults: {},
+    subtle: {
+      backgroundColor: "borderSubtle",
+    },
+    default: {
+      backgroundColor: "borderDefault",
+    },
+    strong: {
+      backgroundColor: "borderStrong",
+    },
+  },
+  // Divider thickness sizes
+  dividerSizes: {
+    defaults: {},
+    thin: {
+      height: 1,
+    },
+    medium: {
+      height: 2,
+    },
+    thick: {
+      height: 4,
+    },
+  },
+  // ==========================================================================
+  // CALENDAR STRIP SIZES
+  // ==========================================================================
+  // Horizontal row of tappable day cards
+  //
+  // | Size | Container Gap | Day Padding V | Day Number  | Label       |
+  // |------|---------------|---------------|-------------|-------------|
+  // | sm   | xs (4px)      | xs (4px)      | labelSmall  | captionSmall|
+  // | md   | md (12px)     | md (12px)     | labelMedium | captionSmall|
+  // | lg   | lg (16px)     | lg (16px)     | labelLarge  | caption     |
+  // ScheduleItem sizes
+  // | Size | Padding | Indicator H | Content Gap | Title       | Time         |
+  // | sm   | xs      | 32px        | 2xs         | labelSmall  | captionSmall |
+  // | md   | sm      | 48px        | 2xs         | labelSmall  | captionSmall |
+  // | lg   | md      | 64px        | xs          | labelMedium | bodySmall    |
+  scheduleItemSizes: {
+    defaults: {
+      flexDirection: "row",
+      alignItems: "center",
+      borderRadius: "sm",
+      backgroundColor: "backgroundSecondary",
+      gap: "sm",
+    },
+    sm: { padding: "xs" },
+    md: { padding: "sm" },
+    lg: { padding: "md" },
+  },
+
+  calendarStripSizes: {
+    defaults: {
+      flexDirection: "row",
+    },
+    sm: {
+      gap: "xs",
+    },
+    md: {
+      gap: "md",
+    },
+    lg: {
+      gap: "lg",
+    },
+  },
+  // ==========================================================================
+  // EMPTY STATE SIZES
+  // ==========================================================================
+  // Centered empty state layouts
+  //
+  // | Variant | Icon Size | Title | Description | Padding | Use Case |
+  // |---------|-----------|-------|-------------|---------|----------|
+  // | default | xl (32px) | headingSmall | bodyMedium | xl | Full-page states |
+  // | compact | lg (24px) | labelLarge | bodySmall | lg | Card/section states |
+  emptyStateSizes: {
+    defaults: {
+      alignItems: "center",
+      justifyContent: "center",
+      flex: 1,
+    },
+    default: {
+      padding: "xl",
+      gap: "lg",
+    },
+    compact: {
+      padding: "lg",
+      gap: "md",
+    },
+  },
+  // ==========================================================================
+  // EMPTY STATE VARIANTS
+  // ==========================================================================
+  // Visual style variants for EmptyState. Layout dimensions live in
+  // emptyStateSizes above; keys here provide the variant type contract
+  // so EmptyStateVariant derives from the theme.
+  //
+  // | Variant | Padding | Gap | Title        | Description  | Use Case |
+  // |---------|---------|-----|--------------|--------------|----------|
+  // | default | xl      | lg  | headingSmall | bodyMedium   | Full-page states |
+  // | compact | lg      | md  | labelLarge   | bodySmall    | Card/section states |
+  emptyStateVariants: {
+    defaults: {},
+    default: {},
+    compact: {},
+  },
+  // ==========================================================================
+  // SEGMENTED CONTROL SIZES
+  // ==========================================================================
+  // Toggle between multiple options - professional sizing with 44px touch target
+  // Container heights: 36/44/52px matching button scale for visual harmony
+  //
+  // | Size | Height | Segment H | Padding | Gap | Text Variant | Use Case |
+  // |------|--------|-----------|---------|-----|--------------|----------|
+  // | sm   | 36px   | 28px      | xs      | 2xs | labelSmall   | Compact filters |
+  // | md   | 44px   | 36px      | xs      | 2xs | labelMedium  | Standard (default) |
+  // | lg   | 52px   | 44px      | sm      | xs  | labelLarge   | Prominent controls |
+  segmentedControlSizes: {
+    defaults: {
+      borderRadius: "lg",
+      flexDirection: "row",
+      alignItems: "center",
+    },
+    sm: {
+      height: 36,
+      padding: "xs",
+      gap: "2xs",
+    },
+    md: {
+      height: 44,
+      padding: "xs",
+      gap: "2xs",
+    },
+    lg: {
+      height: 52,
+      padding: "sm",
+      gap: "xs",
+    },
+  },
+  // Segmented control segment sizes (inner segment dimensions)
+  segmentedControlSegmentSizes: {
+    defaults: {
+      borderRadius: "md",
+      alignItems: "center",
+      justifyContent: "center",
+      flex: 1,
+    },
+    sm: {
+      height: 28,
+      paddingHorizontal: "sm",
+    },
+    md: {
+      height: 36,
+      paddingHorizontal: "md",
+    },
+    lg: {
+      height: 44,
+      paddingHorizontal: "lg",
+    },
+  },
+  // Segmented control variants - visual styles for container
+  segmentedControlVariants: {
+    defaults: {
+      borderRadius: "lg",
+      borderWidth: 0,
+    },
+    default: {
+      backgroundColor: "backgroundTertiary",
+      borderWidth: 0,
+    },
+    outline: {
+      backgroundColor: "transparent",
+      borderWidth: 1.5,
+      borderColor: "borderDefault",
+    },
+  },
+});
+
+// =============================================================================
+// RESTYLE THEMES
+// =============================================================================
+
+export const restyleLightTheme = createTheme(
+  createBaseThemeConfig(lightColors),
+);
+export const restyleDarkTheme = createTheme(createBaseThemeConfig(darkColors));
+
+// Default export for backwards compatibility
+export const restyleTheme = restyleLightTheme;
+
+export type RestyleTheme = typeof restyleLightTheme;
+
+/**
+ * Augmentable interface for app-specific color tokens.
+ *
+ * Apps extend the design system palette by augmenting this interface
+ * via TypeScript declaration merging. Once augmented, the new color
+ * token names are accepted by components whose color prop uses
+ * `AppThemeColors` (e.g. Chip).
+ *
+ * @example
+ * ```ts
+ * // app-theme.d.ts  (in your app, NOT in the package)
+ * declare module "@praxiis/ui" {
+ *   interface AppThemeColors {
+ *     brandOrange: string;
+ *     brandTeal: string;
+ *   }
+ * }
+ * ```
+ *
+ * At runtime, provide a theme with matching color keys via
+ * `<DesignSystemProvider lightTheme={...} darkTheme={...}>`.
+ */
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface AppThemeColors {}
+
+/**
+ * Build a Restyle theme entirely from scratch.
+ *
+ * Use this when you want to define every color yourself with no defaults merged in.
+ * Provide a complete SemanticColors object (same shape as lightSemanticColors /
+ * darkSemanticColors) and get back a fully configured RestyleTheme.
+ *
+ * @example
+ * const myLight = buildRestyleTheme({ background: { primary: '#fff', ... }, ... });
+ */
+export function buildRestyleTheme(
+  colors: SemanticColorsInput,
+): typeof restyleLightTheme {
+  return createTheme(createBaseThemeConfig(flattenColors(colors)));
+}
+
+/**
+ * Build a Restyle theme from ThemeColors overrides.
+ * Merges overrides into the base semantic colors, keeping base primitives intact.
+ */
+export function buildRestyleThemeFromThemeColors(
+  baseSemanticColors: SemanticColorsInput,
+  overrides: DeepPartial<ThemeColors>,
+): typeof restyleLightTheme {
+  const merged = {
+    ...baseSemanticColors,
+    background: { ...baseSemanticColors.background, ...overrides.background },
+    surface: { ...baseSemanticColors.surface, ...overrides.surface },
+    text: { ...baseSemanticColors.text, ...overrides.text },
+    border: { ...baseSemanticColors.border, ...overrides.border },
+    accent: { ...baseSemanticColors.accent, ...overrides.accent },
+    interactive: {
+      ...baseSemanticColors.interactive,
+      ...overrides.interactive,
+    },
+    feedback: { ...baseSemanticColors.feedback, ...overrides.feedback },
+    special: { ...baseSemanticColors.special, ...overrides.special },
+  };
+  return createTheme(createBaseThemeConfig(flattenColors(merged)));
+}