@praxiis/ui 0.0.1

package/src/tokens/radii.ts

@@ -0,0 +1,82 @@
+/**
+ * StayEasy Design System - Border Radius Tokens
+ *
+ * Philosophy: Rounded but not bubbly.
+ * Friendly corners that feel premium, not childish.
+ *
+ * @example
+ * borderRadius: theme.radii.md // 12
+ */
+
+// =============================================================================
+// BORDER RADIUS SCALE
+// =============================================================================
+
+export const radii = {
+  /** 0 - Sharp corners */
+  none: 0,
+
+  /** 4 - Subtle rounding */
+  xs: 4,
+
+  /** 8 - Light rounding */
+  sm: 8,
+
+  /** 12 - Standard rounding (most common) */
+  md: 12,
+
+  /** 16 - Generous rounding */
+  lg: 16,
+
+  /** 20 - Large rounding */
+  xl: 20,
+
+  /** 24 - Extra large rounding */
+  '2xl': 24,
+
+  /** 32 - Very large rounding */
+  '3xl': 32,
+
+  /** 9999 - Full/pill rounding */
+  full: 9999,
+} as const;
+
+// =============================================================================
+// SEMANTIC RADII
+// =============================================================================
+
+export const semanticRadii = {
+  /** Buttons - friendly but not too soft */
+  button: radii.md, // 12
+
+  /** Input fields - matches buttons */
+  input: radii.md, // 12
+
+  /** Cards - generous for premium feel */
+  card: radii.lg, // 16
+
+  /** Modals - prominent rounding */
+  modal: radii.xl, // 20
+
+  /** Bottom sheets - very rounded top */
+  sheet: radii['2xl'], // 24
+
+  /** Chips/badges - pill-like */
+  chip: radii.full, // 9999
+
+  /** Avatars - circular */
+  avatar: radii.full, // 9999
+
+  /** Image thumbnails */
+  thumbnail: radii.md, // 12
+
+  /** Toast notifications */
+  toast: radii.md, // 12
+} as const;
+
+// =============================================================================
+// TYPE EXPORTS
+// =============================================================================
+
+export type Radii = typeof radii;
+export type RadiiKey = keyof typeof radii;

package/src/tokens/scales.ts

