@praxiis/ui 0.0.1

package/src/primitives/content/Badge/Badge.tsx

@@ -0,0 +1,174 @@
+/**
+ * Badge Component
+ *
+ * @description Status indicators, notification counts, and labels - Atom
+ *
+ * Badge displays small pieces of information like counts, statuses, or labels.
+ * Supports multiple sizes, variants, and colors with dot mode for compact
+ * status indicators.
+ *
+ * ## Size Scale
+ * | Size | Height | Min Width | Dot Size | Use Case |
+ * |------|--------|-----------|----------|----------|
+ * | sm   | 16px   | 16px      | 6px      | Inline indicators |
+ * | md   | 20px   | 20px      | 8px      | Standard (default) |
+ * | lg   | 24px   | 24px      | 10px     | Prominent badges |
+ *
+ * ## Variants
+ * - `filled`: Solid background (default)
+ * - `outlined`: Border only
+ *
+ * ## Colors
+ * - `primary`: Primary accent
+ * - `success`: Green
+ * - `warning`: Yellow/amber
+ * - `error`: Red
+ * - `info`: Blue
+ *
+ * ## Features
+ * - Three size presets with responsive support
+ * - Three visual variants
+ * - Five color options
+ * - Dot mode for status indicators
+ * - Max value truncation for counts (e.g., "99+")
+ * - Theme-aware colors via Restyle
+ * - Accessible with proper labels
+ * - Memoized for performance
+ * - Spreads rest props for composability (marginBottom, flex, etc.)
+ *
+ * @see Badge.types.ts - Type definitions
+ * @see Badge.helpers.ts - Dimension and color calculations
+ * @see Badge.a11y.ts - Accessibility props
+ *
+ * @example
+ * // Simple text badge
+ * <Badge label="New" />
+ *
+ * @example
+ * // Notification count
+ * <Badge label={5} color="error" />
+ *
+ * @example
+ * // Count with max
+ * <Badge label={150} max={99} /> // Shows "99+"
+ *
+ * @example
+ * // Dot status indicator
+ * <Badge dot color="success" />
+ *
+ * @example
+ * // Soft variant
+ * <Badge label="Sale" variant="outlined" color="error" />
+ *
+ * @example
+ * // With margin (composable via rest props)
+ * <Badge label="New" marginRight="sm" />
+ */
+
+import {
+  backgroundColor,
+  border,
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo } from "react";
+import { RestyleTheme } from "../../../core/restyle";
+import { BaseThemeColor } from "../../../types";
+import { Box } from "../../layout";
+import { Text } from "../../typography";
+import { BADGE_DOT_SIZE, BADGE_TYPOGRAPHY } from "./Badge.helpers";
+import { BadgeProps, BaseBadgeProps } from "./Badge.types";
+import { useBadgeLogic } from "./useBadgeLogic";
+
+/**
+ * Base Badge container with Restyle variant support.
+ * Uses createRestyleComponent with createVariant for theme-driven styling.
+ * Box is passed as the base component for atomic primacy compliance.
+ * @internal
+ */
+const BaseBadgeContainer = createRestyleComponent<BaseBadgeProps, RestyleTheme>(
+  [
+    createVariant({ themeKey: "badgeVariants" }),
+    createVariant({ themeKey: "badgeSizes", property: "size" }),
+    backgroundColor,
+    border,
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Box,
+);
+
+function BadgeComponent({
+  label,
+  size = "md",
+  variant = "filled",
+  color = "accentPrimary",
+  dot = false,
+  max = 99,
+  accessibilityLabel,
+  testID,
+  style,
+  ...rest
+}: BadgeProps) {
+  const { resolvedSize, displayText, colorStyles, a11yProps } = useBadgeLogic({
+    label,
+    size,
+    variant,
+    color,
+    dot,
+    max,
+    accessibilityLabel,
+  });
+
+  // Dot mode: render small circle
+  if (dot) {
+    const dotDimension = BADGE_DOT_SIZE[resolvedSize];
+    return (
+      <BaseBadgeContainer
+        variant={variant}
+        testID={testID}
+        width={dotDimension}
+        height={dotDimension}
+        minWidth={undefined}
+        backgroundColor={colorStyles.backgroundColor as BaseThemeColor}
+        borderWidth={colorStyles.borderWidth}
+        borderColor={colorStyles.borderColor as BaseThemeColor}
+        style={style}
+        {...a11yProps}
+        {...rest}
+      />
+    );
+  }
+
+  // Text/count badge
+  return (
+    <BaseBadgeContainer
+      variant={variant}
+      size={size}
+      testID={testID}
+      backgroundColor={colorStyles.backgroundColor as BaseThemeColor}
+      borderWidth={colorStyles.borderWidth}
+      borderColor={colorStyles.borderColor as BaseThemeColor}
+      style={style}
+      {...a11yProps}
+      {...rest}
+    >
+      <Text
+        variant={BADGE_TYPOGRAPHY[resolvedSize]}
+        color={colorStyles.textColor as BaseThemeColor}
+        fontWeight="600"
+        includeFontPadding={false}
+        textAlignVertical="center"
+      >
+        {displayText}
+      </Text>
+    </BaseBadgeContainer>
+  );
+}
+
+export const Badge = memo(BadgeComponent);
+Badge.displayName = "Badge";

package/src/primitives/content/Badge/Badge.types.ts

@@ -0,0 +1,223 @@
+/**
+ * Badge Component Types
+ *
+ * Type definitions for the Badge component and its related hooks/helpers.
+ * All types are explicitly exported for external consumption.
+ *
+ * @see Badge.tsx - Component implementation
+ */
+
+import { BoxProps, ResponsiveValue, VariantProps } from "@shopify/restyle";
+import { StyleProp, ViewProps, ViewStyle } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { RestyleColor } from "../../../types";
+
+// =============================================================================
+// VARIANT TYPES
+// =============================================================================
+
+/**
+ * Size preset for the Badge component.
+ *
+ * - `sm`: 16px height - Compact indicators
+ * - `md`: 20px height - Standard badge (default)
+ * - `lg`: 24px height - Prominent badges
+ */
+export type BadgeSize = Exclude<keyof RestyleTheme["badgeSizes"], "defaults">;
+
+/**
+ * Visual variant for the Badge component.
+ *
+ * - `filled`: Solid background color
+ * - `outlined`: Border with transparent background
+ */
+export type BadgeVariant = Exclude<keyof RestyleTheme["badgeVariants"], "defaults">;
+
+// =============================================================================
+// RESTYLE PROP TYPES
+// =============================================================================
+
+type BadgeVariantProps = VariantProps<RestyleTheme, "badgeVariants">;
+type BadgeSizeProps = VariantProps<RestyleTheme, "badgeSizes", "size">;
+
+/** Base props combining Restyle Box props with ViewProps and variant props */
+export type BaseBadgeProps = BadgeVariantProps &
+  BadgeSizeProps &
+  BoxProps<RestyleTheme> &
+  ViewProps;
+
+// =============================================================================
+// COMPONENT PROPS
+// =============================================================================
+
+/**
+ * Props for the Badge component.
+ *
+ * @example
+ * // Text badge
+ * <Badge label="New" />
+ *
+ * @example
+ * // Count badge
+ * <Badge label={5} />
+ *
+ * @example
+ * // Dot mode (status indicator)
+ * <Badge dot color="success" />
+ *
+ * @example
+ * // Different variants
+ * <Badge label="Sale" variant="outlined" color="error" />
+ *
+ * @example
+ * // With spacing props (composable)
+ * <Badge label="New" marginRight="sm" />
+ */
+export interface BadgeProps extends Omit<BaseBadgeProps, "variant" | "width" | "height"> {
+  /**
+   * Text or number to display in the badge.
+   * Ignored when `dot` is true.
+   */
+  label?: string | number;
+
+  /**
+   * Size preset (supports responsive values).
+   * @default "md"
+   */
+  size?: ResponsiveValue<BadgeSize, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Visual variant.
+   * @default "filled"
+   */
+  variant?: ResponsiveValue<BadgeVariant, RestyleTheme["breakpoints"]>;
+
+  /**
+   * Color token.
+   * @default "accentPrimary"
+   */
+  color?: RestyleColor;
+
+  /**
+   * When true, displays a small dot without text.
+   * Useful for status indicators.
+   * @default false
+   */
+  dot?: boolean;
+
+  /**
+   * Maximum number to display before showing "+".
+   * Only applies to numeric labels.
+   * @default 99
+   */
+  max?: number;
+
+  /**
+   * Accessibility label for the badge.
+   */
+  accessibilityLabel?: string;
+
+  /** Test ID for testing frameworks */
+  testID?: string;
+
+  /** Custom style overrides */
+  style?: StyleProp<ViewStyle>;
+}
+
+// =============================================================================
+// HOOK TYPES
+// =============================================================================
+
+/**
+ * Parameters for the useBadgeLogic hook.
+ */
+export interface UseBadgeLogicParams {
+  label?: string | number;
+  size: ResponsiveValue<BadgeSize, RestyleTheme["breakpoints"]>;
+  variant: ResponsiveValue<BadgeVariant, RestyleTheme["breakpoints"]>;
+  color: RestyleColor;
+  dot: boolean;
+  max: number;
+  accessibilityLabel?: string;
+}
+
+/**
+ * Return value from the useBadgeLogic hook.
+ */
+export interface UseBadgeLogicReturn {
+  /** Resolved size value */
+  resolvedSize: BadgeSize;
+  /** Computed badge dimensions */
+  dimensions: BadgeDimensions;
+  /** Formatted display text */
+  displayText: string;
+  /** Style values for variant+color combo */
+  colorStyles: BadgeColorStyles;
+  /** Accessibility props */
+  a11yProps: BadgeA11yProps;
+}
+
+// =============================================================================
+// HELPER TYPES
+// =============================================================================
+
+/**
+ * Dimensions configuration for badge sizes.
+ */
+export interface BadgeDimensions {
+  height: number;
+  minWidth: number;
+  paddingHorizontal: number;
+  borderRadius: number;
+  dotSize: number;
+  fontSize: number;
+}
+
+/**
+ * Size configuration map.
+ */
+export type BadgeSizeConfig = Record<BadgeSize, BadgeDimensions>;
+
+/**
+ * Color styles for badge rendering.
+ */
+export interface BadgeColorStyles {
+  backgroundColor: RestyleColor;
+  textColor: RestyleColor;
+  borderColor: RestyleColor;
+  borderWidth: number;
+}
+
+
+// =============================================================================
+// ACCESSIBILITY TYPES
+// =============================================================================
+
+/**
+ * Parameters for generating badge accessibility props.
+ */
+export interface BadgeA11yParams {
+  /** Badge label */
+  label?: string | number;
+  /** Whether dot mode is enabled */
+  dot: boolean;
+  /** Badge color */
+  color: RestyleColor;
+  /** Custom accessibility label */
+  accessibilityLabel?: string;
+  /** Pre-translated fallback label */
+  fallbackLabel: string;
+  /** Pre-translated status indicator label */
+  statusIndicatorLabel: string;
+  /** Pre-translated color labels */
+  colorLabels: Record<string, string>;
+}
+
+/**
+ * Accessibility props returned by getBadgeA11y.
+ */
+export interface BadgeA11yProps {
+  accessible: boolean;
+  accessibilityRole: "text";
+  accessibilityLabel: string;
+}

package/src/primitives/content/Badge/index.ts

@@ -0,0 +1,40 @@
+/**
+ * Badge Component
+ *
+ * @description Status indicators, notification counts, and labels
+ *
+ * @example
+ * import { Badge } from "@/design-system";
+ *
+ * // Text badge
+ * <Badge label="New" />
+ *
+ * // Count badge
+ * <Badge label={5} color="error" />
+ *
+ * // Dot status indicator
+ * <Badge dot color="success" />
+ */
+
+export { Badge } from "./Badge";
+export type {
+  BadgeA11yParams,
+  BadgeA11yProps,
+  BadgeColorStyles,
+  BadgeDimensions,
+  BadgeProps,
+  BadgeSize,
+  BadgeSizeConfig,
+  BadgeVariant,
+  BaseBadgeProps,
+  UseBadgeLogicParams,
+  UseBadgeLogicReturn,
+} from "./Badge.types";
+export {
+  BADGE_SIZE_CONFIG,
+  formatBadgeLabel,
+  getBadgeColorStyles,
+  getBadgeDimensions,
+} from "./Badge.helpers";
+export { getBadgeA11y } from "./Badge.a11y";
+export { useBadgeLogic } from "./useBadgeLogic";

package/src/primitives/content/Badge/useBadgeLogic.ts

@@ -0,0 +1,128 @@
+/**
+ * Badge Logic Hook
+ *
+ * Extracts all computational logic from the Badge component.
+ * Returns memoized values for optimal render performance.
+ *
+ * Responsibilities:
+ * - Resolve responsive size prop
+ * - Calculate dimensions based on size
+ * - Format display text with max truncation
+ * - Compute color styles based on variant+color
+ * - Provide accessibility props
+ *
+ * @see Badge.tsx - Component consuming this hook
+ * @see Badge.helpers.ts - Pure calculation functions
+ */
+
+import { useDesignSystem } from "../../../provider";
+import { useResponsiveProp } from "@shopify/restyle";
+import { useMemo } from "react";
+import { getBadgeA11y } from "./Badge.a11y";
+import {
+  formatBadgeLabel,
+  getBadgeColorStyles,
+  getBadgeDimensions,
+} from "./Badge.helpers";
+import { BadgeSize, BadgeVariant, UseBadgeLogicParams, UseBadgeLogicReturn } from "./Badge.types";
+
+/**
+ * Orchestrates Badge rendering logic and state management.
+ * 
+ * Handles:
+ * - Responsive size and variant resolution
+ * - Dimension calculation (min height, padding, font size)
+ * - Label formatting with max truncation (e.g., "99+" for values > 99)
+ * - Color style computation (background, text, border)
+ * - Dot mode support (empty badge)
+ * - Accessibility props generation
+ * 
+ * @param params - Configuration object for badge behavior
+ * @param params.label - Badge content (text or number)
+ * @param params.size - Size variant ('sm' | 'md' | 'lg')
+ * @param params.variant - Visual variant ('filled' | 'outlined')
+ * @param params.color - Semantic color ('primary' | 'success' | 'warning' | 'error' | 'neutral')
+ * @param params.dot - Whether to show as dot (no label)
+ * @param params.max - Maximum value before truncation (default: undefined = no limit)
+ * @param params.accessibilityLabel - Custom a11y label
+ * 
+ * @returns Computed values for rendering Badge
+ * @returns {string} resolvedSize - Resolved size variant
+ * @returns {object} dimensions - Min height, padding, font size
+ * @returns {string} displayText - Formatted display text (e.g., "99+")
+ * @returns {object} colorStyles - Background, text, border colors
+ * @returns {object} a11yProps - Accessibility props
+ * 
+ * @performance This hook uses useMemo() for expensive calculations
+ * 
+ * @example
+ * const {
+ *   dimensions,
+ *   displayText,
+ *   colorStyles,
+ *   a11yProps,
+ * } = useBadgeLogic({
+ *   label: "New",
+ *   size: "md",
+ *   variant: "filled",
+ *   color: "primary",
+ *   dot: false,
+ *   max: 99,
+ * });
+ */
+export function useBadgeLogic({
+  label,
+  size,
+  variant,
+  color,
+  dot,
+  max,
+  accessibilityLabel,
+}: UseBadgeLogicParams): UseBadgeLogicReturn {
+  const { labels: t } = useDesignSystem();
+
+  // Resolve responsive size
+  const resolvedSize = (useResponsiveProp(size) ?? "md") as BadgeSize;
+  const resolvedVariant = (useResponsiveProp(variant) ?? "filled") as BadgeVariant;
+
+  // Calculate dimensions
+  const dimensions = getBadgeDimensions(resolvedSize);
+
+  // Format display text
+  const displayText = dot ? "" : formatBadgeLabel(label, max);
+
+  // Get color styles
+  const colorStyles = getBadgeColorStyles(resolvedVariant, color);
+
+  // Build translated color labels
+  const colorLabels = useMemo(() => ({
+    accentPrimary: t.designSystem.badge.colorPrimary,
+    feedbackSuccess: t.designSystem.badge.colorSuccess,
+    feedbackWarning: t.designSystem.badge.colorWarning,
+    feedbackError: t.designSystem.badge.colorError,
+    feedbackInfo: t.designSystem.badge.colorInfo,
+  }), [t]);
+
+  // Accessibility props
+  const a11yProps = useMemo(
+    () =>
+      getBadgeA11y({
+        label,
+        dot,
+        color,
+        accessibilityLabel,
+        fallbackLabel: t.designSystem.badge.fallbackLabel,
+        statusIndicatorLabel: t.designSystem.badge.statusIndicator,
+        colorLabels,
+      }),
+    [label, dot, color, accessibilityLabel, t, colorLabels]
+  );
+
+  return {
+    resolvedSize,
+    dimensions,
+    displayText,
+    colorStyles,
+    a11yProps,
+  };
+}

package/src/primitives/content/Card/Card.helpers.ts

@@ -0,0 +1,27 @@
+/**
+ * Card Component Helpers
+ *
+ * Pure functions for Card variant and style resolution.
+ *
+ * ## Variants
+ * | Variant  | Background         | Border |
+ * |----------|-------------------|--------|
+ * | outlined | backgroundSecondary | Yes    |
+ * | flat     | backgroundSecondary | No     |
+ */
+
+import { CardVariant } from "./Card.types";
+
+/**
+ * Get card variant with default fallback.
+ *
+ * @param variant - The card variant
+ * @returns The resolved card variant (defaults to "outlined")
+ *
+ * @example
+ * getCardVariant(undefined) // "outlined"
+ * getCardVariant("flat")    // "flat"
+ */
+export function getCardVariant(variant?: CardVariant): CardVariant {
+  return variant || "outlined";
+}

package/src/primitives/content/Card/Card.tsx

@@ -0,0 +1,123 @@
+/**
+ * Card Component
+ *
+ * @description Content container with optional pressable behavior - Molecule
+ *
+ * Card provides a contained area for grouping related content.
+ * Combines layout, theming, and optional press handling.
+ * The Card sizes to fit its content.
+ *
+ * ## Variants
+ * - `outlined`: Border with background (default)
+ * - `flat`: Background only, no border
+ *
+ * ## Visual Properties
+ * - Border radius: lg (16px) from theme
+ * - Background: backgroundSecondary from theme
+ *
+ * ## Pressable Behavior
+ * When `onPress` is provided:
+ * - Card becomes a button for accessibility
+ * - Disabled state reduces opacity
+ * - accessibilityLabel is required
+ *
+ * ## Features
+ * - Full Restyle Box props support
+ * - Optional pressable behavior
+ * - Full accessibility support
+ * - Memoized for performance
+ *
+ * @see Card.types.ts - Type definitions
+ * @see Card.helpers.ts - Variant resolution
+ * @see Card.a11y.ts - Accessibility prop generation
+ *
+ * @example
+ * // Basic usage
+ * <Card>
+ *   <Text>Card content</Text>
+ * </Card>
+ *
+ * @example
+ * // Pressable card
+ * <Card
+ *   variant="outlined"
+ *   onPress={handlePress}
+ *   accessibilityLabel="Product card"
+ * >
+ *   <Text>Tap to view details</Text>
+ * </Card>
+ *
+ * @example
+ * // Flat variant
+ * <Card variant="flat">
+ *   <Text>Card content</Text>
+ * </Card>
+ */
+
+import {
+  backgroundColor,
+  border,
+  createRestyleComponent,
+  createVariant,
+  layout,
+  spacing,
+  spacingShorthand,
+} from "@shopify/restyle";
+import React, { memo } from "react";
+import { Pressable } from "react-native";
+import { RestyleTheme } from "../../../core/restyle";
+import { CardProps } from "./Card.types";
+import { useCardLogic } from "./useCardLogic";
+
+/**
+ * Base container with Restyle variant support.
+ * @internal
+ */
+const BaseCardContainer = createRestyleComponent<CardProps, RestyleTheme>(
+  [
+    createVariant({ themeKey: "cardVariants", property: "variant" }),
+    backgroundColor,
+    border,
+    layout,
+    spacing,
+    spacingShorthand,
+  ],
+  Pressable,
+);
+
+function CardComponent({
+  children,
+  variant = "outlined",
+  disabled = false,
+  style,
+  testID,
+  onPress,
+  accessibilityLabel,
+  accessibilityHint,
+  ...rest
+}: CardProps) {
+  const { isDisabled, isPressable, opacity, handlePress, a11yProps } = useCardLogic({
+    disabled,
+    onPress,
+    accessibilityLabel,
+  });
+
+  return (
+    <BaseCardContainer
+      variant={variant}
+      onPress={isPressable ? handlePress : undefined}
+      disabled={isDisabled}
+      testID={testID}
+      accessibilityHint={accessibilityHint}
+      opacity={opacity}
+      style={style}
+      {...a11yProps}
+      {...rest}
+    >
+      {children}
+    </BaseCardContainer>
+  );
+}
+
+export const Card = memo(CardComponent);
+Card.displayName = "Card";