@praxiis/ui 0.0.1

package/src/tokens/typography.ts

@@ -0,0 +1,251 @@
+/**
+ * StayEasy Design System - Typography Tokens
+ *
+ * Typography philosophy:
+ * - System fonts first for performance and native feel
+ * - Clear hierarchy with distinct sizes
+ * - Generous line heights for readability
+ * - Consistent letter spacing
+ *
+ * @example
+ * <Text variant="bodyLarge">Content</Text>
+ */
+
+import { Platform, TextStyle } from 'react-native';
+
+// =============================================================================
+// FONT FAMILIES
+// =============================================================================
+
+/**
+ * System font stack
+ * Uses platform-native fonts for optimal performance and native feel
+ */
+export const fontFamily = {
+  // Primary system font
+  regular: Platform.select({
+    ios: 'System',
+    android: 'Roboto',
+    default: 'System',
+  }),
+
+  // Medium weight
+  medium: Platform.select({
+    ios: 'System',
+    android: 'Roboto-Medium',
+    default: 'System',
+  }),
+
+  // Semibold weight
+  semibold: Platform.select({
+    ios: 'System',
+    android: 'Roboto-Medium', // Android doesn't have semibold
+    default: 'System',
+  }),
+
+  // Bold weight
+  bold: Platform.select({
+    ios: 'System',
+    android: 'Roboto-Bold',
+    default: 'System',
+  }),
+
+  // Monospace (for code snippets)
+  mono: Platform.select({
+    ios: 'Menlo',
+    android: 'monospace',
+    default: 'monospace',
+  }),
+} as const;
+
+// =============================================================================
+// FONT WEIGHTS
+// =============================================================================
+
+export const fontWeight = {
+  regular: '400' as TextStyle['fontWeight'],
+  medium: '500' as TextStyle['fontWeight'],
+  semibold: '600' as TextStyle['fontWeight'],
+  bold: '700' as TextStyle['fontWeight'],
+} as const;
+
+// =============================================================================
+// FONT SIZES (in points)
+// =============================================================================
+
+export const fontSize = {
+  xs: 11,
+  sm: 13,
+  md: 15,
+  lg: 17,
+  xl: 20,
+  '2xl': 24,
+  '3xl': 30,
+  '4xl': 36,
+  '5xl': 48,
+} as const;
+
+// =============================================================================
+// LINE HEIGHTS
+// =============================================================================
+
+export const lineHeight = {
+  tight: 1.2,    // Headings
+  snug: 1.375,   // Subheadings
+  normal: 1.5,   // Body text
+  relaxed: 1.625, // Long-form reading
+  loose: 2,      // Special cases
+} as const;
+
+// Computed line heights (fontSize * multiplier)
+export const lineHeightValues = {
+  xs: Math.round(fontSize.xs * lineHeight.normal),     // 17
+  sm: Math.round(fontSize.sm * lineHeight.normal),     // 20
+  md: Math.round(fontSize.md * lineHeight.normal),     // 23
+  lg: Math.round(fontSize.lg * lineHeight.normal),     // 26
+  xl: Math.round(fontSize.xl * lineHeight.snug),       // 28
+  '2xl': Math.round(fontSize['2xl'] * lineHeight.snug), // 33
+  '3xl': Math.round(fontSize['3xl'] * lineHeight.tight), // 36
+  '4xl': Math.round(fontSize['4xl'] * lineHeight.tight), // 43
+  '5xl': Math.round(fontSize['5xl'] * lineHeight.tight), // 58
+} as const;
+
+// =============================================================================
+// LETTER SPACING
+// =============================================================================
+
+export const letterSpacing = {
+  tighter: -0.8,
+  tight: -0.4,
+  normal: 0,
+  wide: 0.4,
+  wider: 0.8,
+  widest: 1.6,
+} as const;
+
+// =============================================================================
+// TYPOGRAPHY PRESETS
+// =============================================================================
+
+export const typographyPresets = {
+  // Display styles (heroes, splash screens)
+  displayLarge: {
+    fontSize: fontSize['5xl'],
+    lineHeight: lineHeightValues['5xl'],
+    fontWeight: fontWeight.bold,
+    letterSpacing: letterSpacing.tighter,
+  },
+  displayMedium: {
+    fontSize: fontSize['4xl'],
+    lineHeight: lineHeightValues['4xl'],
+    fontWeight: fontWeight.bold,
+    letterSpacing: letterSpacing.tighter,
+  },
+  displaySmall: {
+    fontSize: fontSize['3xl'],
+    lineHeight: lineHeightValues['3xl'],
+    fontWeight: fontWeight.bold,
+    letterSpacing: letterSpacing.tight,
+  },
+
+  // Heading styles
+  headingLarge: {
+    fontSize: fontSize['2xl'],
+    lineHeight: lineHeightValues['2xl'],
+    fontWeight: fontWeight.semibold,
+    letterSpacing: letterSpacing.tight,
+  },
+  headingMedium: {
+    fontSize: fontSize.xl,
+    lineHeight: lineHeightValues.xl,
+    fontWeight: fontWeight.semibold,
+    letterSpacing: letterSpacing.tight,
+  },
+  headingSmall: {
+    fontSize: fontSize.lg,
+    lineHeight: lineHeightValues.lg,
+    fontWeight: fontWeight.semibold,
+    letterSpacing: letterSpacing.normal,
+  },
+
+  // Body styles
+  bodyLarge: {
+    fontSize: fontSize.lg,
+    lineHeight: lineHeightValues.lg,
+    fontWeight: fontWeight.regular,
+    letterSpacing: letterSpacing.normal,
+  },
+  bodyMedium: {
+    fontSize: fontSize.md,
+    lineHeight: lineHeightValues.md,
+    fontWeight: fontWeight.regular,
+    letterSpacing: letterSpacing.normal,
+  },
+  bodySmall: {
+    fontSize: fontSize.sm,
+    lineHeight: lineHeightValues.sm,
+    fontWeight: fontWeight.regular,
+    letterSpacing: letterSpacing.normal,
+  },
+
+  // Label styles (buttons, form labels)
+  labelLarge: {
+    fontSize: fontSize.lg,
+    lineHeight: lineHeightValues.lg,
+    fontWeight: fontWeight.medium,
+    letterSpacing: letterSpacing.normal,
+  },
+  labelMedium: {
+    fontSize: fontSize.md,
+    lineHeight: lineHeightValues.md,
+    fontWeight: fontWeight.medium,
+    letterSpacing: letterSpacing.wide,
+  },
+  labelSmall: {
+    fontSize: fontSize.sm,
+    lineHeight: lineHeightValues.sm,
+    fontWeight: fontWeight.medium,
+    letterSpacing: letterSpacing.wide,
+  },
+
+  // Caption styles
+  caption: {
+    fontSize: fontSize.sm,
+    lineHeight: lineHeightValues.sm,
+    fontWeight: fontWeight.regular,
+    letterSpacing: letterSpacing.wide,
+  },
+  captionSmall: {
+    fontSize: fontSize.xs,
+    lineHeight: lineHeightValues.xs,
+    fontWeight: fontWeight.regular,
+    letterSpacing: letterSpacing.wide,
+  },
+
+  // Overline (small uppercase labels)
+  overline: {
+    fontSize: fontSize.xs,
+    lineHeight: lineHeightValues.xs,
+    fontWeight: fontWeight.semibold,
+    letterSpacing: letterSpacing.widest,
+    textTransform: 'uppercase' as TextStyle['textTransform'],
+  },
+
+  // Code/mono styles
+  code: {
+    fontSize: fontSize.sm,
+    lineHeight: lineHeightValues.sm,
+    fontWeight: fontWeight.regular,
+    letterSpacing: letterSpacing.normal,
+  },
+} as const;
+
+// =============================================================================
+// TYPE EXPORTS
+// =============================================================================
+
+export type FontFamily = typeof fontFamily;
+export type FontWeight = typeof fontWeight;
+export type FontSize = typeof fontSize;
+export type TypographyPresets = typeof typographyPresets;
+export type TypographyVariant = keyof typeof typographyPresets;

