@retray-dev/ui-kit 6.2.0 → 9.0.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v6.2.0)
+# @retray-dev/ui-kit — Component Reference (v8.0.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:
 
@@ -11,7 +11,27 @@ This file is the AI reference for this package. It is shipped inside the npm pac
 
 ## Setup (Required)
 
-Wrap your app root with all required providers in this exact order:
+### Recommended: `RetrayProvider` (one wrapper)
+
+Since v8, a single `RetrayProvider` wires all five required providers in the correct order — use this and skip the manual nesting:
+
+```tsx
+import { RetrayProvider } from '@retray-dev/ui-kit'
+
+export default function App() {
+  const [fontsLoaded] = useFonts(SohneFonts)
+  if (!fontsLoaded) return null
+  return (
+    <RetrayProvider colorScheme="system">
+      {/* your app */}
+    </RetrayProvider>
+  )
+}
+```
+
+### Manual (equivalent) — if you need a custom tree
+
+`RetrayProvider` is exactly this; the individual providers stay exported. Order is mandatory:
 
 ```tsx
 import { SafeAreaProvider, initialWindowMetrics } from 'react-native-safe-area-context'
@@ -42,16 +62,76 @@ export default function App() {
 - `BottomSheetModalProvider` must be inside `GestureHandlerRootView`
 - `ToastProvider` wraps children and renders `Toaster` (from `sonner-native`) internally
 
-## Typography — Poppins (Required)
+### Peer dependencies
+
+Install all required peers (Expo projects: swap `pnpm add` for `npx expo install` to get SDK-pinned versions):
+
+```bash
+pnpm add expo-font expo-haptics expo-linear-gradient react-native-safe-area-context @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets @react-native-picker/picker @react-native-community/slider @expo/vector-icons react-native-size-matters react-native-svg react-native-screens sonner-native pressto
+```
+
+Then add the Worklets Babel plugin to `babel.config.js` (required by `@gorhom/bottom-sheet` and the pressable animations):
+
+```js
+module.exports = function (api) {
+  api.cache(true)
+  return {
+    presets: ['babel-preset-expo'],
+    plugins: ['react-native-worklets/plugin'], // NOT react-native-reanimated/plugin
+  }
+}
+```
+
+| Peer | Required? | Used by | Notes |
+|------|-----------|---------|-------|
+| `pressto` | **Required** | Every interactive component | Press-scale animations (`src/utils/pressable.ts`). Static import via the barrel — omitting it crashes the module load, not just one component. |
+| `sonner-native` | **Required** | `Toast` | Also pulls `react-native-svg` + `react-native-screens`. |
+| `react-native-reanimated` (≥4.0) | **Required** | Animations, `Sheet`, pressables | Needs the `react-native-worklets/plugin` Babel plugin. |
+| `react-native-gesture-handler` | **Required** | `Sheet`, pressables | Wrap app in `GestureHandlerRootView`. |
+| `@gorhom/bottom-sheet` (≥5.2.0) | **Required** | `Sheet`, `ConfirmDialog` | 5.1.x crashes on Reanimated v4. |
+| `expo-haptics` | **Required** | Haptic feedback (all interactions) | Web-safe wrapper, no-op on web. |
+| `expo-font` | **Required** | All `Text` | Load `SohneFonts` at app root before rendering. |
+| `expo-linear-gradient` | **Required** | `Skeleton` shimmer | |
+| `@react-native-picker/picker` | **Required** | `Select` | |
+| `@react-native-community/slider` | **Required** | `Slider` | |
+| `@expo/vector-icons` | **Required** | Icons everywhere | |
+| `react-native-size-matters` | **Required** | Responsive scaling | |
+| `react-native-pulsar` | **Optional** | Rich haptics on dev builds | Loaded via dynamic `import()` + try/catch; falls back to `expo-haptics`. Skip in Expo Go. `pnpm add react-native-pulsar` |
+| `@shopify/react-native-skia` + `expo-sensors` | **Optional** | Deep-import `HolographicCard` only | `pnpm add @shopify/react-native-skia expo-sensors` |
+
+> **Dev build vs Expo Go:** Everything in the kit runs in **Expo Go** — `react-native-pulsar` is the only native module that needs a custom dev build, and it degrades gracefully (basic haptics) when absent. No component is broken by running in Expo Go.
+
+### Troubleshooting: `react-native-screens` codegen on RN 0.83
+
+Toast pulls `sonner-native`, which imports `react-native-screens` via its `src/*` path. On **React Native 0.83** that source trips a `@react-native/codegen` parse error (`CT.WithDefault` not parseable). It is a `react-native-screens` issue, not the kit — but since Toast surfaces it, add this resolver to your `metro.config.js` to force the compiled `lib/commonjs` build:
+
+```js
+// metro.config.js
+const { getDefaultConfig } = require('expo/metro-config')
+const config = getDefaultConfig(__dirname)
+
+const defaultResolveRequest = config.resolver.resolveRequest
+config.resolver.resolveRequest = (context, moduleName, platform) => {
+  // Force react-native-screens to its compiled output, bypassing the src codegen bug.
+  if (moduleName.startsWith('react-native-screens/src')) {
+    moduleName = moduleName.replace('react-native-screens/src', 'react-native-screens/lib/commonjs')
+  }
+  return (defaultResolveRequest ?? context.resolveRequest)(context, moduleName, platform)
+}
+
+module.exports = config
+```
+
+## Typography — Sohne (Required)
 
-All components use **Poppins** as the font family. You **must** load it before rendering any UI kit component.
+All components use **Sohne** as the font family. You **must** load it before rendering any UI kit component.
 
 ```tsx
 import { useFonts } from 'expo-font'
-import { PoppinsFonts } from '@retray-dev/ui-kit/fonts'
+import { SohneFonts } from '@retray-dev/ui-kit/fonts'
 
 export default function App() {
-  const [fontsLoaded] = useFonts(PoppinsFonts)
+  const [fontsLoaded] = useFonts(SohneFonts)
   if (!fontsLoaded) return null
   return (
     // ... your providers and app
@@ -60,16 +140,16 @@ export default function App() {
 ```
 
 **How it works:**
-1. Import `PoppinsFonts` from `@retray-dev/ui-kit/fonts` (separate export path)
+1. Import `SohneFonts` from `@retray-dev/ui-kit/fonts` (separate export path)
 2. Pass it to `expo-font`'s `useFonts()` hook at your app root
 3. Metro resolves font files from `node_modules/@retray-dev/ui-kit/src/assets/fonts/` at bundle time
-4. All library components reference fonts by family name (e.g., `fontFamily: 'Poppins-SemiBold'`)
+4. All library components reference fonts by family name (e.g., `fontFamily: 'Sohne-SemiBold'`)
 
 **Included weights:**
-- Regular: `Poppins-Thin`, `Poppins-ExtraLight`, `Poppins-Light`, `Poppins-Regular`, `Poppins-Medium`, `Poppins-SemiBold`, `Poppins-Bold`, `Poppins-ExtraBold`, `Poppins-Black`
-- Italic: `Poppins-Italic`, `Poppins-MediumItalic`, `Poppins-SemiBoldItalic`, `Poppins-BoldItalic`
+- Sohne: `Sohne-ExtraLight`, `Sohne-Light`, `Sohne-Regular`, `Sohne-Medium`, `Sohne-SemiBold`, `Sohne-Bold`, `Sohne-ExtraBold` + italic variants
+- SohneMono: `SohneMono-ExtraLight`, `SohneMono-Light`, `SohneMono-Regular`, `SohneMono-Medium`, `SohneMono-SemiBold`, `SohneMono-Bold`, `SohneMono-ExtraBold` + italic variants
 
-**Total: 13 font files** exported from the package. Font `.ttf` files ship as raw assets in `src/assets/fonts/` — NOT bundled into `dist/`. Metro resolves `require()` calls at build time.
+**Total: 28 font files** exported from the package. Font `.otf` files ship as raw assets in `src/assets/fonts/` — NOT bundled into `dist/`. Metro resolves `require()` calls at build time.
 
 Pair with `expo-splash-screen` in production:
 ```tsx
@@ -403,6 +483,92 @@ Access resolved values via `useTheme().colors.overlay`, `.accentResolved`, `.acc
 
 ---
 
+## Migration Guide: v6 → v7
+
+### Breaking Changes
+
+**No prop API changes** — all component imports and props are identical. This is a breaking version bump due to visual behavior changes that affect rendered output.
+
+**Typography scale corrected:**
+
+| Token | v6 | v7 | Reason |
+|-------|----|----|--------|
+| `display-lg` | 22px / 500 | 24px / 600 | Removed weight inversion vs display-md |
+| `display-md` | 21px / 700 | 20px / 600 | 4px gap preserved; weight normalised |
+| `title-md` | 16px / 600 | 17px / 600 | Now visibly distinct from title-sm |
+| `title-sm` | 16px / 500 | 15px / 500 | Was same px as title-md |
+| `uppercase-tag` | 10px / 0.8 letterSpacing | 11px / 0.6 | Below Apple HIG 11pt minimum |
+| `badge-text-md` | (missing) | 13px / 600 | New canonical token for Badge md |
+
+**Default color values changed (WCAG AA fixes):**
+
+| Token | v6 | v7 | WCAG impact |
+|-------|----|----|-------------|
+| `foregroundMuted` opacity | 0.38 (~#ababab) | 0.62 (~#767676) | 2.2:1 ❌ → 4.5:1 ✓ |
+| `foregroundSubtle` opacity | 0.55 (~#858585) | 0.70 (~#646464) | 3.5:1 ❌ → 5.9:1 ✓ |
+| `warning` (light) | `#e67e00` | `#9a5200` | 2.86:1 ❌ → 5.86:1 ✓ |
+| `warningForeground` (dark) | `#ffffff` | `#0f0f0f` | Dark text on amber, 8.6:1 ✓ |
+| `destructive` (light) | `#e53935` | `#c72828` | 4.22:1 ❌ → 5.59:1 ✓ |
+| `accent` (light) | `= primary` | `#d4561d` | Explicit brand accent |
+| `accent` (dark) | `= primary` | `#e87645` | Warm accent for dark surfaces |
+
+**Component visual behavior changes:**
+
+| Component | Change |
+|-----------|--------|
+| `AlertBanner` | Background now uses semantic tint per variant (was white card); 1px semantic border added |
+| `Button` (text variant) | Label color: `foreground` → `accentResolved` — clearer CTA signal |
+| `Card` (elevated variant) | `borderWidth: 0` — shadow is sole depth signal; border was redundant |
+| `Chip` | `paddingVertical` doubled to hit 44pt WCAG 2.5.5 tap target |
+| `Input` / `Textarea` | Border: 1px at rest → animates to 2px on focus (was always 2px) |
+| `Switch` | Off-state now shows animated 1.5px border (invisible on white surfaces before) |
+| `Tabs` | Labels always `Sohne-SemiBold`; active = color only — eliminates layout reflow on selection |
+| `Checkbox` / `RadioGroup` | Disabled `opacity: 0.45` now on full row (was box only) |
+| `Toast` | `richColors={true}` — semantic variants now visually distinct by color |
+
+**If you customised any of these values** via `ThemeProvider` overrides, your overrides continue to take precedence — default palette changes only affect apps using the out-of-the-box defaults.
+
+### New Compound Component Section
+
+The example app now has a dedicated **Compound Components** section showcasing `Card`, `ButtonGroup`, `Form`, `ListGroup`, and `MenuGroup` with all sub-components and variants.
+
+---
+
+## Migration Guide: v7 → v8
+
+### Breaking Changes
+
+**1. New required peer dependency: `sonner-native`**
+Toast (`ToastProvider` / `toast` / `useToast`) imports `sonner-native`, but it was never declared as a peer — installs silently lacked it and Metro failed with `Unable to resolve "sonner-native"`. It is now a declared peer. Install it:
+```bash
+pnpm add sonner-native
+```
+(You already need its companions `react-native-svg` and `react-native-screens`.)
+
+**2. `@gorhom/bottom-sheet` peer range tightened to `>=5.2.0`**
+5.1.x crashes with Reanimated v4 (`useWorkletCallback is not a function`), which broke `Sheet`, `ConfirmDialog`, and `Select` on open. The range no longer admits broken versions. Pin `5.2.8` if you also use Worklets `0.5.x`.
+
+**3. `./fonts` stays at `src/fonts.ts` (unchanged)**
+The `./fonts` export deliberately points at `src/fonts.ts`, not `dist`. The `.otf` files ship as raw assets in `src/assets/fonts/` and are resolved by Metro at your build time via `require()`. Compiling this entry to `dist` and repointing the `require()` paths breaks Metro asset resolution under pnpm symlinked workspaces (`requiring unknown module ../src/assets/fonts/...`), so it is intentionally left as source. No API change — import as before:
+```ts
+import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+```
+
+### New — packaging & DX
+
+- **`RetrayProvider`** — one wrapper replacing the five-provider boilerplate (see Setup below).
+- **Dev font guard** — if you render a UI kit component without loading `SohneFonts`, `Text` now logs a one-time `console.warn` in dev (silent in production) instead of failing invisibly.
+
+### New components
+
+`RetrayProvider`, `AppHeader`, `TabBar`, `PagerDots`, `SelectableGrid`, `PricingCard`, `ErrorBoundary`, `ImageViewer`, plus `Skeleton.MediaCard` / `Skeleton.ListItem` sub-skeletons and the optional deep-import-only `HolographicCard` (Skia foil card). `MonthPicker` gained `minValue`/`maxValue` and `Date` bridge helpers.
+
+### Optional peers (only if you use the matching component)
+
+- `@shopify/react-native-skia` + `expo-sensors` → `HolographicCard` (deep-import only, not in the main barrel).
+
+---
+
 ## Components
 
 ---
@@ -1247,6 +1413,74 @@ const [amount, setAmount] = useState(0)
 
 ---
 
+### VirtualList
+
+**Import:** `import { VirtualList } from '@retray-dev/ui-kit'`
+
+**When to use:** Large lists (100+ items) where you need efficient rendering. Thin wrapper over `FlatList` with sane defaults for stable keys and optional fixed-height fast path.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| data | `T[]` | — | Array of items to render |
+| renderItem | `ListRenderItem<T>` | — | Render function for each item |
+| itemHeight | `number` | — | Fixed row height in px. Enables `getItemLayout` for performance with large datasets |
+| keyExtractor | `(item: T, index: number) => string` | Auto | Defaults to `item.id` or index. Override for custom keys |
+| ...FlatListProps | — | — | All standard FlatList props pass through |
+
+**Performance optimization:** When `itemHeight` is provided, `VirtualList` enables `getItemLayout` so FlatList skips async measurement. For 10k+ rows, combine with `React.memo`-wrapped `renderItem` so only on-screen rows mount and re-render.
+
+**Default key extraction:** Uses `item.id` (converted to string) or falls back to index. Override with `keyExtractor` for custom logic.
+
+**Example — simple list:**
+```tsx
+<VirtualList
+  data={items}
+  renderItem={({ item }) => (
+    <ListItem
+      title={item.title}
+      subtitle={item.subtitle}
+      onPress={() => handlePress(item.id)}
+    />
+  )}
+  itemHeight={56}
+/>
+```
+
+**Example — large dataset with memoized render:**
+```tsx
+const renderItem = useCallback(({ item }) => (
+  <ListItem
+    title={item.title}
+    subtitle={item.subtitle}
+    leftIcon="circle"
+    showSeparator
+    onPress={() => navigate('detail', { id: item.id })}
+  />
+), [])
+
+<VirtualList
+  data={thousands}
+  renderItem={renderItem}
+  itemHeight={64}
+/>
+```
+
+**Example — variable height rows (omit itemHeight):**
+```tsx
+<VirtualList
+  data={posts}
+  renderItem={({ item }) => (
+    <Card style={{ margin: SPACING.sm }}>
+      <CardContent>
+        <Text>{item.content}</Text>
+      </CardContent>
+    </Card>
+  )}
+/>
+```
+
+---
+
 ### Separator
 
 **Import:** `import { Separator } from '@retray-dev/ui-kit'`
@@ -1350,15 +1584,29 @@ const [amount, setAmount] = useState(0)
 </View>
 ```
 
-**Composition — skeleton for a ListItem:**
+**Sub-skeletons (v8):** ready-made placeholders that mirror a component's footprint, so grids/lists don't reflow when real data arrives.
+
 ```tsx
-<View style={{ flexDirection: 'row', gap: SPACING.md, padding: SPACING.base }}>
-  <Skeleton preset="circle" diameter={40} />
-  <View style={{ flex: 1, gap: SPACING.xs }}>
-    <Skeleton height={16} width="60%" />
-    <Skeleton preset="text" />
-  </View>
-</View>
+// Matches <MediaCard> — image block + title/subtitle lines
+<Skeleton.MediaCard aspectRatio="4:3" />          // props: aspectRatio ('1:1'|'4:3'|'16:9'|'4:5'|'3:2'), showSubtitle, style
+
+// Matches <ListItem> — leading circle + title/subtitle lines
+<Skeleton.ListItem />                              // props: showAvatar, showSubtitle, style
+
+// Repeated list/grid placeholder — for VirtualList / FlatList while loading.
+// columns=1 → stacked ListItemSkeleton; columns>1 → grid of MediaCardSkeleton.
+<Skeleton.List count={6} />                         // stacked list
+<Skeleton.List count={6} columns={2} />             // 2-col card grid
+// props: count, columns, gap, aspectRatio (grid), showAvatar (list), style
+
+// Also exported as named components: MediaCardSkeleton, ListItemSkeleton, ListSkeleton
+
+// As a VirtualList loading state
+<VirtualList
+  data={loading ? [] : rows}
+  renderItem={renderItem}
+  ListEmptyComponent={loading ? <Skeleton.List count={8} /> : <EmptyState .../>}
+/>
 ```
 
 ---
@@ -1976,10 +2224,13 @@ Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to `ba
 | android_keyboardInputMode | `'adjustPan' \| 'adjustResize'` | `'adjustPan'` | Android-only: `'adjustPan'` moves the window (default — fixes restore issues with dynamic sizing). `'adjustResize'` resizes the container (can cause transparent gap when keyboard dismisses) |
 | footer | `ReactNode` | — | Sticky footer below scroll area (sticky above keyboard) |
 | snapPoints | `(string \| number)[]` | — | Optional snap points (e.g., `['50%', '85%']`). When omitted, uses dynamic sizing (auto-fits content) |
+| responsive | `boolean` | `false` | **(v8)** On wide screens (width ≥ `BREAKPOINTS.wide`) render a centered modal dialog instead of a bottom sheet. Stays a bottom sheet on phones |
+| dialogMaxWidth | `number` | `480` | Max width of the centered dialog. Only applies when `responsive` |
 
 **Features:**
 - `enableDynamicSizing` — height auto-fits content, no `snapPoints` needed (default behavior when `snapPoints` is omitted)
 - `snapPoints` — optionally provide custom snap points (e.g., `['50%', '85%']`). Disables dynamic sizing when provided
+- `responsive` — on tablets/web, becomes a centered dialog (max width `dialogMaxWidth`). Note: the dialog path uses a plain RN `Modal`, so `SheetTextInput` is **not** required there — use a regular `TextInput`
 - `enablePanDownToClose` — swipe down to dismiss
 - Backdrop press dismisses
 - **Scrollable content:** use `scrollable` prop or `maxHeight`. Both use `BottomSheetScrollView` — do NOT use plain `ScrollView` inside Sheet
@@ -2058,6 +2309,195 @@ const [open, setOpen] = useState(false)
 - Default `android_keyboardInputMode="adjustPan"` fixes the transparent gap that occurs with `adjustResize` when keyboard dismisses
 - `enableBlurKeyboardOnGesture={true}` (default) dismisses keyboard when dragging sheet
 
+**Compound components:**
+
+Sheet also supports compound components for custom layouts: `Sheet.Header`, `Sheet.Content`, `Sheet.Footer`.
+
+**Sheet.Header Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Custom header content — replaces title/subtitle/showCloseButton |
+| style | `ViewStyle` | — |
+
+**Sheet.Content Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Body content with automatic gap spacing |
+| style | `ViewStyle` | — |
+
+**Sheet.Footer Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Footer content (e.g., action buttons) |
+| style | `ViewStyle` | — |
+
+**Compound component examples:**
+```tsx
+// Custom header with close button
+<Sheet open={open} onClose={() => setOpen(false)}>
+  <Sheet.Header>
+    <View style={{ flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center' }}>
+      <Text variant="title-md">Custom Header</Text>
+      <IconButton iconName="x" onPress={() => setOpen(false)} />
+    </View>
+  </Sheet.Header>
+  <Sheet.Content>
+    <Text>Content with auto spacing</Text>
+    <Input placeholder="Name" />
+    <Input placeholder="Email" />
+  </Sheet.Content>
+  <Sheet.Footer>
+    <Button label="Cancel" variant="outline" onPress={() => setOpen(false)} />
+    <Button label="Save" onPress={handleSave} />
+  </Sheet.Footer>
+</Sheet>
+
+// Mix compound components with props
+<Sheet open={open} onClose={() => setOpen(false)} title="Edit Profile">
+  <Sheet.Content>
+    <Input label="Name" value={name} onChangeText={setName} />
+    <Input label="Email" value={email} onChangeText={setEmail} />
+  </Sheet.Content>
+  <Sheet.Footer>
+    <Button label="Save" fullWidth onPress={handleSave} />
+  </Sheet.Footer>
+</Sheet>
+```
+
+When using compound components:
+- `Sheet.Header` replaces `title`, `subtitle`, and `showCloseButton` props
+- `Sheet.Content` automatically applies `gap: vs(16)` between children
+- `Sheet.Footer` renders sticky footer with automatic border, padding, and horizontal button layout
+
+---
+
+### Form
+
+**Import:** `import { Form } from '@retray-dev/ui-kit'`
+
+**When to use:** Standardize form layouts with consistent spacing, labels, and validation errors. Compound component pattern for wrapping Input, Select, Textarea, etc.
+
+**Sub-components:**
+- `Form` — Root wrapper with consistent gap spacing between fields
+- `Form.Field` — Wraps a single input with optional label and error
+- `Form.Section` — Groups related fields with title and description
+- `Form.Footer` — Footer area for submit/cancel buttons
+
+**Form Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Form.Field, Form.Section, Form.Footer components |
+| style | `ViewStyle` | — |
+
+**Form.Field Props:**
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | Input, Select, Textarea, etc. |
+| label | `string` | — | Label above input |
+| error | `string` | — | Error message below input |
+| required | `boolean` | `false` | Shows asterisk after label |
+| style | `ViewStyle` | — | — |
+| labelStyle | `TextStyle` | — | — |
+| errorStyle | `TextStyle` | — | — |
+
+**Form.Section Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Form.Field components |
+| title | `string` | Section heading |
+| description | `string` | Supporting text below title |
+| style | `ViewStyle` | — |
+
+**Form.Footer Props:**
+| Prop | Type | Notes |
+|------|------|-------|
+| children | `ReactNode` | Button components |
+| style | `ViewStyle` | — |
+
+**Features:**
+- **Automatic spacing:** `gap: vs(16)` between Form.Field components
+- **Required indicator:** Red asterisk (*) when `required={true}`
+- **Error styling:** Error text in destructive color below input
+- **Label hierarchy:** Sohne-Medium 14px for labels, 12px for errors
+- **Footer layout:** Horizontal row with `gap: s(12)` for button grouping
+
+**Examples:**
+```tsx
+// Basic form
+<Form>
+  <Form.Field label="Full Name" required>
+    <Input value={name} onChangeText={setName} placeholder="John Doe" />
+  </Form.Field>
+  
+  <Form.Field label="Email" required error={emailError}>
+    <Input 
+      value={email} 
+      onChangeText={setEmail} 
+      placeholder="john@example.com"
+      keyboardType="email-address"
+    />
+  </Form.Field>
+  
+  <Form.Field label="Country">
+    <Select 
+      value={country} 
+      onValueChange={setCountry}
+      options={countries}
+    />
+  </Form.Field>
+  
+  <Form.Footer>
+    <Button label="Cancel" variant="outline" onPress={onCancel} />
+    <Button label="Submit" onPress={handleSubmit} />
+  </Form.Footer>
+</Form>
+
+// With sections
+<Form>
+  <Form.Section title="Personal Information" description="Your basic profile details">
+    <Form.Field label="Name" required>
+      <Input value={name} onChangeText={setName} />
+    </Form.Field>
+    <Form.Field label="Email" required error={emailError}>
+      <Input value={email} onChangeText={setEmail} />
+    </Form.Field>
+  </Form.Section>
+  
+  <Form.Section title="Preferences">
+    <Form.Field label="Language">
+      <Select value={lang} onValueChange={setLang} options={languages} />
+    </Form.Field>
+    <Form.Field label="Timezone">
+      <Select value={tz} onValueChange={setTz} options={timezones} />
+    </Form.Field>
+  </Form.Section>
+  
+  <Form.Footer>
+    <Button label="Save" fullWidth onPress={handleSave} />
+  </Form.Footer>
+</Form>
+
+// Inside Sheet
+<Sheet open={open} onClose={() => setOpen(false)} title="Edit Profile">
+  <Form>
+    <Form.Field label="Name" required>
+      <SheetTextInput value={name} onChangeText={setName} />
+    </Form.Field>
+    <Form.Field label="Bio">
+      <SheetTextInput 
+        value={bio} 
+        onChangeText={setBio} 
+        multiline 
+        style={{ minHeight: 80 }}
+      />
+    </Form.Field>
+  </Form>
+  <View style={{ marginTop: 16 }}>
+    <Button label="Save" fullWidth onPress={handleSave} />
+  </View>
+</Sheet>
+```
+
 ---
 
 ### Toast / useToast
@@ -2297,6 +2737,77 @@ dismiss(id)
 
 ---
 
+### ListGroup
+
+**Import:** `import { ListGroup } from '@retray-dev/ui-kit'`
+
+**When to use:** Wrap multiple `ListItem` components to standardize spacing, add automatic separators, and optionally apply a card surface. Identical pattern to `MenuGroup`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | ListItem components + ListGroup.Header + ListGroup.Footer |
+| variant | `'plain' \| 'card'` | `'plain'` | `plain`: no background. `card`: card surface with border |
+| style | `ViewStyle` | — | — |
+
+**Sub-components:**
+- `ListGroup.Header` — Header text or custom content
+- `ListGroup.Footer` — Footer text or custom content
+
+**Features:**
+- **Auto-separators:** Automatically adds `showSeparator={true}` to all ListItem children except the last
+- **Individual override:** ListItem can override with `showSeparator={false}`
+- **Variant `card`:** Applies card surface (`RADIUS.md`, border, shadow)
+
+**Examples:**
+```tsx
+// Transaction list with auto separators
+<ListGroup variant="card">
+  <ListGroup.Header>Recent Transactions</ListGroup.Header>
+  <ListItem
+    leftIcon="coffee"
+    title="Rappi"
+    subtitle="Food · May 12"
+    rightRender={<Text color={colors.destructive}>−$45.000</Text>}
+    onPress={() => {}}
+  />
+  <ListItem
+    leftIcon="car"
+    title="Uber"
+    subtitle="Transport · May 11"
+    rightRender={<Text color={colors.destructive}>−$18.200</Text>}
+    onPress={() => {}}
+  />
+  <ListItem
+    leftIcon="briefcase"
+    title="Salary"
+    subtitle="Income · May 1"
+    rightRender={<Text color={colors.success}>+$3.500.000</Text>}
+    onPress={() => {}}
+  />
+  <ListGroup.Footer>Last 7 days</ListGroup.Footer>
+</ListGroup>
+
+// Plain variant (inside Card)
+<Card>
+  <CardContent>
+    <ListGroup variant="plain">
+      {users.map((user) => (
+        <ListItem
+          key={user.id}
+          leftRender={<Avatar src={user.avatar} fallback={user.name[0]} />}
+          title={user.name}
+          subtitle={user.role}
+          rightRender={<Badge label={user.status} variant="success" />}
+          onPress={() => navigate('user', { id: user.id })}
+        />
+      ))}
+    </ListGroup>
+  </CardContent>
+</Card>
+```
+
+---
+
 ### MenuItem
 
 **Import:** `import { MenuItem } from '@retray-dev/ui-kit'`
@@ -2376,6 +2887,61 @@ dismiss(id)
 
 ---
 
+### MenuGroup
+
+**Import:** `import { MenuGroup } from '@retray-dev/ui-kit'`
+
+**When to use:** Wrap multiple `MenuItem` components to standardize spacing, add automatic separators, and optionally apply a card surface. Compound component pattern like `Card`.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | MenuItem components + MenuGroup.Header + MenuGroup.Footer |
+| variant | `'plain' \| 'card'` | `'plain'` | `plain`: no background. `card`: card surface with border |
+| style | `ViewStyle` | — | — |
+
+**Sub-components:**
+- `MenuGroup.Header` — Header text or custom content
+- `MenuGroup.Footer` — Footer text or custom content
+
+**Features:**
+- **Auto-separators:** Automatically adds `showSeparator={true}` to all MenuItem children except the last
+- **Individual override:** MenuItem can override with `showSeparator={false}`
+- **Variant `card`:** Applies card surface (`RADIUS.md`, border, shadow) like standalone MenuItems with `variant="card"`
+
+**Examples:**
+```tsx
+// Basic group with auto separators
+<MenuGroup variant="card">
+  <MenuItem label="Personal Info" iconName="user" onPress={() => {}} />
+  <MenuItem label="Security" iconName="shield" onPress={() => {}} />
+  <MenuItem label="Privacy" iconName="lock" onPress={() => {}} />
+</MenuGroup>
+
+// With header and footer
+<MenuGroup variant="card">
+  <MenuGroup.Header>Account Settings</MenuGroup.Header>
+  <MenuItem label="Personal Info" subtitle="Name, email, phone" iconName="user" onPress={() => {}} />
+  <MenuItem label="Security" iconName="shield" onPress={() => {}} />
+  <MenuItem label="Privacy" iconName="lock" onPress={() => {}} />
+  <MenuGroup.Footer>Last updated today</MenuGroup.Footer>
+</MenuGroup>
+
+// Plain variant (inside another container)
+<Card>
+  <CardHeader>
+    <CardTitle>Settings</CardTitle>
+  </CardHeader>
+  <CardContent>
+    <MenuGroup variant="plain">
+      <MenuItem label="Notifications" iconName="bell" rightRender={<Switch checked={notifs} onCheckedChange={setNotifs} />} />
+      <MenuItem label="Dark Mode" iconName="moon" rightRender={<Switch checked={dark} onCheckedChange={setDark} />} />
+    </MenuGroup>
+  </CardContent>
+</Card>
+```
+
+---
+
 ### Chip / ChipGroup
 
 **Import:** `import { Chip, ChipGroup } from '@retray-dev/ui-kit'`
@@ -2644,6 +3210,8 @@ Total ·············· $50.000
 |------|------|---------|-------|
 | value | `MonthPickerValue` | required | `{ month: 1–12, year: number }` |
 | onChange | `(value: MonthPickerValue) => void` | required | Called on navigation |
+| minValue | `MonthPickerValue` | — | Earliest selectable month (inclusive). Prev arrow disables + dims at this bound |
+| maxValue | `MonthPickerValue` | — | Latest selectable month (inclusive). Next arrow disables + dims at this bound — e.g. cap at the current month |
 | locale | `string` | `'en'` | BCP 47 locale. Built-in: `'en'`, `'es'`, `'pt'`, `'fr'`. Other locales: use `formatLabel` |
 | formatLabel | `(value: MonthPickerValue) => string` | — | Custom label formatter. Takes precedence over `locale` |
 | style | `ViewStyle` | — | — |
@@ -2653,7 +3221,15 @@ Total ·············· $50.000
 { month: number; year: number }  // month is 1-indexed (January = 1)
 ```
 
-**Navigation:** Year wraps correctly at boundaries (December → January increments year, January → December decrements year). Fully controlled — no internal state.
+**Date bridge helpers** (exported): for domains that store `Date` (e.g. finance apps in a fixed TZ), convert at the boundary instead of changing your model.
+```ts
+import { dateToMonthPickerValue, monthPickerValueToDate } from '@retray-dev/ui-kit'
+
+dateToMonthPickerValue(new Date())          // → { month, year } (local time)
+monthPickerValueToDate({ month: 6, year: 2026 })  // → Date at first day of the month
+```
+
+**Navigation:** Year wraps correctly at boundaries (December → January increments year, January → December decrements year). When `minValue`/`maxValue` are set, the boundary arrow is disabled (opacity 0.3) and presses are ignored. Fully controlled — no internal state.
 
 **Styling:** Centered row with `←` / `→` buttons (44×44px each). Label: 17pt / Medium / 160px min-width, centered.
 
@@ -2752,6 +3328,407 @@ const [period, setPeriod] = useState({
 
 ---
 
+### RetrayProvider
+
+**Import:** `import { RetrayProvider } from '@retray-dev/ui-kit'`
+
+**When to use:** At your app root, instead of hand-nesting the five required providers. Removes an entire class of provider-order bugs. The individual providers stay exported for custom trees.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | Your app |
+| theme | `Theme` | — | Per-scheme token overrides, forwarded to `ThemeProvider` |
+| colorScheme | `'system' \| 'light' \| 'dark'` | `'system'` | Forwarded to `ThemeProvider` |
+
+**Wraps (in order):** `SafeAreaProvider` (with `initialWindowMetrics`) → `GestureHandlerRootView` → `ThemeProvider` → `BottomSheetModalProvider` → `ToastProvider`.
+
+**Example:**
+```tsx
+import { RetrayProvider } from '@retray-dev/ui-kit'
+
+export default function App() {
+  const [fontsLoaded] = useFonts(SohneFonts)
+  if (!fontsLoaded) return null
+  return (
+    <RetrayProvider colorScheme="system" theme={{ light: { primary: '#ff385c' } }}>
+      <RootNavigator />
+    </RetrayProvider>
+  )
+}
+```
+
+---
+
+### AppHeader
+
+**Import:** `import { AppHeader } from '@retray-dev/ui-kit'`
+
+**When to use:** Top app bar / screen chrome — back button, title/subtitle, and a right action slot. Responsive: title left-aligns on phones and centers when width ≥ `BREAKPOINTS.wide`.
+
+**Expo Router compatibility:** ✅ Fully compatible. Use with `useRouter()` for navigation:
+
+```tsx
+import { useRouter } from 'expo-router'
+import { AppHeader } from '@retray-dev/ui-kit'
+
+export default function Screen() {
+  const router = useRouter()
+  return (
+    <AppHeader 
+      title="Settings" 
+      onBack={() => router.back()} 
+      right={<IconButton iconName="more-horizontal" variant="text" />} 
+    />
+  )
+}
+```
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| title | `string` | — | Primary title (truncates to 1 line) |
+| subtitle | `string` | — | Secondary line under the title |
+| onBack | `() => void` | — | Shows a back button on the left when provided |
+| backIconName | `string` | `'chevron-left'` | Icon for the back button |
+| left | `ReactNode` | — | Custom left content — overrides the back button |
+| right | `ReactNode` | — | Custom right content (actions) |
+| titleAlign | `'auto' \| 'left' \| 'center'` | `'auto'` | `auto` = left on narrow, centered on wide |
+| bordered | `boolean` | `true` | Hairline border underneath |
+| withSafeArea | `boolean` | `true` | Apply top safe-area inset as padding |
+| backgroundColor | `string` | `colors.background` | — |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<AppHeader
+  title="Settings"
+  onBack={navigation.goBack}
+  right={<IconButton iconName="more-horizontal" variant="text" onPress={openMenu} />}
+/>
+```
+
+---
+
+### TabBar
+
+**Import:** `import { TabBar } from '@retray-dev/ui-kit'`
+
+**When to use:** Bottom tab navigation — icon + label tabs with active tint and badges. Pair with your navigator, or drive with local state for a single-screen app.
+
+**Expo Router compatibility:** ✅ Fully compatible. Use in `_layout.tsx` to build custom tab navigation:
+
+```tsx
+// app/(tabs)/_layout.tsx
+import { Tabs, useRouter, useSegments } from 'expo-router'
+import { TabBar } from '@retray-dev/ui-kit'
+
+export default function TabLayout() {
+  const router = useRouter()
+  const segments = useSegments()
+  const activeKey = segments[1] || 'home'
+
+  return (
+    <Tabs
+      tabBar={() => (
+        <TabBar
+          items={[
+            { key: 'home', label: 'Home', iconName: 'home' },
+            { key: 'search', label: 'Search', iconName: 'search' },
+            { key: 'profile', label: 'Profile', iconName: 'user', badge: 3 },
+          ]}
+          activeKey={activeKey}
+          onTabPress={(key) => router.push(`/(tabs)/${key}`)}
+        />
+      )}
+    >
+      {/* ... screens */}
+    </Tabs>
+  )
+}
+```
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| items | `TabBarItem[]` | required | `{ key, label?, iconName?, icon?, badge? }` |
+| activeKey | `string` | required | Key of the active tab |
+| onTabPress | `(key: string) => void` | required | — |
+| activeColor | `string` | `colors.primary` | — |
+| inactiveColor | `string` | `colors.foregroundMuted` | — |
+| withSafeArea | `boolean` | `true` | Apply bottom safe-area inset |
+| style | `ViewStyle` | — | — |
+
+**TabBarItem.badge:** `true` shows a dot; a number shows a count (capped at `99+`).
+
+**Haptics:** `selectionAsync` when switching to a new tab.
+
+**Example:**
+```tsx
+<TabBar
+  activeKey={tab}
+  onTabPress={setTab}
+  items={[
+    { key: 'home', label: 'Home', iconName: 'home' },
+    { key: 'wallet', label: 'Wallet', iconName: 'credit-card' },
+    { key: 'profile', label: 'Profile', iconName: 'user', badge: 3 },
+  ]}
+/>
+```
+
+---
+
+### PagerDots
+
+**Import:** `import { PagerDots } from '@retray-dev/ui-kit'`
+
+**When to use:** Page indicator for carousels / document pagers. The active dot stretches into a pill and color-crossfades — all on the UI thread. Now supports optional previous/next control buttons.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| count | `number` | required | Total pages |
+| activeIndex | `number` | required | 0-based active page |
+| onDotPress | `(index: number) => void` | — | Omit to make dots non-interactive |
+| showControls | `boolean \| { onPrevious?, onNext? }` | `false` | Show prev/next buttons. If `true`, uses `onDotPress(activeIndex ± 1)`. If object, uses custom handlers |
+| dotSize | `number` | `8` | Inactive dot diameter (dp) |
+| spacing | `number` | `8` | Gap between dots (dp) |
+| activeColor | `string` | `colors.primary` | — |
+| inactiveColor | `string` | `colors.border` | — |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<PagerDots count={pages.length} activeIndex={page} onDotPress={setPage} showControls />
+```
+
+---
+
+### SelectableGrid
+
+**Import:** `import { SelectableGrid } from '@retray-dev/ui-kit'`
+
+**When to use:** Grid of selectable cells (icon + label) — store / category / emoji pickers where a list would be the wrong shape. Single or multi select. Generic over the value type (`string | number`). Now supports horizontal scrolling mode for single-row layouts.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| items | `SelectableGridItem<T>[]` | required | `{ value, label?, iconName?, icon?, disabled? }` |
+| value | `T \| T[] \| null` | required | Selected value(s) — array when `multiple` |
+| onChange | `(value: T) => void` | required | Fires with the toggled item's value |
+| multiple | `boolean` | `false` | Allow multiple selection (`value` should be an array) |
+| numColumns | `number` | `4` | Cells per row (exact-fit width is measured, not percentage). Ignored when `orientation='horizontal'` |
+| gap | `number` | `12` | Gap between cells (dp) |
+| orientation | `'grid' \| 'horizontal'` | `'grid'` | `'grid'` wraps into rows, `'horizontal'` creates a single scrollable row |
+| style | `ViewStyle` | — | — |
+
+**Selected cell:** primary border + tinted background; icon/label switch to `primary`. **Press scale:** chip (0.94). **Haptics:** `selectionAsync` on press.
+
+**Horizontal mode:** Fixed 96dp cell width, horizontal ScrollView, no vertical wrapping.
+
+**Example:**
+```tsx
+{/* Grid layout */}
+<SelectableGrid
+  items={categories}
+  value={category}
+  onChange={setCategory}
+  numColumns={4}
+/>
+
+{/* Horizontal scrolling */}
+<SelectableGrid
+  items={categories}
+  value={category}
+  onChange={setCategory}
+  orientation="horizontal"
+/>
+```
+
+**Example:**
+```tsx
+<SelectableGrid
+  items={[
+    { value: 'food', label: 'Food', iconName: 'coffee' },
+    { value: 'transport', label: 'Transport', iconName: 'truck' },
+    { value: 'home', label: 'Home', iconName: 'home' },
+  ]}
+  value={category}
+  onChange={setCategory}
+  numColumns={4}
+/>
+```
+
+---
+
+### PricingCard
+
+**Import:** `import { PricingCard } from '@retray-dev/ui-kit'`
+
+**When to use:** Paywalls and freemium tiers — price header, feature list with check marks, optional promo badge, and CTA. Set `highlighted` on the recommended plan.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| name | `string` | required | Plan name |
+| price | `string` | required | Formatted price, e.g. `"$9"` or `"Free"` |
+| period | `string` | — | Billing suffix, e.g. `"/mo"` |
+| description | `string` | — | Short text under the price |
+| features | `(string \| PricingFeature)[]` | `[]` | Strings = included; `{ label, included: false }` for excluded (dashed, struck) |
+| ctaLabel | `string` | — | CTA button label (renders a `Button`) |
+| onCtaPress | `() => void` | — | — |
+| badge | `string` | — | Promo badge, e.g. `"Most popular"` |
+| highlighted | `boolean` | `false` | Primary border + elevation + primary CTA |
+| footnote | `string` | — | Small print under the CTA |
+| style | `ViewStyle` | — | — |
+
+**Example:**
+```tsx
+<PricingCard
+  name="Pro"
+  price="$9"
+  period="/mo"
+  badge="Most popular"
+  highlighted
+  features={['Unlimited docs', 'Priority support', { label: 'SSO', included: false }]}
+  ctaLabel="Start trial"
+  onCtaPress={subscribe}
+  footnote="Cancel anytime"
+/>
+```
+
+---
+
+### ErrorBoundary
+
+**Import:** `import { ErrorBoundary } from '@retray-dev/ui-kit'`
+
+**When to use:** Wrap screens or risky subtrees so a render error shows a themed fallback instead of unmounting the whole app.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | Protected subtree |
+| fallback | `ReactNode \| (props: { error, reset }) => ReactNode` | themed card | Custom fallback |
+| title | `string` | `'Something went wrong'` | Default fallback title |
+| message | `string` | `error.message` | Default fallback body |
+| onError | `(error, info) => void` | — | Wire your crash reporter here |
+
+**Default fallback:** centered themed card with a destructive icon, title, message, and a "Try again" button that calls `reset()`.
+
+**Example:**
+```tsx
+<ErrorBoundary onError={reportCrash}>
+  <DocumentViewer />
+</ErrorBoundary>
+
+// Custom fallback
+<ErrorBoundary fallback={({ error, reset }) => <MyFallback error={error} onRetry={reset} />}>
+  <RiskyScreen />
+</ErrorBoundary>
+```
+
+---
+
+### ImageViewer
+
+**Import:** `import { ImageViewer } from '@retray-dev/ui-kit'`
+
+**When to use:** Full-screen zoomable image gallery — multi-page documents, photo viewers. Horizontal paging + pinch / double-tap zoom + pan, with page dots and a close button. Requires `react-native-gesture-handler` (already a peer).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| images | `ImageSourcePropType[]` | required | `{ uri }` or `require()` sources |
+| visible | `boolean` | required | Controls the modal |
+| onClose | `() => void` | required | — |
+| initialIndex | `number` | `0` | Page to open on |
+
+**Behavior:** pinch to zoom (max 3×), double-tap to toggle 2.5× zoom, pan while zoomed. Paging locks automatically while a page is zoomed in. `PagerDots` shown when there is more than one image.
+
+**Example:**
+```tsx
+<ImageViewer
+  images={doc.pages.map((uri) => ({ uri }))}
+  visible={viewerOpen}
+  initialIndex={page}
+  onClose={() => setViewerOpen(false)}
+/>
+```
+
+---
+
+### HolographicCard
+
+**Import (deep import only):** `import { HolographicCard, FOIL_PRESETS, FoilPreset } from '@retray-dev/ui-kit/HolographicCard'`
+
+> Not re-exported from the main barrel — it depends on the **optional** peers `@shopify/react-native-skia` and `expo-sensors`, which are deliberately kept out of the main module graph. Deep-import it so consumers who don't use it never pull Skia.
+
+**When to use:** Holographic / foil trading-card surface (Pokémon-TCG style). Renders art on a Skia canvas with an animated rainbow sheen and tilts in 3D toward device motion; the sheen tracks the tilt so the foil "catches the light".
+
+**Install:** `pnpm add @shopify/react-native-skia expo-sensors`
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| source | `require()` / `{ uri }` | — | Card art. Omitted = gradient-only foil surface |
+| width | `number` | `300` | Card width (dp) |
+| height | `number` | `width * 1.4` | Trading-card ratio by default |
+| borderRadius | `number` | `RADIUS.md` | — |
+| enableTilt | `boolean` | `true` | React to gyroscope. No-op on web; static sheen if `expo-sensors` is absent |
+| intensity | `number` | `1` | Foil sheen strength, 0–1 |
+| onPress | `() => void` | — | Adds card press-scale + `impactLight` |
+| style | `ViewStyle` | — | — |
+| foilPreset | `FoilPreset` | `'rainbow'` | Foil color preset. Ignored if `foilColors` is provided |
+| foilColors | `string[]` | — | Custom foil gradient colors (array of RGBA strings). Overrides `foilPreset` |
+| maxTiltDegrees | `number` | `10` | Maximum tilt angle in degrees (0–45) |
+| tiltSensitivity | `number` | `1` | Sensitivity of tilt to device motion (0.1–2). Higher = more responsive |
+| sheenSpread | `number` | `0.6` | How far the sheen moves relative to tilt (0–1) |
+| tiltAnimationDuration | `number` | `80` | Animation duration for tilt smoothing in ms |
+| perspective | `number` | `800` | Perspective depth for 3D effect (200–2000) |
+| blendMode | `string` | `'plus'` | Blend mode: `'plus'` \| `'screen'` \| `'overlay'` \| `'softLight'` \| `'hardLight'` |
+
+**Available foil presets (`FoilPreset`):**
+
+| Preset | Description |
+|--------|-------------|
+| `rainbow` | Classic holographic rainbow (default) |
+| `gold` | Premium gold foil |
+| `silver` | Chrome silver foil |
+| `cosmic` | Deep space cosmic |
+| `emerald` | Emerald green luxury |
+| `rose` | Rose gold / pink |
+| `ocean` | Deep ocean blue |
+| `fire` | Hot fire gradient |
+| `aurora` | Aurora borealis |
+| `neon` | Neon cyberpunk |
+
+**Example:**
+```tsx
+import { HolographicCard, FOIL_PRESETS } from '@retray-dev/ui-kit/HolographicCard'
+
+// Basic usage
+<HolographicCard source={require('./assets/card.png')} width={320} onPress={openCard} />
+
+// Gold foil preset with higher tilt
+<HolographicCard
+  source={{ uri: 'https://example.com/card.png' }}
+  width={280}
+  foilPreset="gold"
+  maxTiltDegrees={25}
+  tiltSensitivity={1.5}
+  intensity={0.9}
+/>
+
+// Custom foil colors
+<HolographicCard
+  width={280}
+  foilColors={[
+    'rgba(255, 0, 0, 0.5)',
+    'rgba(255, 255, 0, 0.4)',
+    'rgba(0, 255, 0, 0.5)',
+  ]}
+  blendMode="screen"
+  perspective={1200}
+/>
+
+// Foil-only surface (no image)
+<HolographicCard foilPreset="cosmic" width={200} maxTiltDegrees={30} />
+```
+
+---
+
 ## Icon System
 
 The library ships a built-in icon resolver — pass any icon name string to components without manual imports.