@retray-dev/ui-kit 9.3.1 → 10.1.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v9.3.0)
+# @retray-dev/ui-kit — Component Reference (v10.1.0)
 
 This file is the AI reference for this package. Add all three lines below to your project's `CLAUDE.md` to give Claude full context — components, setup guide, and usage examples:
 
@@ -129,9 +129,49 @@ module.exports = config
 
 All components use **Sohne** as the font family. You **must** load it before rendering any UI kit component.
 
+### How it works
+
+1. When you install `@retray-dev/ui-kit`, the **postinstall script** automatically copies 28 `.otf` font files to `assets/fonts/sohne/` in your project root
+2. You must define `SohneFonts` with static `require()` calls in your `App.tsx` (see boilerplate below)
+3. Pass it to `expo-font`'s `useFonts()` hook at your app root
+4. All library components reference fonts by family name (e.g., `fontFamily: 'Sohne-SemiBold'`)
+
+### SohneFonts boilerplate — copy this into your App.tsx
+
 ```tsx
 import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+
+// Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+const SohneFonts = {
+  'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+  'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+  'Sohne-Light': require('./assets/fonts/sohne/Sohne-Light.otf'),
+  'Sohne-LightItalic': require('./assets/fonts/sohne/Sohne-LightItalic.otf'),
+  'Sohne-Regular': require('./assets/fonts/sohne/Sohne-Regular.otf'),
+  'Sohne-Italic': require('./assets/fonts/sohne/Sohne-Italic.otf'),
+  'Sohne-Medium': require('./assets/fonts/sohne/Sohne-Medium.otf'),
+  'Sohne-MediumItalic': require('./assets/fonts/sohne/Sohne-MediumItalic.otf'),
+  'Sohne-SemiBold': require('./assets/fonts/sohne/Sohne-SemiBold.otf'),
+  'Sohne-SemiBoldItalic': require('./assets/fonts/sohne/Sohne-SemiBoldItalic.otf'),
+  'Sohne-Bold': require('./assets/fonts/sohne/Sohne-Bold.otf'),
+  'Sohne-BoldItalic': require('./assets/fonts/sohne/Sohne-BoldItalic.otf'),
+  'Sohne-ExtraBold': require('./assets/fonts/sohne/Sohne-ExtraBold.otf'),
+  'Sohne-ExtraBoldItalic': require('./assets/fonts/sohne/Sohne-ExtraBoldItalic.otf'),
+  'SohneMono-ExtraLight': require('./assets/fonts/sohne/SohneMono-ExtraLight.otf'),
+  'SohneMono-ExtraLightItalic': require('./assets/fonts/sohne/SohneMono-ExtraLightItalic.otf'),
+  'SohneMono-Light': require('./assets/fonts/sohne/SohneMono-Light.otf'),
+  'SohneMono-LightItalic': require('./assets/fonts/sohne/SohneMono-LightItalic.otf'),
+  'SohneMono-Regular': require('./assets/fonts/sohne/SohneMono-Regular.otf'),
+  'SohneMono-Italic': require('./assets/fonts/sohne/SohneMono-Italic.otf'),
+  'SohneMono-Medium': require('./assets/fonts/sohne/SohneMono-Medium.otf'),
+  'SohneMono-MediumItalic': require('./assets/fonts/sohne/SohneMono-MediumItalic.otf'),
+  'SohneMono-SemiBold': require('./assets/fonts/sohne/SohneMono-SemiBold.otf'),
+  'SohneMono-SemiBoldItalic': require('./assets/fonts/sohne/SohneMono-SemiBoldItalic.otf'),
+  'SohneMono-Bold': require('./assets/fonts/sohne/SohneMono-Bold.otf'),
+  'SohneMono-BoldItalic': require('./assets/fonts/sohne/SohneMono-BoldItalic.otf'),
+  'SohneMono-ExtraBold': require('./assets/fonts/sohne/SohneMono-ExtraBold.otf'),
+  'SohneMono-ExtraBoldItalic': require('./assets/fonts/sohne/SohneMono-ExtraBoldItalic.otf'),
+}
 
 export default function App() {
   const [fontsLoaded] = useFonts(SohneFonts)
@@ -142,18 +182,22 @@ export default function App() {
 }
 ```
 
