@praxiis/ui 0.0.1

package/src/i18n/labels/types.ts

@@ -0,0 +1,165 @@
+/**
+ * Design System Labels — Type Definitions
+ *
+ * Defines the shape of all accessibility labels used by the design system.
+ * Each component group has its own section. The consuming app can override
+ * any or all labels by passing a partial object to DesignSystemProvider.
+ */
+
+export interface ButtonLabels {
+  loadingLabel: string;
+}
+
+export interface IconButtonLabels {
+  loadingLabel: string;
+}
+
+export interface RadioButtonLabels {
+  fallbackLabel: string;
+}
+
+export interface AvatarLabels {
+  fallbackLabel: string;
+  statusOnline: string;
+  statusOffline: string;
+  statusBusy: string;
+  statusAway: string;
+}
+
+export interface BadgeLabels {
+  fallbackLabel: string;
+  statusIndicator: string;
+  colorPrimary: string;
+  colorSuccess: string;
+  colorWarning: string;
+  colorError: string;
+  colorInfo: string;
+}
+
+export interface ChipLabels {
+  toggleHint: string;
+  removeHint: string;
+}
+
+export interface SpinnerLabels {
+  fallbackLabel: string;
+}
+
+export interface ProgressBarLabels {
+  fallbackLabel: string;
+}
+
+export interface ToastLabels {
+  prefixSuccess: string;
+  prefixError: string;
+  prefixWarning: string;
+  prefixInfo: string;
+}
+
+export interface TextInputLabels {
+  fallbackLabel: string;
+  required: string;
+  errorPrefix: string;
+}
+
+export interface ModalLabels {
+  fallbackTitle: string;
+  positionBottom: string;
+  positionTop: string;
+  positionCenter: string;
+  closeLabel: string;
+  closeHint: string;
+}
+
+export interface SegmentedControlLabels {
+  containerLabel: string;
+  options: string;
+  selected: string;
+  currentlySelected: string;
+  doubleTapToSelect: string;
+  of: string;
+}
+
+export interface SelectSheetLabels {
+  positionBottom: string;
+  positionTop: string;
+  positionCenter: string;
+  fallbackTitle: string;
+  selected: string;
+  disabled: string;
+  of: string;
+  doneLabel: string;
+  itemsSelected: string;
+  doneHint: string;
+  closeLabel: string;
+  closeHint: string;
+  deselected: string;
+}
+
+export interface CalendarLabels {
+  datePicker: {
+    label: string;
+    selected: string;
+    today: string;
+    daysShown: string;
+  };
+  days: {
+    sun: string;
+    mon: string;
+    tue: string;
+    wed: string;
+    thu: string;
+    fri: string;
+    sat: string;
+  };
+  months: {
+    jan: string;
+    feb: string;
+    mar: string;
+    apr: string;
+    may: string;
+    jun: string;
+    jul: string;
+    aug: string;
+    sep: string;
+    oct: string;
+    nov: string;
+    dec: string;
+  };
+}
+
+export interface HeaderLabels {
+  backButton: {
+    label: string;
+    hint: string;
+  };
+}
+
+export interface DesignSystemLabels {
+  designSystem: {
+    button: ButtonLabels;
+    iconButton: IconButtonLabels;
+    radioButton: RadioButtonLabels;
+    avatar: AvatarLabels;
+    badge: BadgeLabels;
+    chip: ChipLabels;
+    spinner: SpinnerLabels;
+    progressBar: ProgressBarLabels;
+    toast: ToastLabels;
+    textInput: TextInputLabels;
+    modal: ModalLabels;
+    segmentedControl: SegmentedControlLabels;
+    selectSheet: SelectSheetLabels;
+  };
+  calendar: CalendarLabels;
+  header: HeaderLabels;
+}
+
+/** Deep partial — allows overriding any subset of labels */
+export type DesignSystemLabelsOverride = {
+  [K in keyof DesignSystemLabels]?: {
+    [J in keyof DesignSystemLabels[K]]?: DesignSystemLabels[K][J] extends object
+      ? Partial<DesignSystemLabels[K][J]>
+      : DesignSystemLabels[K][J];
+  };
+};

package/src/index.tsx

