@retray-dev/ui-kit 2.5.2 → 2.7.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v2.5.2)
+# @retray-dev/ui-kit — Component Reference (v2.7.0)
 
 This file is the AI reference for this package. It is shipped inside the npm package so consuming projects can import it into their `CLAUDE.md` with:
 
@@ -105,6 +105,99 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 
 ---
 
+## Design Tokens
+
+Static structural constants exported from the package root — no context or provider needed. Use these instead of hardcoding values.
+
+```ts
+import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS } from '@retray-dev/ui-kit'
+```
+
+### SPACING
+
+8pt-grid spacing scale.
+
+| Key | Value |
+|-----|-------|
+| `xs` | 4 |
+| `sm` | 8 |
+| `md` | 12 |
+| `lg` | 16 |
+| `xl` | 24 |
+| `2xl` | 32 |
+| `3xl` | 48 |
+
+**Types:** `Spacing`, `SpacingKey`
+
+```tsx
+<View style={{ gap: SPACING.md, padding: SPACING.lg }} />
+```
+
+### ICON_SIZES
+
+Semantic icon size scale aligned to HIG roles.
+
+| Key | Value |
+|-----|-------|
+| `sm` | 14 |
+| `md` | 18 |
+| `lg` | 22 |
+| `xl` | 28 |
+| `2xl` | 32 |
+
+**Types:** `IconSize`, `IconSizeKey`
+
+```tsx
+<Icon name="home" size={ICON_SIZES.md} color={colors.foreground} />
+```
+
+### RADIUS
+
+Border radius scale used throughout the library.
+
+| Key | Value | Used in |
+|-----|-------|---------|
+| `sm` | 4 | — |
+| `md` | 8 | Inputs, Buttons, Checkboxes, Toggles, Tabs |
+| `lg` | 12 | Cards, AlertBanner, Toast, EmptyState, Select list |
+| `xl` | 16 | Sheet top corners |
+| `full` | 9999 | Pills, circular elements |
+
+**Types:** `Radius`, `RadiusKey`
+
+```tsx
+<View style={{ borderRadius: RADIUS.lg }} />
+```
+
+### SHADOWS
+
+Cross-platform shadow presets (RN `shadow*` properties + `elevation`).
+
+| Key | Height | Opacity | Radius | Elevation |
+|-----|--------|---------|--------|-----------|
+| `sm` | 1 | 0.08 | 4 | 2 |
+| `md` | 3 | 0.12 | 8 | 5 |
+| `lg` | 6 | 0.20 | 16 | 10 |
+| `xl` | 12 | 0.28 | 24 | 18 |
+
+```tsx
+<View style={[styles.card, SHADOWS.md]} />
+```
+
+### BREAKPOINTS
+
+Layout breakpoints.
+
+| Key | Value |
+|-----|-------|
+| `wide` | 700 |
+
+```tsx
+const isWide = width >= BREAKPOINTS.wide
+```
+
+---
+
 ## Components
 
 ---
@@ -153,6 +246,8 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 | fullWidth | `boolean` | `false` | Stretches to container width (`alignSelf: 'stretch'`) |
 | disabled | `boolean` | — | Reduces opacity to 0.5 |
 | icon | `React.ReactNode \| ((props: { label, size, variant }) => React.ReactNode)` | — | Icon rendered alongside the label. Can be a node or a render function |
