@retray-dev/ui-kit 13.0.0 → 13.4.0

package/{COMPONENTS.md → SKILL.md}

@@ -1,836 +1,559 @@
-# @retray-dev/ui-kit — Component Reference (v13.0.0)
+---
+name: retray-ui-kit
+description: >
+  Complete guide for @retray-dev/ui-kit — a React Native / Expo component
+  library (~57 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
-  }
-}
-```
-
-| 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` |
-
-| `@shopify/react-native-skia` + `expo-sensors` | **Optional** | Deep-import `HolographicCard` only | `pnpm add @shopify/react-native-skia expo-sensors` |
-
-
-
-### 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])
+plugins: ['react-native-worklets/plugin']
+// NOT react-native-reanimated/plugin
 ```
 
----
-
-## 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:**
+| `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
-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>
+import { withAlpha } from '@retray-dev/ui-kit'
+// hex → rgba: withAlpha('#1a1a1a', 0.15) → 'rgba(26,26,26,0.15)'
 ```
 
-### deriveColors export
-
-```tsx
-import { deriveColors } from '@retray-dev/ui-kit'
-
-const resolved = deriveColors(myThemeColors, 'light')
-// resolved contains all 26 ResolvedColors tokens
-```
+### 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.
 
 ---
 
-### 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>
-```
-
----
-
-## 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.12 | 12 | 8 | Modals |
+| `xl` | 0.18 | 24 | 16 | High-elevation |
 
-### BREAKPOINTS
+**BREAKPOINTS**
 
 | Key | Value | Use |
 |-----|-------|-----|
 | `wide` | 700 | Tablet / wide layout threshold |
 
-```tsx
-const isWide = useWindowDimensions().width >= BREAKPOINTS.wide
-```
-
-### TYPOGRAPHY — 16 Airbnb-aligned variants
-
-All components use these tokens for text styling. Import and use in custom components for consistency.
+**TYPOGRAPHY — 17 variants**
 
-| 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,
-  },
-})
-```
+| `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: 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` |
+## Icons
 
----
+### Icon Component
+```tsx
+import { Icon } from '@retray-dev/ui-kit'
+<Icon name="home" size={24} color="#000" />
+// Returns null if name not found — no crash
+```
 
-## Migration Guide: v5 → v6
+### Resolution Order (first-match wins)
+Feather > AntDesign > Entypo > FontAwesome5 > MaterialIcons > Ionicons
 
-### New Components
+**Feather is first** — most names resolve there (outlined style). Names with `-outline` suffix resolve to Ionicons (no Feather collision).
 
-**`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.
+### `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 introspects `glyphMap` per call — no caching between renders.
 
+### `getResponsiveFontSize` utility
 ```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 { getResponsiveFontSize } from '@retray-dev/ui-kit'
+const fontSize = getResponsiveFontSize(text, 48)
+// Steps: ≤10→max, ≤12→max-4, ≤14→max-6, >14→max-8
 ```
 
-### Breaking Changes
+---
 
-**Sheet keyboard defaults changed:**
-| Prop | v5 default | v6 default |
-|------|-----------|-----------|
-| `keyboardBehavior` | `'fillParent'` (Android) / `'interactive'` (iOS) | `'interactive'` (both) |
-| `android_keyboardInputMode` | `'adjustResize'` | `'adjustPan'` |
+## Animations & Interactions
 
-If you relied on `adjustResize`, set it explicitly: `android_keyboardInputMode="adjustResize"`.
+### 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 |
 
-**Toast API simplified:**
+All use `enabled={!disabled}`, `rippleColor="transparent"`, `touchSoundDisabled`.
 
