@retray-dev/ui-kit 12.2.0 → 13.2.0

package/{COMPONENTS.md → SKILL.md}

@@ -1,836 +1,431 @@
-# @retray-dev/ui-kit — Component Reference (v12.1.0)
+---
+name: retray-ui-kit
+description: >
+  Complete guide for @retray-dev/ui-kit — a React Native / Expo component
+  library (~55 components). Airbnb-inspired design, Sohne typography,
+  haptic-rich interactions, animated with pressto + react-native-ease.
+  Theme system, BottomSheet patterns, icon resolution, and conventions.
+---
 
-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:
+# @retray-dev/ui-kit — Agent Skill
 
-```markdown
-## UI Components
-@./node_modules/@retray-dev/ui-kit/COMPONENTS.md
-@./node_modules/@retray-dev/ui-kit/CONSUMER.md
-@./node_modules/@retray-dev/ui-kit/EXAMPLES.md
-```
+> **Recommended — copy to repo root (no dependency on node_modules existing):**
+> ```bash
+> cp node_modules/@retray-dev/ui-kit/SKILL.md SKILL.md
+> cp node_modules/@retray-dev/ui-kit/CONSUMER.md CONSUMER.md
+> cp node_modules/@retray-dev/ui-kit/EXAMPLES.md EXAMPLES.md
+> ```
+>
+> Then add to `CLAUDE.md`:
+> ```markdown
+> ## UI Kit
+> @./SKILL.md
+> @./CONSUMER.md
+> @./EXAMPLES.md
+> ```
 
 ---
 
-## Setup (Required)
-
-### Recommended: `RetrayProvider` (one wrapper)
+## Required Setup
 
-Since v8, a single `RetrayProvider` wires all five required providers in the correct order — use this and skip the manual nesting:
+### Providers
+Use `RetrayProvider` (single wrapper) or manual tree. Order is mandatory:
 
-```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'
-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>
-  )
-}
+SafeAreaProvider > GestureHandlerRootView > ThemeProvider > BottomSheetModalProvider > ToastProvider
 ```
 
-**Provider order is mandatory:**
-- `SafeAreaProvider` must be outermost — required by `@gorhom/bottom-sheet`
-- `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` wraps children and renders `Toaster` (from `sonner-native`) internally
-
-### Peer dependencies
+`initialMetrics={initialWindowMetrics}` required on Android.
 
-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 react-native-ease
-```
-
-Then add the Worklets Babel plugin to `babel.config.js` (required by `@gorhom/bottom-sheet` and the pressable animations):
+### Peer Dependencies (all required unless noted)
+- **Hard:** `expo-haptics`, `expo-linear-gradient`, `expo-font`, `expo-image`, `react-native-reanimated`, `react-native-gesture-handler`, `react-native-worklets`, `react-native-safe-area-context`, `react-native-screens`, `react-native-svg`, `@gorhom/bottom-sheet`, `@react-native-picker/picker`, `@react-native-community/slider`, `@expo/vector-icons`, `react-native-size-matters`, `sonner-native`, `react-native-ease`, `pressto`
+- **Optional:** `react-native-image-picker` (ImageUpload), `@shopify/react-native-skia` + `expo-sensors` (HolographicCard deep-import only)
 
+### Babel Config
 ```js