@@ -0,0 +1,588 @@
+/**
+ * El Sendero Design System - Scale Tokens
+ *
+ * Defines mathematical relationships between component sizes.
+ * All ratios are explicitly documented to prevent magic numbers.
+ *
+ * @example
+ * import { ICON_BUTTON_ICON_SIZE, calculateHitSlop } from '@/design-system/tokens/scales';
+ */
+
+// =============================================================================
+// ICON RATIO CONSTANTS
+// =============================================================================
+
+/**
+ * Icon-to-container ratios for different component types.
+ * These ensure visual consistency across the design system.
+ *
+ * Design Rationale:
+ * - Circular buttons need breathing room for touch feedback ripples
+ * - Toggle controls need maximum icon visibility within compact containers
+ * - Text-adjacent icons should match the text visual weight
+ */
+export const ICON_RATIOS = {
+  /**
+   * Circular button ratio (~45%)
+   * Used by: IconButton
+   * Provides breathing room for touch feedback ripples
+   */
+  circularButton: 0.45,
+
+  /**
+   * Toggle control ratio (~75%)
+   * Used by: Checkbox, Radio
+   * Maximizes icon visibility within compact container
+   */
+  toggleControl: 0.75,
+
+  /**
+   * Text-adjacent ratio (100%)
+   * Used by: Button with icon, TextInput icons
+   * Icon matches the text visual weight
+   */
+  textAdjacent: 1.0,
+} as const;
+
+// =============================================================================
+// COMPONENT SIZE SCALES
+// =============================================================================
+
+/**
+ * Unified container size scale (in pixels)
+ * All interactive button components use this scale.
+ *
+ * | Size | Pixels | Use Case |
+ * |------|--------|----------|
+ * | sm   | 36     | Dense UIs, secondary actions |
+ * | md   | 44     | Default (meets Apple HIG 44px touch target) |
+ * | lg   | 56     | Tablets, high-emphasis actions |
+ */
+export const CONTAINER_SIZES = {
+  sm: 36,
+  md: 44,
+  lg: 56,
+} as const;
+
+/**
+ * Button heights (slightly different scale for text buttons)
+ *
+ * | Size | Pixels | Use Case |
+ * |------|--------|----------|
+ * | sm   | 36     | Dense forms, secondary actions |
+ * | md   | 44     | Default mobile buttons |
+ * | lg   | 52     | Primary CTAs, prominent actions |
+ */
+export const BUTTON_HEIGHTS = {
+  sm: 36,
+  md: 44,
+  lg: 52,
+} as const;
+
+/**
+ * Toggle control container sizes (compact scale for form controls)
+ *
+ * | Size | Pixels | Use Case |
+ * |------|--------|----------|
+ * | sm   | 20     | Dense forms, compact UI |
+ * | md   | 24     | Default mobile checkboxes |
+ * | lg   | 32     | Tablets, accessibility focus |
+ */
+export const TOGGLE_CONTAINER_SIZES = {
+  sm: 20,
+  md: 24,
+  lg: 32,
+} as const;
+
+// =============================================================================
+// ICON SIZE VALUES (in pixels)
+// =============================================================================
+
+/**
+ * Icon size scale in pixels.
+ * Mirrors the iconSizes theme values for calculations.
+ */
+export const ICON_PIXEL_SIZES = {
+  xs: 12,
+  sm: 16,
+  md: 20,
+  lg: 24,
+  xl: 32,
+  "2xl": 40,
+  "3xl": 48,
+} as const;
+
+// =============================================================================
+// DERIVED ICON SIZE MAPPINGS
+// =============================================================================
+
+type ComponentSize = "sm" | "md" | "lg";
+type IconSizeKey = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+
+/**
+ * IconButton: Container -> Icon mapping
+ *
+ * Uses ~45% ratio (ICON_RATIOS.circularButton)
+ *
+ * | Size | Container | Icon   | Actual Ratio |
+ * |------|-----------|--------|--------------|
+ * | sm   | 36px      | 16px   | 44%          |
+ * | md   | 44px      | 20px   | 45%          |
+ * | lg   | 56px      | 24px   | 43%          |
+ */
+export const ICON_BUTTON_ICON_SIZE: Record<ComponentSize, IconSizeKey> = {
+  sm: "sm", // 16px / 36px = 44%
+  md: "md", // 20px / 44px = 45%
+  lg: "lg", // 24px / 56px = 43%
+} as const;
+
+/**
+ * Checkbox: Container -> Icon mapping
+ *
+ * Uses ~75% ratio (ICON_RATIOS.toggleControl)
+ *
+ * | Size | Container | Icon   | Actual Ratio |
+ * |------|-----------|--------|--------------|
+ * | sm   | 20px      | 16px   | 80%          |
+ * | md   | 24px      | 20px   | 83%          |
+ * | lg   | 32px      | 24px   | 75%          |
+ */
+export const CHECKBOX_ICON_SIZE: Record<ComponentSize, IconSizeKey> = {
+  sm: "sm", // 16px / 20px = 80%
+  md: "md", // 20px / 24px = 83%
+  lg: "lg", // 24px / 32px = 75%
+} as const;
+
+/**
+ * Button: Size -> Icon mapping (text-adjacent)
+ *
+ * Icons match label visual weight for optical balance.
+ *
+ * | Size | Height | Icon   | Text Variant |
+ * |------|--------|--------|--------------|
+ * | sm   | 36px   | 16px   | labelSmall   |
+ * | md   | 44px   | 20px   | labelMedium  |
+ * | lg   | 52px   | 24px   | labelLarge   |
+ */
+export const BUTTON_ICON_SIZE: Record<ComponentSize, IconSizeKey> = {
+  sm: "sm", // 16px
+  md: "md", // 20px
+  lg: "lg", // 24px
+} as const;
+
+/**
+ * TextInput: Size -> Icon mapping
+ *
+ * Icons match input text size for visual harmony.
+ *
+ * | Size | Icon   |
+ * |------|--------|
+ * | sm   | 16px   |
+ * | md   | 20px   |
+ * | lg   | 24px   |
+ */
+export const TEXT_INPUT_ICON_SIZE: Record<ComponentSize, IconSizeKey> = {
+  sm: "sm",
+  md: "md",
+  lg: "lg",
+} as const;
+
+// =============================================================================
+// SWITCH SPECIFIC SCALES
+// =============================================================================
+
+/**
+ * Switch thumb inset in pixels.
+ * This is the padding between the track edge and the thumb.
+ * Total thumb padding = inset * 2 (both sides)
+ *
+ * Derived from the 2xs spacing token (2px) for consistency.
+ */
+export const SWITCH_THUMB_INSET = 2;
+
+/**
+ * Switch dimension definitions.
+ *
+ * Track width:height ratio is maintained at approximately 1.7:1
+ * Thumb size is calculated as: trackHeight - (SWITCH_THUMB_INSET * 2)
+ *
+ * | Size | Track W | Track H | Thumb | W:H Ratio |
+ * |------|---------|---------|-------|-----------|
+ * | sm   | 40px    | 24px    | 20px  | 1.67:1    |
+ * | md   | 48px    | 28px    | 24px  | 1.71:1    |
+ * | lg   | 56px    | 32px    | 28px  | 1.75:1    |
+ */
+export const SWITCH_DIMENSIONS: Record<
+  ComponentSize,
+  { trackWidth: number; trackHeight: number }
+> = {
+  sm: { trackWidth: 40, trackHeight: 24 },
+  md: { trackWidth: 48, trackHeight: 28 },
+  lg: { trackWidth: 56, trackHeight: 32 },
+} as const;
+
+/**
+ * Calculate switch thumb size from track height.
+ * Uses SWITCH_THUMB_INSET to maintain consistent padding.
+ *
+ * @param trackHeight - The track height in pixels
+ * @returns The thumb diameter in pixels
+ */
+export function calculateSwitchThumbSize(trackHeight: number): number {
+  return trackHeight - SWITCH_THUMB_INSET * 2;
+}
+
+// =============================================================================
+// TOUCH TARGET UTILITIES
+// =============================================================================
+
+/**
+ * Minimum touch target size per Apple Human Interface Guidelines.
+ * All interactive elements should have at least 44x44px touch area.
+ */
+export const MIN_TOUCH_TARGET = 44;
+
+/**
+ * Calculate hitSlop needed to reach minimum touch target.
+ *
+ * This function ensures all interactive elements meet the 44px
+ * minimum touch target requirement, regardless of their visual size.
+ *
+ * @param visualSize - The visual size of the element in pixels
+ * @returns Insets object to expand the touch target
+ *
+ * @example
+ * // 36px button needs 4px padding each side to reach 44px
+ * calculateHitSlop(36) // { top: 4, bottom: 4, left: 4, right: 4 }
+ *
+ * // 44px button already meets target
+ * calculateHitSlop(44) // { top: 0, bottom: 0, left: 0, right: 0 }
+ */
+export function calculateHitSlop(visualSize: number): {
+  top: number;
+  bottom: number;
+  left: number;
+  right: number;
+} {
+  if (visualSize >= MIN_TOUCH_TARGET) {
+    return { top: 0, bottom: 0, left: 0, right: 0 };
+  }
+
+  const padding = Math.ceil((MIN_TOUCH_TARGET - visualSize) / 2);
+  return { top: padding, bottom: padding, left: padding, right: padding };
+}
+
+/**
+ * Pre-calculated hitSlop for IconButton container sizes.
+ * Uses calculateHitSlop internally.
+ *
+ * | Size | Container | hitSlop | Total Touch Area |
+ * |------|-----------|---------|------------------|
+ * | sm   | 36px      | 4px     | 44px             |
+ * | md   | 44px      | 0px     | 44px             |
+ * | lg   | 56px      | 0px     | 56px             |
+ */
+export const ICON_BUTTON_HIT_SLOP: Record<
+  ComponentSize,
+  { top: number; bottom: number; left: number; right: number }
+> = {
+  sm: calculateHitSlop(CONTAINER_SIZES.sm),
+  md: calculateHitSlop(CONTAINER_SIZES.md),
+  lg: calculateHitSlop(CONTAINER_SIZES.lg),
+} as const;
+
+/**
+ * Pre-calculated hitSlop for Checkbox container sizes.
+ *
+ * | Size | Container | hitSlop | Total Touch Area |
+ * |------|-----------|---------|------------------|
+ * | sm   | 20px      | 12px    | 44px             |
+ * | md   | 24px      | 10px    | 44px             |
+ * | lg   | 32px      | 6px     | 44px             |
+ */
+export const CHECKBOX_HIT_SLOP: Record<
+  ComponentSize,
+  { top: number; bottom: number; left: number; right: number }
+> = {
+  sm: calculateHitSlop(TOGGLE_CONTAINER_SIZES.sm),
+  md: calculateHitSlop(TOGGLE_CONTAINER_SIZES.md),
+  lg: calculateHitSlop(TOGGLE_CONTAINER_SIZES.lg),
+} as const;
+
+/**
+ * RadioButton inner dot size mapping.
+ *
+ * Uses ~40% ratio of container for the inner filled dot.
+ *
+ * | Size | Container | Inner Dot | Actual Ratio |
+ * |------|-----------|-----------|--------------|
+ * | sm   | 20px      | 8px       | 40%          |
+ * | md   | 24px      | 10px      | 42%          |
+ * | lg   | 32px      | 14px      | 44%          |
+ */
+export const RADIO_BUTTON_INNER_SIZE: Record<ComponentSize, number> = {
+  sm: 8,
+  md: 10,
+  lg: 14,
+} as const;
+
+/**
+ * Pre-calculated hitSlop for RadioButton container sizes.
+ * Same as Checkbox (uses TOGGLE_CONTAINER_SIZES).
+ *
+ * | Size | Container | hitSlop | Total Touch Area |
+ * |------|-----------|---------|------------------|
+ * | sm   | 20px      | 12px    | 44px             |
+ * | md   | 24px      | 10px    | 44px             |
+ * | lg   | 32px      | 6px     | 44px             |
+ */
+export const RADIO_BUTTON_HIT_SLOP: Record<
+  ComponentSize,
+  { top: number; bottom: number; left: number; right: number }
+> = {
+  sm: calculateHitSlop(TOGGLE_CONTAINER_SIZES.sm),
+  md: calculateHitSlop(TOGGLE_CONTAINER_SIZES.md),
+  lg: calculateHitSlop(TOGGLE_CONTAINER_SIZES.lg),
+} as const;
+
+/**
+ * Pre-calculated hitSlop for Switch track (uses height for calculation).
+ *
+ * | Size | Track H | hitSlop | Total Touch Area |
+ * |------|---------|---------|------------------|
+ * | sm   | 24px    | 10px    | 44px             |
+ * | md   | 28px    | 8px     | 44px             |
+ * | lg   | 32px    | 6px     | 44px             |
+ */
+export const SWITCH_HIT_SLOP: Record<
+  ComponentSize,
+  { top: number; bottom: number; left: number; right: number }
+> = {
+  sm: calculateHitSlop(SWITCH_DIMENSIONS.sm.trackHeight),
+  md: calculateHitSlop(SWITCH_DIMENSIONS.md.trackHeight),
+  lg: calculateHitSlop(SWITCH_DIMENSIONS.lg.trackHeight),
+} as const;
+
+/**
+ * hitSlop for ghost IconButton variant.
+ * Since ghost has no container, we use the icon visual size.
+ *
+ * | Size | Icon   | hitSlop | Total Touch Area |
+ * |------|--------|---------|------------------|
+ * | sm   | 16px   | 14px    | 44px             |
+ * | md   | 20px   | 12px    | 44px             |
+ * | lg   | 24px   | 10px    | 44px             |
+ */
+export const GHOST_ICON_BUTTON_HIT_SLOP: Record<
+  ComponentSize,
+  { top: number; bottom: number; left: number; right: number }
+> = {
+  sm: calculateHitSlop(ICON_PIXEL_SIZES.sm),
+  md: calculateHitSlop(ICON_PIXEL_SIZES.md),
+  lg: calculateHitSlop(ICON_PIXEL_SIZES.lg),
+} as const;
+
+// =============================================================================
+// SPINNER SIZE MAPPING
+// =============================================================================
+
+/**
+ * Spinner size mapping - consistent across all components.
+ *
+ * | Component Size | Spinner Size |
+ * |----------------|--------------|
+ * | sm             | sm           |
+ * | md             | sm           |
+ * | lg             | lg           |
+ */
+export const SPINNER_SIZE: Record<ComponentSize, "sm" | "lg"> = {
+  sm: "sm",
+  md: "sm",
+  lg: "lg",
+} as const;
+
+// =============================================================================
+// TEXT VARIANT MAPPINGS
+// =============================================================================
+
+type TextVariantKey =
+  | "labelSmall"
+  | "labelMedium"
+  | "labelLarge"
+  | "bodySmall"
+  | "bodyMedium"
+  | "bodyLarge";
+
+/**
+ * Button text variant mapping.
+ *
+ * | Button Size | Text Variant |
+ * |-------------|--------------|
+ * | sm          | labelSmall   |
+ * | md          | labelMedium  |
+ * | lg          | labelLarge   |
+ */
+export const BUTTON_TEXT_VARIANT: Record<ComponentSize, TextVariantKey> = {
+  sm: "labelSmall",
+  md: "labelMedium",
+  lg: "labelLarge",
+} as const;
+
+// =============================================================================
+// PROGRESS BAR SIZE MAPPING
+// =============================================================================
+
+/**
+ * Progress bar height mapping.
+ *
+ * | Size | Height |
+ * |------|--------|
+ * | sm   | 4px    |
+ * | md   | 8px    |
+ * | lg   | 12px   |
+ */
+export const PROGRESS_BAR_HEIGHTS: Record<ComponentSize, number> = {
+  sm: 4,
+  md: 8,
+  lg: 12,
+} as const;
+
+/**
+ * Progress bar border radius mapping.
+ * Uses half of height for pill shape.
+ *
+ * | Size | Radius |
+ * |------|--------|
+ * | sm   | 2px    |
+ * | md   | 4px    |
+ * | lg   | 6px    |
+ */
+export const PROGRESS_BAR_BORDER_RADIUS: Record<ComponentSize, number> = {
+  sm: 2,
+  md: 4,
+  lg: 6,
+} as const;
+
+// =============================================================================
+// ANIMATION TOKENS
+// =============================================================================
+
+/**
+ * Animation spring configuration tokens.
+ * Used by animated components for consistent motion.
+ */
+export const ANIMATION_TOKENS = {
+  /**
+   * Switch toggle animation config.
+   * Uses spring physics for natural feel.
+   */
+  switch: {
+    /** Main toggle animation */
+    toggle: { friction: 8, tension: 100 },
+    /** Thumb scale feedback animation */
+    thumbScale: { friction: 6, tension: 200 },
+  },
+} as const;
+
+/**
+ * Shadow tokens for elevated components.
+ */
+export const SHADOW_TOKENS = {
+  /**
+   * Switch thumb shadow.
+   * Provides depth and separation from track.
+   */
+  switchThumb: {
+    shadowColor: "#000",
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.2,
+    shadowRadius: 2,
+    elevation: 2,
+  },
+} as const;
+
+// =============================================================================
+// SELECT SHEET DIMENSIONS
+// =============================================================================
+
+/**
+ * SelectSheet industry-standard dimensions based on Material Design 3 and iOS HIG.
+ *
+ * Design Rationale:
+ * - Center dialog: max-width 400px (mobile), 560px (tablet) for readability
+ * - Bottom sheet: full width on mobile, max-width on tablet
+ * - Header height: 56px (Material Design standard)
+ * - Option row height: 52px (between Material 48px and iOS 44px minimum)
+ * - Corner radius: 16px (modern rounded aesthetic)
+ * - Overlay opacity: 50% (balanced backdrop)
+ *
+ * Responsive Breakpoints:
+ * - Phone: < 768px (compact layout)
+ * - Tablet: >= 768px (expanded layout with max-width constraints)
+ */
+
+/**
+ * SelectSheet size scale for different use cases.
+ *
+ * | Size | Max Width | List Height | Use Case |
+ * |------|-----------|-------------|----------|
+ * | sm   | 320px     | 200px       | Few options, compact dialogs |
+ * | md   | 400px     | 300px       | Default, most use cases |
+ * | lg   | 560px     | 400px       | Tablets, many options |
+ */
+/**
+ * SelectSheet layout constants.
+ *
+ * Simplified to match Modal pattern:
+ * - Phone: Full width minus horizontalMargin (16px)
+ * - Tablet: Capped at tabletMaxWidth (480px) for phone-like experience
+ */
+export const SELECT_SHEET_LAYOUT = {
+  /** Horizontal margin from screen edges */
+  horizontalMargin: 16,
+  /** Maximum width on tablets (phone-like cap) */
+  tabletMaxWidth: 480,
+  /** Option row height (touch target minimum) */
+  optionRowHeight: 52,
+  /** Header height */
+  headerHeight: 56,
+  /** Footer height (Done button area) */
+  footerHeight: 56,
+  /** Overlay background opacity */
+  overlayOpacity: 0.5,
+  /** Default list height - good UX for most cases */
+  defaultListHeight: 300,
+  /** Tablet breakpoint in pixels */
+  tabletBreakpoint: 768,
+} as const;
+
+// =============================================================================
+// MODAL COMPONENT SCALES
+// =============================================================================
+
+/**
+ * Modal spacing and layout constants.
+ *
+ * Width behavior:
+ * - Phone: Full width minus horizontalMargin (16px = spacing.lg) on each side
+ * - Tablet (≥768px): Capped at tabletMaxWidth (480px) for phone-like experience
+ */
+export const MODAL_LAYOUT = {
+  /** Horizontal margin from screen edges (matches spacing.lg = 16px) */
+  horizontalMargin: 16,
+  /** Max width on tablets — prevents the modal from stretching too wide */
+  tabletMaxWidth: 480,
+  /** Corner radius for the modal container */
+  borderRadius: 16,
+  /** Overlay background opacity */
+  overlayOpacity: 0.5,
+  /** Tablet breakpoint in pixels */
+  tabletBreakpoint: 768,
+} as const;
+
+// =============================================================================
+// TYPE EXPORTS
+// =============================================================================
+
+export type ComponentSizeType = ComponentSize;
+export type IconSizeType = IconSizeKey;