package/src/types.ts

@@ -0,0 +1,50 @@
+/**
+ * El Sendero Design System - Shared Types
+ *
+ * Types shared across the entire design system that can be used
+ * throughout the application.
+ */
+
+import MaterialIcons from "@expo/vector-icons/MaterialIcons";
+import { RestyleTheme, AppThemeColors } from "./core/restyle";
+
+/**
+ * Material Design icon name (strongly typed from @expo/vector-icons/MaterialIcons)
+ *
+ * This type represents all available Material Icons from the Material Icons library.
+ * It is used throughout the design system for icon-based components.
+ *
+ * @example
+ * ```tsx
+ * import { MaterialIconName } from '@/src/design-system';
+ *
+ * const iconName: MaterialIconName = 'add';
+ * ```
+ */
+export type MaterialIconName = keyof typeof MaterialIcons.glyphMap;
+
+/**
+ * Built-in theme color type — only the colors defined in the base Restyle theme.
+ * Used internally by components when passing color tokens to Restyle primitives
+ * (Box, Text, etc.) which are typed against the base theme.
+ *
+ * @internal
+ */
+export type BaseThemeColor = keyof RestyleTheme["colors"];
+
+/**
+ * Restyle color type — represents all available colors in the design system theme,
+ * including any app-specific tokens registered via `AppThemeColors` augmentation.
+ *
+ * This unified type is used across all components that accept a color prop.
+ * Apps extend the palette by augmenting `AppThemeColors` in a `.d.ts` file
+ * and providing a matching theme to `DesignSystemProvider`.
+ *
+ * @example
+ * ```tsx
+ * import { RestyleColor } from '@praxiis/ui';
+ *
+ * const color: RestyleColor = 'accentPrimary';
+ * ```
+ */
+export type RestyleColor = keyof RestyleTheme["colors"] | keyof AppThemeColors;