-```tsx
-// v5 — hook-only API
-const { toast } = useToast()
-toast.success('Done')
+### Spring Presets
+- `glide`: `{ stiffness: 380, damping: 38, mass: 1.0 }` — sliding indicators
+- `elastic`: `{ stiffness: 320, damping: 22, mass: 0.7 }` — Switch thumb, RadioGroup dot
 
-// v6 — direct import preferred (hook still works for compat)
-import { toast } from '@retray-dev/ui-kit'
-toast.success('Done')
-```
+### Timing Presets
+- `state`: 160ms (checkbox/toggle color)
+- `expand` / `collapse`: 240ms / 200ms (Accordion)
+- `shimmer`: 1400ms (Skeleton)
 
-### New Theme Tokens
+### EaseView (react-native-ease)
+Declarative color/opacity transitions: Switch track, Checkbox fill, RadioGroup dot. UI thread.
 
-Three optional `ThemeColors` tokens — fall back gracefully if omitted:
+### Reanimated v4
+Complex animations only (gestures, layout interpolations). Simple opacity: use RN `Animated` + `useNativeDriver`.
 
-| 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`.
+## Sheets (BottomSheetModal)
 
-### Token Corrections
+### 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`
 
-- `TYPOGRAPHY['uppercase-tag']` — size corrected to `10` (was documented as `8`, actual value was always `10`)
+### Input inside Sheet
+Use `<Input sheetMode />` — transparently swaps to `BottomSheetTextInput`. For low-level: `SheetTextInput`.
 
 ---
 
-## Migration Guide: v6 → v7
-
-### Breaking Changes
+## Haptics (expo-haptics)
 
-**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.
+Web-safe via static `import * as Haptics` with `Platform.OS === 'web'` guard at call sites.
 
-**Typography scale corrected:**
+| 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 |
 