-module.exports = function (api) {
-  api.cache(true)
-  return {
-    presets: ['babel-preset-expo'],
-    plugins: ['react-native-worklets/plugin'], // NOT react-native-reanimated/plugin
-  }
-}
+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-ease` | **Required** | `Checkbox`, `Chip`, `CategoryStrip`, `Switch`, `RadioGroup`, `Toggle` | Declarative `EaseView` animation layer. Static import in source — omitting it crashes the module load. `pnpm add react-native-ease` |
-| `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 **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'
-
-// 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
-  return (
-    // ... your providers and 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
-# 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
-
-Pair with `expo-splash-screen` in production:
-```tsx
-import * as SplashScreen from 'expo-splash-screen'
-SplashScreen.preventAutoHideAsync()
-
-useEffect(() => {
-  if (fontsLoaded) SplashScreen.hideAsync()
-}, [fontsLoaded])
-```
-
----
-
-## Theme System
-
-### ThemeProvider Props
-
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| colorScheme | `'light' \| 'dark' \| 'system'` | `'system'` | `'system'` auto-detects device setting and updates when it changes |
-| theme | `{ light?: Partial<ThemeColors>, dark?: Partial<ThemeColors> }` | — | Override any subset of the 12 public tokens per scheme |
-
-**Custom theme example:**
-```tsx
-const myTheme = {
-  light: { primary: '#ff385c', primaryForeground: '#ffffff' },
-  dark:  { primary: '#ff385c', primaryForeground: '#ffffff' },
-}
-<ThemeProvider theme={myTheme} colorScheme="system">
-```
-
-### useTheme Hook
-
-```tsx
-import { useTheme } from '@retray-dev/ui-kit'
-
-function MyComponent() {
-  const { colors, colorScheme } = useTheme()
-  return <View style={{ backgroundColor: colors.background }} />
-}
-```
-
-Returns `colors` (full `ResolvedColors` palette) and `colorScheme` (`'light' | 'dark'`).
+### Fonts (Sohne)
+Postinstall copies 28 `.otf` to `assets/fonts/sohne/`. Consumer defines static `require()` calls in App.tsx with `expo-font`'s `useFonts()`.
 
 ---
 
-## Theme Tokens
+## Design System (Airbnb-inspired)
 
-### Public Tokens (ThemeColors) — 12 tokens consumer can override
+| Token | Rule |
+|---|---|
+| **Touch targets** | ≥44pt height on all interactive elements |
+| **Spacing** | 8pt grid, 4pt micro-steps |
+| **Radius** | sm=6, md=8, lg=12, xl=16 |
+| **Colors** | 12 public tokens → `deriveColors()` computes 26 resolved tokens |
+| **Typography** | Sohne, modest weights (500-600 display), `allowFontScaling={true}` everywhere |
+| **Shadows** | Max 2 tiers. Flat baseline + single float tier |
+| **Elevation** | Depth from rounded corners + surface separation, not shadows |
 
-These are the only values you need to supply when customizing the theme. The library derives all other colors internally.
+### Theme Tokens — 12 Public (consumer can override)
 
-| Token | Light Default | Dark Default | Semantic Role |
-|-------|--------------|--------------|---------------|
+| Token | Light Default | Dark Default | Role |
+|-------|--------------|--------------|------|
 | `background` | `#ffffff` | `#0f0f0f` | Screen / page background |
-| `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 |
+| `foreground` | `#1a1a1a` | `#fafafa` | Primary text |
+| `card` | `#ffffff` | `#1c1c1c` | Card / elevated surface |
+| `primary` | `#1a1a1a` | `#fafafa` | Primary action (buttons, selected states) |
+| `primaryForeground` | `#ffffff` | `#0f0f0f` | Text/icon on primary |
 | `border` | `#dddddd` | `#303030` | Borders, dividers, input outlines |
-| `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` | `#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)* | `#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
-
-The full palette components consume. Never supply these directly — they are computed by `deriveColors()` from the 12 public tokens above.
-
-| Token | Derived From | Purpose |
-|-------|-------------|---------|
-| `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 |
-| `surfaceStrong` | `background` stronger offset | Pressed/hover fill states |
-| `skeleton` | `background` @ ±10% | Skeleton placeholder — higher contrast than surface for visibility |
-| `destructiveTint` | `destructive` blended to bg | Alert banner background, toast background |
-| `destructiveBorder` | `destructive` @ 30% | Alert banner border, badge outline |
-| `successTint` | `success` blended to bg | Success banner background |
+| `destructive` | `#c72828` | `#ef5350` | Error / danger / delete |
+| `destructiveForeground` | `#ffffff` | `#ffffff` | Text on destructive |
+| `success` | `#1a7a45` | `#2e7d52` | Success / confirmation |
+| `successForeground` | `#ffffff` | `#ffffff` | Text on success |
+| `warning` | `#9a5200` | `#f5a623` | Warning / caution |
+| `warningForeground` | `#ffffff` | `#0f0f0f` | Text on warning |
+| `overlay` *(optional)* | `rgba(0,0,0,0.45)` | `rgba(0,0,0,0.45)` | Backdrop behind sheets |
+| `accent` *(optional)* | `#d4561d` | `#e87645` | Brand accent (falls back to `primary`) |
+| `accentForeground` *(optional)* | `primaryForeground` | `primaryForeground` | Text on accent |
+
+### Derived Tokens — 26 ResolvedColors (read-only via `useTheme().colors`)
+
+| Token | Source | Purpose |
+|-------|--------|---------|
+| `foregroundSubtle` | `foreground` @ ~70% | Body text, subtitles |
+| `foregroundMuted` | `foreground` @ ~62% | Captions, placeholders (WCAG AA 4.5:1) |
+| `surface` | `background` off-canvas | Chip backgrounds, input fills |
+| `surfaceStrong` | `background` stronger offset | Pressed/hover states |
+| `skeleton` | `background` @ ±10% | Skeleton placeholder |
+| `destructiveTint` | `destructive` to bg | Alert banner bg |
+| `destructiveBorder` | `destructive` @ 30% | Alert banner border |
+| `successTint` | `success` to bg | Success banner bg |
 | `successBorder` | `success` @ 30% | Success banner border |
-| `warningTint` | `warning` blended to bg | Warning banner background |
+| `warningTint` | `warning` to bg | Warning banner bg |
 | `warningBorder` | `warning` @ 30% | Warning banner border |
-| `ring` | `= primary` | Focus ring color (always matches primary) |
-| `input` | `= border` | Input field border (always matches border) |
-| `separator` | `border` @ ±16-22% | Divider/separator line — deliberately darker than border |
-| `overlay` | `overlay` token or `rgba(0,0,0,0.45)` | Backdrop behind sheets and dialogs |
-| `accentResolved` | `accent` token or `= primary` | Resolved accent color — always present |
-| `accentForegroundResolved` | `accentForeground` token or `= primaryForeground` | Resolved text on accent — always present |
-
-**Usage example — building a custom component using derived tokens:**
-```tsx
-const { colors } = useTheme()
-
-// Text hierarchy
-<Text style={{ color: colors.foreground }}>Primary text</Text>
-<Text style={{ color: colors.foregroundSubtle }}>Secondary text</Text>
-<Text style={{ color: colors.foregroundMuted }}>Caption / timestamp</Text>
-
-// Surface fills (unselected chips, inactive backgrounds)
-<View style={{ backgroundColor: colors.surface }}>
-
-// Warning alert banner
-<View style={{ backgroundColor: colors.warningTint, borderColor: colors.warningBorder }}>
-  <Text style={{ color: colors.warning }}>Warning message</Text>
-```
-
-### deriveColors export
+| `ring` | `= primary` | Focus ring |
+| `input` | `= border` | Input border |
+| `separator` | `border` @ ±16-22% | Divider line |
+| `overlay` | `overlay` token or `rgba(0,0,0,0.45)` | Sheet backdrop |
+| `accentResolved` | `accent` token or `= primary` | Resolved accent |
+| `accentForegroundResolved` | `accentForeground` or `= primaryForeground` | Resolved text on accent |
 
+### Color Utility
 ```tsx
-import { deriveColors } from '@retray-dev/ui-kit'
-
-const resolved = deriveColors(myThemeColors, 'light')
-// resolved contains all 26 ResolvedColors tokens
+import { withAlpha } from '@retray-dev/ui-kit'
+// hex → rgba: withAlpha('#1a1a1a', 0.15) → 'rgba(26,26,26,0.15)'
 ```
 
----
-
-### Color Utilities
-
-**Import:** `import { withAlpha } from '@retray-dev/ui-kit'`
-
-Convert a hex color to rgba with the given alpha. Useful for semi-transparent backgrounds, borders, and overlays derived from theme colors.
-
-```tsx
-import { useTheme, withAlpha } from '@retray-dev/ui-kit'
-
-const { colors } = useTheme()
-
-<View style={{ backgroundColor: withAlpha(colors.primary, 0.15) }}>
-  <Text style={{ color: colors.primary }}>Tinted background</Text>
-</View>
-```
+### Shape Language
+Soft rounded rects everywhere. Buttons: `RADIUS.md=14px` (NOT pill). IconButton: `RADIUS.full` (circle). Inputs: 8px. Cards: 14px. Modals: 16px top corners only.
 
 ---
 
-## Design Tokens
-
-Static structural constants — no context or provider needed.
+### Design Tokens — Static Constants, No Provider Needed
 
 ```ts
 import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS, TYPOGRAPHY } from '@retray-dev/ui-kit'
 ```
 
-### SPACING — 8pt grid with 2pt micro-step
+**SPACING — 8pt grid**
 
 | Key | Value | Use |
 |-----|-------|-----|
-| `xxs` | 2 | Micro gaps (icon to text in badges) |
+| `xxs` | 2 | Micro gaps |
 | `xs` | 4 | Tight internal gaps |
 | `sm` | 8 | Component internal padding |
 | `md` | 12 | Medium gaps |
 | `base` | 16 | Default content padding |
 | `lg` | 24 | Section internal padding |
-| `xl` | 32 | Between major content blocks |
+| `xl` | 32 | Between major blocks |
 | `xxl` | 48 | Section padding |
-| `section` | 64 | Major band separators (Airbnb hero → grid rhythm) |
-
-**Types:** `Spacing`, `SpacingKey`
-
-```tsx
-<View style={{ gap: SPACING.md, padding: SPACING.base }} />
-```
+| `section` | 64 | Major band separators |
 
-### ICON_SIZES
+**ICON_SIZES**
 
 | Key | Value | Use |
 |-----|-------|-----|
-| `sm` | 14 | Badge icons, inline micro icons |
+| `sm` | 14 | Badge icons |
 | `md` | 18 | Standard component icons |
 | `lg` | 22 | Larger inline icons |
 | `xl` | 28 | Feature icons |
 | `2xl` | 32 | Display icons |
 
-**Types:** `IconSize`, `IconSizeKey`
-
-### RADIUS — Airbnb shape language
+**RADIUS — Airbnb shape language**
 
 | Key | Value | Used in |
 |-----|-------|---------|
-| `none` | 0 | No rounding |
+| `none` | 0 | — |
 | `xs` | 4 | Micro chips, tags |
 | `sm` | 8 | Inputs, Textarea, Select, Checkbox |
-| `md` | 14 | Cards, Buttons (all variants), MediaCard, AlertBanner, Toast, EmptyState |
+| `md` | 14 | Cards, Buttons, MediaCard, AlertBanner, Toast |
 | `lg` | 20 | Sheet top corners |
 | `xl` | 32 | Large decorative elements |
 | `full` | 9999 | IconButton (circle), CategoryStrip chips |
 
-**Types:** `Radius`, `RadiusKey`
-
-```tsx
-<View style={{ borderRadius: RADIUS.md }} />
-```
-
-### SHADOWS — Cross-platform shadow presets
-
-| Key | shadowOffset.height | shadowOpacity | shadowRadius | elevation | Use |
-|-----|---------------------|---------------|--------------|-----------|-----|
-| `sm` | 1 | 0.06 | 4 | 2 | Default card shadow |
-| `md` | 2 | 0.10 | 8 | 5 | Hover float / elevated elements |
-| `lg` | 6 | 0.16 | 16 | 10 | Modals, overlays |
-| `xl` | 12 | 0.24 | 24 | 18 | High-elevation dialogs |
+**SHADOWS — Cross-platform**
 
-```tsx
-<View style={[styles.card, SHADOWS.sm]} />
-// Hover state
-<View style={[styles.card, hovered ? SHADOWS.md : SHADOWS.sm]} />
-```
+| Key | opacity | radius | elevation | Use |
+|-----|---------|--------|-----------|-----|
+| `sm` | 0.06 | 4 | 2 | Default card |
+| `md` | 0.10 | 8 | 5 | Hover float |
+| `lg` | 0.16 | 16 | 10 | Modals |
+| `xl` | 0.24 | 24 | 18 | High-elevation |
 
-### BREAKPOINTS
+**BREAKPOINTS**
 
 | Key | Value | Use |
 |-----|-------|-----|
 | `wide` | 700 | Tablet / wide layout threshold |
 
-```tsx
-const isWide = useWindowDimensions().width >= BREAKPOINTS.wide
-```
+**TYPOGRAPHY — 17 variants**
 
-### TYPOGRAPHY — 16 Airbnb-aligned variants
-
-All components use these tokens for text styling. Import and use in custom components for consistency.
-
-| Key | Size | Weight | lineHeight | letterSpacing | Use |
-|-----|------|--------|-----------|---------------|-----|
-| `display-hero` | 64 | 700 | 70 | -1 | Large number display, balance totals |
+| Key | Size | Weight | lh | ls | Use |
+|-----|------|--------|----|----|-----|
+| `display-hero` | 64 | 700 | 70 | -1 | Large number display |
 | `display-xl` | 28 | 700 | 40 | 0 | Screen titles, hero headings |
-| `display-lg` | 22 | 500 | 26 | -0.44 | Section headings |
-| `display-md` | 21 | 700 | 30 | 0 | Card titles, dialog titles |
-| `display-sm` | 20 | 600 | 24 | -0.18 | Sub-section headings |
-| `title-md` | 16 | 600 | 20 | 0 | Row titles, list item titles |
-| `title-sm` | 16 | 500 | 20 | 0 | Secondary titles |
+| `display-lg` | 24 | 600 | 32 | -0.3 | Section headings |
+| `display-md` | 20 | 600 | 28 | 0 | Card titles |
+| `display-sm` | 18 | 600 | 24 | -0.18 | Sub-section headings |
+| `title-md` | 17 | 600 | 22 | 0 | Row titles |
+| `title-sm` | 15 | 500 | 20 | 0 | Secondary titles |
 | `body-md` | 16 | 400 | 24 | 0 | Primary body copy |
-| `body-sm` | 14 | 400 | 20 | 0 | Secondary body, descriptions |
-| `caption` | 14 | 500 | 18 | 0 | Labels above inputs, item captions |
-| `caption-sm` | 13 | 400 | 16 | 0 | Timestamps, metadata |
-| `badge-text` | 11 | 600 | 13 | 0 | Badge labels, small tags |
-| `micro-label` | 12 | 700 | 16 | 0 | Micro labels, overlines |
-| `uppercase-tag` | 10 | 700 | 13 | 0.8 | Uppercase decorative tags (auto-uppercase) |
-| `button-lg` | 16 | 500 | 20 | 0 | Button labels (md/lg size) |
-| `button-sm` | 14 | 500 | 18 | 0 | Button labels (sm size) |
-
-**Types:** `Typography`, `TypographyKey`
-
-```tsx
-import { TYPOGRAPHY } from '@retray-dev/ui-kit'
-
-// Use in StyleSheet
-const styles = StyleSheet.create({
-  heading: {
-    ...TYPOGRAPHY['display-xl'],
-    color: colors.foreground,
-  },
-})
-```
-
----
-
-## Migration Guide: v4 → v5
-
-### Breaking Changes
-
-**Button variants renamed:**
-| v4 | v5 |
-|----|-----|
-| `outline` | `secondary` |
-| `ghost` | `text` |
-| `secondary` (filled gray) | removed — use Card/surface instead |
-
-**Text variants replaced:**
-| v4 | v5 equivalent |
-|----|---------------|
-| `h1` | `display-xl` |
-| `h2` | `display-lg` or `display-md` |
-| `h3` | `display-sm` |
-| `body` | `body-md` |
-| `label` | `title-sm` or `caption` |
-| `caption` | `caption-sm` |
-
-**Theme tokens changed:**
-| v4 | v5 |
-|----|-----|
-| `secondary`, `secondaryForeground` | removed (use `surface` derived token) |
-| `accent`, `accentForeground` | removed (use `surfaceStrong`) |
-| `muted` | removed → `surface` (derived) |
-| `mutedForeground` | removed → `foregroundSubtle` / `foregroundMuted` (derived) |
-| Added | `warning`, `warningForeground` |
-| Added (derived) | `warningTint`, `warningBorder` |
-
-**IconButton variant:**
-| v4 | v5 |
-|----|-----|
-| `ghost` | `text` |
+| `body-sm` | 14 | 400 | 20 | 0 | Secondary body |
+| `caption` | 14 | 500 | 18 | 0 | Input labels |
+| `caption-sm` | 13 | 400 | 16 | 0 | Timestamps |
+| `badge-text` | 11 | 600 | 14 | 0 | Badge labels |
+| `badge-text-md` | 13 | 600 | 16 | 0 | Badge labels (md size) |
+| `micro-label` | 12 | 700 | 16 | 0 | Overlines |
+| `uppercase-tag` | 11 | 700 | 14 | 0.6 | Decorative tags (auto-uppercase) |
+| `button-lg` | 16 | 500 | 22 | 0 | Button (md/lg) |
+| `button-sm` | 14 | 500 | 18 | 0 | Button (sm) |
 
 ---
 
-## Migration Guide: v5 → v6
-
-### New Components
-
-**`MenuItem`** — Navigation row with icon, label, and optional right slot (`rightRender`). Replaces ad-hoc `ListItem` usage for settings/nav menus. Zero horizontal padding by design — consumer controls spacing.
+## Icons
 
+### Icon Component
 ```tsx
-import { MenuItem } from '@retray-dev/ui-kit'
-// variants: 'plain' (default) | 'card'
-<MenuItem label="Profile" subtitle="Edit your details" iconName="user" onPress={() => {}} />
-<MenuItem label="Notifications" iconName="bell" rightRender={<Switch value={on} onValueChange={setOn} />} showChevron={false} onPress={() => {}} />
+import { Icon } from '@retray-dev/ui-kit'
+<Icon name="home" size={24} color="#000" />
+// Returns null if name not found — no crash
 ```
 
-### Breaking Changes
+### Resolution Order (first-match wins)
+Feather > AntDesign > Entypo > FontAwesome5 > MaterialIcons > Ionicons
 
-**Sheet keyboard defaults changed:**
-| Prop | v5 default | v6 default |
-|------|-----------|-----------|
-| `keyboardBehavior` | `'fillParent'` (Android) / `'interactive'` (iOS) | `'interactive'` (both) |
-| `android_keyboardInputMode` | `'adjustResize'` | `'adjustPan'` |
-
-If you relied on `adjustResize`, set it explicitly: `android_keyboardInputMode="adjustResize"`.
+**Feather is first** — most names resolve there (outlined style). Names with `-outline` suffix resolve to Ionicons (no Feather collision).
 
-**Toast API simplified:**
+### `iconName` props on components
+| Component | Prop(s) | Color |
+|-----------|---------|-------|
+| `Button` | `iconName`, `iconColor` | Variant label |
+| `IconButton` | `iconName`, `iconColor` | Variant foreground |
+| `Input` | `prefixIcon`, `prefixIconColor`, `suffixIcon`, `suffixIconColor` | `foregroundMuted` |
+| `ListItem` | `leftIcon`, `leftIconColor`, `rightIcon`, `rightIconColor` | `foreground` / `foregroundMuted` |
+| `Badge` | `iconName`, `iconColor` | Variant foreground |
+| `Toggle` | `iconName`, `iconColor`, `activeIconName`, `activeIconColor` | `foregroundMuted` / `primary` |
+| `AlertBanner` | `iconName`, `iconColor` | Title color |
+| `EmptyState` | `iconName`, `iconColor` | `foregroundMuted` |
+| `MediaCard` | `actionIconName` | White |
+| `AvatarGroup` | — | — (avatars use own colors) |
+| `Chip` | `iconName` | Variant foreground |
+| `DetailRow` | `leftIconName`, `leftIconColor`, `rightIconName`, `rightIconColor` | `foregroundMuted` |
+| `MenuItem` | `iconName`, `iconColor` | `foreground` |
+
+### curatedIcons.ts
+8 categories, ~20 icons each, all Feather (outlined). Actions, comunicación, navegación, comida, negocios, perfil, multimedia, texto.
+
+### Rules
+- Prefer Feather (outlined) over FA5 solid (filled). FA5 `defaultStyle='regular'` but some names only exist in `solid` — avoid those.
+- Icon lookup uses lazy singleton cache from `glyphMap` introspection.
 
+### `getResponsiveFontSize` utility
 ```tsx
-// v5 — hook-only API
-const { toast } = useToast()
-toast.success('Done')
-
-// v6 — direct import preferred (hook still works for compat)
-import { toast } from '@retray-dev/ui-kit'
-toast.success('Done')
+import { getResponsiveFontSize } from '@retray-dev/ui-kit'
+const fontSize = getResponsiveFontSize(text, 48)
+// Steps: ≤10→max, ≤12→max-4, ≤14→max-6, >14→max-8
 ```
 
-### New Theme Tokens
-
-Three optional `ThemeColors` tokens — fall back gracefully if omitted:
-
-| Token | Default | Purpose |
-|-------|---------|---------|
-| `overlay` | `rgba(0,0,0,0.45)` | Backdrop color behind sheets and dialogs |
-| `accent` | `= primary` | Secondary brand accent color |
-| `accentForeground` | `= primaryForeground` | Text on accent backgrounds |
-
-Access resolved values via `useTheme().colors.overlay`, `.accentResolved`, `.accentForegroundResolved`.
-
-### Token Corrections
-
-- `TYPOGRAPHY['uppercase-tag']` — size corrected to `10` (was documented as `8`, actual value was always `10`)
-
 ---
 
-## 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.
+## Animations & Interactions
 
-**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 |
+### Pressables (pressto)
+| Pressable | Scale | Used by |
+|---|---|---|
+| `PressableButton` | 0.95 | Button, IconButton, Toggle, Checkbox |
+| `PressableCard` | 0.98 | Card, MediaCard, Stats, Pressable |
+| `PressableRow` | 0.97 | ListItem, MenuItem |
+| `PressableChip` | 0.94 | Chip |
+| `PressableTab` | 0.95 | Tabs triggers |
 
-**Component visual behavior changes:**
+All use `enabled={!disabled}`, `rippleColor="transparent"`, `touchSoundDisabled`.
 
-| 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 |
+### Spring Presets
+- `glide`: `{ stiffness: 380, damping: 38, mass: 1.0 }` — sliding indicators
+- `elastic`: `{ stiffness: 320, damping: 22, mass: 0.7 }` — Switch thumb, RadioGroup dot
 
-**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.
+### Timing Presets
+- `state`: 160ms (checkbox/toggle color)
+- `expand` / `collapse`: 240ms / 200ms (Accordion)
+- `shimmer`: 1400ms (Skeleton)
 
-### New Compound Component Section
+### EaseView (react-native-ease)
+Declarative color/opacity transitions: Switch track, Checkbox fill, RadioGroup dot. UI thread.
 
-The example app now has a dedicated **Compound Components** section showcasing `Card`, `ButtonGroup`, `Form`, `ListGroup`, and `MenuGroup` with all sub-components and variants.
+### Reanimated v4
+Complex animations only (gestures, layout interpolations). Simple opacity: use RN `Animated` + `useNativeDriver`.
 
 ---
 
-## Migration Guide: v7 → v8
-
-### Breaking Changes
+## Sheets (BottomSheetModal)
 
-**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'
-```
+### Strict rules (from @gorhom/bottom-sheet)
+1. **Always `BottomSheetModal`** — never `BottomSheet` base. `present()` in handler directly (not `useEffect`).
+2. **`enableDynamicSizing`** — no `snapPoints` (mutually exclusive)
+3. **`topInset={insets.top}`** — prevents notch overlap
+4. **`keyboardBehavior="interactive"`** + **`android_keyboardInputMode="adjustPan"`** — keyboard
+5. **`SheetTextInput`** inside sheets — never `<TextInput />`
+6. **`onDismiss`** for cleanup, not `onClose`
+7. **`renderBackdrop`** wrapped in `useCallback`
+8. **`enableBlurKeyboardOnGesture={true}`** — dismiss keyboard on drag
+9. **`BottomSheetModalProvider`** re-exported, included in `RetrayProvider`
 
-### New — packaging & DX
+### Input inside Sheet
+Use `<Input sheetMode />` — transparently swaps to `BottomSheetTextInput`. For low-level: `SheetTextInput`.
 
-- **`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.
+## Haptics (expo-haptics)
 
-### Optional peers (only if you use the matching component)
+Web-safe via `Platform.OS !== 'web'` guard + dynamic `import()`.
 
-- `@shopify/react-native-skia` + `expo-sensors` → `HolographicCard` (deep-import only, not in the main barrel).
+| Function | Usage |
+|---|---|
+| `selectionAsync()` | Checkbox, Switch, Toggle, RadioGroup, Select, Slider (step), Accordion, ListItem, MenuItem, ConfirmDialog cancel |
+| `impactLight()` / `impactMedium()` / `impactHeavy()` | Button, Sheet open, ConfirmDialog open, Stats |
+| `notificationSuccess()` / `notificationError()` / `notificationWarning()` | ConfirmDialog confirm, form validation |
 
 ---
 
-## 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'),
-+}
+## Theming
 