@@ -0,0 +1,215 @@
+/**
+ * El Sendero Design System
+ *
+ * A complete, production-ready design system for React Native (Expo).
+ * Warm, calming aesthetic for anxiety companion app.
+ *
+ * ## Architecture
+ *
+ * ```
+ * design-system/
+ * ├── tokens/      - Design tokens (colors, spacing, typography, motion)
+ * ├── core/        - Low-level primitives (Box, Text, AnimatedBox, restyle)
+ * ├── primitives/  - Atomic, themed components (Button, Card, Input, etc.)
+ * ├── providers/   - Theme providers and contexts
+ * ├── hooks/       - Custom hooks (motion, accessibility)
+ * └── utils/       - Utility functions
+ * ```
+ *
+ * @example
+ * import {
+ *   Button,
+ *   Box,
+ *   Text,
+ *   Card,
+ * } from '@/design-system';
+ *
+ * function App() {
+ *   return <MyApp />;
+ * }
+ */
+
+// =============================================================================
+// TOKENS
+// =============================================================================
+
+export {
+  // Colors
+  baseColors,
+  darkSemanticColors,
+  // Motion
+  duration,
+  easing,
+  // Shadows
+  elevation,
+  // Typography
+  fontFamily,
+  fontSize,
+  fontWeight,
+  hitSlop,
+  // Icons
+  iconSize,
+  letterSpacing,
+  lightSemanticColors,
+  lineHeight,
+  lineHeightValues,
+  opacity,
+  // Radii
+  radii,
+  semanticElevation,
+  semanticMotion,
+  semanticRadii,
+  semanticSpacing,
+  // Spacing
+  spacing,
+  springConfig,
+  touchTarget,
+  typographyPresets,
+  zIndex,
+  // Types
+  type BaseColors,
+  type Duration,
+  type DurationKey,
+  type Easing,
+  type EasingKey,
+  type Elevation,
+  type ElevationKey,
+  type FontFamily,
+  type FontSize,
+  type FontWeight,
+  type IconSize,
+  type IconSizeKey,
+  type Opacity,
+  type Radii,
+  type RadiiKey,
+  type SemanticColors,
+  type SemanticSpacing,
+  type Spacing,
+  type SpacingKey,
+  type SpringConfig,
+  type TypographyPresets,
+  type TypographyVariant,
+  type ZIndex,
+} from "./tokens";
+
+// =============================================================================
+// SHARED TYPES
+// =============================================================================
+
+export type { MaterialIconName, RestyleColor, BaseThemeColor } from "./types";
+
+// =============================================================================
+// CORE PRIMITIVES
+// =============================================================================
+
+export {
+  restyleDarkTheme,
+  restyleLightTheme,
+  restyleTheme,
+  // Restyle
+  ThemeProvider,
+  useRestyleTheme,
+  // Theme building utilities
+  buildPair,
+  buildRestyleTheme,
+  buildRestyleThemeFromThemeColors,
+  restylePresetThemes,
+  type RestyleTheme,
+  type AppThemeColors,
+  type RestyleThemePair,
+  type SemanticColorsInput,
+} from "./core";
+
+// =============================================================================
+// DESIGN SYSTEM PROVIDER
+// =============================================================================
+
+export {
+  DesignSystemProvider,
+  useDesignSystem,
+} from "./provider";
+export type { DesignSystemLanguage, DesignSystemProviderProps } from "./provider";
+export type {
+  DesignSystemLabels,
+  DesignSystemLabelsOverride,
+} from "./i18n/labels";
+export { en, es } from "./i18n";
+
+// =============================================================================
+// PROVIDERS
+// =============================================================================
+
+export {
+  // Theme Factory
+  createTheme,
+  createThemePair,
+  // Built-in theme presets
+  darkTheme,
+  defaultTheme,
+  horizonTheme,
+  lavenderTheme,
+  lightTheme,
+  oceanTheme,
+  roseTheme,
+  sageTheme,
+  sunsetTheme,
+  type DeepPartial,
+  type ShadowStyle,
+  // Types
+  type Theme,
+  type ThemeColors,
+  type ThemeElevation,
+  type ThemeMode,
+  type ThemeMotion,
+  type ThemeOverrides,
+  type ThemeTypography,
+  type TypographyStyle,
+} from "./providers";
+
+// =============================================================================
+// HOOKS
+// =============================================================================
+
+export {
+  useMotionSafeDuration,
+  useReducedMotion,
+  useAnimatedValue,
+  usePulseAnimation,
+  useEntranceAnimation,
+  type PulseAnimationConfig,
+  type EntranceAnimationConfig,
+  type EntranceAnimationResult,
+} from "./hooks";
+
+// =============================================================================
+// UTILS
+// =============================================================================
+
+export {
+  // Accessibility
+  a11yRoles,
+  a11yState,
+  androidOnly,
+  buttonA11yProps,
+  checkboxA11yProps,
+  getContrastRatio,
+  getStatusBarHeight,
+  headingA11yProps,
+  imageA11yProps,
+  iosOnly,
+  isAndroid,
+  // Platform
+  isIOS,
+  meetsContrastAA,
+  meetsContrastAALarge,
+  MIN_TOUCH_TARGET,
+  platformSelect,
+} from "./utils";
+
+// =============================================================================
+// COMPONENTS
+// =============================================================================
+
+export * from "./primitives";
+
+export * from "./components";