-**How it works:**
-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: 'Sohne-SemiBold'`)
+### .gitignore recommendation
 
-**Included weights:**
+Fonts are copied to `assets/fonts/sohne/` on install. You can either:
+- **Commit them** (no network needed during CI builds)
+- **Ignore them** (re-copied on every `pnpm install`)
+
+```gitignore
+# Sohne fonts — copied by @retray-dev/ui-kit postinstall
+# Either commit these or ignore them (re-copied on install)
+assets/fonts/sohne/
+```
+
+**Included weights (28 files):**
 - 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: 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
 import * as SplashScreen from 'expo-splash-screen'
@@ -208,19 +252,19 @@ These are the only values you need to supply when customizing the theme. The lib
 | Token | Light Default | Dark Default | Semantic Role |
 |-------|--------------|--------------|---------------|
 | `background` | `#ffffff` | `#0f0f0f` | Screen / page background |
-| `foreground` | `#222222` | `#fafafa` | Primary text — deep near-black, not pure black |
+| `foreground` | `#1a1a1a` | `#fafafa` | Primary text — deep near-black, not pure black |
 | `card` | `#ffffff` | `#1c1c1c` | Card / elevated surface background |
 | `primary` | `#1a1a1a` | `#fafafa` | Primary action (buttons, selected states, active indicators) |
 | `primaryForeground` | `#ffffff` | `#0f0f0f` | Text/icon placed on primary-colored backgrounds |
 | `border` | `#dddddd` | `#303030` | Borders, dividers, input outlines |
-| `destructive` | `#e53935` | `#ef5350` | Error / danger / delete actions |
+| `destructive` | `#c72828` | `#ef5350` | Error / danger / delete actions |
 | `destructiveForeground` | `#ffffff` | `#ffffff` | Text/icon on destructive backgrounds |
 | `success` | `#1a7a45` | `#2e7d52` | Success / confirmation states |
 | `successForeground` | `#ffffff` | `#ffffff` | Text/icon on success backgrounds |
-| `warning` | `#e67e00` | `#f57c00` | Warning / caution states |
-| `warningForeground` | `#ffffff` | `#ffffff` | Text/icon on warning backgrounds |
+| `warning` | `#9a5200` | `#f5a623` | Warning / caution states |
+| `warningForeground` | `#ffffff` | `#0f0f0f` | Text/icon on warning backgrounds |
 | `overlay` *(optional)* | `rgba(0,0,0,0.45)` | `rgba(0,0,0,0.45)` | Backdrop/overlay color behind sheets and dialogs |
-| `accent` *(optional)* | same as `primary` | same as `primary` | Secondary brand accent (e.g. Airbnb coral). Falls back to `primary` |
+| `accent` *(optional)* | `#d4561d` | `#e87645` | Secondary brand accent (e.g. Airbnb coral). Falls back to `primary` |
 | `accentForeground` *(optional)* | same as `primaryForeground` | same as `primaryForeground` | Text/icon on accent backgrounds. Falls back to `primaryForeground` |
 
 ### Derived Tokens (ResolvedColors) — read-only via useTheme().colors
@@ -229,8 +273,8 @@ The full palette components consume. Never supply these directly — they are co
 
 | Token | Derived From | Purpose |
 |-------|-------------|---------|
-| `foregroundSubtle` | `foreground` @ ~55% | Body text, subtitles, secondary content |
-| `foregroundMuted` | `foreground` @ ~38% | Captions, timestamps, placeholders |
+| `foregroundSubtle` | `foreground` @ ~70% | Body text, subtitles, secondary content |
+| `foregroundMuted` | `foreground` @ ~62% | Captions, timestamps, placeholders |
 | `surface` | `background` slightly off-canvas | Chip backgrounds, input fills, tag backgrounds, skeleton |
 | `surfaceStrong` | `background` stronger offset | Pressed/hover fill states |
 | `destructiveTint` | `destructive` blended to bg | Alert banner background, toast background |
@@ -572,6 +616,74 @@ import { SohneFonts } from '@retray-dev/ui-kit/fonts'
 
 ---
 