+| iconName | `string` | — | Icon name from `@expo/vector-icons` (e.g. `"arrow-right"`). See [icons.expo.fyi](https://icons.expo.fyi). Takes precedence over `icon` |
+| iconColor | `string` | — | Override icon color. Defaults to variant label color |
 | iconPosition | `'left' \| 'right'` | `'left'` | Side the icon appears on |
 
 **Variants:**
@@ -170,7 +265,8 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 <Button label="Cancel" variant="ghost" onPress={onCancel} />
 <Button label="Delete" variant="outline" size="sm" />
 <Button label="Submitting..." loading fullWidth />
-<Button label="Share" icon={<ShareIcon size={16} />} iconPosition="right" />
+<Button label="Continue" iconName="arrow-right" iconPosition="right" />
+<Button label="Delete" variant="destructive" iconName="trash-2" />
 ```
 
 ---
@@ -190,6 +286,10 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 | suffix | `string \| ReactNode` | — | Content rendered after the input field (e.g., `"kg"` or a button) |
 | prefixStyle | `TextStyle` | — | Style applied to the prefix text when prefix is a string |
 | suffixStyle | `TextStyle` | — | Style applied to the suffix text when suffix is a string |
+| prefixIcon | `string` | — | Icon name from `@expo/vector-icons` rendered before the input. Takes precedence over `prefix` |
+| suffixIcon | `string` | — | Icon name from `@expo/vector-icons` rendered after the input. Takes precedence over `suffix` (unless `type="password"`) |
+| prefixIconColor | `string` | — | Override prefix icon color. Defaults to `mutedForeground` |
+| suffixIconColor | `string` | — | Override suffix icon color. Defaults to `mutedForeground` |
 | type | `'text' \| 'password'` | `'text'` | When `'password'`, shows a visibility toggle button in the suffix slot |
 | containerStyle | `ViewStyle` | — | Style for the outer container `View` |
 
@@ -202,6 +302,8 @@ import type { ThemeColors } from '@retray-dev/ui-kit'
 <Input label="Username" hint="Must be at least 4 characters" />
 <Input label="Amount" prefix="$" placeholder="0.00" keyboardType="numeric" />
 <Input label="Weight" suffix="kg" placeholder="0" />
+<Input placeholder="Search..." prefixIcon="search" />
+<Input placeholder="Amount" prefixIcon="dollar-sign" suffixIcon="check" />
 ```
 
 ---
@@ -285,6 +387,8 @@ const [amount, setAmount] = useState(0)
 | variant | `'default' \| 'secondary' \| 'destructive' \| 'outline'` | `'default'` | — |
 | size | `'sm' \| 'md' \| 'lg'` | `'md'` | Controls padding and font size |
 | icon | `ReactNode` | — | Icon rendered before the label/children |
+| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
+| iconColor | `string` | — | Override icon color. Defaults to variant foreground color |
 | style | `ViewStyle` | — | — |
 
 **Example:**
@@ -293,7 +397,8 @@ const [amount, setAmount] = useState(0)
 <Badge label="Error" variant="destructive" />
 <Badge label="Draft" variant="secondary" size="sm" />
 <Badge label="Beta" variant="outline" />
-<Badge icon={<CheckIcon size={12} />} size="sm">Verified</Badge>
+<Badge label="Active" variant="default" iconName="check" size="sm" />
+<Badge label="Error" variant="destructive" iconName="alert-circle" />
 ```
 
 ---
@@ -528,6 +633,8 @@ All sub-components (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`,
 | description | `string` | — | Detail text |
 | variant | `'default' \| 'destructive' \| 'success'` | `'default'` | Controls border/text color |
 | icon | `ReactNode` | — | Icon placed to the left of the text content. Defaults to a variant-appropriate symbol (`ℹ`, `⚠`, `✓`) |
+| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` (but still falls back to the variant default when neither is set) |
+| iconColor | `string` | — | Override icon color. Defaults to the variant title color |
 | style | `ViewStyle` | — | — |
 
 **Example:**
@@ -535,6 +642,7 @@ All sub-components (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`,
 <AlertBanner title="Info" description="Your session will expire in 5 minutes." />
 <AlertBanner variant="destructive" title="Error" description="Failed to save. Try again." />
 <AlertBanner variant="success" title="Done" description="Your changes have been saved." />
+<AlertBanner iconName="bell" title="Reminder" description="Complete your profile." />
 ```
 
 ---
@@ -549,6 +657,8 @@ All sub-components (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`,
 | title | `string` | required | — |
 | description | `string` | — | — |
 | icon | `ReactNode` | — | Shown in a 48×48 muted square above the text |
+| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon`. Sized automatically (48 default, 32 compact) |
+| iconColor | `string` | — | Override icon color. Defaults to `mutedForeground` |
 | action | `ReactNode` | — | Usually a `Button`, placed below the text |
 | size | `'default' \| 'compact'` | `'default'` | `compact` hides description/action, uses a 36×36 icon, smaller title (15px), and tighter spacing |
 | style | `ViewStyle` | — | — |
@@ -560,6 +670,8 @@ All sub-components (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`,
   description="You're all caught up!"
   action={<Button label="Refresh" variant="outline" size="sm" />}
 />
+<EmptyState iconName="inbox" title="No messages" description="You're all caught up." />
+<EmptyState iconName="search" title="No results" size="compact" />
 ```
 
 ---
@@ -621,14 +733,19 @@ const [accepted, setAccepted] = useState(false)
 | label | `string` | — | Text label |
 | icon | `ReactNode \| ((pressed: boolean) => ReactNode)` | — | Icon shown when not pressed — can be combined with `label` |
 | activeIcon | `ReactNode \| ((pressed: boolean) => ReactNode)` | — | Icon shown when pressed. If omitted, a default `✓` check mark is shown |
+| iconName | `string` | — | Icon name from `@expo/vector-icons` shown when not pressed. Takes precedence over `icon` |
+| activeIconName | `string` | — | Icon name shown when pressed. Takes precedence over `activeIcon` |
+| iconColor | `string` | — | Override inactive icon color. Defaults to `mutedForeground` |
+| activeIconColor | `string` | — | Override active icon color. Defaults to `primary` |
 
 **Animation:** `borderColor` and `backgroundColor` animate via `Animated.timing` (150ms, `Easing.out`) on press state change. `borderWidth` stays fixed at 2pt to prevent layout jumps.
 
 **Example:**
 ```tsx
 <Toggle pressed={bold} onPressedChange={setBold} label="Bold" variant="outline" />
+<Toggle pressed={muted} onPressedChange={setMuted} iconName="volume-x" activeIconName="volume" />
 
-// With custom active icon
+// With custom active icon (ReactNode)
 <Toggle
   pressed={favorited}
   onPressedChange={setFavorited}
@@ -873,6 +990,9 @@ function MyComponent() {
       onPress={async () => {
         await save()
         toast({ title: 'Saved', description: 'Your changes were saved.', variant: 'success' })
+        // With custom icon name
+        toast({ title: 'Saved', variant: 'success', iconName: 'check-circle' })
+        toast({ title: 'Oops', variant: 'destructive', iconName: 'x-circle' })
       }}
     />
   )
@@ -888,6 +1008,8 @@ function MyComponent() {
 | variant | `'default' \| 'destructive' \| 'success'` | `'default'` | `default`: dark background. `destructive`: red. `success`: green |
 | duration | `number` (ms) | `3000` | Auto-dismiss after this delay |
 | icon | `ReactNode` | — | Custom icon node. Defaults to a variant-appropriate symbol (`✓`, `✖`, `ℹ`) at 22px |
+| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
+| iconColor | `string` | — | Override icon color. Defaults to variant text color |
 
 **`dismiss(id)`:** Dismiss a toast programmatically. The `id` is returned by the `toast()` call — store it if you need programmatic dismissal.
 
@@ -913,6 +1035,10 @@ function MyComponent() {
 | caption | `string` | — | Tertiary / caption line below the subtitle (12px / 400 weight, 70% opacity) |
 | leftRender | `ReactNode` | — | Arbitrary content in a fixed 44×44pt left slot (avatar, icon, image, etc.) |
 | rightRender | `string \| ReactNode` | — | Content on the right edge. Strings are styled as muted text (15px); pass ReactNode for Badges, prices, switches, etc. |
+| leftIcon | `string` | — | Icon name from `@expo/vector-icons` in the left slot. Takes precedence over `leftRender`. Size 24, color `foreground` |
+| rightIcon | `string` | — | Icon name from `@expo/vector-icons` in the right slot. Takes precedence over `rightRender`. Size 24, color `mutedForeground` |
+| leftIconColor | `string` | — | Override left icon color |
+| rightIconColor | `string` | — | Override right icon color |
 | variant | `'plain' \| 'card'` | `'plain'` | `plain`: no background, sits inside a parent surface. `card`: standalone surface with background, border, and shadow |
 | showChevron | `boolean` | `false` | Shows a `›` chevron on the far right. Ignored when `rightRender` is set |
 | showSeparator | `boolean` | `false` | Renders a hairline separator at the bottom. Useful when stacking multiple plain items in a list |
@@ -952,10 +1078,14 @@ function MyComponent() {
   onPress={() => navigate('detail', { id: item.id })}
 />
 
+// Icon name props (no manual imports needed)
+<ListItem title="Profile" leftIcon="user" rightIcon="chevron-right" onPress={() => {}} />
+<ListItem title="Notifications" leftIcon="bell" subtitle="3 unread" showChevron />
+
 // Card variant (standalone surface)
 <ListItem
   variant="card"
-  leftRender={<Ionicons name="wallet-outline" size={20} />}
+  leftIcon="credit-card"
   title="Balance"
   subtitle="Available funds"
   rightRender="$12.500"
@@ -1117,3 +1247,113 @@ const [period, setPeriod] = useState({ month: new Date().getMonth() + 1, year: n
 <MonthPicker value={period} onChange={setPeriod} />
 // Displays: "April 2026"
 ```
+
+---
+
+## Icon System
+
+The library ships a built-in icon resolver so you can pass a plain icon name string to any component — no manual imports, no size guessing, no color math.
+
+### Supported families
+
+Icons are resolved by checking each family's glyph map in priority order (first match wins):
+
+| Priority | Family | Best for |
+|---|---|---|
+| 1 (highest) | `Feather` | Clean line icons, UI essentials |
+| 2 | `AntDesign` | Semantic UI icons |
+| 3 | `Entypo` | Social, media, navigation icons |
+| 4 | `FontAwesome5` | Wide coverage of named icons |
+| 5 | `MaterialIcons` | Material-style icons |
+| 6 (lowest) | `Ionicons` | Fallback |
+
+Browse all available icons: **https://icons.expo.fyi**
+
+### Standalone `Icon` component
+
+```tsx
+import { Icon } from '@retray-dev/ui-kit'
+
+<Icon name="home" size={24} color="#000" />
+<Icon name="star" size={20} color={colors.primary} />
+
+// Force a specific family when the same name exists in multiple families:
+<Icon name="heart" size={24} color="red" family="FontAwesome5" />
+```
+
+**Props:**
+
+| Prop | Type | Required | Description |
+|---|---|---|---|
+| `name` | `string` | Yes | Icon name (e.g. `"home"`, `"star"`, `"arrow-right"`) |
+| `size` | `number` | Yes | Icon size in points |
+| `color` | `string` | Yes | Icon color |
+| `family` | `IconFamily` | No | Override resolved family |
+
+Returns `null` (no crash) if the icon name is not found in any family.
+
+### `renderIcon` helper
+
+```tsx
+import { renderIcon } from '@retray-dev/ui-kit'
+
+const node = renderIcon('check', 18, colors.primary)
+```
+
+### `iconName` props on components
+
+Each component that accepts icon slots now has a corresponding `iconName` prop. Pass the icon name as a string and the library resolves size and color automatically.
+
+| Component | Prop(s) | Slot | Default size | Default color |
+|---|---|---|---|---|
+| `Button` | `iconName`, `iconColor` | Left or right of label | sm=16 / md=18 / lg=20 | Variant label color |
+| `Input` | `prefixIcon`, `prefixIconColor` | Before input text | 20 | `mutedForeground` |
+| `Input` | `suffixIcon`, `suffixIconColor` | After input text | 20 | `mutedForeground` |
+| `ListItem` | `leftIcon`, `leftIconColor` | Left 44×44 slot | 24 | `foreground` |
+| `ListItem` | `rightIcon`, `rightIconColor` | Right slot | 24 | `mutedForeground` |
+| `Badge` | `iconName`, `iconColor` | Before label | sm=10 / md=12 / lg=14 | Variant foreground |
+| `Toggle` | `iconName`, `iconColor` | When not pressed | sm=16 / md=18 / lg=20 | `mutedForeground` |
+| `Toggle` | `activeIconName`, `activeIconColor` | When pressed | sm=16 / md=18 / lg=20 | `primary` |
+| `AlertBanner` | `iconName`, `iconColor` | Left of content | 18 | Variant title color |
+| `EmptyState` | `iconName`, `iconColor` | Center icon slot | default=48 / compact=32 | `mutedForeground` |
+| `Toast` | `iconName`, `iconColor` | Left of message | 22 | Variant text color |
+
+**Precedence:** `iconName` takes precedence over the corresponding ReactNode prop (`icon`, `prefix`, `suffix`, etc.) when both are supplied.
+
+**Backward compatibility:** All existing `icon`, `prefix`, `suffix`, `leftRender`, `rightRender` ReactNode props continue to work exactly as before.
+
+**Example — Button with icon:**
+```tsx
+<Button label="Continue" iconName="arrow-right" iconPosition="right" />
+<Button label="Delete" variant="destructive" iconName="trash-2" />
+```
+
+**Example — Input with icons:**
+```tsx
+<Input placeholder="Search..." prefixIcon="search" />
+<Input placeholder="Amount" prefixIcon="dollar-sign" suffixIcon="check" />
+```
+
+**Example — ListItem with icons:**
+```tsx
+<ListItem title="Profile" leftIcon="user" rightIcon="chevron-right" />
+<ListItem title="Notifications" leftIcon="bell" subtitle="3 unread" showChevron />
+```
+
+**Example — Badge with icon:**
+```tsx
+<Badge label="Active" variant="default" iconName="check" size="sm" />
+<Badge label="Error" variant="destructive" iconName="alert-circle" />
+```
+
+**Example — Toast with icon:**
+```tsx
+const { toast } = useToast()
+toast({ title: "Saved", variant: "success", iconName: "check-circle" })
+toast({ title: "Oops", variant: "destructive", iconName: "x-circle" })
+```
+
+**Example — EmptyState with icon:**
+```tsx
+<EmptyState iconName="inbox" title="No messages" description="You're all caught up." />
+```

package/README.md

@@ -95,6 +95,24 @@ const { colors, colorScheme } = useTheme()
 
 **Available tokens:** `background`, `foreground`, `card`, `cardForeground`, `primary`, `primaryForeground`, `secondary`, `secondaryForeground`, `muted`, `mutedForeground`, `accent`, `accentForeground`, `destructive`, `destructiveForeground`, `border`, `input`, `ring`, `success`, `successForeground`
 
+## Design Tokens
+
+Static structural constants — no provider required:
+
+```ts
+import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS } from '@retray-dev/ui-kit'
+
+<View style={{ gap: SPACING.md, padding: SPACING.lg, borderRadius: RADIUS.lg, ...SHADOWS.sm }} />
+```
+
+| Token | Keys |
+|-------|------|
+| `SPACING` | `xs` (4), `sm` (8), `md` (12), `lg` (16), `xl` (24), `2xl` (32), `3xl` (48) |
+| `ICON_SIZES` | `sm` (14), `md` (18), `lg` (22), `xl` (28), `2xl` (32) |
+| `RADIUS` | `sm` (4), `md` (8), `lg` (12), `xl` (16), `full` (9999) |
+| `SHADOWS` | `sm`, `md`, `lg`, `xl` — cross-platform shadow presets |
+| `BREAKPOINTS` | `wide` (700) |
+
 ## Components
 
 | Category    | Components                                                                                      |

package/dist/index.d.mts

@@ -75,10 +75,18 @@ interface ButtonProps extends TouchableOpacityProps {
         size: ButtonSize;
         variant: ButtonVariant;
     }) => React.ReactNode);
+    /**
+     * Icon name from `@expo/vector-icons` (e.g. `"home"`, `"star"`, `"arrow-right"`).
+     * See https://icons.expo.fyi to browse available icons.
+     * Takes precedence over `icon` when both are supplied.
+     */
+    iconName?: string;
+    /** Override the resolved icon color. Defaults to the label foreground color for the active variant. */
+    iconColor?: string;
     /** Side the icon appears on. Defaults to `'left'`. */
     iconPosition?: 'left' | 'right';
 }
-declare function Button({ label, variant, size, loading, fullWidth, icon, iconPosition, disabled, style, onPress, ...props }: ButtonProps): React.JSX.Element;
+declare function Button({ label, variant, size, loading, fullWidth, icon, iconName, iconColor, iconPosition, disabled, style, onPress, ...props }: ButtonProps): React.JSX.Element;
 
 type TextVariant = 'h1' | 'h2' | 'h3' | 'body' | 'caption' | 'label';
 interface TextProps extends TextProps$1 {
@@ -101,12 +109,26 @@ interface InputProps extends TextInputProps {
     prefixStyle?: TextStyle;
     /** Style applied to suffix text if suffix is a string. */
     suffixStyle?: TextStyle;
+    /**
+     * Icon name from `@expo/vector-icons` rendered before the input text.
+     * See https://icons.expo.fyi. Takes precedence over `prefix`.
+     */
+    prefixIcon?: string;
+    /**
+     * Icon name from `@expo/vector-icons` rendered after the input text.
+     * See https://icons.expo.fyi. Takes precedence over `suffix` (unless `type="password"`).
+     */
+    suffixIcon?: string;
+    /** Override the resolved prefix icon color. Defaults to `mutedForeground`. */
+    prefixIconColor?: string;
+    /** Override the resolved suffix icon color. Defaults to `mutedForeground`. */
+    suffixIconColor?: string;
     /** Input type. When set to \`'password'\`, shows a toggle button to reveal/hide text. */
     type?: 'text' | 'password';
     /** Style for the outer container \`View\`. Use \`style\` (from \`TextInputProps\`) to style the \`TextInput\` itself. */
     containerStyle?: ViewStyle;
 }
-declare function Input({ label, error, hint, prefix, suffix, prefixStyle, suffixStyle, type, containerStyle, style, onFocus, onBlur, secureTextEntry, ...props }: InputProps): React.JSX.Element;
+declare function Input({ label, error, hint, prefix, suffix, prefixStyle, suffixStyle, prefixIcon, suffixIcon, prefixIconColor, suffixIconColor, type, containerStyle, style, onFocus, onBlur, secureTextEntry, ...props }: InputProps): React.JSX.Element;
 
 type BadgeVariant = 'default' | 'secondary' | 'destructive' | 'outline';
 type BadgeSize = 'sm' | 'md' | 'lg';
@@ -118,9 +140,16 @@ interface BadgeProps {
     size?: BadgeSize;
     /** Icon rendered before the label/children. */
     icon?: React.ReactNode;
+    /**
+     * Icon name from `@expo/vector-icons` rendered before the label.
+     * See https://icons.expo.fyi. Takes precedence over `icon`.
+     */
+    iconName?: string;
+    /** Override the resolved icon color. Defaults to the variant foreground color. */
+    iconColor?: string;
     style?: ViewStyle;
 }
-declare function Badge({ label, children, variant, size, icon, style }: BadgeProps): React.JSX.Element;
+declare function Badge({ label, children, variant, size, icon, iconName, iconColor, style }: BadgeProps): React.JSX.Element;
 
 type CardVariant = 'elevated' | 'outlined' | 'filled';
 interface CardProps {
@@ -196,9 +225,16 @@ interface AlertBannerProps {
     description?: string;
     variant?: AlertBannerVariant;
     icon?: React.ReactNode;
+    /**
+     * Icon name from `@expo/vector-icons`. See https://icons.expo.fyi.
+     * Takes precedence over `icon`. When neither is set, a default variant icon is shown.
+     */
+    iconName?: string;
+    /** Override the resolved icon color. Defaults to the variant title color. */
+    iconColor?: string;
     style?: ViewStyle;
 }
-declare function AlertBanner({ title, description, variant, icon, style }: AlertBannerProps): React.JSX.Element;
+declare function AlertBanner({ title, description, variant, icon, iconName, iconColor, style }: AlertBannerProps): React.JSX.Element;
 
 interface ProgressProps {
     /** Current progress value. Clamped to `[0, max]`. Defaults to `0`. */
@@ -211,6 +247,13 @@ declare function Progress({ value, max, style }: ProgressProps): React.JSX.Eleme
 
 interface EmptyStateProps {
     icon?: React.ReactNode;
+    /**
+     * Icon name from `@expo/vector-icons`. See https://icons.expo.fyi.
+     * Takes precedence over `icon`. Sized automatically to fit the slot (48 default, 32 compact).
+     */
+    iconName?: string;
+    /** Override the resolved icon color. Defaults to `mutedForeground`. */
+    iconColor?: string;
     title: string;
     description?: string;
     action?: React.ReactNode;
@@ -218,7 +261,7 @@ interface EmptyStateProps {
     size?: 'default' | 'compact';
     style?: ViewStyle;
 }
-declare function EmptyState({ icon, title, description, action, size, style }: EmptyStateProps): React.JSX.Element;
+declare function EmptyState({ icon, iconName, iconColor, title, description, action, size, style }: EmptyStateProps): React.JSX.Element;
 
 interface TextareaProps extends TextInputProps {
     label?: string;
@@ -262,8 +305,22 @@ interface ToggleProps extends TouchableOpacityProps {
     icon?: React.ReactNode | ((pressed: boolean) => React.ReactNode);
     /** Icon to show when pressed/active. If omitted, a default check mark is used. */
     activeIcon?: React.ReactNode | ((pressed: boolean) => React.ReactNode);
+    /**
+     * Icon name from `@expo/vector-icons` shown when not pressed.
+     * See https://icons.expo.fyi. Takes precedence over `icon`.
+     */
+    iconName?: string;
+    /**
+     * Icon name from `@expo/vector-icons` shown when pressed/active.
+     * See https://icons.expo.fyi. Takes precedence over `activeIcon`.
+     */
+    activeIconName?: string;
+    /** Override the resolved inactive icon color. Defaults to `mutedForeground`. */
+    iconColor?: string;
+    /** Override the resolved active icon color. Defaults to `primary`. */
+    activeIconColor?: string;
 }
-declare function Toggle({ pressed, onPressedChange, variant, size, label, icon, activeIcon, disabled, style, ...props }: ToggleProps): React.JSX.Element;
+declare function Toggle({ pressed, onPressedChange, variant, size, label, icon, activeIcon, iconName, activeIconName, iconColor, activeIconColor, disabled, style, ...props }: ToggleProps): React.JSX.Element;
 
 interface RadioOption {
     label: string;
@@ -378,6 +435,13 @@ interface ToastItem {
     description?: string;
     variant?: ToastVariant;
     icon?: React.ReactNode;
+    /**
+     * Icon name from `@expo/vector-icons`. See https://icons.expo.fyi.
+     * Takes precedence over `icon`. When neither is set, a default variant icon is shown.
+     */
+    iconName?: string;
+    /** Override the resolved icon color. Defaults to the variant text color. */
+    iconColor?: string;
     /** Auto-dismiss delay in milliseconds. Defaults to `3000`. */
     duration?: number;
 }
@@ -446,6 +510,20 @@ interface ListItemProps {
     trailing?: React.ReactNode | string;
     /** @deprecated Use `leftRender` instead. */
     icon?: React.ReactNode;
+    /**
+     * Icon name from `@expo/vector-icons` rendered in the left slot.
+     * See https://icons.expo.fyi. Takes precedence over `leftRender`.
+     */
+    leftIcon?: string;
+    /**
+     * Icon name from `@expo/vector-icons` rendered in the right slot.
+     * See https://icons.expo.fyi. Takes precedence over `rightRender`.
+     */
+    rightIcon?: string;
+    /** Override the resolved left icon color. Defaults to `foreground`. */
+    leftIconColor?: string;
+    /** Override the resolved right icon color. Defaults to `mutedForeground`. */
+    rightIconColor?: string;
     title: string;
     /** Secondary line below the title. */
     subtitle?: string;
@@ -471,7 +549,7 @@ interface ListItemProps {
     /** Style applied to the caption Text. */
     captionStyle?: TextStyle;
 }
-declare function ListItem({ leftRender, rightRender, trailing, icon, title, subtitle, caption, variant, showChevron, showSeparator, onPress, disabled, style, titleStyle, subtitleStyle, captionStyle, }: ListItemProps): React.JSX.Element;
+declare function ListItem({ leftRender, rightRender, trailing, icon, leftIcon, rightIcon, leftIconColor, rightIconColor, title, subtitle, caption, variant, showChevron, showSeparator, onPress, disabled, style, titleStyle, subtitleStyle, captionStyle, }: ListItemProps): React.JSX.Element;
 
 interface ChipProps {
     label: string;
@@ -525,4 +603,91 @@ interface MonthPickerProps {
 }
 declare function MonthPicker({ value, onChange, style }: MonthPickerProps): React.JSX.Element;
 
-export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, Avatar, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeVariant, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, CardContent, type CardContentProps, CardDescription, type CardDescriptionProps, CardFooter, type CardFooterProps, CardHeader, type CardHeaderProps, type CardProps, CardTitle, type CardTitleProps, Checkbox, type CheckboxProps, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, CurrencyInput, CurrencyInput as CurrencyInputLarge, type CurrencyInputProps, EmptyState, type EmptyStateProps, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, Progress, type ProgressProps, RadioGroup, type RadioGroupProps, type RadioOption, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, type SpinnerSize, Switch, type SwitchProps, type TabItem, Tabs, TabsContent, type TabsContentProps, type TabsProps, Text, type TextProps, type TextVariant, Textarea, type TextareaProps, type Theme, type ThemeColors, ThemeProvider, type ThemeProviderProps, type ToastItem, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, type ToggleVariant, defaultDark, defaultLight, useTheme, useToast };
+type IconFamily = 'Feather' | 'AntDesign' | 'Entypo' | 'FontAwesome5' | 'MaterialIcons' | 'Ionicons';
+interface IconProps {
+    /** Icon name from any supported @expo/vector-icons family. See https://icons.expo.fyi */
+    name: string;
+    size: number;
+    color: string;
+    /** Override the resolved family when the same name exists in multiple families. */
+    family?: IconFamily;
+}
+declare function Icon({ name, size, color, family }: IconProps): React.ReactElement | null;
+declare function renderIcon(name: string, size: number, color: string): React.ReactElement | null;
+
+declare const SPACING: {
+    readonly xs: 4;
+    readonly sm: 8;
+    readonly md: 12;
+    readonly lg: 16;
+    readonly xl: 24;
+    readonly '2xl': 32;
+    readonly '3xl': 48;
+};
+declare const ICON_SIZES: {
+    readonly sm: 14;
+    readonly md: 18;
+    readonly lg: 22;
+    readonly xl: 28;
+    readonly '2xl': 32;
+};
+declare const RADIUS: {
+    readonly sm: 4;
+    readonly md: 8;
+    readonly lg: 12;
+    readonly xl: 16;
+    readonly full: 9999;
+};
+declare const SHADOWS: {
+    readonly sm: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 1;
+        };
+        readonly shadowOpacity: 0.08;
+        readonly shadowRadius: 4;
+        readonly elevation: 2;
+    };
+    readonly md: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 3;
+        };
+        readonly shadowOpacity: 0.12;
+        readonly shadowRadius: 8;
+        readonly elevation: 5;
+    };
+    readonly lg: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 6;
+        };
+        readonly shadowOpacity: 0.2;
+        readonly shadowRadius: 16;
+        readonly elevation: 10;
+    };
+    readonly xl: {
+        readonly shadowColor: "#000";
+        readonly shadowOffset: {
+            readonly width: 0;
+            readonly height: 12;
+        };
+        readonly shadowOpacity: 0.28;
+        readonly shadowRadius: 24;
+        readonly elevation: 18;
+    };
+};
+declare const BREAKPOINTS: {
+    readonly wide: 700;
+};
+type Spacing = typeof SPACING;
+type SpacingKey = keyof Spacing;
+type IconSize = typeof ICON_SIZES;
+type IconSizeKey = keyof IconSize;
+type Radius = typeof RADIUS;
+type RadiusKey = keyof Radius;
+
+export { Accordion, type AccordionItem, type AccordionProps, AlertBanner, type AlertBannerProps, type AlertBannerVariant, Avatar, type AvatarProps, type AvatarSize, BREAKPOINTS, Badge, type BadgeProps, type BadgeVariant, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Card, CardContent, type CardContentProps, CardDescription, type CardDescriptionProps, CardFooter, type CardFooterProps, CardHeader, type CardHeaderProps, type CardProps, CardTitle, type CardTitleProps, Checkbox, type CheckboxProps, Chip, ChipGroup, type ChipGroupProps, type ChipOption, type ChipProps, type ColorScheme, ConfirmDialog, type ConfirmDialogProps, CurrencyDisplay, type CurrencyDisplayProps, CurrencyInput, CurrencyInput as CurrencyInputLarge, type CurrencyInputProps, EmptyState, type EmptyStateProps, ICON_SIZES, Icon, type IconFamily, type IconProps, type IconSize, type IconSizeKey, Input, type InputProps, LabelValue, type LabelValueProps, ListItem, type ListItemProps, MonthPicker, type MonthPickerProps, type MonthPickerValue, Progress, type ProgressProps, RADIUS, RadioGroup, type RadioGroupProps, type RadioOption, type Radius, type RadiusKey, SHADOWS, SPACING, Select, type SelectOption, type SelectProps, Separator, type SeparatorProps, Sheet, type SheetProps, Skeleton, type SkeletonProps, Slider, type SliderProps, type Spacing, type SpacingKey, Spinner, type SpinnerProps, type SpinnerSize, Switch, type SwitchProps, type TabItem, Tabs, TabsContent, type TabsContentProps, type TabsProps, Text, type TextProps, type TextVariant, Textarea, type TextareaProps, type Theme, type ThemeColors, ThemeProvider, type ThemeProviderProps, type ToastItem, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, type ToggleSize, type ToggleVariant, defaultDark, defaultLight, renderIcon, useTheme, useToast };