package/src/primitives/actions/Button/Button.helpers.ts

@@ -0,0 +1,243 @@
+/**
+ * Button Component Helpers
+ *
+ * Pure functions for computing Button styles, sizes, and colors.
+ * All calculations are derived from the centralized scales.ts token file.
+ */
+
+import { Insets } from "react-native";
+import {
+  BUTTON_HEIGHTS,
+  BUTTON_ICON_SIZE,
+  BUTTON_TEXT_VARIANT,
+  calculateHitSlop,
+  SPINNER_SIZE,
+} from "../../../tokens/scales";
+import { BaseThemeColor, RestyleColor } from "../../../types";
+import { IconSize } from "../../content/Icon";
+import {
+  ButtonSize,
+  ButtonStyleResult,
+  ButtonTextVariant,
+  ButtonVariant,
+  ResolveButtonStyleParams,
+} from "./Button.types";
+
+// =============================================================================
+// TEXT VARIANT RESOLUTION
+// =============================================================================
+
+/**
+ * Get text variant based on button size.
+ *
+ * Uses BUTTON_TEXT_VARIANT from scales.ts for consistency.
+ *
+ * | Button Size | Text Variant |
+ * |-------------|--------------|
+ * | sm          | labelSmall   |
+ * | md          | labelMedium  |
+ * | lg          | labelLarge   |
+ *
+ * @param size - The button size
+ * @returns The text variant for Text
+ */
+export function getTextVariant(size: ButtonSize): ButtonTextVariant {
+  return BUTTON_TEXT_VARIANT[size];
+}
+
+// =============================================================================
+// ICON SIZE RESOLUTION
+// =============================================================================
+
+/**
+ * Get icon size based on button size.
+ *
+ * Uses BUTTON_ICON_SIZE from scales.ts for consistency.
+ * Icons match label visual weight for optical balance.
+ *
+ * | Button Size | Icon Size |
+ * |-------------|-----------|
+ * | sm          | sm (16px) |
+ * | md          | md (20px) |
+ * | lg          | lg (24px) |
+ *
+ * @param size - The button size
+ * @returns The icon size
+ */
+export function getButtonIconSize(size: ButtonSize): IconSize {
+  return BUTTON_ICON_SIZE[size];
+}
+
+// =============================================================================
+// TOUCH TARGET (hitSlop)
+// =============================================================================
+
+/**
+ * Get hitSlop based on button size.
+ *
+ * Uses calculateHitSlop from scales.ts to ensure
+ * all buttons meet the 44px minimum touch target.
+ *
+ * | Size | Height | hitSlop | Total Touch Target |
+ * |------|--------|---------|-------------------|
+ * | sm   | 36px   | 4px     | 44px              |
+ * | md   | 44px   | 0px     | 44px              |
+ * | lg   | 52px   | 0px     | 52px              |
+ *
+ * @param size - The button size variant
+ * @returns Insets for touch target expansion
+ */
+export function getButtonHitSlop(size: ButtonSize): Insets {
+  return calculateHitSlop(BUTTON_HEIGHTS[size]);
+}
+
+// =============================================================================
+// SPINNER SIZE RESOLUTION
+// =============================================================================
+
+/**
+ * Get spinner size based on button size.
+ *
+ * Uses SPINNER_SIZE from scales.ts for consistency across all components.
+ *
+ * | Button Size | Spinner Size |
+ * |-------------|--------------|
+ * | sm          | sm           |
+ * | md          | sm           |
+ * | lg          | lg           |
+ *
+ * @param size - The button size
+ * @returns The spinner size
+ */
+export function getButtonSpinnerSize(size: ButtonSize): "sm" | "lg" {
+  return SPINNER_SIZE[size];
+}
+
+// =============================================================================
+// COLOR RESOLUTION
+// =============================================================================
+
+/**
+ * Get text color based on variant and disabled state.
+ *
+ * | Variant  | Normal       | Disabled     |
+ * |----------|--------------|--------------|
+ * | solid    | textInverse  | textDisabled |
+ * | outline  | color prop   | textDisabled |
+ * | ghost    | color prop   | textDisabled |
+ *
+ * Note: Disabled state uses textDisabled for accessibility.
+ * Opacity is also applied on the container for additional visual cue.
+ *
+ * @param variant - The visual variant
+ * @param color - The primary color prop
+ * @param disabled - Whether the button is disabled
+ * @returns The computed text color
+ */
+export function getTextColor(
+  variant: ButtonVariant,
+  color: RestyleColor,
+  disabled: boolean = false,
+): RestyleColor {
+  if (disabled) {
+    return "textDisabled";
+  }
+
+  if (variant === "solid") {
+    return "textInverse";
+  }
+  return color;
+}
+
+/**
+ * Get icon color based on variant and disabled state.
+ *
+ * Follows the same logic as text color for visual consistency.
+ *
+ * @param variant - The visual variant
+ * @param color - The primary color prop
+ * @param disabled - Whether the button is disabled
+ * @returns The computed icon color
+ */
+export function getButtonIconColor(
+  variant: ButtonVariant,
+  color: RestyleColor,
+  disabled: boolean = false,
+): RestyleColor {
+  // Icon uses same color logic as text
+  return getTextColor(variant, color, disabled);
+}
+
+/**
+ * Get spinner color based on variant and disabled state.
+ *
+ * Follows the same logic as text color for visual consistency.
+ *
+ * @param variant - The visual variant
+ * @param color - The primary color prop
+ * @param disabled - Whether the button is disabled
+ * @returns The computed spinner color
+ */
+export function getButtonSpinnerColor(
+  variant: ButtonVariant,
+  color: RestyleColor,
+  disabled: boolean = false,
+): RestyleColor {
+  // Spinner uses same color logic as text
+  return getTextColor(variant, color, disabled);
+}
+
+// =============================================================================
+// STYLE RESOLUTION
+// =============================================================================
+
+/**
+ * Resolve dynamic style properties for the Button container.
+ *
+ * Static styles (borderRadius, padding) come from theme variants.
+ * This function handles dynamic state-based values:
+ * - backgroundColor based on variant and disabled state
+ * - borderColor based on variant and disabled state
+ * - opacity based on disabled/loading state
+ *
+ * @param params - Resolution parameters
+ * @returns Computed style object
+ */
+export function resolveButtonStyle(
+  params: ResolveButtonStyleParams,
+): ButtonStyleResult {
+  const { variant, disabled, isLoading, color, theme } = params;
+
+  const isDisabledOrLoading = disabled || isLoading;
+
+  let backgroundColor: string;
+  let borderColor: string;
+  let borderWidth: number;
+
+  switch (variant) {
+    case "solid":
+      backgroundColor = isDisabledOrLoading
+        ? theme.colors.interactiveDisabled
+        : theme.colors[color as BaseThemeColor];
+      borderColor = "transparent";
+      borderWidth = 0;
+      break;
+
+    case "outline":
+      backgroundColor = "transparent";
+      borderColor = isDisabledOrLoading
+        ? theme.colors.borderDefault
+        : theme.colors[color as BaseThemeColor];
+      borderWidth = 2;
+      break;
+
+    case "ghost":
+    default:
+      backgroundColor = "transparent";
+      borderColor = "transparent";
+      borderWidth = 0;
+      break;
+  }
+
+  return { backgroundColor, borderColor, borderWidth, opacity: 1 };
+}