+## Migration Guide: v9 → v10
+
+### Breaking Changes
+
+**1. `SohneFonts` export removed from `@retray-dev/ui-kit/fonts`**
+
+The `SohneFonts` object with `require()` calls is no longer exported. Metro cannot reliably resolve `require()` from inside `node_modules`, especially in monorepos. The export now returns `undefined` and logs a deprecation warning.
+
+**New approach — postinstall script:**
+1. When you install `@retray-dev/ui-kit`, a **postinstall script** automatically copies 28 `.otf` font files to `assets/fonts/sohne/` in your project root
+2. Define `SohneFonts` locally in your `App.tsx` with static `require()` calls (see below)
+3. Pass it to `expo-font`'s `useFonts()` hook
+
+**Migration:**
+
+```diff
+// App.tsx
+import { useFonts } from 'expo-font'
+-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+
++// Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
++const SohneFonts = {
++  'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
++  'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
++  'Sohne-Light': require('./assets/fonts/sohne/Sohne-Light.otf'),
++  'Sohne-LightItalic': require('./assets/fonts/sohne/Sohne-LightItalic.otf'),
++  'Sohne-Regular': require('./assets/fonts/sohne/Sohne-Regular.otf'),
++  'Sohne-Italic': require('./assets/fonts/sohne/Sohne-Italic.otf'),
++  'Sohne-Medium': require('./assets/fonts/sohne/Sohne-Medium.otf'),
++  'Sohne-MediumItalic': require('./assets/fonts/sohne/Sohne-MediumItalic.otf'),
++  'Sohne-SemiBold': require('./assets/fonts/sohne/Sohne-SemiBold.otf'),
++  'Sohne-SemiBoldItalic': require('./assets/fonts/sohne/Sohne-SemiBoldItalic.otf'),
++  'Sohne-Bold': require('./assets/fonts/sohne/Sohne-Bold.otf'),
++  'Sohne-BoldItalic': require('./assets/fonts/sohne/Sohne-BoldItalic.otf'),
++  'Sohne-ExtraBold': require('./assets/fonts/sohne/Sohne-ExtraBold.otf'),
++  'Sohne-ExtraBoldItalic': require('./assets/fonts/sohne/Sohne-ExtraBoldItalic.otf'),
++  'SohneMono-ExtraLight': require('./assets/fonts/sohne/SohneMono-ExtraLight.otf'),
++  'SohneMono-ExtraLightItalic': require('./assets/fonts/sohne/SohneMono-ExtraLightItalic.otf'),
++  'SohneMono-Light': require('./assets/fonts/sohne/SohneMono-Light.otf'),
++  'SohneMono-LightItalic': require('./assets/fonts/sohne/SohneMono-LightItalic.otf'),
++  'SohneMono-Regular': require('./assets/fonts/sohne/SohneMono-Regular.otf'),
++  'SohneMono-Italic': require('./assets/fonts/sohne/SohneMono-Italic.otf'),
++  'SohneMono-Medium': require('./assets/fonts/sohne/SohneMono-Medium.otf'),
++  'SohneMono-MediumItalic': require('./assets/fonts/sohne/SohneMono-MediumItalic.otf'),
++  'SohneMono-SemiBold': require('./assets/fonts/sohne/SohneMono-SemiBold.otf'),
++  'SohneMono-SemiBoldItalic': require('./assets/fonts/sohne/SohneMono-SemiBoldItalic.otf'),
++  'SohneMono-Bold': require('./assets/fonts/sohne/SohneMono-Bold.otf'),
++  'SohneMono-BoldItalic': require('./assets/fonts/sohne/SohneMono-BoldItalic.otf'),
++  'SohneMono-ExtraBold': require('./assets/fonts/sohne/SohneMono-ExtraBold.otf'),
++  'SohneMono-ExtraBoldItalic': require('./assets/fonts/sohne/SohneMono-ExtraBoldItalic.otf'),
++}
+
+export default function App() {
+  const [fontsLoaded] = useFonts(SohneFonts)
+  // ...
+}
+```
+
+**.gitignore recommendation:**
+```gitignore
+# Sohne fonts — copied by @retray-dev/ui-kit postinstall
+assets/fonts/sohne/
+```
+
+**Why this change:** Metro bundler requires `require()` calls to originate from the consumer's source tree, not from `node_modules`. The previous approach worked in simple setups but failed in monorepos and symlinked workspaces.
+
+---
+
 ## Components
 
 ---
@@ -1814,7 +1926,7 @@ const [accepted, setAccepted] = useState(false)
 
 **Dimensions:** Track 52×30px (pill), Thumb 24×24px with 3px offset.
 
-**Animation:** Thumb translates via spring; track color transitions via opacity (150ms).
+**Animation:** Thumb translates via spring (`SPRINGS.elastic`); track color and border animate via `EaseView` `COLOR_TRANSITION`; icons crossfade via `OPACITY_TRANSITION`. All declarative — UI thread.
 
 **Haptics:** `selectionAsync` on toggle.
 
