@retray-dev/ui-kit 0.1.0 → 1.5.0

package/COMPONENTS.md

@@ -0,0 +1,710 @@
+# @retray-dev/ui-kit — Component Reference
+
+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:
+
+```markdown
+## UI Components
+@./node_modules/@retray-dev/ui-kit/COMPONENTS.md
+```
+
+---
+
+## Setup (Required)
+
+Wrap your app root with all required providers in this exact order:
+
+```tsx
+import { SafeAreaProvider, initialWindowMetrics } from 'react-native-safe-area-context'
+import { GestureHandlerRootView } from 'react-native-gesture-handler'
+import { ThemeProvider, BottomSheetModalProvider, ToastProvider } from '@retray-dev/ui-kit'
+
+export default function App() {
+  return (
+    <SafeAreaProvider initialMetrics={initialWindowMetrics}>
+      <GestureHandlerRootView style={{ flex: 1 }}>
+        <ThemeProvider colorScheme="system">
+          <BottomSheetModalProvider>
+            <ToastProvider>
+              {/* your app */}
+            </ToastProvider>
+          </BottomSheetModalProvider>
+        </ThemeProvider>
+      </GestureHandlerRootView>
+    </SafeAreaProvider>
+  )
+}
+```
+
+**Provider order is mandatory:**
+- `SafeAreaProvider` must be outermost — required by `useSafeAreaInsets` in `ToastProvider`
+- `initialMetrics={initialWindowMetrics}` is required on Android to avoid a "No safe area value available" crash on first render
+- `GestureHandlerRootView` must wrap everything — required by `@gorhom/bottom-sheet`
+- `BottomSheetModalProvider` must be inside `GestureHandlerRootView`
+- `ToastProvider` must be inside `SafeAreaProvider`
+
+### ThemeProvider Props
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| colorScheme | `'light' \| 'dark' \| 'system'` | `'system'` | `'system'` auto-detects the device setting and updates when it changes |
+| theme | `{ light?: Partial<ThemeColors>, dark?: Partial<ThemeColors> }` | — | Override any subset of color tokens per scheme |
+
+**Custom theme example:**
+```tsx
+const myTheme = {
+  light: { primary: '#6366f1', primaryForeground: '#ffffff' },
+  dark:  { primary: '#818cf8', primaryForeground: '#ffffff' },
+}
+<ThemeProvider theme={myTheme} colorScheme="system">
+```
+
+### useTheme Hook
+
+Access the active color tokens and scheme inside any component:
+```tsx
+import { useTheme } from '@retray-dev/ui-kit'
+
+function MyComponent() {
+  const { colors, colorScheme } = useTheme()
+  return <View style={{ backgroundColor: colors.background }} />
+}
+```
+
+---
+
+## Theme Tokens
+
+All 18 tokens are available via `useTheme().colors`.
+
+| Token | Light | Dark | Semantic Role |
+|-------|-------|------|---------------|
+| `background` | `#ffffff` | `#171717` | Screen / page background |
+| `foreground` | `#171717` | `#fafafa` | Primary text color |
+| `card` | `#ffffff` | `#1f1f1f` | Card / surface background |
+| `cardForeground` | `#171717` | `#fafafa` | Text on cards |
+| `primary` | `#1a1a1a` | `#fafafa` | Primary action (buttons, selected states) |
+| `primaryForeground` | `#fafafa` | `#1a1a1a` | Text/icon on primary background |
+| `secondary` | `#f5f5f5` | `#2a2a2a` | Secondary surfaces |
+| `secondaryForeground` | `#1a1a1a` | `#fafafa` | Text on secondary |
+| `muted` | `#f5f5f5` | `#2a2a2a` | Muted backgrounds, skeleton fills, track fills |
+| `mutedForeground` | `#646464` | `#a3a3a3` | Placeholder text, helper text, captions (WCAG AA ≥4.5:1) |
+| `accent` | `#f5f5f5` | `#2a2a2a` | Hover / pressed state fills |
+| `accentForeground` | `#1a1a1a` | `#fafafa` | Text on accent |
+| `destructive` | `#ef4444` | `#dc2626` | Error / danger / delete actions |
+| `destructiveForeground` | `#fafafa` | `#fafafa` | Text on destructive |
+| `border` | `#e5e5e5` | `#2a2a2a` | Borders and dividers |
+| `input` | `#e5e5e5` | `#2a2a2a` | Input field border color |
+| `ring` | `#a3a3a3` | `#d4d4d4` | Focus ring color |
+
+---
+
+## Components
+
+---
+
+### Text
+
+**Import:** `import { Text } from '@retray-dev/ui-kit'`
+**When to use:** All text in the app. Replaces React Native's `Text` with semantic variants.
+**Extends:** `TextProps` from React Native — all native props pass through.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| variant | `'h1' \| 'h2' \| 'h3' \| 'body' \| 'caption' \| 'label'` | `'body'` | Sets font size, weight, and line height |
+| color | `string` | — | Override the color. Defaults to `foreground`, except `caption` which uses `mutedForeground` |
+
+**Sizes:**
+- `h1`: 32px / 700 weight
+- `h2`: 24px / 700 weight
+- `h3`: 20px / 600 weight
+- `body`: 16px / 400 weight
+- `label`: 14px / 500 weight
+- `caption`: 12px / 400 weight / `mutedForeground` color by default
+
+**Example:**
+```tsx
+<Text variant="h2">Welcome back</Text>
+<Text variant="body">Your account is ready.</Text>
+<Text variant="caption">Last updated 2 hours ago</Text>
+<Text variant="label" color="#6366f1">Pro plan</Text>
+```
+
+---
+
+### Button
+
+**Import:** `import { Button } from '@retray-dev/ui-kit'`
+**When to use:** Any interactive action. Use `variant` to communicate intent.
+**Extends:** `TouchableOpacityProps` — all RN TouchableOpacity props pass through.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| label | `string` | required | Button text |
+| variant | `'primary' \| 'secondary' \| 'outline' \| 'ghost'` | `'primary'` | Visual style |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | — |
+| loading | `boolean` | `false` | Replaces label with a spinner and forces disabled state |
+| fullWidth | `boolean` | `false` | Stretches to container width (`alignSelf: 'stretch'`) |
+| disabled | `boolean` | — | Reduces opacity to 0.45 |
+
+**Variants:**
+- `primary`: filled with `primary` token — main actions
+- `secondary`: filled with `secondary` token — less prominent actions
+- `outline`: transparent with `border` — alternative without fill
+- `ghost`: fully transparent — in-context or low-emphasis actions
+
+**Animations:** Scale springs to 0.97 on `onPressIn`, back to 1.0 on `onPressOut`.
+
+**Example:**
+```tsx
+<Button label="Save changes" onPress={handleSave} />
+<Button label="Cancel" variant="ghost" onPress={onCancel} />
+<Button label="Delete" variant="outline" size="sm" />
+<Button label="Submitting..." loading fullWidth />
+```
+
+---
+
+### Input
+
+**Import:** `import { Input } from '@retray-dev/ui-kit'`
+**When to use:** Single-line text entry. Includes built-in label, error, and hint support.
+**Extends:** `TextInputProps` from React Native — all native props pass through.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| label | `string` | — | Label above the input |
+| error | `string` | — | Shows error text below; turns border red (`destructive` token) |
+| hint | `string` | — | Helper text below (hidden when `error` is set) |
+
+**Border colors:** `destructive` when `error` is set, `ring` when focused, `border` otherwise.
+
+**Example:**
+```tsx
+<Input label="Email" placeholder="you@example.com" keyboardType="email-address" />
+<Input label="Password" secureTextEntry error="Incorrect password" />
+<Input label="Username" hint="Must be at least 4 characters" />
+```
+
+---
+
+### Textarea
+
+**Import:** `import { Textarea } from '@retray-dev/ui-kit'`
+**When to use:** Multi-line text entry. Same API as `Input` plus `rows`.
+**Extends:** `TextInputProps` from React Native — all native props pass through.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| label | `string` | — | Label above |
+| error | `string` | — | Error text below; red border |
+| hint | `string` | — | Helper text below |
+| rows | `number` | `4` | Sets `minHeight` (each row ≈ 28px) |
+
+**Example:**
+```tsx
+<Textarea label="Bio" placeholder="Tell us about yourself" rows={5} />
+```
+
+---
+
+### Badge
+
+**Import:** `import { Badge } from '@retray-dev/ui-kit'`
+**When to use:** Status labels, tags, counts.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| label | `string` | required | — |
+| variant | `'default' \| 'secondary' \| 'destructive' \| 'outline'` | `'default'` | — |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<Badge label="New" />
+<Badge label="Error" variant="destructive" />
+<Badge label="Draft" variant="secondary" />
+<Badge label="Beta" variant="outline" />
+```
+
+---
+
+### Avatar
+
+**Import:** `import { Avatar } from '@retray-dev/ui-kit'`
+**When to use:** User profile pictures with automatic fallback to initials.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| src | `string` | — | Image URI |
+| fallback | `string` | — | Text shown when image fails or `src` is absent — first 2 chars, uppercased |
+| size | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | sm=24, md=32, lg=48, xl=64 (diameter in pt) |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<Avatar src="https://..." fallback="JC" size="lg" />
+<Avatar fallback="AN" size="md" />
+```
+
+---
+
+### Separator
+
+**Import:** `import { Separator } from '@retray-dev/ui-kit'`
+**When to use:** Visual dividers between sections.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| orientation | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical requires a parent with a defined height |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<Separator />
+<View style={{ flexDirection: 'row', height: 40 }}>
+  <Text>Left</Text>
+  <Separator orientation="vertical" style={{ marginHorizontal: 12 }} />
+  <Text>Right</Text>
+</View>
+```
+
+---
+
+### Spinner
+
+**Import:** `import { Spinner } from '@retray-dev/ui-kit'`
+**When to use:** Loading state indicator. Wraps React Native's `ActivityIndicator`.
+**Extends:** `ActivityIndicatorProps` (except `size`).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | `sm`/`md` map to RN `'small'`, `lg` maps to `'large'` |
+| color | `string` | `primary` token | Override spinner color |
+
+**Example:**
+```tsx
+<Spinner />
+<Spinner size="lg" color="#6366f1" />
+```
+
+---
+
+### Skeleton
+
+**Import:** `import { Skeleton } from '@retray-dev/ui-kit'`
+**When to use:** Placeholder while content is loading. Pulses with a looping opacity animation.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| width | `number \| string` | `'100%'` | — |
+| height | `number` | `16` | — |
+| borderRadius | `number` | `6` | — |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<Skeleton height={20} width="60%" />
+<Skeleton height={80} borderRadius={10} />
+```
+
+---
+
+### Progress
+
+**Import:** `import { Progress } from '@retray-dev/ui-kit'`
+**When to use:** Show completion percentage for a task or upload.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `number` | `0` | Current value |
+| max | `number` | `100` | Maximum value |
+| style | `ViewStyle` | — | — |
+
+**Animation:** Spring-animates the fill width on `value` changes (JS thread — `useNativeDriver: false`). Uses `onLayout` to capture track pixel width and interpolates to pixels (cannot animate `width: '%'`).
+
+**Example:**
+```tsx
+<Progress value={60} />
+<Progress value={3} max={10} />
+```
+
+---
+
+### Card
+
+**Import:** `import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@retray-dev/ui-kit'`
+**When to use:** Grouped content with a surface background, border, and shadow.
+
+All sub-components accept a `style` prop for overrides.
+
+**Example:**
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Account</CardTitle>
+    <CardDescription>Manage your profile settings</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <Input label="Name" />
+  </CardContent>
+  <CardFooter>
+    <Button label="Save" fullWidth />
+  </CardFooter>
+</Card>
+```
+
+**Notes:**
+- `CardHeader` and `CardContent` have `padding: 24`
+- `CardFooter` has `paddingTop: 0` so it connects naturally to `CardContent`
+- `CardTitle`: 18px / 600 weight, `cardForeground` color
+- `CardDescription`: 14px, `mutedForeground` color
+
+---
+
+### Alert
+
+**Import:** `import { Alert } from '@retray-dev/ui-kit'`
+**When to use:** Inline feedback messages (info, success, warning, error). Not for transient toasts.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| title | `string` | — | Bold heading |
+| description | `string` | — | Detail text |
+| variant | `'default' \| 'destructive'` | `'default'` | `destructive` turns border and text to `destructive` token |
+| icon | `ReactNode` | — | Icon placed to the left of the text content |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<Alert title="Success" description="Your profile has been updated." />
+<Alert variant="destructive" title="Error" description="Failed to save. Try again." />
+```
+
+---
+
+### EmptyState
+
+**Import:** `import { EmptyState } from '@retray-dev/ui-kit'`
+**When to use:** When a list or section has no content yet.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| title | `string` | required | — |
+| description | `string` | — | — |
+| icon | `ReactNode` | — | Shown in a 48×48 muted square above the text |
+| action | `ReactNode` | — | Usually a `Button`, placed below the text |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<EmptyState
+  title="No notifications"
+  description="You're all caught up!"
+  action={<Button label="Refresh" variant="outline" size="sm" />}
+/>
+```
+
+---
+
+### Checkbox
+
+**Import:** `import { Checkbox } from '@retray-dev/ui-kit'`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| checked | `boolean` | `false` | — |
+| onCheckedChange | `(checked: boolean) => void` | — | — |
+| label | `string` | — | Text to the right of the box |
+| disabled | `boolean` | — | — |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+const [accepted, setAccepted] = useState(false)
+<Checkbox checked={accepted} onCheckedChange={setAccepted} label="I agree to the terms" />
+```
+
+---
+
+### Switch
+
+**Import:** `import { Switch } from '@retray-dev/ui-kit'`
+**When to use:** Binary on/off settings.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| checked | `boolean` | `false` | — |
+| onCheckedChange | `(checked: boolean) => void` | — | — |
+| disabled | `boolean` | — | Reduces opacity to 0.45 |
+| style | `ViewStyle` | — | — |
+
+**Dimensions:** Track 56×32pt, Thumb 24×24pt with 4pt offset from edges.
+
+**Animation:** Thumb translates via spring (bounciness: 4); track color transitions via opacity timing (150ms).
+
+**Example:**
+```tsx
+<Switch checked={notifications} onCheckedChange={setNotifications} />
+```
+
+---
+
+### Toggle
+
+**Import:** `import { Toggle } from '@retray-dev/ui-kit'`
+**When to use:** Toggleable button (e.g., bold/italic in a toolbar). Looks like a button, unlike `Switch`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| pressed | `boolean` | `false` | — |
+| onPressedChange | `(pressed: boolean) => void` | — | — |
+| variant | `'default' \| 'outline'` | `'default'` | `outline` adds a border when unpressed |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | sm=minH 40pt, md=minH 44pt, lg=minH 48pt |
+| label | `string` | — | Text label |
+| icon | `ReactNode` | — | Icon — can be combined with `label` |
+
+**Example:**
+```tsx
+<Toggle pressed={bold} onPressedChange={setBold} label="Bold" variant="outline" />
+```
+
+---
+
+### RadioGroup
+
+**Import:** `import { RadioGroup } from '@retray-dev/ui-kit'`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| options | `RadioOption[]` | required | Each option: `{ label: string, value: string, disabled?: boolean }` |
+| value | `string` | — | Currently selected value |
+| onValueChange | `(value: string) => void` | — | — |
+| orientation | `'vertical' \| 'horizontal'` | `'vertical'` | — |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<RadioGroup
+  options={[
+    { label: 'Free', value: 'free' },
+    { label: 'Pro', value: 'pro' },
+    { label: 'Enterprise', value: 'enterprise', disabled: true },
+  ]}
+  value={plan}
+  onValueChange={setPlan}
+/>
+```
+
+---
+
+### Select
+
+**Import:** `import { Select } from '@retray-dev/ui-kit'`
+**When to use:** Dropdown picker. Tapping the trigger opens a modal with a scrollable list.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| options | `SelectOption[]` | required | Each option: `{ label: string, value: string, disabled?: boolean }` |
+| value | `string` | — | Selected value |
+| onValueChange | `(value: string) => void` | — | — |
+| placeholder | `string` | `'Select an option'` | Shown when no value is selected |
+| label | `string` | — | Label above the trigger |
+| error | `string` | — | Error text below the trigger |
+| disabled | `boolean` | — | — |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<Select
+  label="Country"
+  options={[{ label: 'Argentina', value: 'AR' }, { label: 'Spain', value: 'ES' }]}
+  value={country}
+  onValueChange={setCountry}
+  placeholder="Pick a country"
+/>
+```
+
+---
+
+### Slider
+
+**Import:** `import { Slider } from '@retray-dev/ui-kit'`
+**When to use:** Select a numeric value within a range by dragging.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `number` | `0` | — |
+| minimumValue | `number` | `0` | — |
+| maximumValue | `number` | `1` | — |
+| step | `number` | `0` | `0` means continuous (no snapping) |
+| onValueChange | `(value: number) => void` | — | Fires while dragging |
+| onSlidingComplete | `(value: number) => void` | — | Fires on finger release |
+| disabled | `boolean` | — | — |
+| style | `ViewStyle` | — | — |
+
+**Dimensions:** Container height=32pt, track height=6pt, thumb 28×28pt. Uses `PanResponder` internally.
+
+**Example:**
+```tsx
+<Slider value={volume} minimumValue={0} maximumValue={100} step={1} onValueChange={setVolume} />
+```
+
+---
+
+### Tabs
+
+**Import:** `import { Tabs, TabsContent } from '@retray-dev/ui-kit'`
+**When to use:** Switching between categorized sections on the same screen.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| tabs | `TabItem[]` | required | Each item: `{ label: string, value: string }` |
+| value | `string` | — | Controlled active tab |
+| onValueChange | `(value: string) => void` | — | — |
+| children | `ReactNode` | — | `TabsContent` components |
+| style | `ViewStyle` | — | — |
+
+**`TabsContent` Props:**
+
+| Prop | Type | Notes |
+|------|------|-------|
+| value | `string` | Must match a tab value in `tabs` |
+| activeValue | `string` | Pass the current active tab — content is hidden when not active |
+| children | `ReactNode` | — |
+| style | `ViewStyle` | — |
+
+**Animation:** An absolutely-positioned pill slides and resizes via spring (speed: 20, bounciness: 0) to track the active tab.
+
+**Example:**
+```tsx
+const [tab, setTab] = useState('profile')
+
+<Tabs
+  tabs={[{ label: 'Profile', value: 'profile' }, { label: 'Security', value: 'security' }]}
+  value={tab}
+  onValueChange={setTab}
+>
+  <TabsContent value="profile" activeValue={tab}>
+    <Text>Profile content</Text>
+  </TabsContent>
+  <TabsContent value="security" activeValue={tab}>
+    <Text>Security content</Text>
+  </TabsContent>
+</Tabs>
+```
+
+---
+
+### Accordion
+
+**Import:** `import { Accordion } from '@retray-dev/ui-kit'`
+**When to use:** FAQs, collapsible sections. Animated expand/collapse.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| items | `AccordionItem[]` | required | Each: `{ value: string, trigger: string, content: ReactNode }` |
+| type | `'single' \| 'multiple'` | `'single'` | `single`: only one open at a time. `multiple`: any number can be open |
+| defaultValue | `string \| string[]` | — | Initially open item(s). Use `string[]` with `type='multiple'` |
+| style | `ViewStyle` | — | — |
+
+**Animation:** Height and chevron rotation are animated on the UI thread via `react-native-reanimated` (`withTiming`, `useSharedValue`). `Easing.out(Easing.ease)` for expand, `Easing.in(Easing.ease)` for collapse (220ms, 60 fps).
+
+**Example:**
+```tsx
+<Accordion
+  type="single"
+  items={[
+    { value: 'q1', trigger: 'What is this?', content: <Text>It's a UI kit.</Text> },
+    { value: 'q2', trigger: 'Is it free?', content: <Text>Yes.</Text> },
+  ]}
+/>
+```
+
+---
+
+### Sheet
+
+**Import:** `import { Sheet, BottomSheetModalProvider } from '@retray-dev/ui-kit'`
+**When to use:** Bottom sheet with physics-based gestures, rubber-band overscroll, and snap points. Powered by `@gorhom/bottom-sheet`.
+
+**Required setup** — add to your app root (see Setup section above):
+```tsx
+import { GestureHandlerRootView } from 'react-native-gesture-handler'
+import { BottomSheetModalProvider } from '@retray-dev/ui-kit'
+
+<GestureHandlerRootView style={{ flex: 1 }}>
+  <BottomSheetModalProvider>
+    {/* rest of app */}
+  </BottomSheetModalProvider>
+</GestureHandlerRootView>
+```
+
+**Peer dependencies** (install in your app):
+```bash
+pnpm add @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets
+```
+Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to your `babel.config.js` plugins.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| open | `boolean` | required | `true` presents the sheet, `false` dismisses it |
+| onClose | `() => void` | required | Called on swipe-dismiss or backdrop press |
+| snapPoints | `(string \| number)[]` | `['50%']` | Snap positions, e.g. `['40%', '80%']` |
+| title | `string` | — | — |
+| description | `string` | — | — |
+| children | `ReactNode` | — | — |
+| style | `ViewStyle` | — | Applied to the inner content container |
+
+**Example:**
+```tsx
+<Sheet open={open} onClose={() => setOpen(false)} title="Filters" snapPoints={['50%']}>
+  <RadioGroup options={sortOptions} value={sort} onValueChange={setSort} />
+</Sheet>
+```
+
+---
+
+### Toast / useToast
+
+**Import:** `import { ToastProvider, useToast } from '@retray-dev/ui-kit'`
+**When to use:** Ephemeral feedback messages (save success, network error, copy confirmation).
+
+**Required setup** — `ToastProvider` must wrap your app inside `SafeAreaProvider` (see Setup section above).
+
+**Peer dependency:** `react-native-safe-area-context` — required for `useSafeAreaInsets` inside `ToastProvider`.
+
+```tsx
+import { useToast } from '@retray-dev/ui-kit'
+
+function MyComponent() {
+  const { toast, dismiss } = useToast()
+
+  return (
+    <Button
+      label="Save"
+      onPress={async () => {
+        await save()
+        toast({ title: 'Saved', description: 'Your changes were saved.', variant: 'success' })
+      }}
+    />
+  )
+}
+```
+
+**`toast()` options:**
+
+| Field | Type | Default | Notes |
+|-------|------|---------|-------|
+| title | `string` | — | Bold heading |
+| description | `string` | — | Detail text |
+| variant | `'default' \| 'destructive' \| 'success'` | `'default'` | `default`: dark background. `destructive`: red. `success`: green |
+| duration | `number` (ms) | `3000` | Auto-dismiss after this delay |
+
+**`dismiss(id)`:** Dismiss a toast programmatically. The `id` is returned by the `toast()` call — store it if you need programmatic dismissal.
+
+**Notes:**
+- Max 3 toasts shown simultaneously (oldest is removed when a 4th arrives)
+- Toasts appear at the top of the screen, below the status bar (dynamic safe area inset)
+- Entrance: `withTiming(120ms, Easing.out(Easing.exp))` slide-down + opacity fade — fast, sharp feel
+- Exit: `withTiming(200ms)` slide-up + opacity fade
+- Swipe left or right to dismiss early (threshold: 80px or 800 pt/s velocity)