package/src/utils/accessibility.ts

@@ -0,0 +1,169 @@
+/**
+ * StayEasy Design System - Accessibility Utilities
+ *
+ * Helpers for building accessible components.
+ */
+
+import { AccessibilityRole, AccessibilityState } from "react-native";
+
+/**
+ * Common accessibility roles mapped to their purposes
+ */
+export const a11yRoles = {
+  button: "button" as AccessibilityRole,
+  link: "link" as AccessibilityRole,
+  search: "search" as AccessibilityRole,
+  image: "image" as AccessibilityRole,
+  header: "header" as AccessibilityRole,
+  text: "text" as AccessibilityRole,
+  checkbox: "checkbox" as AccessibilityRole,
+  slider: "adjustable" as AccessibilityRole,
+  tab: "tab" as AccessibilityRole,
+  tablist: "tablist" as AccessibilityRole,
+  menu: "menu" as AccessibilityRole,
+  menuitem: "menuitem" as AccessibilityRole,
+  progressbar: "progressbar" as AccessibilityRole,
+  alert: "alert" as AccessibilityRole,
+  none: "none" as AccessibilityRole,
+};
+
+/**
+ * Create accessibility state object
+ *
+ * @example
+ * <Pressable accessibilityState={a11yState({ selected: isSelected, disabled })} />
+ */
+export function a11yState(state: {
+  disabled?: boolean;
+  selected?: boolean;
+  checked?: boolean | "mixed";
+  busy?: boolean;
+  expanded?: boolean;
+}): AccessibilityState {
+  return state;
+}
+
+/**
+ * Generate accessibility props for a button
+ */
+export function buttonA11yProps(options: {
+  label: string;
+  hint?: string;
+  disabled?: boolean;
+}) {
+  return {
+    accessible: true,
+    accessibilityRole: a11yRoles.button,
+    accessibilityLabel: options.label,
+    accessibilityHint: options.hint,
+    accessibilityState: a11yState({ disabled: options.disabled }),
+  };
+}
+
+/**
+ * Generate accessibility props for a checkbox
+ */
+export function checkboxA11yProps(options: {
+  label: string;
+  checked: boolean;
+  disabled?: boolean;
+}) {
+  return {
+    accessible: true,
+    accessibilityRole: a11yRoles.checkbox,
+    accessibilityLabel: options.label,
+    accessibilityState: a11yState({
+      checked: options.checked,
+      disabled: options.disabled,
+    }),
+  };
+}
+
+/**
+ * Generate accessibility props for an image
+ */
+export function imageA11yProps(options: {
+  label: string;
+  isDecorative?: boolean;
+}) {
+  if (options.isDecorative) {
+    return {
+      accessible: false,
+      accessibilityElementsHidden: true,
+      importantForAccessibility: "no-hide-descendants" as const,
+    };
+  }
+
+  return {
+    accessible: true,
+    accessibilityRole: a11yRoles.image,
+    accessibilityLabel: options.label,
+  };
+}
+
+/**
+ * Generate accessibility props for a heading
+ */
+export function headingA11yProps(
+  options: { level?: 1 | 2 | 3 | 4 | 5 | 6 } = {}
+) {
+  return {
+    accessible: true,
+    accessibilityRole: a11yRoles.header,
+  };
+}
+
+/**
+ * Calculate if a color combination meets WCAG contrast requirements
+ * Returns approximate ratio (not perfect but useful for dev-time checks)
+ *
+ * @param foreground - Hex color string
+ * @param background - Hex color string
+ * @returns Approximate contrast ratio
+ */
+export function getContrastRatio(
+  foreground: string,
+  background: string
+): number {
+  const getLuminance = (hex: string): number => {
+    const rgb = hex
+      .replace("#", "")
+      .match(/.{2}/g)
+      ?.map((c) => {
+        const val = parseInt(c, 16) / 255;
+        return val <= 0.03928
+          ? val / 12.92
+          : Math.pow((val + 0.055) / 1.055, 2.4);
+      });
+
+    if (!rgb) return 0;
+    return 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2];
+  };
+
+  const l1 = getLuminance(foreground);
+  const l2 = getLuminance(background);
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+/**
+ * Check if contrast meets WCAG AA for normal text (4.5:1)
+ */
+export function meetsContrastAA(
+  foreground: string,
+  background: string
+): boolean {
+  return getContrastRatio(foreground, background) >= 4.5;
+}
+
+/**
+ * Check if contrast meets WCAG AA for large text (3:1)
+ */
+export function meetsContrastAALarge(
+  foreground: string,
+  background: string
+): boolean {
+  return getContrastRatio(foreground, background) >= 3;
+}