@@ -2165,7 +2277,7 @@ const [tab, setTab] = useState('profile')
 ```ts
 {
   value: string
-  trigger: string
+  trigger: string | ReactNode
   content: ReactNode
   iconName?: string          // Icon name from @expo/vector-icons
   icon?: ReactNode           // Custom icon node
@@ -2173,7 +2285,7 @@ const [tab, setTab] = useState('profile')
 }
 ```
 
-**Animation:** `react-native-reanimated` `withTiming` (220ms) for height and chevron rotation (180°). Press scale uses `withSpring`. Runs on UI thread at 60fps.
+**Animation:** `react-native-reanimated` `withTiming` (240ms expand / 200ms collapse) for height and chevron rotation (180°). Runs on UI thread at 60fps.
 
 **Haptics:** `selectionAsync` on toggle.
 
@@ -2581,11 +2693,13 @@ dismiss(id)
 |------|------|---------|-------|
 | visible | `boolean` | required | Controls dialog visibility |
 | title | `string` | required | Dialog heading |
-| description | `string` | — | Supporting text — describe what exactly will happen |
+| subtitle | `string` | — | Secondary text below title |
+| description | `string` | — | **Deprecated** — use `subtitle` instead |
 | confirmLabel | `string` | `'Confirm'` | Confirm button text |
 | cancelLabel | `string` | `'Cancel'` | Cancel button text |
 | confirmVariant | `'primary' \| 'destructive'` | `'primary'` | Use `'destructive'` for delete/remove actions |
 | loading | `boolean` | `false` | Show spinner in confirm button and disable it (for async `onConfirm`) |
+| showCloseButton | `boolean` | `false` | Show an X close button in the top-right corner |
 | onConfirm | `() => void` | required | Called when confirm is tapped |
 | onCancel | `() => void` | required | Called when cancel is tapped or backdrop pressed |
 
