@retray-dev/ui-kit 5.2.0 → 6.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@retray-dev/ui-kit",
-  "version": "5.2.0",
+  "version": "6.0.0",
   "description": "Personal UI Kit for React Native / Expo",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -16,7 +16,8 @@
   "files": [
     "dist",
     "src",
-    "COMPONENTS.md"
+    "COMPONENTS.md",
+    "EXAMPLES.md"
   ],
   "scripts": {
     "build": "tsup",
@@ -51,7 +52,9 @@
     "react-native-reanimated": ">=4.0.0",
     "react-native-safe-area-context": ">=4.0.0",
     "react-native-size-matters": ">=0.4.0",
-    "react-native-worklets": ">=0.5.0"
+    "react-native-worklets": ">=0.5.0",
+    "react-native-svg": ">=15.0.0",
+    "react-native-screens": ">=3.0.0"
   },
   "pnpm": {
     "overrides": {
@@ -86,6 +89,9 @@
     "react-native-reanimated": "~4.1.1",
     "react-native-safe-area-context": "~5.6.2",
     "react-native-worklets": "~0.5.1",
+    "sonner-native": "0.23.1",
+    "react-native-svg": "15.12.1",
+    "react-native-screens": "4.16.0",
     "tsup": "^8.0.0",
     "typescript": "^5.4.0",
     "typescript-eslint": "^8.0.0"

package/src/components/Accordion/Accordion.tsx

@@ -12,16 +12,27 @@ import Animated, {
   useAnimatedStyle,
   withTiming,
   Easing,
+  type EasingFunction,
 } from 'react-native-reanimated'
+
+const easingExpand: EasingFunction = Easing.bezier(0.23, 1, 0.32, 1) as unknown as EasingFunction
+const easingCollapse: EasingFunction = Easing.in(Easing.ease)
 import { Entypo } from '@expo/vector-icons'
 import { selectionAsync as hapticSelection } from '../../utils/haptics'
 import { useTheme } from '../../theme'
 import { s, vs, ms } from '../../utils/scaling'
+import { renderIcon } from '../../utils/icons'
 
 export interface AccordionItem {
   value: string
   trigger: string
   content: React.ReactNode
+  /** Icon name from @expo/vector-icons rendered left of trigger. */
+  iconName?: string
+  /** Custom icon node rendered left of trigger. */
+  icon?: React.ReactNode
+  /** Override icon color. Defaults to foregroundMuted. */
+  iconColor?: string
 }
 
 export interface AccordionProps {
@@ -47,6 +58,10 @@ function AccordionItemComponent({
 }) {
   const { colors } = useTheme()
 
+  const resolvedIcon = item.iconName
+    ? renderIcon(item.iconName, ms(16), item.iconColor ?? colors.foregroundMuted)
+    : item.icon
+
   // Shared values — all animation lives on the UI thread
   const isExpanded = useSharedValue(isOpen)
   const height = useSharedValue(0)
@@ -62,14 +77,14 @@ function AccordionItemComponent({
   const derivedHeight = useDerivedValue(() =>
     withTiming(height.value * Number(isExpanded.value), {
       duration: 220,
-      easing: isExpanded.value ? Easing.out(Easing.ease) : Easing.in(Easing.ease),
+      easing: isExpanded.value ? easingExpand : easingCollapse,
     })
   )
 
   const derivedRotation = useDerivedValue(() =>
     withTiming(isExpanded.value ? 1 : 0, {
       duration: 220,
-      easing: isExpanded.value ? Easing.out(Easing.ease) : Easing.in(Easing.ease),
+      easing: isExpanded.value ? easingExpand : easingCollapse,
     })
   )
 
@@ -91,7 +106,10 @@ function AccordionItemComponent({
           onToggle()
         }}
       >
-        <Text style={[styles.triggerText, { color: colors.foreground }]} allowFontScaling={true}>{item.trigger}</Text>
+        <View style={styles.triggerContent}>
+          {resolvedIcon ? <View style={styles.icon}>{resolvedIcon}</View> : null}
+          <Text style={[styles.triggerText, { color: colors.foreground }]} allowFontScaling={true}>{item.trigger}</Text>
+        </View>
         <Animated.View style={[styles.chevron, rotationStyle]}>
           <Entypo name="chevron-down" size={18} color={colors.foregroundMuted} />
         </Animated.View>
@@ -163,10 +181,19 @@ const styles = StyleSheet.create({
     paddingHorizontal: s(14),
     paddingVertical: vs(12),
   },
+  triggerContent: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: s(8),
+    flex: 1,
+  },
+  icon: {
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
   triggerText: {
     fontFamily: 'Poppins-Medium',
     fontSize: ms(14),
-    flex: 1,
   },
   chevron: {
     marginLeft: s(8),

package/src/components/AlertBanner/AlertBanner.tsx

@@ -4,6 +4,7 @@ import { FontAwesome5, MaterialIcons, Entypo } from '@expo/vector-icons'
 import { useTheme } from '../../theme'
 import { s, vs, ms } from '../../utils/scaling'
 import { renderIcon } from '../../utils/icons'
+import { RADIUS } from '../../tokens'
 
 export type AlertBannerVariant = 'default' | 'destructive' | 'success' | 'warning'
 
@@ -20,52 +21,36 @@ export interface AlertBannerProps {
 export function AlertBanner({ title, description, variant = 'default', icon, iconName, iconColor, style }: AlertBannerProps) {
   const { colors } = useTheme()
 
-  const bgColor =
-    variant === 'destructive' ? colors.destructiveTint
-    : variant === 'success'   ? colors.successTint
-    : variant === 'warning'   ? colors.warningTint
-    : colors.card
-
-  const borderColor =
-    variant === 'destructive' ? colors.destructiveBorder
-    : variant === 'success'   ? colors.successBorder
-    : variant === 'warning'   ? colors.warningBorder
-    : colors.border
-
   const accentColor =
     variant === 'destructive' ? colors.destructive
     : variant === 'success'   ? colors.success
     : variant === 'warning'   ? colors.warning
     : colors.primary
 
-  const titleColor =
-    variant === 'default' ? colors.foreground : accentColor
-
-  const descColor =
-    variant === 'default' ? colors.foregroundMuted : accentColor
-
   const defaultIcon =
     variant === 'success' ? (
-      <FontAwesome5 name="check-circle" size={16} color={accentColor} />
+      <FontAwesome5 name="check-circle" size={ms(16)} color={accentColor} />
     ) : variant === 'destructive' ? (
-      <MaterialIcons name="error-outline" size={17} color={accentColor} />
+      <MaterialIcons name="error-outline" size={ms(17)} color={accentColor} />
     ) : variant === 'warning' ? (
-      <MaterialIcons name="warning-amber" size={17} color={accentColor} />
+      <MaterialIcons name="warning-amber" size={ms(17)} color={accentColor} />
     ) : (
-      <Entypo name="info-with-circle" size={16} color={accentColor} />
+      <Entypo name="info-with-circle" size={ms(16)} color={accentColor} />
     )
 
   const effectiveIcon: React.ReactNode = iconName
-    ? renderIcon(iconName, 16, iconColor ?? accentColor)
+    ? renderIcon(iconName, ms(16), iconColor ?? accentColor)
     : icon ?? defaultIcon
 
   return (
-    <View style={[styles.container, { backgroundColor: bgColor, borderColor }, style]}>
+    <View style={[styles.container, { backgroundColor: colors.card }, style]}>
+      {/* Icon */}
       <View style={styles.iconSlot}>{effectiveIcon}</View>
+      {/* Text */}
       <View style={styles.content}>
-        <Text style={[styles.title, { color: titleColor }]} allowFontScaling={true}>{title}</Text>
+        <Text style={[styles.title, { color: colors.foreground }]} allowFontScaling={true}>{title}</Text>
         {description ? (
-          <Text style={[styles.description, { color: descColor }]} allowFontScaling={true}>{description}</Text>
+          <Text style={[styles.description, { color: colors.foregroundMuted }]} allowFontScaling={true}>{description}</Text>
         ) : null}
       </View>
     </View>
@@ -76,11 +61,10 @@ const styles = StyleSheet.create({
   container: {
     flexDirection: 'row',
     alignItems: 'flex-start',
-    borderWidth: 0.5,
-    borderRadius: 10,
-    paddingHorizontal: s(12),
-    paddingVertical: vs(10),
-    gap: s(10),
+    borderRadius: RADIUS.lg,
+    gap: s(8),
+    paddingVertical: vs(8),
+    paddingHorizontal: s(10),
   },
   iconSlot: {
     marginTop: vs(1),
@@ -92,12 +76,11 @@ const styles = StyleSheet.create({
   title: {
     fontFamily: 'Poppins-Medium',
     fontSize: ms(13),
-    lineHeight: ms(18),
+    lineHeight: ms(19),
   },
   description: {
     fontFamily: 'Poppins-Regular',
     fontSize: ms(12),
     lineHeight: ms(17),
-    opacity: 0.85,
   },
 })

package/src/components/Avatar/Avatar.tsx

@@ -8,9 +8,12 @@ export type AvatarSize = 'sm' | 'md' | 'lg' | 'xl'
 export type AvatarStatus = 'online' | 'offline' | 'busy' | 'away'
 
 export interface AvatarProps {
-  src?: string
+  src?: string | null
+  /** Manual initials (max 2 chars). */
   fallback?: string
-  size?: AvatarSize
+  /** Full name — extracts up to 2 initials (e.g. "Julian Cruz" → "JC"). */
+  fallbackText?: string
+  size?: AvatarSize | number
   /** Optional status indicator dot — bottom-right corner. */
   status?: AvatarStatus
   style?: ViewStyle
@@ -37,13 +40,24 @@ const statusSizeMap: Record<AvatarSize, number> = {
   xl: 16,
 }
 
-export function Avatar({ src, fallback, size = 'md', status, style }: AvatarProps) {
+function getInitials(fallback?: string, fallbackText?: string): string {
+  if (fallback) return fallback.slice(0, 2).toUpperCase()
+  if (fallbackText) {
+    const words = fallbackText.trim().split(/\s+/)
+    if (words.length === 1) return words[0].slice(0, 2).toUpperCase()
+    return (words[0][0] + words[words.length - 1][0]).toUpperCase()
+  }
+  return '?'
+}
+
+export function Avatar({ src, fallback, fallbackText, size = 'md', status, style }: AvatarProps) {
   const { colors } = useTheme()
   const [imageError, setImageError] = useState(false)
-  const dimension = sizeMap[size]
+  const dimension = typeof size === 'number' ? size : sizeMap[size as AvatarSize]
+  const fontSize = typeof size === 'number' ? size * 0.38 : fontSizeMap[size as AvatarSize]
   const showFallback = !src || imageError
 
-  const statusSize = statusSizeMap[size]
+  const statusSize = typeof size === 'number' ? size * 0.25 : statusSizeMap[size as AvatarSize]
 
   const statusColor: Record<AvatarStatus, string> = {
     online:  '#22c55e',
@@ -71,10 +85,10 @@ export function Avatar({ src, fallback, size = 'md', status, style }: AvatarProp
           />
         ) : (
           <Text
-            style={[styles.fallback, { color: colors.foregroundMuted, fontSize: fontSizeMap[size] }]}
+            style={[styles.fallback, { color: colors.foregroundMuted, fontSize }]}
             allowFontScaling={true}
           >
-            {fallback?.slice(0, 2).toUpperCase() ?? '?'}
+            {getInitials(fallback, fallbackText)}
           </Text>
         )}
       </View>

package/src/components/Button/Button.tsx

@@ -12,9 +12,9 @@ import {
 } from 'react-native'
 
 const nativeDriver = Platform.OS !== 'web'
-import { impactLight } from '../../utils/haptics'
+import { impactMedium } from '../../utils/haptics'
 import { useTheme } from '../../theme'
-import { s, vs, ms } from '../../utils/scaling'
+import { s, vs, ms, mvs } from '../../utils/scaling'
 import { renderIcon } from '../../utils/icons'
 import { RADIUS, TYPOGRAPHY } from '../../tokens'
 
@@ -31,7 +31,7 @@ export interface ButtonProps extends TouchableOpacityProps {
   size?: ButtonSize
   loading?: boolean
   fullWidth?: boolean
-  icon?: React.ReactNode | ((props: { label: string; size: ButtonSize; variant: ButtonVariant }) => React.ReactNode)
+  icon?: React.ReactNode | ((props: { label: string; size: ButtonSize; variant: ButtonVariant; color: string }) => React.ReactNode)
   iconName?: string
   iconColor?: string
   iconPosition?: 'left' | 'right'
@@ -47,7 +47,7 @@ const containerSizeStyles: Record<ButtonSize, ViewStyle> = {
 const labelSizeStyles: Record<ButtonSize, TextStyle> = {
   sm: { ...TYPOGRAPHY['button-sm'], fontSize: ms(TYPOGRAPHY['button-sm'].fontSize) },
   md: { ...TYPOGRAPHY['button-lg'], fontSize: ms(TYPOGRAPHY['button-lg'].fontSize) },
-  lg: { ...TYPOGRAPHY['button-lg'], fontSize: ms(TYPOGRAPHY['button-lg'].fontSize + 1) },
+  lg: { ...TYPOGRAPHY['button-lg'], fontSize: ms(TYPOGRAPHY['button-lg'].fontSize + 1), lineHeight: mvs(24) },
 }
 
 const iconSizeMap: Record<ButtonSize, number> = { sm: 16, md: 18, lg: 20 }
@@ -73,15 +73,15 @@ export function Button({
 
   const handlePressIn = () => {
     if (isDisabled) return
-    Animated.spring(scale, { toValue: 0.95, useNativeDriver: nativeDriver, speed: 40, bounciness: 0 }).start()
+    Animated.spring(scale, { toValue: 0.95, useNativeDriver: nativeDriver, stiffness: 600, damping: 35, mass: 0.8 }).start()
   }
 
   const handlePressOut = () => {
-    Animated.spring(scale, { toValue: 1, useNativeDriver: nativeDriver, speed: 40, bounciness: 4 }).start()
+    Animated.spring(scale, { toValue: 1, useNativeDriver: nativeDriver, stiffness: 280, damping: 22, mass: 0.8 }).start()
   }
 
   const handlePress: TouchableOpacityProps['onPress'] = (e) => {
-    impactLight()
+    impactMedium()
     onPress?.(e)
   }
 
@@ -99,17 +99,24 @@ export function Button({
     destructive: { color: colors.destructiveForeground },
   }[variant]
 
+  const textColor = iconColor ?? (labelVariantStyle.color as string)
+
   const effectiveIcon: React.ReactNode = iconName
-    ? renderIcon(iconName, iconSizeMap[size], iconColor ?? (labelVariantStyle.color as string))
-    : typeof icon === 'function' ? icon({ label, size, variant }) : icon
+    ? renderIcon(iconName, iconSizeMap[size], textColor)
+    : typeof icon === 'function' ? icon({ label, size, variant, color: textColor }) : icon
 
   const spinnerColor =
     variant === 'destructive' ? colors.destructiveForeground
     : variant === 'primary' ? colors.primaryForeground
     : colors.foreground
 
+  // Extract flex from style for wrapper — ButtonGroup sets flex: 1
+  const styleArray = Array.isArray(style) ? style : style ? [style] : []
+  const flatStyle = StyleSheet.flatten(styleArray)
+  const { flex, ...restStyle } = flatStyle || {}
+
   return (
-    <Animated.View style={[fullWidth && styles.fullWidth, { transform: [{ scale }] }]}>
+    <Animated.View style={[fullWidth && styles.fullWidth, flex !== undefined && { flex }, { transform: [{ scale }] }]}>
       <TouchableOpacity
         style={[
           styles.base,
@@ -117,7 +124,7 @@ export function Button({
           containerSizeStyles[size],
           fullWidth && styles.fullWidth,
           isDisabled && styles.disabled,
-          style,
+          restStyle,
         ]}
         disabled={isDisabled}
         activeOpacity={1}
@@ -128,13 +135,23 @@ export function Button({
         {...props}
       >
         {loading ? (
-          <ActivityIndicator size="small" color={spinnerColor} />
+          <>
+            <ActivityIndicator size="small" color={spinnerColor} style={{ marginRight: s(6) }} />
+            <Text
+              style={[styles.label, labelVariantStyle, labelSizeStyles[size], styles.labelLoading]}
+              allowFontScaling={true}
+              numberOfLines={1}
+            >
+              {label}
+            </Text>
+          </>
         ) : (
           <>
             {effectiveIcon && iconPosition === 'left' && <>{effectiveIcon}</>}
             <Text
               style={[styles.label, labelVariantStyle, labelSizeStyles[size], effectiveIcon ? styles.labelWithIcon : undefined]}
               allowFontScaling={true}
+              numberOfLines={1}
             >
               {label}
             </Text>
@@ -148,7 +165,7 @@ export function Button({
 
 const styles = StyleSheet.create({
   base: {
-    borderRadius: RADIUS.xl,   // 32px — pill-shaped primary CTA (Airbnb spec)
+    borderRadius: RADIUS.md,   // 14px — Airbnb-aligned rounded rect (not pill)
     alignItems: 'center',
     justifyContent: 'center',
     flexDirection: 'row',
@@ -161,8 +178,12 @@ const styles = StyleSheet.create({
   },
   label: {
     fontFamily: 'Poppins-Medium',
+    flexShrink: 1,
   },
   labelWithIcon: {
     marginHorizontal: s(6),
   },
+  labelLoading: {
+    opacity: 0.6,
+  },
 })

package/src/components/ButtonGroup/ButtonGroup.tsx

@@ -0,0 +1,60 @@
+import React from 'react'
+import { View, ViewStyle, StyleSheet } from 'react-native'
+import { s } from '../../utils/scaling'
+
+export interface ButtonGroupProps {
+  children: React.ReactNode
+  /** Spacing between buttons. Defaults to 12px. */
+  gap?: number
+  /** Stack buttons vertically instead of horizontally. */
+  vertical?: boolean
+  style?: ViewStyle
+}
+
+/**
+ * Container that auto-distributes space equally among Button children.
+ * Each child gets `flex: 1` — perfect for side-by-side CTAs.
+ *
+ * @example
+ * ```tsx
+ * <ButtonGroup>
+ *   <Button label="Cancel" variant="secondary" onPress={...} />
+ *   <Button label="Confirm" onPress={...} />
+ * </ButtonGroup>
+ * ```
+ */
+export function ButtonGroup({ children, gap = 12, vertical = false, style }: ButtonGroupProps) {
+  return (
+    <View
+      style={[
+        styles.container,
+        vertical ? styles.vertical : styles.horizontal,
+        { gap: s(gap) },
+        style,
+      ]}
+    >
+      {React.Children.map(children, (child) =>
+        React.isValidElement(child)
+          ? React.cloneElement(child as React.ReactElement<any>, {
+              style: [
+                (child as React.ReactElement<any>).props.style,
+                { flex: 1 },
+              ],
+            })
+          : child,
+      )}
+    </View>
+  )
+}
+
+const styles = StyleSheet.create({
+  container: {
+    width: '100%',
+  },
+  horizontal: {
+    flexDirection: 'row',
+  },
+  vertical: {
+    flexDirection: 'column',
+  },
+})

package/src/components/ButtonGroup/index.ts

@@ -0,0 +1 @@
+export * from './ButtonGroup'

package/src/components/Card/Card.tsx

@@ -3,6 +3,7 @@ import { View, Text, TouchableOpacity, Animated, StyleSheet, ViewStyle, TextStyl
 import { impactLight } from '../../utils/haptics'
 import { useTheme } from '../../theme'
 import { s, vs, ms, mvs } from '../../utils/scaling'
+import { RADIUS } from '../../tokens'
 
 const nativeDriver = Platform.OS !== 'web'
 
@@ -51,8 +52,9 @@ export function Card({ children, variant = 'elevated', onPress, style }: CardPro
     Animated.spring(scale, {
       toValue: 0.98,
       useNativeDriver: nativeDriver,
-      speed: 40,
-      bounciness: 0,
+      stiffness: 400,
+      damping: 30,
+      mass: 1.0,
     }).start()
   }
 
@@ -61,8 +63,9 @@ export function Card({ children, variant = 'elevated', onPress, style }: CardPro
     Animated.spring(scale, {
       toValue: 1,
       useNativeDriver: nativeDriver,
-      speed: 40,
-      bounciness: 4,
+      stiffness: 250,
+      damping: 24,
+      mass: 1.0,
     }).start()
   }
 
@@ -77,10 +80,10 @@ export function Card({ children, variant = 'elevated', onPress, style }: CardPro
       backgroundColor: colors.card,
       borderColor: colors.border,
       shadowColor: '#000',
-      shadowOffset: { width: 0, height: 4 },
-      shadowOpacity: 0.06,
-      shadowRadius: 12,
-      elevation: 3,
+      shadowOffset: { width: 0, height: 6 },
+      shadowOpacity: 0.10,
+      shadowRadius: 16,
+      elevation: 4,
     },
     outlined: {
       backgroundColor: colors.card,
@@ -147,7 +150,7 @@ export function CardFooter({ children, style }: CardFooterProps) {
 
 const styles = StyleSheet.create({
   card: {
-    borderRadius: 14,           // RADIUS.md — Airbnb property card spec
+    borderRadius: RADIUS.md,    // 14px — Airbnb property card spec
     borderWidth: 1,
   },
   header: {

package/src/components/Chip/Chip.tsx

@@ -30,6 +30,11 @@ export interface ChipProps {
 export interface ChipOption {
   label: string
   value: string | number
+  /** Icon name resolved via renderIcon (Feather, AntDesign, etc.). */
+  iconName?: string
+  /** Icon tint color override. */
+  iconColor?: string
+  disabled?: boolean
 }
 
 export interface ChipGroupProps {
@@ -154,7 +159,9 @@ export function ChipGroup({ options, value, onValueChange, multiSelect = false,
           key={opt.value}
           label={opt.label}
           selected={isSelected(opt.value)}
-          onPress={() => handlePress(opt.value)}
+          onPress={opt.disabled ? undefined : () => handlePress(opt.value)}
+          iconName={opt.iconName}
+          style={opt.disabled ? { opacity: 0.4 } : undefined}
         />
       ))}
     </View>

package/src/components/ConfirmDialog/ConfirmDialog.tsx

@@ -7,7 +7,7 @@ import {
   type BottomSheetBackdropProps,
 } from '@gorhom/bottom-sheet'
 import { Feather } from '@expo/vector-icons'
-import { impactLight } from '../../utils/haptics'
+import { impactMedium, notificationSuccess, selectionAsync as hapticSelection } from '../../utils/haptics'
 import { useTheme } from '../../theme'
 import { Button } from '../Button'
 import { s, vs, ms, mvs } from '../../utils/scaling'
@@ -38,7 +38,7 @@ export function ConfirmDialog({
 
   useEffect(() => {
     if (visible) {
-      impactLight()
+      impactMedium()
       ref.current?.present()
     } else {
       ref.current?.dismiss()
@@ -78,7 +78,7 @@ export function ConfirmDialog({
             label={confirmLabel}
             variant={confirmVariant}
             fullWidth
-            onPress={onConfirm}
+            onPress={() => { notificationSuccess(); onConfirm() }}
             icon={
               <Feather
                 name={confirmVariant === 'destructive' ? 'trash-2' : 'check'}
@@ -95,7 +95,7 @@ export function ConfirmDialog({
             label={cancelLabel}
             variant="secondary"
             fullWidth
-            onPress={onCancel}
+            onPress={() => { hapticSelection(); onCancel() }}
             icon={<Feather name="x" size={15} color={colors.foreground} />}
           />
         </View>

package/src/components/CurrencyDisplay/CurrencyDisplay.tsx

@@ -3,6 +3,22 @@ import { View, Text, StyleSheet, ViewStyle } from 'react-native'
 import { useTheme } from '../../theme'
 import { ms } from '../../utils/scaling'
 
+export type CurrencyDisplayVariant = 'hero' | 'large' | 'medium' | 'small'
+
+const variantFontSize: Record<CurrencyDisplayVariant, number> = {
+  hero:   ms(48),
+  large:  ms(32),
+  medium: ms(18),
+  small:  ms(14),
+}
+
+const variantLetterSpacing: Record<CurrencyDisplayVariant, number> = {
+  hero:   -2,
+  large:  -1,
+  medium: -0.5,
+  small:  0,
+}
+
 export interface CurrencyDisplayProps {
   value: number | string
   /** Symbol prepended to the formatted value. Defaults to `'$'`. */
@@ -11,6 +27,12 @@ export interface CurrencyDisplayProps {
   showDecimals?: boolean
   /** Override the color of the formatted text. Defaults to the `foreground` theme token. */
   textColor?: string
+  /** Predefined size variant. Overrides the default 56px size. */
+  variant?: CurrencyDisplayVariant
+  /** Enable adjustsFontSizeToFit so long values shrink to fit in one line. */
+  autoScale?: boolean
+  /** Maximum font size when autoScale is true (defaults to variant size or 56px). */
+  maxFontSize?: number
   style?: ViewStyle
 }
 
@@ -27,13 +49,22 @@ function formatValue(value: number | string, prefix: string, showDecimals: boole
   return `${sign}${prefix}${intPart}`
 }
 
-export function CurrencyDisplay({ value, prefix = '$', showDecimals = false, textColor, style }: CurrencyDisplayProps) {
+export function CurrencyDisplay({ value, prefix = '$', showDecimals = false, textColor, variant, autoScale, maxFontSize, style }: CurrencyDisplayProps) {
   const { colors } = useTheme()
   const formatted = formatValue(value, prefix, showDecimals)
+  const baseFontSize = variant ? variantFontSize[variant] : ms(56)
+  const fontSize = maxFontSize ?? baseFontSize
+  const letterSpacing = variant ? variantLetterSpacing[variant] : -2
 
   return (
     <View style={[styles.container, style]}>
-      <Text style={[styles.amount, { color: textColor ?? colors.foreground }]} allowFontScaling={true}>
+      <Text
+        style={[styles.amount, { color: textColor ?? colors.foreground, fontSize, letterSpacing }]}
+        allowFontScaling={true}
+        numberOfLines={autoScale ? 1 : undefined}
+        adjustsFontSizeToFit={autoScale}
+        minimumFontScale={autoScale ? 0.5 : undefined}
+      >
         {formatted}
       </Text>
     </View>
@@ -41,10 +72,12 @@ export function CurrencyDisplay({ value, prefix = '$', showDecimals = false, tex
 }
 
 const styles = StyleSheet.create({
-  container: {},
+  container: {
+    alignSelf: 'flex-start',
+  },
   amount: {
     fontFamily: 'Poppins-Bold',
-    fontSize: ms(56),
-    letterSpacing: -2,
+    includeFontPadding: false,
+    textAlignVertical: 'top',
   },
 })