package/src/utils/index.ts

@@ -0,0 +1,25 @@
+/**
+ * StayEasy Design System - Utils Exports
+ */
+
+export {
+  isIOS,
+  isAndroid,
+  platformSelect,
+  iosOnly,
+  androidOnly,
+  getStatusBarHeight,
+  MIN_TOUCH_TARGET,
+} from './platform';
+
+export {
+  a11yRoles,
+  a11yState,
+  buttonA11yProps,
+  checkboxA11yProps,
+  imageA11yProps,
+  headingA11yProps,
+  getContrastRatio,
+  meetsContrastAA,
+  meetsContrastAALarge,
+} from './accessibility';

package/src/utils/platform.ts

@@ -0,0 +1,72 @@
+/**
+ * StayEasy Design System - Platform Utilities
+ *
+ * Cross-platform helpers for consistent behavior across iOS and Android.
+ */
+
+import { Platform } from 'react-native';
+
+/**
+ * Check if running on iOS
+ */
+export const isIOS = Platform.OS === 'ios';
+
+/**
+ * Check if running on Android
+ */
+export const isAndroid = Platform.OS === 'android';
+
+/**
+ * Get platform-specific value
+ *
+ * @example
+ * const padding = platformSelect({ ios: 16, android: 12 });
+ */
+export function platformSelect<T>(specifics: { ios: T; android: T }): T {
+  return Platform.select(specifics) as T;
+}
+
+/**
+ * Apply iOS-only styles
+ *
+ * @example
+ * const styles = StyleSheet.create({
+ *   container: {
+ *     ...iosOnly({ shadowOpacity: 0.1 }),
+ *   },
+ * });
+ */
+export function iosOnly<T extends object>(styles: T): T | object {
+  return isIOS ? styles : {};
+}
+
+/**
+ * Apply Android-only styles
+ *
+ * @example
+ * const styles = StyleSheet.create({
+ *   container: {
+ *     ...androidOnly({ elevation: 4 }),
+ *   },
+ * });
+ */
+export function androidOnly<T extends object>(styles: T): T | object {
+  return isAndroid ? styles : {};
+}
+
+/**
+ * Get the status bar height for the platform
+ */
+export function getStatusBarHeight(): number {
+  return Platform.select({
+    ios: 44, // Approximate, use SafeAreaView for accuracy
+    android: 24,
+    default: 0,
+  });
+}
+
+/**
+ * Get minimum touch target size per platform guidelines
+ * iOS: 44pt, Android: 48dp (we use 44 for consistency)
+ */
+export const MIN_TOUCH_TARGET = 44;