-| Token | v6 | v7 | Reason |
-|-------|----|----|--------|
-| `display-lg` | 22px / 500 | 24px / 600 | Removed weight inversion vs display-md |
-| `display-md` | 21px / 700 | 20px / 600 | 4px gap preserved; weight normalised |
-| `title-md` | 16px / 600 | 17px / 600 | Now visibly distinct from title-sm |
-| `title-sm` | 16px / 500 | 15px / 500 | Was same px as title-md |
-| `uppercase-tag` | 10px / 0.8 letterSpacing | 11px / 0.6 | Below Apple HIG 11pt minimum |
-| `badge-text-md` | (missing) | 13px / 600 | New canonical token for Badge md |
-
-**Default color values changed (WCAG AA fixes):**
-
-| Token | v6 | v7 | WCAG impact |
-|-------|----|----|-------------|
-| `foregroundMuted` opacity | 0.38 (~#ababab) | 0.62 (~#767676) | 2.2:1 ❌ → 4.5:1 ✓ |
-| `foregroundSubtle` opacity | 0.55 (~#858585) | 0.70 (~#646464) | 3.5:1 ❌ → 5.9:1 ✓ |
-| `warning` (light) | `#e67e00` | `#9a5200` | 2.86:1 ❌ → 5.86:1 ✓ |
-| `warningForeground` (dark) | `#ffffff` | `#0f0f0f` | Dark text on amber, 8.6:1 ✓ |
-| `destructive` (light) | `#e53935` | `#c72828` | 4.22:1 ❌ → 5.59:1 ✓ |
-| `accent` (light) | `= primary` | `#d4561d` | Explicit brand accent |
-| `accent` (dark) | `= primary` | `#e87645` | Warm accent for dark surfaces |
+---
 
-**Component visual behavior changes:**
+## Theming
 
-| 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 |
+### Consumer supplies 12 ThemeColors
+```tsx
+import { ThemeProvider, ThemeColors } from '@retray-dev/ui-kit'
 
-**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.
+const customLight: ThemeColors = {
+  background: '#ffffff',
+  foreground: '#1a1a1a',
+  primary: '#d4561d',
+}
+```
 
-### New Compound Component Section
+### deriveColors()
+Computes 26 `ResolvedColors` from 12 `ThemeColors`. Components consume `useTheme().colors` — never raw `ThemeColors`.
 
-The example app now has a dedicated **Compound Components** section showcasing `Card`, `ButtonGroup`, `Form`, `ListGroup`, and `MenuGroup` with all sub-components and variants.
+### Structural tokens (not in theme)
+Spacing, radii, shadows, typography = static `as const` exports from `tokens.ts`. No provider needed.
 
 ---
 
-## Migration Guide: v7 → v8
+## Toast (sonner-native)
 
-### Breaking Changes
+```tsx
+import { toast } from 'sonner-native'
+// or
+import { useToast } from '@retray-dev/ui-kit'
+const { toast } = useToast()
 
-**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
+toast('Hello', { description: 'World' })
+toast.success('Saved')
+toast.error('Failed', { description: 'Check network' })
+toast.promise(save(), { loading: 'Saving...', success: 'Done', error: 'Failed' })
 ```
-(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`.
+`Toaster` rendered inside `ToastProvider`. Config: `richColors: false`, `swipeToDismissDirection="up"`, `duration: 4000`.
 
-**3. `./fonts` stays at `src/fonts.ts` (unchanged)**
-The `./fonts` export deliberately points at `src/fonts.ts`, not `dist`. The `.otf` files ship as raw assets in `src/assets/fonts/` and are resolved by Metro at your build time via `require()`. Compiling this entry to `dist` and repointing the `require()` paths breaks Metro asset resolution under pnpm symlinked workspaces (`requiring unknown module ../src/assets/fonts/...`), so it is intentionally left as source. No API change — import as before:
-```ts
-import { SohneFonts } from '@retray-dev/ui-kit/fonts'
-```
+---
 
-### New — packaging & DX
+## Data Display Patterns
 
-- **`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.
+### ListItem
+- `rightActions` prop for swipe-to-reveal (iOS Mail style)
+- Uses `PressableRow` (scale 0.97)
+- Haptic: `selectionAsync()` on press
+- Zero horizontal padding by design
 
-### New components
+### ListGroup
+- Optional `Header` / `Footer` sub-components
+- Auto-separators between items except last
 
-`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.
+### MenuItem / MenuGroup
+- Settings/nav rows. Auto-separators.
+- `rightRender` for Switch, Badge, etc.
+- `variant="card"` for standalone surface
 
-### Optional peers (only if you use the matching component)
+### Chip / ChipGroup
+- Multi-select toggle chips. `PressableChip` (scale 0.94)
+- `ChipGroup` wraps to rows; `CategoryStrip` scrolls horizontally
 
-- `@shopify/react-native-skia` + `expo-sensors` → `HolographicCard` (deep-import only, not in the main barrel).
+### LabelValue
+- Key-value rows (label left, value right)
+- Icon support
 
----
+### DetailRow
+- Ticket/receipt rows with `···` dotted separator
+- Icon + label + value
 
-## 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'),
-+}
+### Skeleton
+- `Skeleton.MediaCard`, `Skeleton.ListItem`, `Skeleton.List` (6 items, 2 columns)
+- Shimmer animation loops every 1200ms
 
-export default function App() {
-  const [fontsLoaded] = useFonts(SohneFonts)
-  // ...
-}
-```
+---
 
-**.gitignore recommendation:**
-```gitignore
-# Sohne fonts — copied by @retray-dev/ui-kit postinstall
-assets/fonts/sohne/
-```
+## Accessibility (WCAG AA)
 
-**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.
+- `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`
 
 ---
 
-## 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.
+## Deep Import Pattern
 
+Prefer deep imports in production for smaller bundle:
 ```tsx
-import { useTheme, withAlpha } from '@retray-dev/ui-kit'
-
-const { colors } = useTheme()
-<View style={{ backgroundColor: withAlpha(colors.primary, 0.15) }} />
+import { Button } from '@retray-dev/ui-kit/Button'  // deep
+// vs
+import { Button } from '@retray-dev/ui-kit'           // barrel
 ```
 
-### 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.
+Deep-import only (NOT in barrel):
+```tsx
+import { HolographicCard } from '@retray-dev/ui-kit/HolographicCard'
+```
 
 ---
 
-## Migration Guide: v11 → v12
-
-### Breaking Changes
+## Anti-Patterns
 
-`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.
+| 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 |
 
-**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.
+### Image
 
-```diff
- <Sheet
-   open={open}
-   onClose={() => setOpen(false)}
-   title="Options"
--  responsive
--  dialogMaxWidth={600}
- />
-```
+**Import:** `import { Image } from '@retray-dev/ui-kit'`
 
-**2. `onClose` is the only close handler**
+**When to use:** Image display with automatic fallback when source is null or fails to load. Wraps `expo-image` for performant caching and cross-fade transitions. Supports aspect ratio containers.
 
-`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.
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| src | `string \| null` | — | Image URI. `null` or load failure shows fallback/skeleton |
+| fallback | `ReactNode` | — | Custom fallback when src is null or image fails |
+| aspectRatio | `number` | — | Width/height ratio — sets container proportionally (e.g. `16/9`, `4/3`) |
+| borderRadius | `number` | `0` | Corner radius on the image |
+| style | `ImageStyle` | — | — |
 
-**3. `Sheet` requires `BottomSheetModalProvider` at app root**
+All remaining `expo-image` props (`contentFit`, `transition`, `placeholder`, etc.) pipe through.
 
-`RetrayProvider` already wires it. If you assemble providers manually, ensure `BottomSheetModalProvider` sits inside `GestureHandlerRootView`:
+**Fallback behavior:** When `src` is null/falsy or the image errors on load:
+- If `fallback` is provided: renders fallback node inside a container
+- Otherwise: renders a `skeleton`-colored placeholder matching the image dimensions
 
+**Examples:**
 ```tsx
-<SafeAreaProvider initialMetrics={initialWindowMetrics}>
-  <GestureHandlerRootView style={{ flex: 1 }}>
-    <ThemeProvider>
-      <BottomSheetModalProvider>
-        <ToastProvider>{/* app */}</ToastProvider>
-      </BottomSheetModalProvider>
-    </ThemeProvider>
-  </GestureHandlerRootView>
-</SafeAreaProvider>
+<Image src="https://example.com/photo.jpg" aspectRatio={4/3} borderRadius={12} />
+<Image src={null} fallback={<Icon name="image" size={32} color={colors.foregroundMuted} />} />
+<Image src={avatar} borderRadius={40} style={{ width: 80, height: 80 }} />
+<Image src={banner} aspectRatio={16/9} contentFit="cover" transition={500} />
 ```
 
-**4. Keyboard prop renames (no consumer action — defaults match v11)**
-
-| Prop | v11 | v12 default |
-|------|-----|-------------|
-| `keyboardBehavior` | `'interactive'` | `'interactive'` (unchanged) |
-| `android_keyboardInputMode` | `'adjustPan'` | `'adjustPan'` (unchanged) |
-
-**5. Removed top-level imports of `Modal`, `ScrollView`, `useWindowDimensions`, `BREAKPOINTS` from `Sheet.tsx`**
-
-Internal only — no public API.
+---
 
-### Behavioral changes (no code change required)
+### ScreenContainer
 
-- **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).
+**Import:** `import { ScreenContainer } from '@retray-dev/ui-kit'`
 
-### New — recommended pattern
+**When to use:** Consistent screen-level layout wrapper. Sets background color, safe area padding, optional scroll, keyboard avoidance, and centers content with a max-width constraint for wide screens.
 
-**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").
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | Screen content |
+| maxWidth | `number` | `700` (BREAKPOINTS.wide) | Max content width. Set to `0` to disable centering |
+| scroll | `boolean` | `false` | Wrap content in ScrollView |
+| backgroundColor | `string` | Theme `background` | Override background color |
+| paddingTop | `number` | Safe area top | Override top padding |
+| paddingBottom | `number` | Safe area bottom | Override bottom padding |
+| paddingHorizontal | `number` | `0` | Horizontal padding |
+| keyboard | `boolean` | `false` | Enable KeyboardAvoidingView (iOS: padding behavior) |
+| style | `ViewStyle` | — | Additional container styles |
+
+**Behavior:** Wraps children in a centered View (maxWidth with `alignSelf: 'center'`). When `keyboard={true}`, wraps in `KeyboardAvoidingView`. When `scroll={true}`, wraps in `ScrollView` with `keyboardShouldPersistTaps="handled"`.
 
+**Examples:**
 ```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>
+// Basic screen
+<ScreenContainer>
+  <Text variant="display-xl">Home</Text>
+  {/* screen content */}
+</ScreenContainer>
+
+// Scrollable with keyboard avoidance
+<ScreenContainer scroll keyboard paddingHorizontal={16}>
+  <Input label="Name" />
+  <Input label="Email" />
+  <Button label="Submit" fullWidth />
+</ScreenContainer>
+
+// Wide desktop constraint
+<ScreenContainer maxWidth={700} paddingHorizontal={16}>
+  <Text variant="display-lg">Dashboard</Text>
+</ScreenContainer>
 ```
 
-`SheetTextInput` is still re-exported for low-level use.
-
 ---
 
-## Migration Guide: v12.0 → v12.1
+### VirtualizedList
 
-### New — IconPicker feedback pattern (REGLA 4)
+**Import:** `import { VirtualizedList } from '@retray-dev/ui-kit'`
 
-`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.
+**When to use:** Performant sectioned lists with sticky headers, pull-to-refresh, and empty state. Built on React Native `SectionList` for memory-efficient rendering of large datasets.
 
-This is now the canonical pattern for any sheet whose content needs to measure or load before rendering — apply it to new overlay components.
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| sections | `VirtualizedListSection<T>[]` | required | `{ title?: string, data: T[] }` — sections with optional headers |
+| renderItem | `(info: SectionListRenderItemInfo<T>) => ReactElement` | required | Row renderer for each item |
+| emptyTitle | `string` | `'Sin contenido'` | Title shown when no data |
+| emptyDescription | `string` | — | Description below empty title |
+| emptyComponent | `ReactNode` | — | Custom empty state (overrides emptyTitle/emptyDescription) |
+| refreshing | `boolean` | `false` | Pull-to-refresh loading state |
+| onRefresh | `() => void` | — | Pull-to-refresh handler |
+| stickyHeaders | `boolean` | `true` | Section headers stick to top while scrolling |
+| headerColor | `string` | `foregroundMuted` | Section header text color override |
+| style | `ViewStyle` | — | List container style |
 
-### New — race-condition fix in `Sheet` and `ConfirmDialog`
+Also accepts all `SectionListProps` (e.g. `ListHeaderComponent`, `ListFooterComponent`, `ItemSeparatorComponent`).
 
-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.
+**Section headers:** Uppercase 13pt SemiBold text. Sections with empty `data` arrays are filtered out automatically.
 
-No consumer action required — the fix is internal.
+**Empty state:** When all sections have empty data, shows centered emptyTitle/emptyDescription or custom emptyComponent.
 
-### New — expanded curated icon library
+**Examples:**
+```tsx
+// Simple sectioned list
+<VirtualizedList
+  sections={[
+    { title: 'Fruits', data: ['Apple', 'Banana', 'Cherry'] },
+    { title: 'Vegetables', data: ['Carrot', 'Broccoli'] },
+  ]}
+  renderItem={({ item }) => <ListItem title={item} showSeparator />}
+/>
+
+// With pull-to-refresh
+<VirtualizedList
+  sections={data}
+  renderItem={renderRow}
+  refreshing={loading}
+  onRefresh={handleRefresh}
+/>
 
-`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).
+// Custom empty state
+<VirtualizedList
+  sections={[]}
+  renderItem={() => null}
+  emptyTitle="No items found"
+  emptyDescription="Try adjusting your filters"
+/>
+```
+
+---
 
-### Updated
+## Version
 
-- `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.
+**Current: 13.4.0.** Requires Expo SDK 54+, React Native 0.81+, React 19.
+
+For full setup guide, see `CONSUMER.md`. For usage examples, see `EXAMPLES.md`.
 
 ---
 
-## Components
+## Component Reference
 
 ---
 
@@ -857,18 +580,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) |
 
@@ -1835,9 +1559,10 @@ const [guests, setGuests] = useState(2)
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | orientation | `'horizontal' \| 'vertical'` | `'horizontal'` | Direction of the line |
+| label | `string` | — | Label shown in center of horizontal separator — renders as `── label ──` |
 | style | `ViewStyle` | — | — |
 
-**Styling:** 1px thickness, `border` token color.
+**Styling:** 1px thickness, `border` token color. When `label` is provided, uses uppercase medium text with letter-spacing.
 
 **Examples:**
 ```tsx
@@ -1851,6 +1576,9 @@ const [guests, setGuests] = useState(2)
   <Text>Right</Text>
 </View>
 
+// With label
+<Separator label="o" />
+
 // With custom spacing
 <Separator style={{ marginVertical: SPACING.lg }} />
 ```
@@ -2501,15 +2229,21 @@ const [accepted, setAccepted] = useState(false)
 | tabs | `TabItem[]` | required | Tab definitions |
 | variant | `'pill' \| 'underline'` | `'pill'` | Visual style |
 | value | `string` | — | Controlled active tab |
-| onValueChange | `(value: string) => void` | — | — |
+| onValueChange | `(value: T) => void` | — | Generic — infers from `value` prop type |
 | children | `ReactNode` | — | `TabsContent` components |
 | style | `ViewStyle` | — | — |
 
 **TabItem type:**
 ```ts
-{ label: string; value: string; icon?: ReactNode | ((isActive: boolean) => ReactNode) }
+interface TabItem<T extends string = string> {
+  label: string
+  value: T
+  icon?: ReactNode | ((isActive: boolean) => ReactNode)
+}
 ```
 
+The generic `T` propagates from `TabItem<T>` through `onValueChange(value: T)`, so callbacks receive the correct union type without manual casting.
+
 **Variants:**
 - `pill` — Animated background pill slides to active tab. Full-width distributed tabs. Active: filled `primary` + `primaryForeground` text. Default for top-of-screen navigation.
 - `underline` — 2px bottom border on active tab, no background. Tabs don't stretch — natural width. Airbnb-style filter tabs.
@@ -3847,7 +3581,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 |
@@ -3862,6 +3597,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()}
+/>
 ```
 
 ---
@@ -4135,17 +3877,23 @@ export default function TabLayout() {
 | title | `string` | `'Something went wrong'` | Default fallback title |
 | message | `string` | `error.message` | Default fallback body |
 | onError | `(error, info) => void` | — | Wire your crash reporter here |
+| onCatch | `(error, componentStack) => void` | — | Simplified callback — just error + stack string |
 
 **Default fallback:** centered themed card with a destructive icon, title, message, and a "Try again" button that calls `reset()`.
 
-**Example:**
+**Examples:**
 ```tsx
 <ErrorBoundary onError={reportCrash}>
   <DocumentViewer />
 </ErrorBoundary>
 
-// Custom fallback
-<ErrorBoundary fallback={({ error, reset }) => <MyFallback error={error} onRetry={reset} />}>
+// Use componentStack in custom fallback
+<ErrorBoundary fallback={({ error, componentStack, reset }) => <MyFallback error={error} stack={componentStack} onRetry={reset} />}>
+  <RiskyScreen />
+</ErrorBoundary>
+
+// Simplified crash reporter
+<ErrorBoundary onCatch={(error, stack) => logCrash(error, stack)}>
   <RiskyScreen />
 </ErrorBoundary>
 ```
@@ -4309,7 +4057,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 |
 |------|------|---------|-------|
@@ -4323,9 +4071,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
@@ -4465,171 +4213,123 @@ const { visible, loading, open, onConfirm, onCancel } = useConfirmDialog({
 
 ---
 
-## Icon System
+### Image
 
-The library ships a built-in icon resolver — pass any icon name string to components without manual imports.
+**Import:** `import { Image } from '@retray-dev/ui-kit'`
 
-### Supported families (priority order — first match wins)
+**When to use:** Display images with automatic fallback on load failure. Wraps `expo-image` for performant loading and caching.
 
-| Priority | Family | Best for |
-|---|---|---|
-| 1 | `Feather` | Clean line icons, UI essentials (first match wins) |
-| 2 | `AntDesign` | Semantic UI icons |
-| 3 | `Entypo` | Social, media, navigation icons |
-| 4 | `FontAwesome5` | Wide coverage |
-| 5 | `MaterialIcons` | Material-style icons |
-| 6 | `Ionicons` | Fallback |
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| src | `string \| null` | — | Image URI. `null` or failed load shows fallback |
+| fallback | `ReactNode` | — | Custom fallback content when image fails to load |
+| aspectRatio | `number` | — | Width/height ratio — e.g. `16/9`, `4/3`. Sets container height proportionally |
+| borderRadius | `number` | `0` | Border radius override |
 
-Browse all available icons: **https://icons.expo.fyi**
+**All other `expo-image` props pass through** (except `source` — use `src` instead).
 
-### Standalone `Icon` component
+**Behavior:** On load error or `null` src: if `fallback` node provided, renders it inside container; otherwise renders a skeleton-colored placeholder with `accessibilityLabel="Imagen no disponible"`.
 
+**Examples:**
 ```tsx
-import { Icon } from '@retray-dev/ui-kit'
+// Basic
+<Image src="https://example.com/photo.jpg" aspectRatio={16/9} />
 
-<Icon name="home" size={24} color={colors.foreground} />
-<Icon name="star" size={20} color={colors.primary} />
+// With fallback
+<Image src={user.avatar} fallback={<Avatar fallbackText={user.name} />} />
 
-// Force a specific family when same name exists in multiple families:
-<Icon name="heart" size={24} color="red" family="FontAwesome5" />
+// Rounded
+<Image src={photo.uri} borderRadius={12} aspectRatio={4/3} />
 ```
 
-**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.
-
-> **v13:** `renderIcon`, `getValidIconNames`, and `configureIconFamilies` were removed. Use `Icon` component directly for all icon rendering.
-
-### `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'
+### ScreenContainer
 
-// Default steps: ≤10 chars → max, ≤12 → max-4, ≤14 → max-6, >14 → max-8
-const fontSize = getResponsiveFontSize(formatCOP(amount), 48)
+**Import:** `import { ScreenContainer } from '@retray-dev/ui-kit'`
 
-<Text style={{ fontSize }} numberOfLines={1} adjustsFontSizeToFit>
-  {formatCOP(amount)}
-</Text>
-```
+**When to use:** Consistent screen layout with safe area insets, optional scroll, keyboard avoidance, and responsive max-width centering.
 
-**Signature:**
-```ts
-getResponsiveFontSize(
-  text: string,
-  maxSize: number,
-  steps?: { maxLen: number; subtract: number }[]
-): number
-```
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | Screen content |
+| maxWidth | `number` | `700` | Max content width (points). `0` disables |
+| scroll | `boolean` | `false` | Enable scroll view |
+| backgroundColor | `string` | theme `background` | — |
+| paddingTop | `number` | safe area top | Override top padding |
+| paddingBottom | `number` | safe area bottom | Override bottom padding |
+| paddingHorizontal | `number` | `0` | Horizontal padding |
+| keyboard | `boolean` | `false` | Enable `KeyboardAvoidingView` (iOS `padding` behavior) |
+| style | `ViewStyle` | — | Additional wrapper style |
+
+**Behavior:** Applies top/bottom safe area insets, centers content horizontally when screen exceeds `maxWidth`. When `keyboard` is enabled, wraps content in `KeyboardAvoidingView` with iOS `padding` behavior.
 
-Custom steps example:
+**Examples:**
 ```tsx
-getResponsiveFontSize(text, 48, [
-  { maxLen: 8,  subtract: 0 },
-  { maxLen: 11, subtract: 6 },
-  { maxLen: 14, subtract: 10 },
-])
+// Basic scroll screen
+<ScreenContainer scroll paddingHorizontal={16}>
+  <Text variant="title-md">Welcome</Text>
+</ScreenContainer>
+
+// With keyboard avoidance for forms
+<ScreenContainer keyboard paddingHorizontal={16}>
+  <Input label="Name" />
+  <Input label="Email" />
+  <Button label="Submit" />
+</ScreenContainer>
+
+// Non-scroll, max width disabled
+<ScreenContainer maxWidth={0}>
+  <FullWidthContent />
+</ScreenContainer>
 ```
 
-**Alternative:** Use `<CurrencyDisplay autoScale maxFontSize={48} />` for currency values — no manual sizing needed.
-
 ---
 
-## 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
-- `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.
+### VirtualizedList
 
----
+**Import:** `import { VirtualizedList } from '@retray-dev/ui-kit'`
 
-## Full Composition Examples
+**When to use:** Sectioned lists with sticky headers, empty state, and pull-to-refresh. Wraps React Native `SectionList` with Spanish defaults.
 
-The package includes **EXAMPLES.md** with complete, working code for 4 real-world app screens:
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| sections | `VirtualizedListSection<T>[]` | required | `{ title?: string; data: T[] }` — only non-empty sections render |
+| renderItem | `(info) => ReactElement` | required | Standard `SectionList` render function |
+| emptyTitle | `string` | `'Sin contenido'` | Title shown when no data |
+| emptyDescription | `string` | — | Description below title |
+| emptyComponent | `ReactNode` | — | Custom empty state (overrides titles) |
+| refreshing | `boolean` | `false` | Pull-to-refresh state |
+| onRefresh | `() => void` | — | Refresh handler |
+| stickyHeaders | `boolean` | `true` | Enable sticky section headers |
+| headerColor | `string` | `foregroundMuted` | Section header text color |
 
-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
+**All other `SectionList` props pass through** (except `sections`, `renderItem`, `ListEmptyComponent`).
 
-**For AI agents:** Import EXAMPLES.md from the package for full source code and patterns:
+**Behavior:** Sections with empty `data` arrays are filtered out. When no sections have data, renders the empty state (custom component or default title). Sticky headers render section titles in uppercase with `Sohne-SemiBold`.
+
+**Examples:**
+```tsx
+const sections = [
+  { title: 'Hoy', data: todayItems },
+  { title: 'Ayer', data: yesterdayItems },
+]
+
+<VirtualizedList
+  sections={sections}
+  renderItem={({ item }) => <ListItem title={item.name} />}
+  refreshing={refreshing}
+  onRefresh={handleRefresh}
+/>
 
-```markdown
-## UI Kit Composition Examples
-@./node_modules/@retray-dev/ui-kit/EXAMPLES.md
+// With custom empty state
+<VirtualizedList
+  sections={[]}
+  renderItem={() => null}
+  emptyTitle="No hay transacciones"
+  emptyDescription="Tus transacciones aparecerán aquí"
+/>
 ```
 
-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.