-export default function App() {
-  const [fontsLoaded] = useFonts(SohneFonts)
-  // ...
+### Consumer supplies 12 ThemeColors
+```tsx
+import { ThemeProvider, ThemeColors } from '@retray-dev/ui-kit'
+
+const customLight: ThemeColors = {
+  background: '#ffffff',
+  foreground: '#1a1a1a',
+  primary: '#d4561d',
 }
 ```
 
-**.gitignore recommendation:**
-```gitignore
-# Sohne fonts — copied by @retray-dev/ui-kit postinstall
-assets/fonts/sohne/
-```
+### deriveColors()
+Computes 26 `ResolvedColors` from 12 `ThemeColors`. Components consume `useTheme().colors` — never raw `ThemeColors`.
 
-**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.
+### Structural tokens (not in theme)
+Spacing, radii, shadows, typography = static `as const` exports from `tokens.ts`. No provider needed.
 
 ---
 
-## Migration Guide: v10 → v11
-
-### New — public utility
-
-**`withAlpha(hex, alpha)`** — hex-to-rgba color helper, now exported from the package root. Useful for semi-transparent overlays derived from theme colors without adding a new token.
+## Toast (sonner-native)
 
 ```tsx
-import { useTheme, withAlpha } from '@retray-dev/ui-kit'
+import { toast } from 'sonner-native'
+// or
+import { useToast } from '@retray-dev/ui-kit'
+const { toast } = useToast()
 
-const { colors } = useTheme()
-<View style={{ backgroundColor: withAlpha(colors.primary, 0.15) }} />
+toast('Hello', { description: 'World' })
+toast.success('Saved')
+toast.error('Failed', { description: 'Check network' })
+toast.promise(save(), { loading: 'Saving...', success: 'Done', error: 'Failed' })
 ```
 
-### Updated
-
-- `Stats` component promoted from internal/experimental to public (`Stats` + `Stats.Group`).
-- Documentation refreshed for `IconPicker` and `NumberStepper`.
-
-No breaking changes in v11. Safe minor upgrade from v10.
+`Toaster` rendered inside `ToastProvider`. Config: `richColors: false`, `swipeToDismissDirection="up"`, `duration: 4000`.
 
 ---
 
-## Migration Guide: v11 → v12
-
-### Breaking Changes
-
-`Sheet` and `ConfirmDialog` were rewritten on top of `@gorhom/bottom-sheet`'s **`BottomSheetModal`** (lazy-mounted, `present()` / `dismiss()` driven) — replacing the old `BottomSheet` + `index={-1}` + `snapToIndex(0)` pattern. This fixes timing issues with `enableDynamicSizing` and unifies the API with the rest of the gorhom ecosystem.
+## Data Display Patterns
 
-**1. Removed `responsive` / `dialogMaxWidth` props from `Sheet` and `ConfirmDialog`**
-
-The previous wide-screen fallback that bypassed gorhom with a native `Modal` + `ScrollView` was a partial workaround (see REGLA 1). It has been deleted. `@gorhom/bottom-sheet` handles responsive behavior natively — the modal simply renders inside its modal layer at the device width.
-
-```diff
- <Sheet
-   open={open}
-   onClose={() => setOpen(false)}
-   title="Options"
--  responsive
--  dialogMaxWidth={600}
- />
-```
-
-**2. `onClose` is the only close handler**
-
-`onClose` is called from `BottomSheetModal.onDismiss` — the native gorhom callback. The previous `onClose` prop (passed directly to `BottomSheet`) was redundant. No public-API change for consumers; this is an internal alignment.
+### ListItem
+- `rightActions` prop for swipe-to-reveal (iOS Mail style)
+- Uses `PressableRow` (scale 0.97)
+- Haptic: `selectionAsync()` on press
+- Zero horizontal padding by design
 
-**3. `Sheet` requires `BottomSheetModalProvider` at app root**
+### ListGroup
+- Optional `Header` / `Footer` sub-components
+- Auto-separators between items except last
 
-`RetrayProvider` already wires it. If you assemble providers manually, ensure `BottomSheetModalProvider` sits inside `GestureHandlerRootView`:
+### MenuItem / MenuGroup
+- Settings/nav rows. Auto-separators.
+- `rightRender` for Switch, Badge, etc.
+- `variant="card"` for standalone surface
 
-```tsx
-<SafeAreaProvider initialMetrics={initialWindowMetrics}>
-  <GestureHandlerRootView style={{ flex: 1 }}>
-    <ThemeProvider>
-      <BottomSheetModalProvider>
-        <ToastProvider>{/* app */}</ToastProvider>
-      </BottomSheetModalProvider>
-    </ThemeProvider>
-  </GestureHandlerRootView>
-</SafeAreaProvider>
-```
+### Chip / ChipGroup
+- Multi-select toggle chips. `PressableChip` (scale 0.94)
+- `ChipGroup` wraps to rows; `CategoryStrip` scrolls horizontally
 
-**4. Keyboard prop renames (no consumer action — defaults match v11)**
+### LabelValue
+- Key-value rows (label left, value right)
+- Icon support
 
-| Prop | v11 | v12 default |
-|------|-----|-------------|
-| `keyboardBehavior` | `'interactive'` | `'interactive'` (unchanged) |
-| `android_keyboardInputMode` | `'adjustPan'` | `'adjustPan'` (unchanged) |
+### DetailRow
+- Ticket/receipt rows with `···` dotted separator
+- Icon + label + value
 
-**5. Removed top-level imports of `Modal`, `ScrollView`, `useWindowDimensions`, `BREAKPOINTS` from `Sheet.tsx`**
+### Skeleton
+- `Skeleton.MediaCard`, `Skeleton.ListItem`, `Skeleton.List` (6 items, 2 columns)
+- Shimmer animation loops every 1200ms
 
-Internal only — no public API.
+---
 
-### Behavioral changes (no code change required)
+## Accessibility (WCAG AA)
 
-- **Backdrop / swipe close is now driven by gorhom's modal lifecycle** — `onClose` fires once on full dismiss instead of on every interaction. State-setter closures (e.g. `setOpen(false)`) are safe to call from `onClose` without causing "dismiss on unmounted" loops.
-- **`topInset={insets.top}`** is now applied automatically from safe-area context — sheet never crosses the notch / status bar on iOS or Android.
-- **`snapPoints` + `enableDynamicSizing` are mutually exclusive.** If you pass `snapPoints`, dynamic sizing is disabled and the sheet snaps to those points. Omit `snapPoints` to use dynamic sizing (default).
+- `allowFontScaling={true}` on all `<Text>` and `<TextInput>`
+- Touch targets ≥44pt
+- `foregroundMuted` = `#9a9a9a` (dark) / `#a2a2a2` (light) — ≥4.5:1 contrast
+- Accessibility props passed through via `...props`
 
-### New — recommended pattern
+---
 
-**Use `Input` with `sheetMode` inside a Sheet** instead of `SheetTextInput` directly. The new `sheetMode` prop on `Input` swaps in `BottomSheetTextInput` for keyboard-aware focus/blur handling while preserving the full `Input` API (label, error, hint, prefix/suffix, icons, type="password").
+## Deep Import Pattern
 
+Prefer deep imports in production for smaller bundle:
 ```tsx
-<Sheet open={open} onClose={() => setOpen(false)} title="Add note">
-  <Input
-    label="Note"
-    placeholder="Type your note..."
-    value={note}
-    onChangeText={setNote}
-    sheetMode
-  />
-  <Button label="Save" fullWidth onPress={handleSave} />
-</Sheet>
+import { Button } from '@retray-dev/ui-kit/Button'  // deep
+// vs
+import { Button } from '@retray-dev/ui-kit'           // barrel
 ```
 
-`SheetTextInput` is still re-exported for low-level use.
+Deep-import only (NOT in barrel):
+```tsx
+import { HolographicCard } from '@retray-dev/ui-kit/HolographicCard'
+```
 
 ---
 
-## Migration Guide: v12.0 → v12.1
-
-### New — IconPicker feedback pattern (REGLA 4)
+## Anti-Patterns
 
-`IconPicker` now follows the "no frozen screen" rule. When the user taps the trigger, the sheet presents **immediately** (no `useEffect` delay). While the inner grid measures its container, a centered `<Spinner />` is shown inside the sheet so the user sees visible feedback. The grid fades in as soon as `onLayout` fires.
-
-This is now the canonical pattern for any sheet whose content needs to measure or load before rendering — apply it to new overlay components.
-
-### New — race-condition fix in `Sheet` and `ConfirmDialog`
-
-Both components now track a `wasOpened` ref so `dismiss()` is only called after the sheet has been presented at least once. This eliminates a class of crashes that occurred when the parent component unmounted (or the `open`/`visible` prop flipped) before the gorham modal had a chance to mount.
-
-No consumer action required — the fix is internal.
+| Anti-pattern | Why | Fix |
+|---|---|---|
+| `<TextInput />` inside Sheet | Keyboard broken | Use `<Input sheetMode />` or `<SheetTextInput />` |
+| `BottomSheet` base with `snapToIndex` | Fragile timing | Use `BottomSheetModal` with `present()` |
+| `snapPoints` + `enableDynamicSizing` | Runtime error | Use one or the other |
+| Static import of optional peer | Crash at module init | Dynamic `import()` in handler |
+| Bundling native modules | Duplicate Context | Externalize in tsup |
+| `--legacy-peer-deps` | Hides conflicts | Use `overrides` in package.json |
 
-### New — expanded curated icon library
+---
 
-`src/utils/curatedIcons.ts` has been expanded: every category now carries 42+ icons (some up to 66), totaling ~600 themed icons across the 12 categories. Selection rules are now codified in REGLA 5 — only Feather, Ionicons `-outline`, and themed FA5/Entypo/AntDesign icons are eligible (no filled variants).
+## Version
 
-### Updated
+**Current: 13.1.0.** Requires Expo SDK 54+, React Native 0.81+, React 19.
 
-- `Sheet` and `ConfirmDialog` pass a stable `name` prop to `BottomSheetModal` (from `useId()`) for correct gorhom modal registry behavior when multiple modals are mounted.
-- `Input` `sheetMode` prop documented in the Setup section (replaces the `SheetTextInput` boilerplate inside sheets).
-- `CompositionScreen` example now uses `<Input sheetMode />` inside a `Sheet` to demonstrate the keyboard-friendly pattern.
+For full setup guide, see `CONSUMER.md`. For usage examples, see `EXAMPLES.md`.
 
 ---
 
-## Components
+## Component Reference
 
 ---
 
@@ -857,18 +452,19 @@ No consumer action required — the fix is internal.
 |---------|------|--------|--------------|-------------|
 | `display-hero` | 64 | 700 | `foreground` | Large numeric displays — balance totals, stats, hero numbers |
 | `display-xl` | 28 | 700 | `foreground` | Screen-level titles, onboarding hero headings |
-| `display-lg` | 22 | 500 | `foreground` | Section headings, card group labels |
-| `display-md` | 21 | 700 | `foreground` | Card titles, dialog headings |
-| `display-sm` | 20 | 600 | `foreground` | Sub-section titles |
-| `title-md` | 16 | 600 | `foreground` | List row titles, navigation labels |
-| `title-sm` | 16 | 500 | `foreground` | Secondary row titles |
+| `display-lg` | 24 | 600 | `foreground` | Section headings, card group labels |
+| `display-md` | 20 | 600 | `foreground` | Card titles, dialog headings |
+| `display-sm` | 18 | 600 | `foreground` | Sub-section titles |
+| `title-md` | 17 | 600 | `foreground` | List row titles, navigation labels |
+| `title-sm` | 15 | 500 | `foreground` | Secondary row titles |
 | `body-md` | 16 | 400 | `foregroundSubtle` | Main body copy, descriptions |
 | `body-sm` | 14 | 400 | `foregroundSubtle` | Secondary descriptions, detail text |
 | `caption` | 14 | 500 | `foreground` | Labels above inputs, item captions |
 | `caption-sm` | 13 | 400 | `foregroundMuted` | Timestamps, metadata, helper text |
 | `badge-text` | 11 | 600 | `foreground` | Badge labels, small status tags |
+| `badge-text-md` | 13 | 600 | `foreground` | Badge labels (md size) |
 | `micro-label` | 12 | 700 | `foreground` | Micro labels, overlines |
-| `uppercase-tag` | 10 | 700 | `foreground` | Decorative uppercase category labels (auto-transforms text) |
+| `uppercase-tag` | 11 | 700 | `foreground` | Decorative uppercase category labels (auto-transforms text) |
 | `button-lg` | 16 | 500 | `foreground` | Internal use in Button component (md/lg) |
 | `button-sm` | 14 | 500 | `foreground` | Internal use in Button component (sm) |
 
@@ -1561,6 +1157,65 @@ const [guests, setGuests] = useState(2)
 
 ---
 
+### AvatarGroup
+
+**Import:** `import { AvatarGroup } from '@retray-dev/ui-kit'`
+
+**When to use:** Stacked/overlapping avatars to show multiple users in a compact space. Common for collaborator indicators, multi-waiter tables, and team members.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| users | `{ name: string; src?: string }[]` | required | User data — name used for fallback initials |
+| max | `number` | `3` | Max avatars visible before `+N` overflow badge |
+| size | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'sm'` | Avatar size preset, passed to each `Avatar` |
+| overlap | `number` | `vs(8)` | Overlap in points between consecutive avatars |
+| onOverflowPress | `() => void` | — | Tap handler for the `+N` overflow badge |
+| style | `ViewStyle` | — | Outer container style |
+
+**Sizes:** Same as `Avatar` — `sm` (28px), `md` (40px), `lg` (56px), `xl` (72px).
+
+**Notes:**
+- Overflow badge uses `surfaceStrong` background with `foregroundMuted` text.
+- Individual avatars are not tappable — only the `+N` badge fires `onOverflowPress`.
+- `overlap` follows the spacing grid (defaults to `spacing.sm` = 8pt).
+
+**Examples:**
+```tsx
+// Basic — 5 waiters, show max 3
+<AvatarGroup
+  users={[
+    { name: 'Ana', src: 'https://...' },
+    { name: 'Bob', src: 'https://...' },
+    { name: 'Carlos' },
+    { name: 'Diana', src: 'https://...' },
+    { name: 'Elena' },
+  ]}
+  max={3}
+/>
+
+// With overflow tap
+<AvatarGroup
+  users={waiters}
+  max={3}
+  size="sm"
+  onOverflowPress={() => showAllWaiters()}
+/>
+
+// In a ListItem
+<ListItem
+  title="Table 4 — 5 waiters"
+  leftRender={
+    <AvatarGroup
+      users={table.waiters}
+      max={3}
+      size="sm"
+    />
+  }
+/>
+```
+
+---
+
 ### Card
 
 **Import:** `import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@retray-dev/ui-kit'`
@@ -1765,73 +1420,7 @@ const [guests, setGuests] = useState(2)
 
 ---
 
-### 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
 
@@ -1946,7 +1535,7 @@ const renderItem = useCallback(({ item }) => (
 // Matches <ListItem> — leading circle + title/subtitle lines
 <Skeleton.ListItem />                              // props: showAvatar, showSubtitle, style
 
-// Repeated list/grid placeholder — for VirtualList / FlatList while loading.
+// Repeated list/grid placeholder — for 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
@@ -1954,8 +1543,8 @@ const renderItem = useCallback(({ item }) => (
 
 // Also exported as named components: MediaCardSkeleton, ListItemSkeleton, ListSkeleton
 
-// As a VirtualList loading state
-<VirtualList
+// As a FlatList loading state
+<FlatList
   data={loading ? [] : rows}
   renderItem={renderItem}
   ListEmptyComponent={loading ? <Skeleton.List count={8} /> : <EmptyState .../>}
@@ -3854,7 +3443,8 @@ export default function Screen() {
 | 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 |
+| iconName | `string` | — | Decorative icon left of title, after back button. Ignored when `left` is provided |
+| left | `ReactNode` | — | Custom left content — overrides the back button and `iconName` |
 | right | `ReactNode` | — | Custom right content (actions) |
 | titleAlign | `'auto' \| 'left' \| 'center'` | `'auto'` | `auto` = left on narrow, centered on wide |
 | bordered | `boolean` | `true` | Hairline border underneath |
@@ -3869,6 +3459,13 @@ export default function Screen() {
   onBack={navigation.goBack}
   right={<IconButton iconName="more-horizontal" variant="text" onPress={openMenu} />}
 />
+
+{/* With decorative icon and back button */}
+<AppHeader
+  title="Perfil"
+  iconName="user"
+  onBack={() => router.back()}
+/>
 ```
 
 ---
@@ -4316,7 +3913,7 @@ import { HolographicCard, FOIL_PRESETS } from '@retray-dev/ui-kit/HolographicCar
 
 **When to use:** Image selection from the device library — product photos, profile avatars, tenant logos. Shows a dashed placeholder when empty, the selected image when filled, and a loading overlay while uploading.
 
-**Requires:** `expo-image-picker` installed in the consuming app (`pnpm add expo-image-picker`). It is an optional peer dep — consumers who don't use `ImageUpload` never pull it.
+**Requires:** `react-native-image-picker` installed in the consuming app (`pnpm add react-native-image-picker`). It is an optional peer dep — consumers who don't use `ImageUpload` never pull it. It is dynamically imported at tap time.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
@@ -4330,9 +3927,9 @@ import { HolographicCard, FOIL_PRESETS } from '@retray-dev/ui-kit/HolographicCar
 | borderRadius | `number` | `RADIUS.lg` | — |
 | resizeMode | `'cover' \| 'contain' \| 'stretch'` | `'cover'` | Image resize mode |
 | disabled | `boolean` | `false` | Prevents pressing |
-| allowsEditing | `boolean` | `true` | When `true`, iOS opens the crop/editing screen after selecting an image. Set `false` to accept the image directly without cropping |
 | style | `ViewStyle` | — | — |
 | accessibilityLabel | `string` | — | — |
+| onPickerStarting | `() => void` | — | Called synchronously when user taps the upload area, before dynamic import and permission request |
 
 **Examples:**
 ```tsx
@@ -4425,10 +4022,12 @@ const [icon, setIcon] = useState<string | null>(null)
 
 **Import:** `import { useConfirmDialog } from '@retray-dev/ui-kit'`
 
-**When to use:** Manage `ConfirmDialog` state without boilerplate. Replaces the `[target, setTarget]` + `visible` + `loading` state pattern that each screen would otherwise duplicate.
+**When to use:** Manage `ConfirmDialog` state without boilerplate. Replaces the `visible` + `loading` state pattern that each screen would otherwise duplicate.
+
+**Note (v13):** The generic `T`, `target`, and `dialogProps` convenience object were removed. Returns `onConfirm`/`onCancel` directly. Uses refs for callback stability and `mountedRef` for safe async cleanup.
 
 ```ts
-function useConfirmDialog<T>(options: UseConfirmDialogOptions): UseConfirmDialogResult<T>
+function useConfirmDialog(options: UseConfirmDialogOptions): UseConfirmDialogResult
 
 interface UseConfirmDialogOptions {
   onConfirm: () => void | Promise<void>
@@ -4441,253 +4040,32 @@ interface UseConfirmDialogOptions {
 | Field | Type | Notes |
 |-------|------|-------|
 | visible | `boolean` | Pass to `ConfirmDialog.visible` |
-| target | `T \| null` | The value passed to `open()` — e.g. the item being deleted |
 | loading | `boolean` | Pass to `ConfirmDialog.loading` |
-| open | `(target?: T) => void` | Call to show the dialog |
-| dialogProps | `object` | Spread directly onto `<ConfirmDialog>` (contains `visible`, `loading`, `onConfirm`, `onCancel`) |
+| open | `() => void` | Call to show the dialog |
+| onConfirm | `() => void` | Pass directly to `ConfirmDialog.onConfirm` |
+| onCancel | `() => void` | Pass directly to `ConfirmDialog.onCancel` |
 
 **Example:**
 ```tsx
-const { open, target, dialogProps } = useConfirmDialog<Product>({
+const { visible, loading, open, onConfirm, onCancel } = useConfirmDialog({
   onConfirm: async () => {
-    await deleteProduct(target!.id)
+    await deleteProduct(productId)
     toast.success('Product deleted')
   },
 })
 
-// Somewhere in your list:
-<ListItem
-  title={product.name}
-  rightIcon="trash-2"
-  onPress={() => open(product)}
-/>
-
-// Once in your screen's JSX:
+// Somewhere in your screen:
 <ConfirmDialog
-  title={`Delete "${target?.name}"?`}
-  description="This action cannot be undone."
+  visible={visible}
+  title="Delete product?"
+  subtitle="This action cannot be undone."
   confirmLabel="Delete"
   confirmVariant="destructive"
-  {...dialogProps}
+  loading={loading}
+  onConfirm={onConfirm}
+  onCancel={onCancel}
 />
 ```
 
 ---
 
-## Icon System
-
-The library ships a built-in icon resolver — pass any icon name string to components without manual imports.
-
-### Supported families (priority order — first match wins)
-
-| Priority | Family | Best for |
-|---|---|---|
-| 1 (highest) | `Feather` | Clean line icons, UI essentials |
-| 2 | `AntDesign` | Semantic UI icons |
-| 3 | `Entypo` | Social, media, navigation icons |
-| 4 | `FontAwesome5` | Wide coverage |
-| 5 | `MaterialIcons` | Material-style icons |
-| 6 (lowest) | `Ionicons` | Fallback |
-
-Browse all available icons: **https://icons.expo.fyi**
-
-### Standalone `Icon` component
-
-```tsx
-import { Icon } from '@retray-dev/ui-kit'
-
-<Icon name="home" size={24} color={colors.foreground} />
-<Icon name="star" size={20} color={colors.primary} />
-
-// Force a specific family when same name exists in multiple families:
-<Icon name="heart" size={24} color="red" family="FontAwesome5" />
-```
-
-**Props:**
-
-| Prop | Type | Required | Notes |
-|------|------|----------|-------|
-| name | `string` | yes | Icon name (e.g. `"home"`, `"arrow-right"`) |
-| size | `number` | yes | Icon size in points |
-| color | `string` | yes | Icon color |
-| family | `IconFamily` | no | Force a specific family |
-
-Returns `null` (no crash) if name not found in any family.
-
-### `renderIcon` helper
-
-```tsx
-import { renderIcon } from '@retray-dev/ui-kit'
-
-// Returns ReactNode or null
-const icon = renderIcon('check', 18, colors.primary)
-```
-
-### `getValidIconNames` utility
-
-```tsx
-import { getValidIconNames } from '@retray-dev/ui-kit'
-
-// All icon names across all configured families
-const allIcons: string[] = getValidIconNames()
-// => ["home", "user", "heart", "star", ...]
-
-// Scoped to specific families (does not mutate global config)
-const featherOnly: string[] = getValidIconNames(['Feather'])
-```
-
-Returns `string[]` — all resolvable icon names from the configured families. Respects `configureIconFamilies()` global config. The optional `families` parameter builds a temporary cache scoped to those families without mutating global state. Use to build icon pickers, search, and galleries.
-
-### `iconName` props on components
-
-All components with icon slots accept `iconName` — auto-resolved size and color:
-
-| Component | Prop(s) | Slot | Default color |
-|-----------|---------|------|---------------|
-| `Button` | `iconName`, `iconColor` | Left or right of label | Variant label color |
-| `IconButton` | `iconName`, `iconColor` | Center | Variant foreground |
-| `Input` | `prefixIcon`, `prefixIconColor` | Before input | `foregroundMuted` |
-| `Input` | `suffixIcon`, `suffixIconColor` | After input | `foregroundMuted` |
-| `ListItem` | `leftIcon`, `leftIconColor` | Left 44×44 slot | `foreground` |
-| `ListItem` | `rightIcon`, `rightIconColor` | Right slot | `foregroundMuted` |
-| `Badge` | `iconName`, `iconColor` | Before label | Variant foreground |
-| `Toggle` | `iconName`, `iconColor` | When not pressed | `foregroundMuted` |
-| `Toggle` | `activeIconName`, `activeIconColor` | When pressed | `primary` |
-| `AlertBanner` | `iconName`, `iconColor` | Left of content | Variant title color |
-| `EmptyState` | `iconName`, `iconColor` | Center icon slot | `foregroundMuted` |
-| `Toast` | `iconName`, `iconColor` | Left of message | Variant text color |
-| `MediaCard` | `actionIconName` | Top-right of image | `#ffffff` |
-| `Chip` | `iconName` | Before label | Variant foreground |
-
-**Precedence:** `iconName` always takes precedence over the corresponding `ReactNode` prop when both are supplied.
-
----
-
-### `getResponsiveFontSize` utility
-
-Calculates a stepped-down font size for long numeric strings (currency amounts, large numbers) that would overflow at full size.
-
-```tsx
-import { getResponsiveFontSize } from '@retray-dev/ui-kit'
-
-// Default steps: ≤10 chars → max, ≤12 → max-4, ≤14 → max-6, >14 → max-8
-const fontSize = getResponsiveFontSize(formatCOP(amount), 48)
-
-<Text style={{ fontSize }} numberOfLines={1} adjustsFontSizeToFit>
-  {formatCOP(amount)}
-</Text>
-```
-
-**Signature:**
-```ts
-getResponsiveFontSize(
-  text: string,
-  maxSize: number,
-  steps?: { maxLen: number; subtract: number }[]
-): number
-```
-
-Custom steps example:
-```tsx
-getResponsiveFontSize(text, 48, [
-  { maxLen: 8,  subtract: 0 },
-  { maxLen: 11, subtract: 6 },
-  { maxLen: 14, subtract: 10 },
-])
-```
-
-**Alternative:** Use `<CurrencyDisplay autoScale maxFontSize={48} />` for currency values — no manual sizing needed.
-
----
-
-## Hover Support (Web)
-
-```tsx
-import { useHover } from '@retray-dev/ui-kit'
-
-function MyHoverableComponent() {
-  const { hovered, hoverHandlers } = useHover()
-
-  return (
-    <View
-      {...hoverHandlers}
-      style={[
-        styles.container,
-        hovered && { backgroundColor: colors.surfaceStrong }
-      ]}
-    />
-  )
-}
-```
-
-- **Web:** Returns `{ hovered: boolean, hoverHandlers: { onMouseEnter, onMouseLeave } }`
-- **Native:** Always returns `{ hovered: false, hoverHandlers: {} }` — no-op, no crashes
-
-Built-in web hover: `MediaCard` (shadow lift), interactive components use this internally.
-
----
-
-## Design System Conventions
-
-### Touch targets
-All interactive elements maintain ≥44pt touch height per Apple HIG:
-- Button md: 48px, sm: 40px, lg: 56px
-- Input / Textarea: 56px (14px vertical padding)
-- IconButton md: 44px, lg: 52px
-- Checkbox: 24×24px box
-- Switch: 30px track height
-- MonthPicker arrows: 44×44px
-
-### Haptic patterns
-- `impactLight` — Button, Card (press), Sheet open, Toast, MediaCard action
-- `selectionAsync` — Checkbox, Switch, Toggle, RadioGroup, Select, Slider steps, Accordion, ListItem, Chip, CategoryStrip, Tabs, MonthPicker
-- `notificationSuccess` — Toast `success`
-- `notificationError` — Toast `destructive`, Toast `warning`
-
-### Animation press scales
-- `Button` → 0.95 (strong spring feedback)
-- `Card` → 0.98 (subtle, appropriate for large surfaces)
-- `ListItem` → 0.97 (between — medium row targets)
-- `MediaCard` → 0.98 (large surface)
-- `IconButton` → 0.95
-- `Chip`, `CategoryStrip chip` → 0.95
-
-### Platform differences
-- `useNativeDriver` — `Platform.OS !== 'web'` everywhere (native driver disabled on web)
-- `Select` — wheel modal on iOS, dialog on Android, `<select>` on web
-- `Toast` — full width on mobile, 400px centered on web
-- Hover states — web only via `useHover()`
-- `Skeleton` shimmer highlight — adapts opacity for light/dark mode
-
-### Dynamic Type
-All `Text` and `TextInput` components have `allowFontScaling={true}` — respects user font size accessibility settings.
-
-### Scaling utilities (internal)
-Used internally — not exported. `s()` horizontal scale, `vs()` vertical scale, `ms()` moderate scale relative to 350×680 base.
-
----
-
-## Full Composition Examples
-
-The package includes **EXAMPLES.md** with complete, working code for 4 real-world app screens:
-
-1. **Finance Dashboard** — MonthPicker, CurrencyDisplay, Progress, CategoryStrip, ListItem, DetailRow
-2. **Edit Profile** — Avatar, Badge, Input, Select, Switch, Card, AlertBanner
-3. **Onboarding Flow** — Badge, Progress, Input, RadioGroup, EmptyState (multi-step wizard)
-4. **Settings Screen** — MenuGroup, ListGroup, Form, MenuItem, ListItem, compound component patterns
-
-**For AI agents:** Import EXAMPLES.md from the package for full source code and patterns:
-
-```markdown
-## UI Kit Composition Examples
-@./node_modules/@retray-dev/ui-kit/EXAMPLES.md
-```
-
-Each example includes:
-- Complete component code (copy-paste ready)
-- State management setup
-- Proper imports and theme usage
-- Common patterns (spacing, colors, navigation, toast feedback)
-- StyleSheet definitions
-
-**For human developers:** Examples are also live in the `example/` app. Clone the repo, run `pnpm install && pnpm build`, then `cd example && pnpm start` to see them in action.