@@ -3654,7 +3768,7 @@ export default function TabLayout() {
 | 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.
+**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. Swipe down to dismiss (drag down or fling; backdrop fades proportionally). `PagerDots` shown when there is more than one image.
 
 **Example:**
 ```tsx

package/CONSUMER.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Consumer Setup Guide (v9.2.0)
+# @retray-dev/ui-kit — Consumer Setup Guide (v10.1.0)
 
 > **For AI assistants (Claude Code):** Add all three lines below to your project's `CLAUDE.md` so Claude has full context about this UI kit:
 > ```markdown
@@ -119,9 +119,40 @@ module.exports = config
 
 ```tsx
 import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
 import { RetrayProvider } from '@retray-dev/ui-kit'
 
+// Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+const SohneFonts = {
+  'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+  'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+  'Sohne-Light': require('./assets/fonts/sohne/Sohne-Light.otf'),
+  'Sohne-LightItalic': require('./assets/fonts/sohne/Sohne-LightItalic.otf'),
+  'Sohne-Regular': require('./assets/fonts/sohne/Sohne-Regular.otf'),
+  'Sohne-Italic': require('./assets/fonts/sohne/Sohne-Italic.otf'),
+  'Sohne-Medium': require('./assets/fonts/sohne/Sohne-Medium.otf'),
+  'Sohne-MediumItalic': require('./assets/fonts/sohne/Sohne-MediumItalic.otf'),
+  'Sohne-SemiBold': require('./assets/fonts/sohne/Sohne-SemiBold.otf'),
+  'Sohne-SemiBoldItalic': require('./assets/fonts/sohne/Sohne-SemiBoldItalic.otf'),
+  'Sohne-Bold': require('./assets/fonts/sohne/Sohne-Bold.otf'),
+  'Sohne-BoldItalic': require('./assets/fonts/sohne/Sohne-BoldItalic.otf'),
+  'Sohne-ExtraBold': require('./assets/fonts/sohne/Sohne-ExtraBold.otf'),
+  'Sohne-ExtraBoldItalic': require('./assets/fonts/sohne/Sohne-ExtraBoldItalic.otf'),
+  'SohneMono-ExtraLight': require('./assets/fonts/sohne/SohneMono-ExtraLight.otf'),
+  'SohneMono-ExtraLightItalic': require('./assets/fonts/sohne/SohneMono-ExtraLightItalic.otf'),
+  'SohneMono-Light': require('./assets/fonts/sohne/SohneMono-Light.otf'),
+  'SohneMono-LightItalic': require('./assets/fonts/sohne/SohneMono-LightItalic.otf'),
+  'SohneMono-Regular': require('./assets/fonts/sohne/SohneMono-Regular.otf'),
+  'SohneMono-Italic': require('./assets/fonts/sohne/SohneMono-Italic.otf'),
+  'SohneMono-Medium': require('./assets/fonts/sohne/SohneMono-Medium.otf'),
+  'SohneMono-MediumItalic': require('./assets/fonts/sohne/SohneMono-MediumItalic.otf'),
+  'SohneMono-SemiBold': require('./assets/fonts/sohne/SohneMono-SemiBold.otf'),
+  'SohneMono-SemiBoldItalic': require('./assets/fonts/sohne/SohneMono-SemiBoldItalic.otf'),
+  'SohneMono-Bold': require('./assets/fonts/sohne/SohneMono-Bold.otf'),
+  'SohneMono-BoldItalic': require('./assets/fonts/sohne/SohneMono-BoldItalic.otf'),
+  'SohneMono-ExtraBold': require('./assets/fonts/sohne/SohneMono-ExtraBold.otf'),
+  'SohneMono-ExtraBoldItalic': require('./assets/fonts/sohne/SohneMono-ExtraBoldItalic.otf'),
+}
+
 export default function App() {
   const [fontsLoaded] = useFonts(SohneFonts)
   if (!fontsLoaded) return null
@@ -234,14 +265,23 @@ npx expo install @shopify/react-native-skia expo-sensors
 
 ## Fonts
 
-All components use the **Sohne** font family. Load fonts before rendering any component:
+All components use the **Sohne** font family.
 
-```tsx
-import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+### How it works
+
+1. When you install `@retray-dev/ui-kit`, the **postinstall script** copies 28 `.otf` font files to `assets/fonts/sohne/` in your project
+2. You define `SohneFonts` with static `require()` calls in your `App.tsx` (see Provider Setup above for the full boilerplate)
+3. Metro resolves fonts from your project's `assets/` folder at bundle time
+
+### .gitignore recommendation
+
+Fonts are copied to `assets/fonts/sohne/` on install. You can either:
+- **Commit them** — no network needed during CI builds
+- **Ignore them** — re-copied on every `pnpm install`
 
-const [fontsLoaded] = useFonts(SohneFonts)
-if (!fontsLoaded) return null
+```gitignore
+# Sohne fonts — copied by @retray-dev/ui-kit postinstall
+assets/fonts/sohne/
 ```
 
 See `FONTS.md` for the full font inventory and weight reference.

package/FONTS.md

@@ -4,13 +4,51 @@
 
 All components in `@retray-dev/ui-kit` use the **Sohne** font family. Consumer apps must load these fonts at the app root using `expo-font`.
 
-### Installation
+### How It Works
+
+1. When you install `@retray-dev/ui-kit`, the **postinstall script** automatically copies 28 `.otf` font files to `assets/fonts/sohne/` in your project root
+2. You must define `SohneFonts` with static `require()` calls in your `App.tsx` (see boilerplate below)
+3. Pass it to `expo-font`'s `useFonts()` hook at your app root
+4. All library components reference fonts by family name (e.g., `fontFamily: 'Sohne-SemiBold'`)
 
-The library includes Sohne font files as raw `.otf` assets. Import and load them:
+### SohneFonts Boilerplate
+
+Copy this into your `App.tsx`:
 
 ```tsx
 import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+
+// Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+const SohneFonts = {
+  'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+  'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+  'Sohne-Light': require('./assets/fonts/sohne/Sohne-Light.otf'),
+  'Sohne-LightItalic': require('./assets/fonts/sohne/Sohne-LightItalic.otf'),
+  'Sohne-Regular': require('./assets/fonts/sohne/Sohne-Regular.otf'),
+  'Sohne-Italic': require('./assets/fonts/sohne/Sohne-Italic.otf'),
+  'Sohne-Medium': require('./assets/fonts/sohne/Sohne-Medium.otf'),
+  'Sohne-MediumItalic': require('./assets/fonts/sohne/Sohne-MediumItalic.otf'),
+  'Sohne-SemiBold': require('./assets/fonts/sohne/Sohne-SemiBold.otf'),
+  'Sohne-SemiBoldItalic': require('./assets/fonts/sohne/Sohne-SemiBoldItalic.otf'),
+  'Sohne-Bold': require('./assets/fonts/sohne/Sohne-Bold.otf'),
+  'Sohne-BoldItalic': require('./assets/fonts/sohne/Sohne-BoldItalic.otf'),
+  'Sohne-ExtraBold': require('./assets/fonts/sohne/Sohne-ExtraBold.otf'),
+  'Sohne-ExtraBoldItalic': require('./assets/fonts/sohne/Sohne-ExtraBoldItalic.otf'),
+  'SohneMono-ExtraLight': require('./assets/fonts/sohne/SohneMono-ExtraLight.otf'),
+  'SohneMono-ExtraLightItalic': require('./assets/fonts/sohne/SohneMono-ExtraLightItalic.otf'),
+  'SohneMono-Light': require('./assets/fonts/sohne/SohneMono-Light.otf'),
+  'SohneMono-LightItalic': require('./assets/fonts/sohne/SohneMono-LightItalic.otf'),
+  'SohneMono-Regular': require('./assets/fonts/sohne/SohneMono-Regular.otf'),
+  'SohneMono-Italic': require('./assets/fonts/sohne/SohneMono-Italic.otf'),
+  'SohneMono-Medium': require('./assets/fonts/sohne/SohneMono-Medium.otf'),
+  'SohneMono-MediumItalic': require('./assets/fonts/sohne/SohneMono-MediumItalic.otf'),
+  'SohneMono-SemiBold': require('./assets/fonts/sohne/SohneMono-SemiBold.otf'),
+  'SohneMono-SemiBoldItalic': require('./assets/fonts/sohne/SohneMono-SemiBoldItalic.otf'),
+  'SohneMono-Bold': require('./assets/fonts/sohne/SohneMono-Bold.otf'),
+  'SohneMono-BoldItalic': require('./assets/fonts/sohne/SohneMono-BoldItalic.otf'),
+  'SohneMono-ExtraBold': require('./assets/fonts/sohne/SohneMono-ExtraBold.otf'),
+  'SohneMono-ExtraBoldItalic': require('./assets/fonts/sohne/SohneMono-ExtraBoldItalic.otf'),
+}
 
 export default function App() {
   const [fontsLoaded] = useFonts(SohneFonts)
@@ -32,12 +70,11 @@ export default function App() {
 ```tsx
 import * as SplashScreen from 'expo-splash-screen'
 import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
 
 SplashScreen.preventAutoHideAsync()
 
 export default function App() {
-  const [fontsLoaded] = useFonts(SohneFonts)
+  const [fontsLoaded] = useFonts(SohneFonts) // Use the SohneFonts object above
 
   useEffect(() => {
     if (fontsLoaded) {
@@ -57,9 +94,20 @@ export default function App() {
 }
 ```
 
+### .gitignore Recommendation
+
+Fonts are copied to `assets/fonts/sohne/` on install. You can either:
+- **Commit them** — no network needed during CI builds
+- **Ignore them** — re-copied on every `pnpm install`
+
+```gitignore
+# Sohne fonts — copied by @retray-dev/ui-kit postinstall
+assets/fonts/sohne/
+```
+
 ### Font Weights Included
 
-`SohneFonts` exports 28 `.otf` files total.
+`SohneFonts` includes 28 `.otf` files total.
 
 **Sohne (14 files):**
 - `Sohne-ExtraLight`
@@ -93,13 +141,6 @@ export default function App() {
 - `SohneMono-ExtraBold`
 - `SohneMono-ExtraBoldItalic`
 
-### How It Works
-
-1. **Library components** reference fonts by family name (e.g., `fontFamily: 'Sohne-SemiBold'`)
-2. **Consumer app** loads font files at startup via `useFonts(SohneFonts)`
-3. **Metro bundler** resolves `require()` calls to `.otf` files in `node_modules/@retray-dev/ui-kit/src/assets/fonts/`
-4. **React Native** maps family names to loaded font files
-
 Font files ship as raw assets — **not bundled into `dist/`**. Metro handles asset resolution natively.
 
 ### Peer Dependency

package/README.md

@@ -46,11 +46,44 @@ module.exports = function (api) {
 
 ## Typography
 
-All components use **Sohne** font family. You must load the fonts at app root before rendering any component:
+All components use **Sohne** font family. You must load the fonts at app root before rendering any component.
+
+When you install `@retray-dev/ui-kit`, a **postinstall script** automatically copies 28 `.otf` font files to `assets/fonts/sohne/` in your project. Then define `SohneFonts` locally in your `App.tsx`:
 
 ```tsx
 import { useFonts } from 'expo-font'
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+
+// Fonts copied to assets/fonts/sohne/ by @retray-dev/ui-kit postinstall
+const SohneFonts = {
+  'Sohne-ExtraLight': require('./assets/fonts/sohne/Sohne-ExtraLight.otf'),
+  'Sohne-ExtraLightItalic': require('./assets/fonts/sohne/Sohne-ExtraLightItalic.otf'),
+  'Sohne-Light': require('./assets/fonts/sohne/Sohne-Light.otf'),
+  'Sohne-LightItalic': require('./assets/fonts/sohne/Sohne-LightItalic.otf'),
+  'Sohne-Regular': require('./assets/fonts/sohne/Sohne-Regular.otf'),
+  'Sohne-Italic': require('./assets/fonts/sohne/Sohne-Italic.otf'),
+  'Sohne-Medium': require('./assets/fonts/sohne/Sohne-Medium.otf'),
+  'Sohne-MediumItalic': require('./assets/fonts/sohne/Sohne-MediumItalic.otf'),
+  'Sohne-SemiBold': require('./assets/fonts/sohne/Sohne-SemiBold.otf'),
+  'Sohne-SemiBoldItalic': require('./assets/fonts/sohne/Sohne-SemiBoldItalic.otf'),
+  'Sohne-Bold': require('./assets/fonts/sohne/Sohne-Bold.otf'),
+  'Sohne-BoldItalic': require('./assets/fonts/sohne/Sohne-BoldItalic.otf'),
+  'Sohne-ExtraBold': require('./assets/fonts/sohne/Sohne-ExtraBold.otf'),
+  'Sohne-ExtraBoldItalic': require('./assets/fonts/sohne/Sohne-ExtraBoldItalic.otf'),
+  'SohneMono-ExtraLight': require('./assets/fonts/sohne/SohneMono-ExtraLight.otf'),
+  'SohneMono-ExtraLightItalic': require('./assets/fonts/sohne/SohneMono-ExtraLightItalic.otf'),
+  'SohneMono-Light': require('./assets/fonts/sohne/SohneMono-Light.otf'),
+  'SohneMono-LightItalic': require('./assets/fonts/sohne/SohneMono-LightItalic.otf'),
+  'SohneMono-Regular': require('./assets/fonts/sohne/SohneMono-Regular.otf'),
+  'SohneMono-Italic': require('./assets/fonts/sohne/SohneMono-Italic.otf'),
+  'SohneMono-Medium': require('./assets/fonts/sohne/SohneMono-Medium.otf'),
+  'SohneMono-MediumItalic': require('./assets/fonts/sohne/SohneMono-MediumItalic.otf'),
+  'SohneMono-SemiBold': require('./assets/fonts/sohne/SohneMono-SemiBold.otf'),
+  'SohneMono-SemiBoldItalic': require('./assets/fonts/sohne/SohneMono-SemiBoldItalic.otf'),
+  'SohneMono-Bold': require('./assets/fonts/sohne/SohneMono-Bold.otf'),
+  'SohneMono-BoldItalic': require('./assets/fonts/sohne/SohneMono-BoldItalic.otf'),
+  'SohneMono-ExtraBold': require('./assets/fonts/sohne/SohneMono-ExtraBold.otf'),
+  'SohneMono-ExtraBoldItalic': require('./assets/fonts/sohne/SohneMono-ExtraBoldItalic.otf'),
+}
 
 export default function App() {
   const [fontsLoaded] = useFonts(SohneFonts)
@@ -62,7 +95,11 @@ export default function App() {
 }
 ```
 
-The library ships 28 font files (14 Sohne base + 14 SohneMono, each with 7 weights + italic variants) as raw `.otf` files. Metro resolves them at bundle time.
+**.gitignore recommendation:**
+```gitignore
+# Sohne fonts — copied by @retray-dev/ui-kit postinstall
+assets/fonts/sohne/
+```
 
 ## Setup
 

package/dist/Accordion.d.mts

@@ -3,7 +3,7 @@ import { ViewStyle } from 'react-native';
 
 interface AccordionItem {
     value: string;
-    trigger: string;
+    trigger: string | React.ReactNode;
     content: React.ReactNode;
     /** Icon name from @expo/vector-icons rendered left of trigger. */
     iconName?: string;

package/dist/Accordion.d.ts

@@ -3,7 +3,7 @@ import { ViewStyle } from 'react-native';
 
 interface AccordionItem {
     value: string;
-    trigger: string;
+    trigger: string | React.ReactNode;
     content: React.ReactNode;
     /** Icon name from @expo/vector-icons rendered left of trigger. */
     iconName?: string;

package/dist/Accordion.js

@@ -302,9 +302,9 @@ function AccordionItemComponent({
       },
       accessibilityRole: "button",
       accessibilityState: { expanded: isOpen },
-      accessibilityLabel: item.trigger
+      accessibilityLabel: typeof item.trigger === "string" ? item.trigger : void 0
     },
-    /* @__PURE__ */ React3__default.default.createElement(reactNative.View, { style: styles.triggerContent }, resolvedIcon ? /* @__PURE__ */ React3__default.default.createElement(reactNative.View, { style: styles.icon }, resolvedIcon) : null, /* @__PURE__ */ React3__default.default.createElement(reactNative.Text, { style: [styles.triggerText, { color: colors.foreground }], allowFontScaling: true }, item.trigger)),
+    /* @__PURE__ */ React3__default.default.createElement(reactNative.View, { style: styles.triggerContent }, resolvedIcon ? /* @__PURE__ */ React3__default.default.createElement(reactNative.View, { style: styles.icon }, resolvedIcon) : null, typeof item.trigger === "string" ? /* @__PURE__ */ React3__default.default.createElement(reactNative.Text, { style: [styles.triggerText, { color: colors.foreground }], allowFontScaling: true }, item.trigger) : item.trigger),
     /* @__PURE__ */ React3__default.default.createElement(Animated__default.default.View, { style: [styles.chevron, rotationStyle] }, /* @__PURE__ */ React3__default.default.createElement(vectorIcons.Entypo, { name: "chevron-down", size: 18, color: colors.foregroundMuted }))
   ), /* @__PURE__ */ React3__default.default.createElement(Animated__default.default.View, { style: bodyStyle }, /* @__PURE__ */ React3__default.default.createElement(
     reactNative.View,

package/dist/Accordion.mjs

@@ -1,4 +1,4 @@
-export { Accordion } from './chunk-O3HA6TYM.mjs';
+export { Accordion } from './chunk-DJ7RN37L.mjs';
 import './chunk-EJ7ZPXOH.mjs';
 import './chunk-DVK4G2GT.mjs';
 import './chunk-T7XZ7H7Y.mjs';

package/dist/ConfirmDialog.d.mts

@@ -3,15 +3,20 @@ import React from 'react';
 interface ConfirmDialogProps {
     visible: boolean;
     title: string;
+    /** Secondary text below title. */
+    subtitle?: string;
+    /** @deprecated Use `subtitle` instead. */
     description?: string;
     confirmLabel?: string;
     cancelLabel?: string;
     confirmVariant?: 'primary' | 'destructive';
     /** Show a loading spinner in the confirm button (e.g. while async action completes). */
     loading?: boolean;
+    /** Show an X close button in the top-right corner. */
+    showCloseButton?: boolean;
     onConfirm: () => void;
     onCancel: () => void;
 }
-declare function ConfirmDialog({ visible, title, description, confirmLabel, cancelLabel, confirmVariant, loading, onConfirm, onCancel, }: ConfirmDialogProps): React.JSX.Element;
+declare function ConfirmDialog({ visible, title, subtitle, description, confirmLabel, cancelLabel, confirmVariant, loading, showCloseButton, onConfirm, onCancel, }: ConfirmDialogProps): React.JSX.Element;
 
 export { ConfirmDialog, type ConfirmDialogProps };

package/dist/ConfirmDialog.d.ts

@@ -3,15 +3,20 @@ import React from 'react';
 interface ConfirmDialogProps {
     visible: boolean;
     title: string;
+    /** Secondary text below title. */
+    subtitle?: string;
+    /** @deprecated Use `subtitle` instead. */
     description?: string;
     confirmLabel?: string;
     cancelLabel?: string;
     confirmVariant?: 'primary' | 'destructive';
     /** Show a loading spinner in the confirm button (e.g. while async action completes). */
     loading?: boolean;
+    /** Show an X close button in the top-right corner. */
+    showCloseButton?: boolean;
     onConfirm: () => void;
     onCancel: () => void;
 }
-declare function ConfirmDialog({ visible, title, description, confirmLabel, cancelLabel, confirmVariant, loading, onConfirm, onCancel, }: ConfirmDialogProps): React.JSX.Element;
+declare function ConfirmDialog({ visible, title, subtitle, description, confirmLabel, cancelLabel, confirmVariant, loading, showCloseButton, onConfirm, onCancel, }: ConfirmDialogProps): React.JSX.Element;
 
 export { ConfirmDialog, type ConfirmDialogProps };