@retray-dev/ui-kit 4.0.0 → 5.2.0

package/COMPONENTS.md

@@ -1,4 +1,4 @@
-# @retray-dev/ui-kit — Component Reference (v4.0.0)
+# @retray-dev/ui-kit — Component Reference (v5.2.0)
 
 This file is the AI reference for this package. It is shipped inside the npm package so consuming projects can import it into their `CLAUDE.md` with:
 
@@ -44,7 +44,7 @@ export default function App() {
 
 ## Typography — Poppins (Required)
 
-All components use **Poppins** as the font family. You **must** load it before rendering any UI kit component, otherwise text will fall back to the system font.
+All components use **Poppins** as the font family. You **must** load it before rendering any UI kit component.
 
 ```tsx
 import { useFonts } from 'expo-font'
@@ -52,8 +52,7 @@ import { PoppinsFonts } from '@retray-dev/ui-kit/fonts'
 
 export default function App() {
   const [fontsLoaded] = useFonts(PoppinsFonts)
-  if (!fontsLoaded) return null   // or show a splash screen
-
+  if (!fontsLoaded) return null
   return (
     // ... your providers and app
   )
@@ -66,49 +65,44 @@ export default function App() {
 3. Metro resolves font files from `node_modules/@retray-dev/ui-kit/src/assets/fonts/` at bundle time
 4. All library components reference fonts by family name (e.g., `fontFamily: 'Poppins-SemiBold'`)
 
-**Why this pattern:**
-- Fonts are NOT bundled into `dist/` — they ship as raw `.ttf` files inside `src/assets/fonts/`
-- Metro resolves `require()` calls to these files when it bundles your app
-- This prevents font corruption that can occur when `.ttf` files pass through bundlers like esbuild/tsup
-
-**Setup:**
-- Add `expo-font` to your app: `pnpm add expo-font`
-- The `if (!fontsLoaded) return null` guard prevents text from rendering before fonts are ready
-- Pair with `expo-splash-screen` in production to avoid a flash:
-  ```tsx
-  import * as SplashScreen from 'expo-splash-screen'
-  SplashScreen.preventAutoHideAsync()
-  
-  useEffect(() => {
-    if (fontsLoaded) SplashScreen.hideAsync()
-  }, [fontsLoaded])
-  ```
-
 **Included weights:**
 - Regular: `Poppins-Thin`, `Poppins-ExtraLight`, `Poppins-Light`, `Poppins-Regular`, `Poppins-Medium`, `Poppins-SemiBold`, `Poppins-Bold`, `Poppins-ExtraBold`, `Poppins-Black`
 - Italic: `Poppins-Italic`, `Poppins-MediumItalic`, `Poppins-SemiBoldItalic`, `Poppins-BoldItalic`
 
-**Total: 13 font files** exported from the package. Additional italic variants exist in `src/assets/fonts/` but are not exported — if you need them, open an issue.
+**Total: 13 font files** exported from the package. Font `.ttf` files ship as raw assets in `src/assets/fonts/` — NOT bundled into `dist/`. Metro resolves `require()` calls at build time.
+
+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 the device setting and updates when it changes |
-| theme | `{ light?: Partial<ThemeColors>, dark?: Partial<ThemeColors> }` | — | Override any subset of color tokens per scheme |
+| 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: '#6366f1', primaryForeground: '#ffffff' },
-  dark:  { primary: '#818cf8', primaryForeground: '#ffffff' },
+  light: { primary: '#ff385c', primaryForeground: '#ffffff' },
+  dark:  { primary: '#ff385c', primaryForeground: '#ffffff' },
 }
 <ThemeProvider theme={myTheme} colorScheme="system">
 ```
 
 ### useTheme Hook
 
-Access the active color tokens and scheme inside any component:
 ```tsx
 import { useTheme } from '@retray-dev/ui-kit'
 
@@ -118,138 +112,238 @@ function MyComponent() {
 }
 ```
 
+Returns `colors` (full `ResolvedColors` palette) and `colorScheme` (`'light' | 'dark'`).
+
 ---
 
 ## Theme Tokens
 
-All 23 tokens are available via `useTheme().colors` and are applied exactly as provided — there is no automatic color derivation or forced contrast applied by the library. Consumers may pass partial overrides for `light` and/or `dark` and the values are used as-is.
+### Public Tokens (ThemeColors) — 12 tokens consumer can override
 
-The `ThemeColors` type (and `Theme`, `ColorScheme`) are exported directly from the package:
-```ts
-import type { ThemeColors } from '@retray-dev/ui-kit'
-```
+These are the only values you need to supply when customizing the theme. The library derives all other colors internally.
 
-| Token | Light | Dark | Semantic Role |
-|-------|-------|------|---------------|
+| Token | Light Default | Dark Default | Semantic Role |
+|-------|--------------|--------------|---------------|
 | `background` | `#ffffff` | `#0f0f0f` | Screen / page background |
-| `foreground` | `#171717` | `#fafafa` | Primary text color |
-| `card` | `#ffffff` | `#1c1c1c` | Card / surface background |
-| `cardForeground` | `#171717` | `#fafafa` | Text on cards |
-| `primary` | `#1a1a1a` | `#fafafa` | Primary action (buttons, selected states) |
-| `primaryForeground` | `#ffffff` | `#0f0f0f` | Text/icon on primary background |
-| `secondary` | `#f1f1f1` | `#272727` | Secondary surfaces |
-| `secondaryForeground` | `#171717` | `#fafafa` | Text on secondary |
-| `muted` | `#f1f1f1` | `#272727` | Muted backgrounds, skeleton fills, track fills |
-| `mutedForeground` | `#a2a2a2` | `#9a9a9a` | Placeholder text, helper text, captions |
-| `accent` | `#e4e4e4` | `#2e2e2e` | Hover / pressed state fills |
-| `accentForeground` | `#171717` | `#fafafa` | Text on accent |
-| `destructive` | `#ef4444` | `#dc2626` | Error / danger / delete actions — base color |
-| `destructiveForeground` | `#ffffff` | `#ffffff` | Text on destructive |
-| `destructiveTint` | `#fff5f5` | `#3b0a0a` | Very light/dark background tint for destructive states |
-| `destructiveBorder` | `#fecaca` | `#7f1d1d` | Border color for destructive outlined elements |
-| `success` | `#1a7a45` | `#166534` | Success / confirmation / done actions — base color |
-| `successForeground` | `#ffffff` | `#ffffff` | Text on success |
-| `successTint` | `#f0fdf4` | `#052e16` | Very light/dark background tint for success states |
-| `successBorder` | `#bbf7d0` | `#166534` | Border color for success outlined elements |
-| `border` | `#e5e5e5` | `#303030` | Borders and dividers |
-| `input` | `#e5e5e5` | `#2a2a2a` | Input field border color |
-| `ring` | `#1a1a1a` | `#fafafa` | Optional focus ring token (components may use `primary` by default) |
+| `foreground` | `#222222` | `#fafafa` | Primary text — deep near-black, not pure black |
+| `card` | `#ffffff` | `#1c1c1c` | Card / elevated surface background |
+| `primary` | `#1a1a1a` | `#fafafa` | Primary action (buttons, selected states, active indicators) |
+| `primaryForeground` | `#ffffff` | `#0f0f0f` | Text/icon placed on primary-colored backgrounds |
+| `border` | `#dddddd` | `#303030` | Borders, dividers, input outlines |
+| `destructive` | `#e53935` | `#ef5350` | Error / danger / delete actions |
+| `destructiveForeground` | `#ffffff` | `#ffffff` | Text/icon on destructive backgrounds |
+| `success` | `#1a7a45` | `#2e7d52` | Success / confirmation states |
+| `successForeground` | `#ffffff` | `#ffffff` | Text/icon on success backgrounds |
+| `warning` | `#e67e00` | `#f57c00` | Warning / caution states |
+| `warningForeground` | `#ffffff` | `#ffffff` | Text/icon on warning backgrounds |
+
+### 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` @ ~55% | Body text, subtitles, secondary content |
+| `foregroundMuted` | `foreground` @ ~38% | Captions, timestamps, placeholders |
+| `surface` | `background` slightly off-canvas | Chip backgrounds, input fills, tag backgrounds, skeleton |
+| `surfaceStrong` | `background` stronger offset | Pressed/hover fill states |
+| `destructiveTint` | `destructive` blended to bg | Alert banner background, toast background |
+| `destructiveBorder` | `destructive` @ 30% | Alert banner border, badge outline |
+| `successTint` | `success` blended to bg | Success banner background |
+| `successBorder` | `success` @ 30% | Success banner border |
+| `warningTint` | `warning` blended to bg | Warning banner background |
+| `warningBorder` | `warning` @ 30% | Warning banner border |
+| `ring` | `= primary` | Focus ring color (always matches primary) |
+| `input` | `= border` | Input field border (always matches border) |
+
+**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
+
+```tsx
+import { deriveColors } from '@retray-dev/ui-kit'
+
+const resolved = deriveColors(myThemeColors, 'light')
+// resolved contains all 24 ResolvedColors tokens
+```
 
 ---
 
 ## Design Tokens
 
-Static structural constants exported from the package root — no context or provider needed. Use these instead of hardcoding values.
+Static structural constants — no context or provider needed.
 
 ```ts
-import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS } from '@retray-dev/ui-kit'
+import { SPACING, ICON_SIZES, RADIUS, SHADOWS, BREAKPOINTS, TYPOGRAPHY } from '@retray-dev/ui-kit'
 ```
 
-### SPACING
-
-8pt-grid spacing scale.
+### SPACING — 8pt grid with 2pt micro-step
 
-| Key | Value |
-|-----|-------|
-| `xs` | 4 |
-| `sm` | 8 |
-| `md` | 12 |
-| `lg` | 16 |
-| `xl` | 24 |
-| `2xl` | 32 |
-| `3xl` | 48 |
+| Key | Value | Use |
+|-----|-------|-----|
+| `xxs` | 2 | Micro gaps (icon to text in badges) |
+| `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 |
+| `xxl` | 48 | Section padding |
+| `section` | 64 | Major band separators (Airbnb hero → grid rhythm) |
 
 **Types:** `Spacing`, `SpacingKey`
 
 ```tsx
-<View style={{ gap: SPACING.md, padding: SPACING.lg }} />
+<View style={{ gap: SPACING.md, padding: SPACING.base }} />
 ```
 
 ### ICON_SIZES
 
-Semantic icon size scale aligned to HIG roles.
-
-| Key | Value |
-|-----|-------|
-| `sm` | 14 |
-| `md` | 18 |
-| `lg` | 22 |
-| `xl` | 28 |
-| `2xl` | 32 |
+| Key | Value | Use |
+|-----|-------|-----|
+| `sm` | 14 | Badge icons, inline micro icons |
+| `md` | 18 | Standard component icons |
+| `lg` | 22 | Larger inline icons |
+| `xl` | 28 | Feature icons |
+| `2xl` | 32 | Display icons |
 
 **Types:** `IconSize`, `IconSizeKey`
 
-```tsx
-<Icon name="home" size={ICON_SIZES.md} color={colors.foreground} />
-```
-
-### RADIUS
-
-Border radius scale used throughout the library.
+### RADIUS — Airbnb shape language
 
 | Key | Value | Used in |
 |-----|-------|---------|
-| `sm` | 4 | — |
-| `md` | 8 | Inputs, Buttons, Checkboxes, Toggles, Tabs |
-| `lg` | 12 | Cards, AlertBanner, Toast, EmptyState, Select list |
-| `xl` | 16 | Sheet top corners |
-| `full` | 9999 | Pills, circular elements |
+| `none` | 0 | No rounding |
+| `xs` | 4 | Micro chips, tags |
+| `sm` | 8 | Inputs, Textarea, Select, Checkbox |
+| `md` | 14 | Cards, MediaCard, AlertBanner, Toast, EmptyState |
+| `lg` | 20 | Sheet top corners |
+| `xl` | 32 | Primary CTA buttons (pill-like) |
+| `full` | 9999 | Circular elements, CategoryStrip chips |
 
 **Types:** `Radius`, `RadiusKey`
 
 ```tsx
-<View style={{ borderRadius: RADIUS.lg }} />
+<View style={{ borderRadius: RADIUS.md }} />
 ```
 
-### SHADOWS
-
-Cross-platform shadow presets (RN `shadow*` properties + `elevation`).
+### SHADOWS — Cross-platform shadow presets
 
-| Key | Height | Opacity | Radius | Elevation |
-|-----|--------|---------|--------|-----------|
-| `sm` | 1 | 0.08 | 4 | 2 |
-| `md` | 3 | 0.12 | 8 | 5 |
-| `lg` | 6 | 0.20 | 16 | 10 |
-| `xl` | 12 | 0.28 | 24 | 18 |
+| 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 |
 
 ```tsx
-<View style={[styles.card, SHADOWS.md]} />
+<View style={[styles.card, SHADOWS.sm]} />
+// Hover state
+<View style={[styles.card, hovered ? SHADOWS.md : SHADOWS.sm]} />
 ```
 
 ### BREAKPOINTS
 
-Layout breakpoints.
+| Key | Value | Use |
+|-----|-------|-----|
+| `wide` | 700 | Tablet / wide layout threshold |
+
+```tsx
+const isWide = useWindowDimensions().width >= BREAKPOINTS.wide
+```
 
-| Key | Value |
-|-----|-------|
-| `wide` | 700 |
+### 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 |
+| `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 |
+| `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` | 8 | 700 | 10 | 0.32 | 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
-const isWide = width >= BREAKPOINTS.wide
+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` |
+
+---
+
 ## Components
 
 ---
@@ -257,28 +351,68 @@ const isWide = width >= BREAKPOINTS.wide
 ### Text
 
 **Import:** `import { Text } from '@retray-dev/ui-kit'`
-**When to use:** All text in the app. Replaces React Native's `Text` with semantic variants.
-**Extends:** `TextProps` from React Native — all native props pass through.
+
+**When to use:** Every piece of text in your app. Provides Airbnb-aligned typographic hierarchy with correct font, weight, size, and line height. Replaces React Native's `Text` directly — all native `TextProps` pass through.
+
+**Extends:** `TextProps` from React Native
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| variant | `'h1' \| 'h2' \| 'h3' \| 'body' \| 'caption' \| 'label'` | `'body'` | Sets font size, weight, and line height |
-| color | `string` | — | Override the color. Defaults to `foreground`, except `caption` which uses `mutedForeground` |
-
-**Sizes:**
-- `h1`: 40px / 700 weight / lineHeight 52
-- `h2`: 28px / 700 weight / lineHeight 36
-- `h3`: 22px / 600 weight / lineHeight 30
-- `body`: 17px / 400 weight / lineHeight 26
-- `label`: 15px / 500 weight / lineHeight 22
-- `caption`: 13px / 400 weight / lineHeight 20 / `mutedForeground` color by default
-
-**Example:**
+| variant | `TextVariant` | `'body-md'` | Sets font, size, weight, line height, letter spacing |
+| color | `string` | — | Override text color. Each variant has a semantic default (see table below) |
+| children | `ReactNode` | required | — |
+| style | `TextStyle` | — | Additional styles (merged after variant styles) |
+| (all TextProps) | — | — | `numberOfLines`, `ellipsizeMode`, `onPress`, etc. all pass through |
+
+**Variant reference with semantic defaults:**
+
+| Variant | Size | Weight | Default Color | When to use |
+|---------|------|--------|--------------|-------------|
+| `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 |
+| `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 |
+| `micro-label` | 12 | 700 | `foreground` | Micro labels, overlines |
+| `uppercase-tag` | 8 | 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) |
+
+**All text has `allowFontScaling={true}` — respects user's font size settings.**
+
+**Examples:**
 ```tsx
-<Text variant="h2">Welcome back</Text>
-<Text variant="body">Your account is ready.</Text>
-<Text variant="caption">Last updated 2 hours ago</Text>
-<Text variant="label" color="#6366f1">Pro plan</Text>
+// Screen title
+<Text variant="display-xl">Welcome back</Text>
+
+// Financial balance display
+<Text variant="display-hero" color={colors.primary}>$25.000</Text>
+
+// Section heading with subtle color
+<Text variant="display-lg" color={colors.foregroundSubtle}>Recent activity</Text>
+
+// Body copy
+<Text variant="body-md">Your account is ready to use.</Text>
+
+// Caption / metadata
+<Text variant="caption-sm" color={colors.foregroundMuted}>2 hours ago</Text>
+
+// Input label (used automatically by Input, but also useful standalone)
+<Text variant="caption">Email address</Text>
+
+// Uppercase category tag
+<Text variant="uppercase-tag">New</Text>
+
+// Color override
+<Text variant="title-md" color={colors.primary}>Primary colored title</Text>
+<Text variant="body-sm" color={colors.destructive}>Error message in body</Text>
 ```
 
 ---
@@ -286,39 +420,81 @@ const isWide = width >= BREAKPOINTS.wide
 ### Button
 
 **Import:** `import { Button } from '@retray-dev/ui-kit'`
-**When to use:** Any interactive action. Use `variant` to communicate intent.
-**Extends:** `TouchableOpacityProps` — all RN TouchableOpacity props pass through.
+
+**When to use:** Any interactive action. Use `variant` to communicate intent and visual weight. Primary is the main CTA per screen — use sparingly (one per screen ideally).
+
+**Extends:** `TouchableOpacityProps` from React Native — all native props pass through.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | label | `string` | required | Button text |
-| variant | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive'` | `'primary'` | Visual style |
-| size | `'sm' \| 'md' \| 'lg'` | `'md'` | — |
-| loading | `boolean` | `false` | Replaces label with a spinner and forces disabled state |
+| variant | `'primary' \| 'secondary' \| 'text' \| 'destructive'` | `'primary'` | Visual style |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | Controls height, padding, and icon size |
+| loading | `boolean` | `false` | Replaces label with spinner, forces disabled state |
 | fullWidth | `boolean` | `false` | Stretches to container width (`alignSelf: 'stretch'`) |
 | disabled | `boolean` | — | Reduces opacity to 0.5 |
-| icon | `React.ReactNode \| ((props: { label, size, variant }) => React.ReactNode)` | — | Icon rendered alongside the label. Can be a node or a render function |
-| iconName | `string` | — | Icon name from `@expo/vector-icons` (e.g. `"arrow-right"`). See [icons.expo.fyi](https://icons.expo.fyi). Takes precedence over `icon` |
+| icon | `React.ReactNode \| ((props: { label, size, variant }) => React.ReactNode)` | — | Icon rendered alongside label |
+| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
 | iconColor | `string` | — | Override icon color. Defaults to variant label color |
 | iconPosition | `'left' \| 'right'` | `'left'` | Side the icon appears on |
+| style | `ViewStyle` | — | Override container style |
 
 **Variants:**
-- `primary`: filled with `primary` token — main actions
-- `secondary`: filled with `secondary` token — less prominent actions
-- `outline`: transparent with `border` — alternative without fill
-- `ghost`: fully transparent — in-context or low-emphasis actions
-- `destructive`: filled with `destructive` token — irreversible or dangerous actions
+
+| Variant | Background | Border | Text | When to use |
+|---------|-----------|--------|------|-------------|
+| `primary` | `primary` | none | `primaryForeground` | Main CTA — save, submit, continue |
+| `secondary` | transparent | `primary` (1.5px) | `primary` | Alternative action alongside primary |
+| `text` | transparent | none | `primary` | Low-emphasis — cancel, skip, see more |
+| `destructive` | `destructive` | none | `destructiveForeground` | Irreversible actions — delete, remove |
+
+**Sizes:**
+
+| Size | Height | Horizontal padding | Icon size | Font |
+|------|--------|--------------------|-----------|------|
+| `sm` | 40px | 16px | 16px | `button-sm` (14pt/500) |
+| `md` | 48px | 24px | 18px | `button-lg` (16pt/500) |
+| `lg` | 56px | 28px | 20px | `button-lg` (16pt/500) |
+
+**Shape:** `borderRadius: RADIUS.xl = 32px` — pill-shaped on all sizes.
 
 **Animations:** Scale springs to 0.95 on `onPressIn`, back to 1.0 on `onPressOut`.
 
-**Example:**
+**Haptics:** `impactLight` on every press.
+
+**Examples:**
 ```tsx
-<Button label="Save changes" onPress={handleSave} />
-<Button label="Cancel" variant="ghost" onPress={onCancel} />
-<Button label="Delete" variant="outline" size="sm" />
-<Button label="Submitting..." loading fullWidth />
-<Button label="Continue" iconName="arrow-right" iconPosition="right" />
-<Button label="Delete" variant="destructive" iconName="trash-2" />
+// Standard CTA
+<Button label="Continue" onPress={handleContinue} />
+
+// Destructive action
+<Button label="Delete account" variant="destructive" onPress={handleDelete} />
+
+// Cancel (low emphasis)
+<Button label="Cancel" variant="text" onPress={onCancel} />
+
+// Alternative action
+<Button label="Save draft" variant="secondary" onPress={saveDraft} />
+
+// Loading state
+<Button label="Saving..." loading onPress={handleSave} />
+
+// Full width with icon
+<Button label="Get started" iconName="arrow-right" iconPosition="right" fullWidth />
+
+// Destructive with icon
+<Button label="Delete" variant="destructive" iconName="trash-2" size="sm" />
+
+// Large with icon on left
+<Button label="Add to trip" iconName="plus" size="lg" />
+```
+
+**Composition — action pair (primary + secondary):**
+```tsx
+<View style={{ gap: SPACING.sm }}>
+  <Button label="Book now" fullWidth />
+  <Button label="Save for later" variant="secondary" fullWidth />
+</View>
 ```
 
 ---
@@ -326,29 +502,81 @@ const isWide = width >= BREAKPOINTS.wide
 ### IconButton
 
 **Import:** `import { IconButton } from '@retray-dev/ui-kit'`
-**When to use:** Compact icon-only pressable action — toolbars, FABs, inline icon actions. Use `Button` when a label is needed.
-**Extends:** `TouchableOpacityProps` — all RN TouchableOpacity props pass through.
+
+**When to use:** Icon-only pressable actions — toolbars, FABs, navigation actions, close buttons, header actions. Use `Button` when a text label is needed.
+
+**Extends:** `TouchableOpacityProps` from React Native
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| iconName | `string` | — | Icon name from `@expo/vector-icons` (e.g. `"plus"`, `"x"`, `"home"`). Takes precedence over `icon` |
-| icon | `React.ReactNode` | — | Custom icon node — used when `iconName` is not provided |
+| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
+| icon | `ReactNode` | — | Custom icon node when `iconName` is not provided |
 | iconColor | `string` | — | Override icon color. Defaults to variant foreground color |
-| variant | `'primary' \| 'secondary' \| 'outline' \| 'ghost' \| 'destructive'` | `'primary'` | Visual style — same tokens as `Button` |
-| size | `'sm' \| 'md' \| 'lg'` | `'md'` | sm=40pt / md=44pt / lg=52pt (all ≥44pt on md/lg per HIG) |
-| loading | `boolean` | `false` | Replaces icon with a spinner and forces disabled state |
+| variant | `'primary' \| 'secondary' \| 'outline' \| 'text' \| 'destructive'` | `'primary'` | Visual style |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | Button size |
+| loading | `boolean` | `false` | Replaces icon with spinner |
+| badge | `boolean \| number` | — | Notification badge overlay |
 | disabled | `boolean` | — | Reduces opacity to 0.5 |
+| style | `ViewStyle` | — | — |
+
+**Variants:** Same token logic as Button.
+
+| Variant | Background | Border | Icon color | When to use |
+|---------|-----------|--------|-----------|-------------|
+| `primary` | `primary` | none | `primaryForeground` | Prominent action (FAB, main toolbar action) |
+| `secondary` | `surface` | none | `foreground` | Secondary toolbar action |
+| `outline` | transparent | `border` | `foreground` | Tertiary action with visible boundary |
+| `text` | transparent | none | `foreground` | Inline action, header close/back |
+| `destructive` | `destructive` | none | `destructiveForeground` | Delete/remove action |
 
-**Variants:** Same color logic as `Button` — `primary`, `secondary`, `outline`, `ghost`, `destructive`.
+**Sizes:**
+
+| Size | Dimensions | Icon size |
+|------|-----------|-----------|
+| `sm` | 32 × 32px | 16px |
+| `md` | 44 × 44px | 20px |
+| `lg` | 52 × 52px | 24px |
+
+**Badge prop:**
+- `true` → 8×8px dot (primary color, top-right corner)
+- `number` → 16×16px pill with count, capped at 99 (shows "99+" for higher values)
+- Badge is positioned absolutely — does not affect button layout
 
-**Animations:** Scale springs to 0.95 on `onPressIn`, back to 1.0 on `onPressOut`. `impactAsync(Light)` haptic on press.
+**Animations:** Scale springs to 0.95 on press.
 
-**Example:**
+**Haptics:** `impactLight` on press.
+
+**Examples:**
 ```tsx
-<IconButton iconName="plus" onPress={handleAdd} />
-<IconButton iconName="x" variant="ghost" size="sm" onPress={handleClose} />
+// Close button
+<IconButton iconName="x" variant="text" size="sm" onPress={handleClose} />
+
+// FAB
+<IconButton iconName="plus" size="lg" onPress={handleAdd} />
+
+// Delete action
 <IconButton iconName="trash-2" variant="destructive" onPress={handleDelete} />
-<IconButton iconName="check" variant="outline" size="lg" loading={saving} />
+
+// Notification bell with badge count
+<IconButton iconName="bell" variant="text" badge={3} onPress={() => navigate('notifications')} />
+
+// Unread dot (boolean badge)
+<IconButton iconName="mail" variant="outline" badge={true} onPress={() => {}} />
+
+// Header back button
+<IconButton iconName="arrow-left" variant="text" onPress={navigation.goBack} />
+
+// Loading state while action runs
+<IconButton iconName="save" loading={saving} onPress={handleSave} />
+```
+
+**Composition — toolbar row:**
+```tsx
+<View style={{ flexDirection: 'row', gap: SPACING.xs }}>
+  <IconButton iconName="share" variant="text" onPress={handleShare} />
+  <IconButton iconName="bookmark" variant="text" onPress={handleBookmark} />
+  <IconButton iconName="more-horizontal" variant="text" onPress={handleMore} />
+</View>
 ```
 
 ---
@@ -356,36 +584,114 @@ const isWide = width >= BREAKPOINTS.wide
 ### Input
 
 **Import:** `import { Input } from '@retray-dev/ui-kit'`
-**When to use:** Single-line text entry. Includes built-in label, error, and hint support.
-**Extends:** `TextInputProps` from React Native — all native props pass through.
+
+**When to use:** Single-line text entry in forms. Includes label, error, hint, and icon/prefix/suffix support. Covers email, phone, search, password, and custom numeric inputs.
+
+**Extends:** `TextInputProps` from React Native — all native props pass through (`keyboardType`, `autoCapitalize`, `returnKeyType`, etc.)
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| label | `string` | — | Label above the input |
-| error | `string` | — | Shows error text below; turns border red (`destructive` token) |
+| label | `string` | — | Label above the input field |
+| error | `string` | — | Error text below — turns border `destructive` (2px) |
 | hint | `string` | — | Helper text below (hidden when `error` is set) |
-| prefix | `string \| ReactNode` | — | Content rendered before the input field (e.g., `"$"` or an icon) |
-| suffix | `string \| ReactNode` | — | Content rendered after the input field (e.g., `"kg"` or a button) |
-| prefixStyle | `TextStyle` | — | Style applied to the prefix text when prefix is a string |
-| suffixStyle | `TextStyle` | — | Style applied to the suffix text when suffix is a string |
-| prefixIcon | `string` | — | Icon name from `@expo/vector-icons` rendered before the input. Takes precedence over `prefix` |
-| suffixIcon | `string` | — | Icon name from `@expo/vector-icons` rendered after the input. Takes precedence over `suffix` (unless `type="password"`) |
-| prefixIconColor | `string` | — | Override prefix icon color. Defaults to `mutedForeground` |
-| suffixIconColor | `string` | — | Override suffix icon color. Defaults to `mutedForeground` |
-| type | `'text' \| 'password'` | `'text'` | When `'password'`, shows a visibility toggle button in the suffix slot |
-| containerStyle | `ViewStyle` | — | Style for the outer container `View` |
-
-**Border colors:** `destructive` when `error` is set, `ring` when focused, `border` otherwise.
-
-**Example:**
+| prefix | `string \| ReactNode` | — | Content before the input text (e.g. `"$"`, icon node) |
+| suffix | `string \| ReactNode` | — | Content after the input text (e.g. `"kg"`, icon node) |
+| prefixStyle | `TextStyle` | — | Style for prefix string (no effect on ReactNode) |
+| suffixStyle | `TextStyle` | — | Style for suffix string (no effect on ReactNode) |
+| prefixIcon | `string` | — | Icon name rendered before input. Takes precedence over `prefix` |
+| suffixIcon | `string` | — | Icon name rendered after input. Takes precedence over `suffix` unless `type="password"` |
+| prefixIconColor | `string` | — | Override prefix icon color. Defaults to `foregroundMuted` |
+| suffixIconColor | `string` | — | Override suffix icon color. Defaults to `foregroundMuted` |
+| type | `'text' \| 'password'` | `'text'` | Password shows eye/eye-off toggle button in suffix slot |
+| containerStyle | `ViewStyle` | — | Outer container View style |
+| inputWrapperStyle | `ViewStyle` | — | The bordered wrapper around the input row |
+| style | `TextStyle` | — | TextInput element style |
+
+**Dimensions:** 56px height (14px vertical padding), 8px border radius.
+
+**Border states:**
+- Default: `border` token (1px)
+- Focused: `primary` (2px)
+- Error: `destructive` (2px)
+- Focused + error: `destructive` (2px)
+
+**Examples:**
 ```tsx
-<Input label="Email" placeholder="you@example.com" keyboardType="email-address" />
+// Standard email input
+<Input label="Email" placeholder="you@example.com" keyboardType="email-address" autoCapitalize="none" />
+
+// Password with toggle
 <Input label="Password" type="password" error="Incorrect password" />
-<Input label="Username" hint="Must be at least 4 characters" />
-<Input label="Amount" prefix="$" placeholder="0.00" keyboardType="numeric" />
-<Input label="Weight" suffix="kg" placeholder="0" />
+
+// With hint text
+<Input label="Username" hint="4–20 characters, letters and numbers only" />
+
+// Currency prefix (string)
+<Input label="Amount" prefix="$" placeholder="0.00" keyboardType="decimal-pad" />
+
+// Unit suffix
+<Input label="Weight" suffix="kg" placeholder="0" keyboardType="numeric" />
+
+// Search (no label, prefix icon)
 <Input placeholder="Search..." prefixIcon="search" />
+
+// With both icons
 <Input placeholder="Amount" prefixIcon="dollar-sign" suffixIcon="check" />
+
+// With custom ReactNode prefix
+<Input
+  label="Phone"
+  prefix={<Text variant="body-md">+1</Text>}
+  keyboardType="phone-pad"
+/>
+
+// Controlled with error
+<Input
+  label="Email"
+  value={email}
+  onChangeText={setEmail}
+  error={emailError}
+  keyboardType="email-address"
+/>
+```
+
+**Composition — form fields:**
+```tsx
+<View style={{ gap: SPACING.md }}>
+  <Input label="First name" value={firstName} onChangeText={setFirstName} />
+  <Input label="Last name" value={lastName} onChangeText={setLastName} />
+  <Input label="Email" value={email} onChangeText={setEmail} error={emailError} keyboardType="email-address" />
+  <Input label="Password" type="password" value={password} onChangeText={setPassword} />
+  <Button label="Create account" fullWidth onPress={handleSubmit} />
+</View>
+```
+
+---
+
+### Textarea
+
+**Import:** `import { Textarea } from '@retray-dev/ui-kit'`
+
+**When to use:** Multi-line text entry — bios, descriptions, notes, reviews. Same visual design as `Input` but taller with multi-line support.
+
+**Extends:** `TextInputProps` from React Native — all native props pass through.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| label | `string` | — | Label above the textarea |
+| error | `string` | — | Error text below; turns border destructive (2px) |
+| hint | `string` | — | Helper text below (hidden when `error` is set) |
+| rows | `number` | `4` | Minimum row count — each row ≈ 30px. Sets `numberOfLines` |
+| containerStyle | `ViewStyle` | — | Outer container style |
+| style | `TextStyle` | — | TextInput element style |
+
+**Border states:** Identical to Input (focused=primary 2px, error=destructive 2px).
+
+**Examples:**
+```tsx
+<Textarea label="Bio" placeholder="Tell us about yourself" rows={5} />
+<Textarea label="Review" hint="Be honest and helpful" />
+<Textarea label="Notes" error="Notes are required" rows={3} />
 ```
 
 ---
@@ -393,29 +699,32 @@ const isWide = width >= BREAKPOINTS.wide
 ### CurrencyInput
 
 **Import:** `import { CurrencyInput } from '@retray-dev/ui-kit'`
-**When to use:** Monetary or numeric inputs that need thousands formatting while typing. Wraps `Input` — shares the same visual design, label, error, and hint behavior.
+
+**When to use:** Monetary or numeric entries that need thousands-separator formatting while typing. Amount entry, price fields, transfer amounts. Wraps `Input` — shares the same label, error, hint, and visual design.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| value | `string` | — | Controlled display value (includes prefix, e.g. `'$1,234'`) |
-| onChangeText | `(formatted: string) => void` | — | Called with the formatted display string |
+| value | `string` | — | Controlled display value including prefix (e.g. `'$1.234'`) |
+| onChangeText | `(formatted: string) => void` | — | Called with the formatted display string on each keystroke |
 | onChangeValue | `(raw: number) => void` | — | Called with the parsed number (no separators, no prefix) |
-| prefix | `string` | `'$'` | Symbol prepended to the formatted value |
-| thousandsSeparator | `'.' \| ','` | `'.'` | Character used to separate groups of three digits |
-| size | `'default' \| 'large'` | `'default'` | `'large'` uses 36px font size (previously `CurrencyInputLarge`) |
-| label | `string` | — | Label above the input |
-| error | `string` | — | Error text below; turns border red |
+| prefix | `string` | `'$'` | Symbol prepended to formatted value |
+| thousandsSeparator | `'.' \| ','` | `'.'` | Character separating groups of three digits |
+| size | `'default' \| 'large'` | `'default'` | `'large'` uses 36px font for prominent payment screens |
+| label | `string` | — | Label above input |
+| error | `string` | — | Error text below |
 | hint | `string` | — | Helper text below (hidden when `error` is set) |
 | placeholder | `string` | `'$0'` | Defaults to `prefix + '0'` |
-| editable | `boolean` | — | Pass `false` to disable editing |
-| containerStyle | `ViewStyle` | — | Style for the outer container |
+| editable | `boolean` | — | Pass `false` to disable |
+| containerStyle | `ViewStyle` | — | Outer container style |
+
+**Formatting behavior:** Strips all non-digit characters from input, then re-applies thousands separator every 3 digits from the right, then prepends `prefix`. Decimal point input is not supported — this is for whole-number monetary amounts.
 
-**Example:**
+**Examples:**
 ```tsx
 const [display, setDisplay] = useState('')
 const [amount, setAmount] = useState(0)
 
-// Default: dot as thousands separator → "$1.234.567"
+// Standard with dot separator ($1.234.567)
 <CurrencyInput
   label="Amount"
   value={display}
@@ -424,7 +733,7 @@ const [amount, setAmount] = useState(0)
   hint={`Parsed: ${amount}`}
 />
 
-// Comma as thousands separator → "$1,234,567"
+// Comma separator ($1,234,567)
 <CurrencyInput
   prefix="$"
   thousandsSeparator=","
@@ -432,27 +741,67 @@ const [amount, setAmount] = useState(0)
   onChangeText={setDisplay}
   onChangeValue={setAmount}
 />
+
+// Large variant for payment screens
+<CurrencyInput
+  size="large"
+  label="Transfer amount"
+  value={display}
+  onChangeText={setDisplay}
+  onChangeValue={setAmount}
+/>
+
+// Euro with error
+<CurrencyInput
+  prefix="€"
+  label="Price"
+  value={display}
+  onChangeText={setDisplay}
+  onChangeValue={setAmount}
+  error={amount < 1000 ? "Minimum amount is €1.000" : undefined}
+/>
 ```
 
 ---
 
-### Textarea
+### CurrencyDisplay
 
-**Import:** `import { Textarea } from '@retray-dev/ui-kit'`
-**When to use:** Multi-line text entry. Same API as `Input` plus `rows`.
-**Extends:** `TextInputProps` from React Native — all native props pass through.
+**Import:** `import { CurrencyDisplay } from '@retray-dev/ui-kit'`
+
+**When to use:** Prominent read-only display of monetary values — account balances, totals, summary screens. Uses `display-hero` typography (56pt bold) for visual impact.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| label | `string` | — | Label above |
-| error | `string` | — | Error text below; red border |
-| hint | `string` | — | Helper text below |
-| rows | `number` | `4` | Sets `minHeight` (each row ≈ 30px) and `numberOfLines` |
-| containerStyle | `ViewStyle` | — | Style for the outer container `View` |
+| value | `number \| string` | required | Numeric value to display |
+| prefix | `string` | `'$'` | Symbol prepended to formatted value |
+| showDecimals | `boolean` | `false` | Show two decimal places with comma separator (e.g. `$25.000,00`) |
+| textColor | `string` | — | Override text color. Defaults to `foreground` token |
+| style | `ViewStyle` | — | Outer container style |
+
+**Format:** Dot (`.`) as thousands separator, comma (`,`) as decimal separator — Latin American / European format.
 
-**Example:**
+**Examples:**
 ```tsx
-<Textarea label="Bio" placeholder="Tell us about yourself" rows={5} />
+<CurrencyDisplay value={25000} />
+// → $25.000
+
+<CurrencyDisplay value={25000000.5} showDecimals />
+// → $25.000.000,50
+
+<CurrencyDisplay value={1500} prefix="€" />
+// → €1.500
+
+<CurrencyDisplay value={balance} textColor={balance < 0 ? colors.destructive : colors.foreground} />
+```
+
+**Composition — balance card:**
+```tsx
+<Card>
+  <CardContent>
+    <Text variant="caption-sm" color={colors.foregroundMuted}>Available balance</Text>
+    <CurrencyDisplay value={12500} />
+  </CardContent>
+</Card>
 ```
 
 ---
@@ -460,27 +809,59 @@ const [amount, setAmount] = useState(0)
 ### Badge
 
 **Import:** `import { Badge } from '@retray-dev/ui-kit'`
-**When to use:** Status labels, tags, counts.
+
+**When to use:** Status labels, counts, category tags, feature flags. Pill-shaped with optional icon.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| label | `string` | — | Badge text — can be omitted if using `children` |
+| label | `string` | — | Badge text. Can be omitted when using `children` |
 | children | `ReactNode` | — | Alternative to `label` for custom content |
-| variant | `'default' \| 'secondary' \| 'destructive' \| 'outline'` | `'default'` | — |
+| variant | `BadgeVariant` | `'default'` | Visual style |
 | size | `'sm' \| 'md' \| 'lg'` | `'md'` | Controls padding and font size |
-| icon | `ReactNode` | — | Icon rendered before the label/children |
+| icon | `ReactNode` | — | Icon rendered before label |
 | iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
 | iconColor | `string` | — | Override icon color. Defaults to variant foreground color |
 | style | `ViewStyle` | — | — |
 
-**Example:**
+**Variants:**
+
+| Variant | Background | Text | Border | When to use |
+|---------|-----------|------|--------|-------------|
+| `default` | `primary` | `primaryForeground` | none | Primary status — active, featured |
+| `secondary` | `surface` | `foregroundSubtle` | `border` | Neutral — draft, inactive, secondary status |
+| `destructive` | `destructive` | `destructiveForeground` | none | Error, failed, danger |
+| `outline` | transparent | `foreground` | `border` | Subtle tag, no emphasis |
+| `success` | `success` | `successForeground` | none | Completed, verified, paid |
+| `warning` | `warning` | `warningForeground` | none | Pending, caution, expiring |
+| `successOutline` | `successTint` | `success` | `successBorder` | Soft success (less visual weight) |
+| `destructiveOutline` | `destructiveTint` | `destructive` | `destructiveBorder` | Soft error (less visual weight) |
+| `warningOutline` | `warningTint` | `warning` | `warningBorder` | Soft warning (less visual weight) |
+
+**Sizes:**
+
+| Size | Padding (V×H) | Font size | Icon size |
+|------|--------------|-----------|-----------|
+| `sm` | 2 × 8 | 11pt | 10px |
+| `md` | 4 × 10 | 13pt | 12px |
+| `lg` | 6 × 12 | 15pt | 14px |
+
+**All badges have `borderRadius: 9999` (pill-shaped).**
+
+**Examples:**
 ```tsx
 <Badge label="New" />
 <Badge label="Error" variant="destructive" />
 <Badge label="Draft" variant="secondary" size="sm" />
 <Badge label="Beta" variant="outline" />
-<Badge label="Active" variant="default" iconName="check" size="sm" />
-<Badge label="Error" variant="destructive" iconName="alert-circle" />
+<Badge label="Paid" variant="success" iconName="check" />
+<Badge label="Pending" variant="warningOutline" />
+<Badge label="3" variant="destructive" size="sm" />
+
+// With status in ListItem
+<ListItem
+  title="Payment"
+  rightRender={<Badge label="Pending" variant="warningOutline" size="sm" />}
+/>
 ```
 
 ---
@@ -488,245 +869,452 @@ const [amount, setAmount] = useState(0)
 ### Avatar
 
 **Import:** `import { Avatar } from '@retray-dev/ui-kit'`
-**When to use:** User profile pictures with automatic fallback to initials.
+
+**When to use:** User profile pictures with automatic fallback to initials. Works with remote URIs and local images.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| src | `string` | — | Image URI |
-| fallback | `string` | — | Text shown when image fails or `src` is absent — first 2 chars, uppercased |
-| size | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | sm=24, md=32, lg=48, xl=64 (diameter in pt) |
+| src | `string` | — | Image URI (remote or local) |
+| fallback | `string` | — | Text shown when image fails or `src` is absent — first 2 characters shown, uppercased |
+| size | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Diameter in points |
+| status | `'online' \| 'offline' \| 'busy' \| 'away'` | — | Status indicator dot, bottom-right |
 | style | `ViewStyle` | — | — |
 
-**Example:**
+**Sizes:**
+
+| Size | Diameter | Fallback font | Status dot size |
+|------|---------|--------------|----------------|
+| `sm` | 28px | 12pt | 8px |
+| `md` | 40px | 16pt | 10px |
+| `lg` | 56px | 22pt | 13px |
+| `xl` | 72px | 28pt | 16px |
+
+**Status dot colors:**
+- `online` → `#22c55e` (green)
+- `offline` → transparent fill, `border` color outline only
+- `busy` → `destructive` token
+- `away` → `warning` token
+
+**Status dot is absolutely positioned at bottom-right with a 2px white border.**
+
+**Examples:**
 ```tsx
 <Avatar src="https://..." fallback="JC" size="lg" />
 <Avatar fallback="AN" size="md" />
+<Avatar src={user.avatar} fallback={user.initials} size="xl" status="online" />
+<Avatar fallback="BU" size="sm" status="busy" />
+
+// In a ListItem
+<ListItem
+  leftRender={<Avatar src={user.avatar} fallback={user.initials} status="online" />}
+  title={user.name}
+  subtitle={user.role}
+/>
 ```
 
 ---
 
-### Separator
+### Card
 
-**Import:** `import { Separator } from '@retray-dev/ui-kit'`
-**When to use:** Visual dividers between sections.
+**Import:** `import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@retray-dev/ui-kit'`
+
+**When to use:** Grouped content with a surface background. Use `Card` as the container and sub-components for structured layout.
+
+**`Card` Props:**
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| orientation | `'horizontal' \| 'vertical'` | `'horizontal'` | Vertical requires a parent with a defined height |
+| variant | `'elevated' \| 'outlined' \| 'filled'` | `'elevated'` | Visual style |
+| onPress | `() => void` | — | Makes card pressable with scale animation + haptics |
+| children | `ReactNode` | required | — |
 | style | `ViewStyle` | — | — |
 
-**Example:**
+**Variants:**
+
+| Variant | Background | Border | Shadow | When to use |
+|---------|-----------|--------|--------|-------------|
+| `elevated` | `card` | `border` (1px) | `SHADOWS.sm` | Default card — standard content groups |
+| `outlined` | `card` | `border` (1px) | none | Flat bordered cards, lists of cards |
+| `filled` | `surfaceStrong` | none | none | Background fill cards, stat blocks, sidebar items |
+
+**Sub-components (all accept `style` prop):**
+
+| Sub-component | Padding | Notes |
+|--------------|---------|-------|
+| `CardHeader` | 16px all, 0 bottom | Use for title + description |
+| `CardTitle` | — | 18pt / SemiBold / `cardForeground` |
+| `CardDescription` | — | 14pt / Regular / `foregroundMuted` |
+| `CardContent` | 16px all (12px top) | Main content area |
+| `CardFooter` | 16px horizontal, 14px bottom | Row layout, use for buttons |
+
+**Shape:** `borderRadius: RADIUS.md = 14px`
+
+**Press animation:** Scale springs to 0.98 (subtler than button — appropriate for large targets).
+
+**Haptics:** `impactLight` when `onPress` is provided.
+
+**Examples:**
 ```tsx
-<Separator />
-<View style={{ flexDirection: 'row', height: 40 }}>
-  <Text>Left</Text>
-  <Separator orientation="vertical" style={{ marginHorizontal: 12 }} />
-  <Text>Right</Text>
+// Standard card
+<Card>
+  <CardHeader>
+    <CardTitle>Account settings</CardTitle>
+    <CardDescription>Manage your profile and preferences</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <Input label="Display name" value={name} onChangeText={setName} />
+  </CardContent>
+  <CardFooter>
+    <Button label="Save" fullWidth />
+  </CardFooter>
+</Card>
+
+// Pressable navigation card
+<Card variant="outlined" onPress={() => navigate('profile')}>
+  <CardContent>
+    <Text variant="title-md">Profile</Text>
+    <Text variant="body-sm">Edit your information</Text>
+  </CardContent>
+</Card>
+
+// Stat block (filled)
+<Card variant="filled">
+  <CardContent>
+    <Text variant="caption-sm" color={colors.foregroundMuted}>Total spent</Text>
+    <CurrencyDisplay value={totalSpent} />
+  </CardContent>
+</Card>
+```
+
+**Composition — dashboard grid:**
+```tsx
+<View style={{ flexDirection: 'row', gap: SPACING.md }}>
+  <Card variant="filled" style={{ flex: 1 }}>
+    <CardContent>
+      <Text variant="micro-label" color={colors.foregroundMuted}>INCOME</Text>
+      <Text variant="display-md" color={colors.success}>$8.500</Text>
+    </CardContent>
+  </Card>
+  <Card variant="filled" style={{ flex: 1 }}>
+    <CardContent>
+      <Text variant="micro-label" color={colors.foregroundMuted}>EXPENSES</Text>
+      <Text variant="display-md" color={colors.destructive}>$3.200</Text>
+    </CardContent>
+  </Card>
 </View>
 ```
 
 ---
 
-### Spinner
+### MediaCard
 
-**Import:** `import { Spinner } from '@retray-dev/ui-kit'`
-**When to use:** Loading state indicator. Wraps React Native's `ActivityIndicator`.
-**Extends:** `ActivityIndicatorProps` (except `size`).
+**Import:** `import { MediaCard } from '@retray-dev/ui-kit'`
+
+**When to use:** Image-first content cards — product listings, properties, experiences, photo-based content. Think Airbnb listing card or marketplace item.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| size | `'sm' \| 'md' \| 'lg'` | `'md'` | `sm`/`md` map to RN `'small'`, `lg` maps to `'large'` |
-| color | `string` | `primary` token | Override spinner color |
-| label | `string` | — | Text displayed below the spinner |
+| imageSource | `ImageSourcePropType` | — | Image — `{ uri: '...' }` or `require('./img.jpg')` |
+| aspectRatio | `MediaCardAspectRatio` | `'4:3'` | Controls image height relative to card width |
+| badge | `ReactNode` | — | Floating content top-left of image |
+| actionIcon | `ReactNode` | — | Icon top-right of image (defaults to heart outline) |
+| actionIconName | `string` | — | Icon name. Overrides `actionIcon` |
+| actionActive | `boolean` | `false` | Whether action is in active/filled state |
+| onActionPress | `() => void` | — | Press handler for action icon. Stops event propagation |
+| title | `string` | — | Below image — primary label |
+| subtitle | `string` | — | Secondary line below title |
+| caption | `string` | — | Tertiary metadata line |
+| footer | `ReactNode` | — | Custom content below caption (price, rating, etc.) |
+| onPress | `() => void` | — | Press the card body |
+| style | `ViewStyle` | — | Outer card style |
+| imageStyle | `ViewStyle` | — | Image container override |
 
-**Example:**
-```tsx
-<Spinner />
-<Spinner size="lg" color="#6366f1" />
-<Spinner size="lg" label="Loading..." />
-```
+**Aspect ratios (`MediaCardAspectRatio`):**
 
----
+| Value | Width:Height | When to use |
+|-------|-------------|-------------|
+| `'1:1'` | Square | Profile cards, avatars, square products |
+| `'4:3'` | Classic | Default — general listings |
+| `'16:9'` | Wide | Videos, wide landscape imagery |
+| `'4:5'` | Portrait | Tall product photos, fashion |
+| `'3:2'` | Photo | Standard photography ratio |
 
-### Skeleton
+**Image implementation:** Uses `paddingTop` percentage for cross-platform consistent aspect ratios with `position: absolute` image fill — no fixed height needed.
 
-**Import:** `import { Skeleton } from '@retray-dev/ui-kit'`
-**When to use:** Placeholder while content is loading. Pulses with a looping opacity animation.
+**Shape:** `borderRadius: RADIUS.md = 14px`, `overflow: hidden`.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| width | `number \| string` | `'100%'` | — |
-| height | `number` | `16` | — |
-| borderRadius | `number` | `6` | — |
-| style | `ViewStyle` | — | — |
+**Action button:** 32×32px circle, semi-transparent background (24% opacity), top-right corner 8px from edges.
 
-**Example:**
-```tsx
-<Skeleton height={20} width="60%" />
-<Skeleton height={80} borderRadius={10} />
-```
+**Badge:** Positioned top-left 8px from edges — pass any ReactNode (Badge component recommended).
 
----
+**Web hover:** Lifts shadow from `SHADOWS.sm` to `SHADOWS.md` on hover.
 
-### Progress
+**Press animation:** Scale springs to 0.98.
 
-**Import:** `import { Progress } from '@retray-dev/ui-kit'`
-**When to use:** Show completion percentage for a task or upload.
+**Haptics:** `impactLight` on `onActionPress`.
 
-| Prop | Type | Default | Notes |
-|------|------|---------|-------|
-| value | `number` | `0` | Current value |
-| max | `number` | `100` | Maximum value |
-| style | `ViewStyle` | — | — |
+**Examples:**
+```tsx
+// Basic listing card
+<MediaCard
+  imageSource={{ uri: listing.photo }}
+  title={listing.name}
+  subtitle={listing.location}
+  caption={`$${listing.price} / night`}
+  onPress={() => navigate('listing', { id: listing.id })}
+/>
+
+// With save action and aspect ratio
+<MediaCard
+  imageSource={{ uri: product.image }}
+  aspectRatio="4:5"
+  title={product.name}
+  subtitle={product.brand}
+  actionActive={saved}
+  onActionPress={() => toggleSave(product.id)}
+  onPress={() => navigate('product', { id: product.id })}
+/>
+
+// With badge overlay
+<MediaCard
+  imageSource={{ uri: item.photo }}
+  badge={<Badge label="New" size="sm" />}
+  title={item.name}
+  onPress={() => {}}
+/>
 
-**Animation:** Spring-animates the fill width on `value` changes (JS thread — `useNativeDriver: false`). Uses `onLayout` to capture track pixel width and interpolates to pixels (cannot animate `width: '%'`).
+// With custom footer (price + rating)
+<MediaCard
+  imageSource={{ uri: place.photo }}
+  aspectRatio="4:3"
+  title={place.name}
+  footer={
+    <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
+      <Text variant="title-sm">$120 / night</Text>
+      <Text variant="caption-sm">★ 4.8</Text>
+    </View>
+  }
+  onPress={() => navigate('place', { id: place.id })}
+/>
+```
 
-**Example:**
+**Composition — listing grid:**
 ```tsx
-<Progress value={60} />
-<Progress value={3} max={10} />
+<View style={{ flexDirection: 'row', flexWrap: 'wrap', gap: SPACING.md }}>
+  {listings.map((item) => (
+    <MediaCard
+      key={item.id}
+      style={{ width: (screenWidth - SPACING.base * 2 - SPACING.md) / 2 }}
+      imageSource={{ uri: item.photo }}
+      title={item.name}
+      caption={item.price}
+      actionActive={savedIds.includes(item.id)}
+      onActionPress={() => toggleSave(item.id)}
+      onPress={() => navigate('listing', { id: item.id })}
+    />
+  ))}
+</View>
 ```
 
 ---
 
-### CurrencyDisplay
+### Separator
 
-**Import:** `import { CurrencyDisplay } from '@retray-dev/ui-kit'`
-**When to use:** Prominent display of monetary values (account balances, totals). Large, attention-grabbing typographic treatment with dot-separated thousands and optional comma-decimal.
+**Import:** `import { Separator } from '@retray-dev/ui-kit'`
+
+**When to use:** Visual divider between sections, list items, or columns.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| value | `number \| string` | required | Numeric value to display |
-| prefix | `string` | `'$'` | Symbol prepended to the formatted value |
-| showDecimals | `boolean` | `false` | When `true`, shows two decimal places separated by a comma (e.g. `$25.000,00`) |
-| textColor | `string` | — | Override the color of the formatted text. Defaults to the `foreground` token |
-| style | `ViewStyle` | — | Style override for outer container |
+| orientation | `'horizontal' \| 'vertical'` | `'horizontal'` | Direction of the line |
+| style | `ViewStyle` | — | — |
+
+**Styling:** 1px thickness, `border` token color.
 
-**Example:**
+**Examples:**
 ```tsx
-<CurrencyDisplay value={25000} />
-// → $25.000
+// Section divider
+<Separator />
 
-<CurrencyDisplay value={25000000.5} showDecimals />
-// → $25.000.000,50
+// Vertical divider (parent must have defined height)
+<View style={{ flexDirection: 'row', height: 40, alignItems: 'center' }}>
+  <Text>Left</Text>
+  <Separator orientation="vertical" style={{ marginHorizontal: 12 }} />
+  <Text>Right</Text>
+</View>
 
-<CurrencyDisplay value={1500} prefix="€" />
-// → €1.500
+// With custom spacing
+<Separator style={{ marginVertical: SPACING.lg }} />
 ```
 
-**Notes:**
-- Uses dot (`.`) as thousands separator and comma (`,`) as decimal separator — Latin American / European format.
-- Intended as a display-only component (not editable).
-- `allowFontScaling={true}` is set on the inner `Text`.
-
 ---
 
-### CurrencyInputLarge
+### Spinner
+
+**Import:** `import { Spinner } from '@retray-dev/ui-kit'`
 
-**Import:** `import { CurrencyInputLarge } from '@retray-dev/ui-kit'`
-**When to use:** Large, form-style monetary input for prominent entry screens (payments, transfers). Same formatting behavior as `CurrencyInput` but with 36px font size.
+**When to use:** Loading state indicator. Use inline (within buttons or content areas) or full-screen.
+
+**Extends:** `ActivityIndicatorProps` (except `size` — use the string size prop instead)
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| value | `string` | — | Controlled display value (includes prefix, e.g. `'$1.234'`) |
-| onChangeText | `(formatted: string) => void` | — | Called with the formatted display string |
-| onChangeValue | `(raw: number) => void` | — | Called with the parsed number (no separators, no prefix) |
-| label | `string` | — | Label above the input |
-| prefix | `string` | `'$'` | Currency prefix |
-| thousandsSeparator | `'.' \| ','` | `'.'` | Separator used to format groups of three digits |
-| error | `string` | — | Error text below; turns border red |
-| hint | `string` | — | Helper text below (hidden when `error` is set) |
-| placeholder | `string` | `'$0'` | Defaults to `prefix + '0'` |
-| editable | `boolean` | — | Pass `false` to disable editing |
-| containerStyle | `ViewStyle` | — | Style for the outer container |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | `sm`/`md` → RN `'small'`, `lg` → RN `'large'` |
+| color | `string` | `primary` token | Override spinner color |
+| label | `string` | — | Text displayed below spinner |
 
-**Example:**
+**Examples:**
 ```tsx
-const [display, setDisplay] = useState('')
-const [amount, setAmount] = useState(0)
+<Spinner />
+<Spinner size="lg" />
+<Spinner size="lg" label="Loading..." />
+<Spinner color={colors.foregroundMuted} />
 
-<CurrencyInputLarge
-  label="Amount"
-  value={display}
-  onChangeText={setDisplay}
-  onChangeValue={setAmount}
-/>
-// Typing "25000" produces "$25.000"
+// Full-screen loading overlay
+<View style={{ flex: 1, alignItems: 'center', justifyContent: 'center' }}>
+  <Spinner size="lg" label="Fetching data..." />
+</View>
 ```
 
 ---
 
-### Card
+### Skeleton
 
-**Import:** `import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter } from '@retray-dev/ui-kit'`
-**When to use:** Grouped content with a surface background, border, and shadow.
+**Import:** `import { Skeleton } from '@retray-dev/ui-kit'`
 
-**`Card` Props:**
+**When to use:** Placeholder while content is loading. Use to match the shape of the content that will appear — creates a visual loading skeleton that prevents layout shift.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| variant | `'elevated' \| 'outlined' \| 'filled'` | `'elevated'` | `elevated`: shadow + border; `outlined`: border only; `filled`: background fill, no border |
-| onPress | `() => void` | — | Makes the card pressable with scale animation + haptics |
-| children | `ReactNode` | — | — |
+| width | `number \| string` | `'100%'` | Width of placeholder |
+| height | `number` | `16` | Height of placeholder |
+| borderRadius | `number` | `6` | Corner radius |
+| preset | `'base' \| 'circle' \| 'text'` | `'base'` | Convenience preset |
+| diameter | `number` | `40` | Used by `'circle'` preset — overrides width/height |
 | style | `ViewStyle` | — | — |
 
-All sub-components (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`) accept a `style` prop for overrides.
+**Presets:**
+- `'base'` — Uses `width`, `height`, `borderRadius` exactly as specified
+- `'circle'` — Forces square dimensions from `diameter`, `borderRadius: 9999`
+- `'text'` — 60% width, 14px height, 4px border radius (typical text line shape)
 
-**Example:**
+**Animation:** Shimmer sweep loops every 1200ms. Highlight color adapts to light/dark mode.
+
+**Examples:**
 ```tsx
-<Card variant="elevated">
-  <CardHeader>
-    <CardTitle>Account</CardTitle>
-    <CardDescription>Manage your profile settings</CardDescription>
-  </CardHeader>
-  <CardContent>
-    <Input label="Name" />
-  </CardContent>
-  <CardFooter>
-    <Button label="Save" fullWidth />
-  </CardFooter>
-</Card>
+// Text line placeholders
+<Skeleton height={20} width="80%" />
+<Skeleton height={16} width="60%" style={{ marginTop: 8 }} />
+
+// Circle avatar placeholder
+<Skeleton preset="circle" diameter={40} />
+
+// Text preset (auto-sized)
+<Skeleton preset="text" />
+
+// Custom card skeleton
+<View style={{ gap: SPACING.sm }}>
+  <Skeleton height={180} borderRadius={14} />   {/* image */}
+  <Skeleton height={18} width="70%" />           {/* title */}
+  <Skeleton preset="text" />                     {/* subtitle */}
+  <Skeleton height={14} width="40%" />           {/* caption */}
+</View>
+```
 
-// Pressable card
-<Card variant="outlined" onPress={() => navigate('detail')}>
-  <CardContent>
-    <Text>Tap me</Text>
-  </CardContent>
-</Card>
+**Composition — skeleton for a ListItem:**
+```tsx
+<View style={{ flexDirection: 'row', gap: SPACING.md, padding: SPACING.base }}>
+  <Skeleton preset="circle" diameter={40} />
+  <View style={{ flex: 1, gap: SPACING.xs }}>
+    <Skeleton height={16} width="60%" />
+    <Skeleton preset="text" />
+  </View>
+</View>
 ```
 
-**Notes:**
-- `CardHeader` and `CardContent` have `padding: 24`. Override via the `style` prop: `<CardContent style={{ padding: 16 }}>`
-- `CardFooter` has `paddingTop: 0` so it connects naturally to `CardContent`
-- `CardTitle`: 20px / 600 weight / lineHeight 28, `cardForeground` color
-- `CardDescription`: 15px / lineHeight 22, `mutedForeground` color
-- Press animation scales to 0.98 via `Animated.spring` when `onPress` is provided
+---
+
+### Progress
+
+**Import:** `import { Progress } from '@retray-dev/ui-kit'`
+
+**When to use:** Show completion percentage for tasks, uploads, onboarding steps, multi-step flows.
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| value | `number` | `0` | Current progress value |
+| max | `number` | `100` | Maximum value — `value/max` determines fill percentage |
+| variant | `'default' \| 'success' \| 'warning' \| 'destructive'` | `'default'` | Indicator color |
+| style | `ViewStyle` | — | Outer container style |
+
+**Variants — indicator color:**
+- `default` → `primary` token
+- `success` → `success` token
+- `warning` → `warning` token
+- `destructive` → `destructive` token
+
+**Styling:** 8px height, `borderRadius: 9999` (pill). Track uses `surface` background.
+
+**Animation:** Spring-animates fill width on `value` changes (JS thread). Uses `onLayout` to capture pixel width.
+
+**Examples:**
+```tsx
+<Progress value={60} />
+<Progress value={3} max={10} />
+<Progress value={uploadProgress} variant="success" />
+<Progress value={daysRemaining} max={30} variant="warning" />
+<Progress value={errors} max={100} variant="destructive" />
+
+// Labeled progress
+<View style={{ gap: SPACING.xs }}>
+  <View style={{ flexDirection: 'row', justifyContent: 'space-between' }}>
+    <Text variant="caption">Profile completion</Text>
+    <Text variant="caption">{progress}%</Text>
+  </View>
+  <Progress value={progress} />
+</View>
+```
 
 ---
 
 ### AlertBanner
 
 **Import:** `import { AlertBanner } from '@retray-dev/ui-kit'`
-**When to use:** Inline feedback messages (info, success, error). Not for transient toasts — use `Toast` for ephemeral feedback.
+
+**When to use:** Inline feedback messages that persist in the UI — info notices, form-level errors, feature announcements, status alerts. Not for ephemeral feedback — use `Toast` for temporary messages.
 
 > **Note:** Named `AlertBanner` (not `Alert`) to avoid collision with React Native's built-in `Alert` module.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | title | `string` | required | Bold heading |
-| description | `string` | — | Optional detail text below the title |
-| variant | `'default' \| 'destructive' \| 'success'` | `'default'` | Controls border/text color |
-| icon | `ReactNode` | — | Icon placed to the left of the text content. Defaults to a variant-appropriate symbol (`ℹ`, `⚠`, `✓`) |
-| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` (but still falls back to the variant default when neither is set) |
-| iconColor | `string` | — | Override icon color. Defaults to the variant title color |
+| description | `string` | — | Supporting detail text below title |
+| variant | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | Controls colors and default icon |
+| icon | `ReactNode` | — | Override default icon with custom ReactNode |
+| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon`, but still falls back to variant default when neither is set |
+| iconColor | `string` | — | Override icon color. Defaults to variant title color |
 | style | `ViewStyle` | — | — |
 
-**Example:**
+**Variants:**
+
+| Variant | Background | Border | Icon | When to use |
+|---------|-----------|--------|------|-------------|
+| `default` | `card` | `border` | ℹ️ info | Neutral notices, informational messages |
+| `destructive` | `destructiveTint` | `destructiveBorder` | ⚠️ error | Form errors, action failures |
+| `success` | `successTint` | `successBorder` | ✓ check | Confirmations, completed states |
+| `warning` | `warningTint` | `warningBorder` | ⚠️ warning | Cautions, expiring states, pending actions |
+
+**Styling:** 12px border radius, 14px horizontal + 12px vertical padding, 1px border.
+
+**Examples:**
 ```tsx
-<AlertBanner title="Info" description="Your session will expire in 5 minutes." />
-<AlertBanner variant="destructive" title="Error" description="Failed to save. Try again." />
-<AlertBanner variant="success" title="Done" description="Your changes have been saved." />
-<AlertBanner iconName="bell" title="Reminder" description="Complete your profile." />
+<AlertBanner title="Your session expires in 5 minutes" />
+<AlertBanner variant="destructive" title="Payment failed" description="Please check your card details." />
+<AlertBanner variant="success" title="Profile updated" description="Your changes have been saved." />
+<AlertBanner variant="warning" title="ID verification required" description="Complete verification to unlock transfers." />
+
+// Custom icon
+<AlertBanner iconName="bell" title="Reminder" description="Complete your profile to get started." />
 ```
 
 ---
@@ -734,28 +1322,48 @@ All sub-components (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`,
 ### EmptyState
 
 **Import:** `import { EmptyState } from '@retray-dev/ui-kit'`
-**When to use:** When a list or section has no content yet.
+
+**When to use:** When a list, section, or screen has no content. Provides a centered illustration/icon, message, and optional CTA.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| title | `string` | required | — |
-| description | `string` | — | — |
-| icon | `ReactNode` | — | Shown in a 48×48 muted square above the text |
-| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon`. Sized automatically (48 default, 32 compact) |
-| iconColor | `string` | — | Override icon color. Defaults to `mutedForeground` |
-| action | `ReactNode` | — | Usually a `Button`, placed below the text |
-| size | `'default' \| 'compact'` | `'default'` | `compact` hides description/action, uses a 36×36 icon, smaller title (15px), and tighter spacing |
+| title | `string` | required | Primary message |
+| description | `string` | — | Supporting text (hidden in `compact` size) |
+| icon | `ReactNode` | — | Icon in the top circle container |
+| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
+| iconColor | `string` | — | Override icon color. Defaults to `foregroundMuted` |
+| action | `ReactNode` | — | CTA below text — typically a `Button`. Hidden in `compact` size |
+| size | `'default' \| 'compact'` | `'default'` | `compact` is smaller, hides description and action |
 | style | `ViewStyle` | — | — |
 
-**Example:**
+**Sizes:**
+
+| Size | Icon container | Title font | Description | Action |
+|------|---------------|-----------|-------------|--------|
+| `default` | 48×48px, 12px radius | 18pt / Medium | shown | shown |
+| `compact` | 36×36px, 8px radius | 15pt / Medium | hidden | hidden |
+
+**Styling:** Centered layout, dashed border container, `surface` icon background, 32px padding.
+
+**Examples:**
 ```tsx
+// Full empty state with action
 <EmptyState
+  iconName="inbox"
   title="No notifications"
-  description="You're all caught up!"
-  action={<Button label="Refresh" variant="outline" size="sm" />}
+  description="You're all caught up! Check back later."
+  action={<Button label="Refresh" variant="secondary" size="sm" onPress={refresh} />}
 />
-<EmptyState iconName="inbox" title="No messages" description="You're all caught up." />
-<EmptyState iconName="search" title="No results" size="compact" />
+
+// Search no results
+<EmptyState
+  iconName="search"
+  title="No results for &quot;coffee&quot;"
+  description="Try a different search term."
+/>
+
+// Compact inline empty state
+<EmptyState iconName="file-text" title="No transactions" size="compact" />
 ```
 
 ---
@@ -764,18 +1372,39 @@ All sub-components (`CardHeader`, `CardTitle`, `CardDescription`, `CardContent`,
 
 **Import:** `import { Checkbox } from '@retray-dev/ui-kit'`
 
+**When to use:** Binary boolean choices in forms — terms acceptance, feature toggles, multi-select item selection.
+
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| checked | `boolean` | `false` | — |
-| onCheckedChange | `(checked: boolean) => void` | — | — |
-| label | `string` | — | Text to the right of the box |
-| disabled | `boolean` | — | — |
+| checked | `boolean` | `false` | Controlled checked state |
+| onCheckedChange | `(checked: boolean) => void` | — | Called with new boolean on press |
+| label | `string` | — | Text to the right of the checkbox |
+| disabled | `boolean` | — | Reduces opacity to 0.5, disables interaction |
 | style | `ViewStyle` | — | — |
 
-**Example:**
+**Styling:** 24×24px box, 4px border radius, 1.5px border. Checkmark: 12×7px L-shape.
+
+**Animation:** Scale spring on press (0.95).
+
+**Haptics:** `selectionAsync` on change.
+
+**Examples:**
 ```tsx
 const [accepted, setAccepted] = useState(false)
-<Checkbox checked={accepted} onCheckedChange={setAccepted} label="I agree to the terms" />
+
+<Checkbox checked={accepted} onCheckedChange={setAccepted} label="I agree to the terms and conditions" />
+<Checkbox checked={rememberMe} onCheckedChange={setRememberMe} label="Remember me" />
+<Checkbox checked={true} onCheckedChange={() => {}} label="Can't uncheck this" disabled />
+
+// Multi-select list
+{options.map((opt) => (
+  <Checkbox
+    key={opt.id}
+    checked={selected.includes(opt.id)}
+    onCheckedChange={(checked) => toggleSelected(opt.id, checked)}
+    label={opt.label}
+  />
+))}
 ```
 
 ---
@@ -783,22 +1412,47 @@ const [accepted, setAccepted] = useState(false)
 ### Switch
 
 **Import:** `import { Switch } from '@retray-dev/ui-kit'`
-**When to use:** Binary on/off settings.
+
+**When to use:** Binary on/off settings that take effect immediately — notifications, dark mode, feature flags. When the action is immediate (no form submit), prefer Switch over Checkbox.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| checked | `boolean` | `false` | — |
-| onCheckedChange | `(checked: boolean) => void` | — | — |
-| disabled | `boolean` | — | Reduces opacity to 0.45 |
+| checked | `boolean` | `false` | Controlled state |
+| onCheckedChange | `(checked: boolean) => void` | — | Called with new state on press |
+| disabled | `boolean` | — | Reduces opacity to 0.45, disables interaction |
 | style | `ViewStyle` | — | — |
 
-**Dimensions:** Track 60×36pt, Thumb 28×28pt with 4pt offset from edges (`top: 4, left: 4`). Thumb uses `position: 'absolute'` inside the track.
+**Dimensions:** Track 52×30px (pill), Thumb 24×24px with 3px offset.
 
-**Animation:** Thumb translates via spring (bounciness: 4); track color transitions via opacity timing (150ms).
+**Animation:** Thumb translates via spring; track color transitions via opacity (150ms).
 
-**Example:**
+**Haptics:** `selectionAsync` on toggle.
+
+**Examples:**
 ```tsx
 <Switch checked={notifications} onCheckedChange={setNotifications} />
+
+// In a settings row
+<ListItem
+  title="Push notifications"
+  subtitle="Get alerts for new activity"
+  rightRender={<Switch checked={push} onCheckedChange={setPush} />}
+/>
+
+// Full settings list
+{settings.map((setting) => (
+  <ListItem
+    key={setting.key}
+    title={setting.label}
+    rightRender={
+      <Switch
+        checked={prefs[setting.key]}
+        onCheckedChange={(v) => updatePref(setting.key, v)}
+      />
+    }
+    showSeparator
+  />
+))}
 ```
 
 ---
@@ -806,36 +1460,64 @@ const [accepted, setAccepted] = useState(false)
 ### Toggle
 
 **Import:** `import { Toggle } from '@retray-dev/ui-kit'`
-**When to use:** Toggleable button (e.g., bold/italic in a toolbar). Looks like a button, unlike `Switch`.
+
+**When to use:** Toggleable button that shows its active state visually — bold/italic/underline in toolbars, favorite/bookmark actions, filter toggles. Looks like a button (not a switch). Use `Switch` when a pure on/off control is needed.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| pressed | `boolean` | `false` | — |
-| onPressedChange | `(pressed: boolean) => void` | — | — |
-| variant | `'default' \| 'outline'` | `'default'` | `outline` adds a border when unpressed |
-| size | `'sm' \| 'md' \| 'lg'` | `'md'` | sm=minH 40pt, md=minH 44pt, lg=minH 48pt |
+| pressed | `boolean` | `false` | Controlled pressed state |
+| onPressedChange | `(pressed: boolean) => void` | — | Called with new state on press |
+| variant | `'default' \| 'outline'` | `'default'` | `outline` adds border when unpressed |
+| size | `'sm' \| 'md' \| 'lg'` | `'md'` | Controls minimum height and padding |
 | label | `string` | — | Text label |
-| icon | `ReactNode \| ((pressed: boolean) => ReactNode)` | — | Icon shown when not pressed — can be combined with `label` |
-| activeIcon | `ReactNode \| ((pressed: boolean) => ReactNode)` | — | Icon shown when pressed. If omitted, a default `✓` check mark is shown |
-| iconName | `string` | — | Icon name from `@expo/vector-icons` shown when not pressed. Takes precedence over `icon` |
-| activeIconName | `string` | — | Icon name shown when pressed. Takes precedence over `activeIcon` |
-| iconColor | `string` | — | Override inactive icon color. Defaults to `mutedForeground` |
-| activeIconColor | `string` | — | Override active icon color. Defaults to `primary` |
+| icon | `ReactNode \| ((pressed: boolean) => ReactNode)` | — | Icon when not pressed |
+| activeIcon | `ReactNode \| ((pressed: boolean) => ReactNode)` | — | Icon when pressed. Defaults to check-circle |
+| iconName | `string` | — | Icon name when not pressed. Takes precedence over `icon` |
+| activeIconName | `string` | — | Icon name when pressed. Takes precedence over `activeIcon` |
+| iconColor | `string` | — | Inactive icon color. Defaults to `foregroundMuted` |
+| activeIconColor | `string` | — | Active icon color. Defaults to `primary` |
+| disabled | `boolean` | — | — |
+| style | `ViewStyle` | — | — |
+
+**Sizes:**
+
+| Size | Min height | Horizontal padding | Icon size |
+|------|-----------|-------------------|-----------|
+| `sm` | 40px | 12px | 16px |
+| `md` | 44px | 16px | 18px |
+| `lg` | 48px | 20px | 20px |
 
-**Animation:** `borderColor` and `backgroundColor` animate via `Animated.timing` (150ms, `Easing.out`) on press state change. `borderWidth` stays fixed at 2pt to prevent layout jumps.
+**Animation:** `borderColor`, `backgroundColor`, `textColor` animate via `Animated.timing` (150ms) on state change. `borderWidth` stays fixed at 2pt to prevent layout shifts.
 
-**Example:**
+**Haptics:** `selectionAsync` on press.
+
+**Examples:**
 ```tsx
 <Toggle pressed={bold} onPressedChange={setBold} label="Bold" variant="outline" />
-<Toggle pressed={muted} onPressedChange={setMuted} iconName="volume-x" activeIconName="volume" />
 
-// With custom active icon (ReactNode)
+// With icon names
+<Toggle
+  pressed={muted}
+  onPressedChange={setMuted}
+  iconName="volume-x"
+  activeIconName="volume"
+/>
+
+// Bookmark
 <Toggle
-  pressed={favorited}
-  onPressedChange={setFavorited}
-  icon={<HeartIcon size={18} />}
-  activeIcon={<HeartIcon size={18} color={colors.primary} />}
+  pressed={saved}
+  onPressedChange={setSaved}
+  iconName="bookmark"
+  activeIconName="bookmark"
+  activeIconColor={colors.primary}
 />
+
+// Toolbar row
+<View style={{ flexDirection: 'row', gap: SPACING.xs }}>
+  <Toggle pressed={bold} onPressedChange={setBold} iconName="bold" variant="outline" size="sm" />
+  <Toggle pressed={italic} onPressedChange={setItalic} iconName="italic" variant="outline" size="sm" />
+  <Toggle pressed={underline} onPressedChange={setUnderline} iconName="underline" variant="outline" size="sm" />
+</View>
 ```
 
 ---
@@ -844,15 +1526,28 @@ const [accepted, setAccepted] = useState(false)
 
 **Import:** `import { RadioGroup } from '@retray-dev/ui-kit'`
 
+**When to use:** Single selection from a small set of options (2–6). When options are mutually exclusive and all should be visible simultaneously.
+
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| options | `RadioOption[]` | required | Each option: `{ label: string, value: string, disabled?: boolean }` |
+| options | `RadioOption[]` | required | `{ label: string, value: string, disabled?: boolean }` |
 | value | `string` | — | Currently selected value |
-| onValueChange | `(value: string) => void` | — | — |
-| orientation | `'vertical' \| 'horizontal'` | `'vertical'` | — |
+| onValueChange | `(value: string) => void` | — | Called on selection change |
+| orientation | `'vertical' \| 'horizontal'` | `'vertical'` | Layout direction |
 | style | `ViewStyle` | — | — |
 
-**Example:**
+**RadioOption type:**
+```ts
+{ label: string; value: string; disabled?: boolean }
+```
+
+**Styling:** Radio circle 24×24px, 1.5px border. Filled dot 10×10px when selected. 12px gap between radio and label. 8px gap between options (vertical), 16px (horizontal).
+
+**Animation:** Scale spring on press.
+
+**Haptics:** `selectionAsync` on selection.
+
+**Examples:**
 ```tsx
 <RadioGroup
   options={[
@@ -863,6 +1558,14 @@ const [accepted, setAccepted] = useState(false)
   value={plan}
   onValueChange={setPlan}
 />
+
+// Horizontal orientation
+<RadioGroup
+  options={[{ label: 'Yes', value: 'yes' }, { label: 'No', value: 'no' }]}
+  value={answer}
+  onValueChange={setAnswer}
+  orientation="horizontal"
+/>
 ```
 
 ---
@@ -870,27 +1573,47 @@ const [accepted, setAccepted] = useState(false)
 ### Select
 
 **Import:** `import { Select } from '@retray-dev/ui-kit'`
-**When to use:** Dropdown picker. Uses the native system picker UI on each platform — wheel modal on iOS (confirm with "Done"), spinner dialog on Android, native `<select>` on web (full keyboard support). Requires `@react-native-picker/picker` installed in the consuming app.
+
+**When to use:** Dropdown selection from a list too long for RadioGroup (7+ options), or options that don't need to all be visible at once. Uses platform-native picker UI.
+
+**Peer dependency:** `@react-native-picker/picker` must be installed.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| options | `SelectOption[]` | required | Each option: `{ label: string, value: string, disabled?: boolean }` |
-| value | `string` | — | Selected value |
+| options | `SelectOption[]` | required | `{ label: string, value: string, disabled?: boolean }` |
+| value | `string` | — | Currently selected value |
 | onValueChange | `(value: string) => void` | — | — |
 | placeholder | `string` | `'Select an option'` | Shown when no value is selected |
 | label | `string` | — | Label above the trigger |
-| error | `string` | — | Error text below the trigger |
+| error | `string` | — | Error text below trigger |
 | disabled | `boolean` | — | — |
-| style | `ViewStyle` | — | — |
+| style | `ViewStyle` | — | Outer container style |
+
+**Platform behavior:**
+- **iOS:** Modal sheet with wheel `Picker`, "Done" button, transparent backdrop, opens on trigger press
+- **Android:** Native dialog picker opened via `TextInput.focus()`
+- **Web:** Native HTML `<select>` element — full keyboard navigation
+
+**Styling:** 8px border radius trigger, 14px horizontal + 11px vertical padding. Error state: 2px destructive border.
+
+**Haptics:** `selectionAsync` on open and confirm.
 
-**Example:**
+**Examples:**
 ```tsx
 <Select
   label="Country"
-  options={[{ label: 'Argentina', value: 'AR' }, { label: 'Spain', value: 'ES' }]}
+  options={countries.map((c) => ({ label: c.name, value: c.code }))}
   value={country}
   onValueChange={setCountry}
-  placeholder="Pick a country"
+  placeholder="Select a country"
+/>
+
+<Select
+  label="Category"
+  options={categories}
+  value={category}
+  onValueChange={setCategory}
+  error={categoryError}
 />
 ```
 
@@ -899,37 +1622,55 @@ const [accepted, setAccepted] = useState(false)
 ### Slider
 
 **Import:** `import { Slider } from '@retray-dev/ui-kit'`
-**When to use:** Select a numeric value within a range by dragging.
+
+**When to use:** Selecting a numeric value in a continuous range by dragging — volume, brightness, price range, percentage.
+
+**Peer dependency:** `@react-native-community/slider` must be installed.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| value | `number` | `0` | — |
+| value | `number` | `0` | Controlled current value |
 | minimumValue | `number` | `0` | — |
 | maximumValue | `number` | `1` | — |
-| step | `number` | `0` | `0` means continuous (no snapping) |
+| step | `number` | `0` | `0` = continuous. Any positive number = snapping + haptic per step |
 | onValueChange | `(value: number) => void` | — | Fires while dragging |
 | onSlidingComplete | `(value: number) => void` | — | Fires on finger release |
+| label | `string` | — | Label text above slider |
+| showValue | `boolean` | `false` | Displays current value top-right |
+| formatValue | `(value: number) => string` | `toFixed(2)` | Custom display formatter |
+| accessibilityLabel | `string` | — | Screen reader label |
 | disabled | `boolean` | — | — |
-| label | `string` | — | Label text displayed above the slider |
-| showValue | `boolean` | `false` | When `true`, displays the current value at the top right |
-| formatValue | `(value: number) => string` | — | Custom formatter for the displayed value |
-| accessibilityLabel | `string` | — | Accessibility label for screen readers |
 | style | `ViewStyle` | — | — |
 
-**Notes:** Uses `@react-native-community/slider` natively — theming applied via `minimumTrackTintColor` (primary), `maximumTrackTintColor` (muted), `thumbTintColor` (primary). Requires `@react-native-community/slider` installed in the consuming app.
+**Haptics:** `selectionAsync` on each step (only when `step > 0`).
+
+**Theming:** `minimumTrackTintColor = primary`, `maximumTrackTintColor = surface`, `thumbTintColor = primary`.
 
-**Example:**
+**Examples:**
 ```tsx
 <Slider value={volume} minimumValue={0} maximumValue={100} step={1} onValueChange={setVolume} />
-<Slider 
-  label="Volume" 
-  showValue 
-  value={volume} 
-  minimumValue={0} 
-  maximumValue={100} 
+
+<Slider
+  label="Volume"
+  showValue
+  value={volume}
+  minimumValue={0}
+  maximumValue={100}
   step={5}
   formatValue={(v) => `${v}%`}
-  onValueChange={setVolume} 
+  onValueChange={setVolume}
+/>
+
+<Slider
+  label="Price range"
+  showValue
+  value={price}
+  minimumValue={50}
+  maximumValue={500}
+  step={10}
+  formatValue={(v) => `$${v}`}
+  onValueChange={setPrice}
+  onSlidingComplete={applyFilter}
 />
 ```
 
@@ -938,43 +1679,81 @@ const [accepted, setAccepted] = useState(false)
 ### Tabs
 
 **Import:** `import { Tabs, TabsContent } from '@retray-dev/ui-kit'`
-**When to use:** Switching between categorized sections on the same screen.
+
+**When to use:** Switching between categorized sections on the same screen — profile/activity/settings, different data views, content filters.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| tabs | `TabItem[]` | required | Each item: `{ label: string, value: string, icon?: ReactNode \| ((active: boolean) => ReactNode) }` |
+| tabs | `TabItem[]` | required | Tab definitions |
+| variant | `'pill' \| 'underline'` | `'pill'` | Visual style |
 | value | `string` | — | Controlled active tab |
 | onValueChange | `(value: string) => void` | — | — |
 | children | `ReactNode` | — | `TabsContent` components |
 | style | `ViewStyle` | — | — |
 
+**TabItem type:**
+```ts
+{ label: string; value: string; icon?: ReactNode | ((isActive: boolean) => ReactNode) }
+```
+
+**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.
+
 **`TabsContent` Props:**
 
 | Prop | Type | Notes |
 |------|------|-------|
 | value | `string` | Must match a tab value in `tabs` |
-| activeValue | `string` | Pass the current active tab — content is hidden when not active |
+| activeValue | `string` | Pass the current active tab — content hidden when not active |
 | children | `ReactNode` | — |
 | style | `ViewStyle` | — |
 
-**Animation:** An absolutely-positioned pill slides and resizes via spring (speed: 20, bounciness: 0) to track the active tab.
+**Animation (pill variant):** Absolutely-positioned pill slides via spring (speed: 20, bounciness: 0) to track active tab layout.
+
+**Haptics:** `selectionAsync` on tab change.
 
-**Example:**
+**Examples:**
 ```tsx
 const [tab, setTab] = useState('profile')
 
+// Pill variant (default)
 <Tabs
-  tabs={[{ label: 'Profile', value: 'profile' }, { label: 'Security', value: 'security' }]}
+  tabs={[
+    { label: 'Profile', value: 'profile' },
+    { label: 'Activity', value: 'activity' },
+    { label: 'Settings', value: 'settings' },
+  ]}
   value={tab}
   onValueChange={setTab}
 >
   <TabsContent value="profile" activeValue={tab}>
     <Text>Profile content</Text>
   </TabsContent>
-  <TabsContent value="security" activeValue={tab}>
-    <Text>Security content</Text>
+  <TabsContent value="activity" activeValue={tab}>
+    <Text>Activity content</Text>
+  </TabsContent>
+  <TabsContent value="settings" activeValue={tab}>
+    <Text>Settings content</Text>
   </TabsContent>
 </Tabs>
+
+// Underline variant with icons
+<Tabs
+  variant="underline"
+  tabs={[
+    { label: 'All', value: 'all' },
+    { label: 'Trips', value: 'trips' },
+    { label: 'Experiences', value: 'experiences' },
+  ]}
+  value={filter}
+  onValueChange={setFilter}
+/>
+
+// Content-only (no TabsContent — manage content externally)
+<Tabs tabs={tabs} value={tab} onValueChange={setTab} />
+{tab === 'profile' && <ProfileSection />}
+{tab === 'activity' && <ActivitySection />}
 ```
 
 ---
@@ -982,26 +1761,47 @@ const [tab, setTab] = useState('profile')
 ### Accordion
 
 **Import:** `import { Accordion } from '@retray-dev/ui-kit'`
-**When to use:** FAQs, collapsible sections. Animated expand/collapse.
+
+**When to use:** FAQs, expandable settings sections, collapsible help content. Animated expand/collapse.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| items | `AccordionItem[]` | required | Each: `{ value: string, trigger: string, content: ReactNode }` |
-| type | `'single' \| 'multiple'` | `'single'` | `single`: only one open at a time. `multiple`: any number can be open |
-| defaultValue | `string \| string[]` | — | Initially open item(s). Use `string[]` with `type='multiple'` |
+| items | `AccordionItem[]` | required | Accordion entries |
+| type | `'single' \| 'multiple'` | `'single'` | `single`: one item open at a time. `multiple`: any number |
+| defaultValue | `string \| string[]` | — | Initially open items. Use `string[]` with `type='multiple'` |
 | style | `ViewStyle` | — | — |
 
-**Animation:** All animation is handled exclusively by `react-native-reanimated` (`withTiming` for height/rotation, `withSpring` for press scale, `useSharedValue`, `useAnimatedStyle`) on the UI thread at 60 fps. `Easing.out(Easing.ease)` for expand, `Easing.in(Easing.ease)` for collapse (220ms). Press scale springs to 0.95 on press-in and back to 1.0 on press-out.
+**AccordionItem type:**
+```ts
+{ value: string; trigger: string; content: ReactNode }
+```
+
+**Animation:** `react-native-reanimated` `withTiming` (220ms) for height and chevron rotation (180°). Press scale uses `withSpring`. Runs on UI thread at 60fps.
+
+**Haptics:** `selectionAsync` on toggle.
 
-**Example:**
+**Examples:**
 ```tsx
 <Accordion
-  type="single"
   items={[
-    { value: 'q1', trigger: 'What is this?', content: <Text>It's a UI kit.</Text> },
-    { value: 'q2', trigger: 'Is it free?', content: <Text>Yes.</Text> },
+    {
+      value: 'q1',
+      trigger: 'What payment methods do you accept?',
+      content: <Text variant="body-sm">We accept Visa, Mastercard, and bank transfers.</Text>,
+    },
+    {
+      value: 'q2',
+      trigger: 'Can I cancel my booking?',
+      content: <Text variant="body-sm">Yes — free cancellation within 48 hours of booking.</Text>,
+    },
   ]}
 />
+
+// Multiple open simultaneously
+<Accordion type="multiple" defaultValue={['q1']} items={faqItems} />
+
+// Pre-opened
+<Accordion defaultValue="getting-started" items={helpSections} />
 ```
 
 ---
@@ -1009,66 +1809,96 @@ const [tab, setTab] = useState('profile')
 ### Sheet
 
 **Import:** `import { Sheet, BottomSheetModalProvider } from '@retray-dev/ui-kit'`
-**When to use:** Bottom sheet that automatically sizes to its content. No snap points needed — just put children inside and it fits. Powered by `@gorhom/bottom-sheet` with `enableDynamicSizing`.
 
-**Required setup** — add to your app root (see Setup section above):
-```tsx
-import { GestureHandlerRootView } from 'react-native-gesture-handler'
-import { BottomSheetModalProvider } from '@retray-dev/ui-kit'
+**When to use:** Bottom sheet for contextual actions, filters, pickers, or detail views that don't need a full screen. Auto-sizes to content — no snap points needed.
 
-<GestureHandlerRootView style={{ flex: 1 }}>
-  <BottomSheetModalProvider>
-    {/* rest of app */}
-  </BottomSheetModalProvider>
-</GestureHandlerRootView>
-```
+**Required setup** — `BottomSheetModalProvider` must wrap app at root (inside `GestureHandlerRootView`). See Setup section above.
 
-**Peer dependencies** (install in your app):
+**Peer dependencies:**
 ```bash
 pnpm add @gorhom/bottom-sheet react-native-reanimated react-native-gesture-handler react-native-worklets
 ```
-Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to your `babel.config.js` plugins.
-
-> **Important — Expo managed workflow:** Expo's install tool may downgrade `@gorhom/bottom-sheet` to an incompatible version (v4). Pin it in `app.json` to prevent this:
-> ```json
-> { "expo": { "install": { "exclude": ["@gorhom/bottom-sheet"] } } }
-> ```
+Add `react-native-worklets/plugin` (not `react-native-reanimated/plugin`) to `babel.config.js`.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | open | `boolean` | required | `true` presents the sheet, `false` dismisses it |
 | onClose | `() => void` | required | Called on swipe-dismiss or backdrop press |
-| title | `string` | — | — |
-| description | `string` | — | — |
-| children | `ReactNode` | — | — |
-| style | `ViewStyle` | — | Applied to the inner content container |
+| title | `string` | — | Sheet heading |
+| description | `string` | — | Supporting text below title |
+| children | `ReactNode` | — | Sheet content |
+| style | `ViewStyle` | — | Inner content container style |
+| scrollable | `boolean` | `false` | Wraps children in `BottomSheetScrollView` — fixes gesture conflict on both platforms when content needs to scroll |
+| maxHeight | `number` | — | Caps sheet height (dp). Automatically enables scrolling when content exceeds this value |
+
+**Features:**
+- `enableDynamicSizing` — height auto-fits content, no `snapPoints` needed
+- `enablePanDownToClose` — swipe down to dismiss
+- Backdrop press dismisses
+- **Scrollable content:** use `scrollable` prop (explicit) or `maxHeight` prop (capped height). Both use `BottomSheetScrollView` internally — do NOT use plain `ScrollView` inside Sheet, it breaks gesture handling on iOS
+
+**Styling:** `RADIUS.lg = 20px` top corners, 16px horizontal + 20px bottom padding.
 
-**Example:**
+**Haptics:** `impactLight` on open.
+
+**Examples:**
 ```tsx
-<Sheet open={open} onClose={() => setOpen(false)} title="Filters">
-  <RadioGroup options={sortOptions} value={sort} onValueChange={setSort} />
+const [open, setOpen] = useState(false)
+
+<Sheet open={open} onClose={() => setOpen(false)} title="Sort by">
+  <RadioGroup
+    options={[
+      { label: 'Newest', value: 'newest' },
+      { label: 'Price: Low to High', value: 'price_asc' },
+      { label: 'Price: High to Low', value: 'price_desc' },
+      { label: 'Rating', value: 'rating' },
+    ]}
+    value={sort}
+    onValueChange={(v) => { setSort(v); setOpen(false) }}
+  />
 </Sheet>
-```
 
-**Notes:**
-- Height is calculated automatically from content via `enableDynamicSizing` (gorhom v5 feature). No `snapPoints` prop.
-- Swipe down to dismiss (`enablePanDownToClose`). Backdrop press also dismisses.
-- `impactAsync(Light)` haptic fires on open.
+// Scrollable sheet — long list
+<Sheet open={open} onClose={() => setOpen(false)} title="Logs" scrollable>
+  {logs.map((log) => (
+    <Text key={log.id}>{log.message}</Text>
+  ))}
+</Sheet>
+
+// Capped height — scroll kicks in when content overflows 400dp
+<Sheet open={open} onClose={() => setOpen(false)} title="Results" maxHeight={400}>
+  {results.map((r) => <ListItem key={r.id} title={r.name} />)}
+</Sheet>
+
+// Filter sheet
+<Sheet open={filterOpen} onClose={() => setFilterOpen(false)} title="Filters">
+  <View style={{ gap: SPACING.lg }}>
+    <View>
+      <Text variant="title-sm">Price range</Text>
+      <Slider value={maxPrice} minimumValue={0} maximumValue={1000} step={50} onValueChange={setMaxPrice} showValue formatValue={(v) => `$${v}`} />
+    </View>
+    <Separator />
+    <View>
+      <Text variant="title-sm">Category</Text>
+      <ChipGroup options={categoryOptions} value={selectedCategory} onValueChange={setSelectedCategory} />
+    </View>
+    <Button label="Apply filters" fullWidth onPress={() => { applyFilters(); setFilterOpen(false) }} />
+  </View>
+</Sheet>
+```
 
 ---
 
 ### Toast / useToast
 
 **Import:** `import { ToastProvider, useToast } from '@retray-dev/ui-kit'`
-**When to use:** Ephemeral feedback messages (save success, network error, copy confirmation).
 
-**Required setup** — `ToastProvider` must wrap your app inside `SafeAreaProvider` (see Setup section above).
+**When to use:** Ephemeral feedback messages — save confirmations, errors, copy notifications, background process updates. Auto-dismiss after duration.
 
-**Peer dependency:** `react-native-safe-area-context` — required for `useSafeAreaInsets` inside `ToastProvider`.
+**Required setup:** `ToastProvider` must wrap app inside `SafeAreaProvider`. See Setup section above.
 
+**Usage:**
 ```tsx
-import { useToast } from '@retray-dev/ui-kit'
-
 function MyComponent() {
   const { toast, dismiss } = useToast()
 
@@ -1077,10 +1907,7 @@ function MyComponent() {
       label="Save"
       onPress={async () => {
         await save()
-        toast({ title: 'Saved', description: 'Your changes were saved.', variant: 'success' })
-        // With custom icon name
-        toast({ title: 'Saved', variant: 'success', iconName: 'check-circle' })
-        toast({ title: 'Oops', variant: 'destructive', iconName: 'x-circle' })
+        toast({ title: 'Saved', variant: 'success' })
       }}
     />
   )
@@ -1092,90 +1919,223 @@ function MyComponent() {
 | Field | Type | Default | Notes |
 |-------|------|---------|-------|
 | title | `string` | — | Bold heading |
-| description | `string` | — | Detail text |
-| variant | `'default' \| 'destructive' \| 'success'` | `'default'` | `default`: dark background. `destructive`: red. `success`: green |
-| duration | `number` (ms) | `3000` | Auto-dismiss after this delay |
-| icon | `ReactNode` | — | Custom icon node. Defaults to a variant-appropriate symbol (`✓`, `✖`, `ℹ`) at 22px |
+| description | `string` | — | Detail text below title |
+| variant | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` | Background and icon color |
+| duration | `number` (ms) | `3000` | Auto-dismiss delay. Pass `Infinity` to prevent auto-dismiss |
+| icon | `ReactNode` | — | Custom icon. Defaults to variant symbol |
 | iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
-| iconColor | `string` | — | Override icon color. Defaults to variant text color |
+| iconColor | `string` | — | Override icon color |
+| action | `{ label: string, onPress: () => void }` | — | Optional action button beside dismiss |
+
+**`dismiss(id)`:** Dismiss a specific toast programmatically. `id` is returned by the `toast()` call.
+
+**Variant details:**
+- `default` — dark/primary background, `impactLight` haptic
+- `success` — `success` token background, `notificationSuccess` haptic
+- `destructive` — `destructive` token background, `notificationError` haptic
+- `warning` — `warning` token background, `notificationError` haptic
+
+**Behavior:**
+- Max 3 toasts shown simultaneously — oldest removed when 4th arrives
+- Appear at top of screen below status bar (dynamic safe area inset)
+- Swipe left or right to dismiss early (threshold: 80px or 800pt/s velocity)
+- **Web:** 400px max width, centered
+
+**Animation:** Entrance: `withTiming(120ms, Easing.out(Easing.exp))` slide-down + opacity. Exit: `withTiming(200ms)` slide-up + opacity fade.
+
+**Examples:**
+```tsx
+const { toast, dismiss } = useToast()
+
+// Basic variants
+toast({ title: 'Saved', variant: 'success' })
+toast({ title: 'Connection error', variant: 'destructive' })
+toast({ title: 'Check your email', variant: 'warning' })
+toast({ title: 'Link copied' })
+
+// With description
+toast({
+  title: 'Payment sent',
+  description: '$250 sent to John Doe',
+  variant: 'success',
+  iconName: 'check-circle',
+})
+
+// With action button
+toast({
+  title: 'Message deleted',
+  action: { label: 'Undo', onPress: () => restoreMessage() },
+})
+
+// Custom duration (longer)
+toast({ title: 'Processing your request...', duration: 8000 })
+
+// Programmatic dismiss
+const id = toast({ title: 'Uploading...', duration: Infinity })
+await upload()
+dismiss(id)
+toast({ title: 'Upload complete', variant: 'success' })
+```
 
-**`dismiss(id)`:** Dismiss a toast programmatically. The `id` is returned by the `toast()` call — store it if you need programmatic dismissal.
+---
+
+### ConfirmDialog
+
+**Import:** `import { ConfirmDialog } from '@retray-dev/ui-kit'`
+
+**When to use:** Confirmation prompts before irreversible or destructive actions — delete, send money, discard changes. Always confirm before actions that can't be undone.
+
+**Requires:** `BottomSheetModalProvider` at app root (same as `Sheet`).
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| visible | `boolean` | required | Controls dialog visibility |
+| title | `string` | required | Dialog heading |
+| description | `string` | — | Supporting text — describe what exactly will happen |
+| confirmLabel | `string` | `'Confirm'` | Confirm button text |
+| cancelLabel | `string` | `'Cancel'` | Cancel button text |
+| confirmVariant | `'primary' \| 'destructive'` | `'primary'` | Use `'destructive'` for delete/remove actions |
+| onConfirm | `() => void` | required | Called when confirm is tapped |
+| onCancel | `() => void` | required | Called when cancel is tapped or backdrop pressed |
 
 **Notes:**
-- Max 3 toasts shown simultaneously (oldest is removed when a 4th arrives)
-- Toasts appear at the top of the screen, below the status bar (dynamic safe area inset)
-- **On web:** constrained to 400px wide and centered (`alignSelf: 'center'`) — not full-width
-- Entrance: `withTiming(120ms, Easing.out(Easing.exp))` slide-down + opacity fade — fast, sharp feel
-- Exit: `withTiming(200ms)` slide-up + opacity fade
-- Swipe left or right to dismiss early (threshold: 80px or 800 pt/s velocity)
+- Powered by `@gorhom/bottom-sheet` with `enableDynamicSizing`
+- Buttons are full-width, stacked vertically (confirm on top)
+- Cancel shows X icon, confirm shows check (primary) or trash-2 (destructive) icon
+- Swipe down or backdrop press calls `onCancel`
+
+**Haptics:** `impactLight` on open.
+
+**Examples:**
+```tsx
+// Delete confirmation
+<ConfirmDialog
+  visible={showDelete}
+  title="Delete transaction?"
+  description="$45.000 · Mercado · 12 mar · This action cannot be undone."
+  confirmLabel="Delete"
+  confirmVariant="destructive"
+  onConfirm={handleDelete}
+  onCancel={() => setShowDelete(false)}
+/>
+
+// Send money confirmation
+<ConfirmDialog
+  visible={showConfirm}
+  title="Send payment?"
+  description={`Send $${amount} to ${recipientName}`}
+  confirmLabel="Send"
+  onConfirm={handleSend}
+  onCancel={() => setShowConfirm(false)}
+/>
+
+// Discard changes
+<ConfirmDialog
+  visible={showDiscard}
+  title="Discard changes?"
+  description="All unsaved changes will be lost."
+  confirmLabel="Discard"
+  confirmVariant="destructive"
+  onConfirm={() => { setShowDiscard(false); goBack() }}
+  onCancel={() => setShowDiscard(false)}
+/>
+```
 
 ---
 
 ### ListItem
 
 **Import:** `import { ListItem } from '@retray-dev/ui-kit'`
-**When to use:** Rows in a list, feed, or menu. Composes a left slot (avatar, icon, image), title/subtitle/caption text block, and a right slot (price, badge, chevron, switch, etc.) in a standard horizontal layout. Supports both plain and card visual variants.
+
+**When to use:** Rows in lists, feeds, menus, settings screens. The most compositional component — composes left slot, text block, and right slot in a standard horizontal layout. Supports plain (list items) and card (standalone cards) variants.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| title | `string` | required | Primary text (17px / 500 weight) |
-| subtitle | `string` | — | Secondary line below the title (14px / 400 weight) |
-| caption | `string` | — | Tertiary / caption line below the subtitle (12px / 400 weight, 70% opacity) |
-| leftRender | `ReactNode` | — | Arbitrary content in a fixed 44×44pt left slot (avatar, icon, image, etc.) |
-| rightRender | `string \| ReactNode` | — | Content on the right edge. Strings are styled as muted text (15px); pass ReactNode for Badges, prices, switches, etc. |
-| leftIcon | `string` | — | Icon name from `@expo/vector-icons` in the left slot. Takes precedence over `leftRender`. Size 24, color `foreground` |
-| rightIcon | `string` | — | Icon name from `@expo/vector-icons` in the right slot. Takes precedence over `rightRender`. Size 24, color `mutedForeground` |
-| leftIconColor | `string` | — | Override left icon color |
-| rightIconColor | `string` | — | Override right icon color |
-| variant | `'plain' \| 'card'` | `'plain'` | `plain`: no background, sits inside a parent surface. `card`: standalone surface with background, border, and shadow |
-| showChevron | `boolean` | `false` | Shows a `›` chevron on the far right. Ignored when `rightRender` is set |
-| showSeparator | `boolean` | `false` | Renders a hairline separator at the bottom. Useful when stacking multiple plain items in a list |
-| onPress | `() => void` | — | Makes the row pressable (scale spring + haptics). No animation or haptics when omitted |
+| title | `string` | required | Primary text |
+| subtitle | `string` | — | Secondary line below title |
+| caption | `string` | — | Tertiary line below subtitle |
+| leftRender | `ReactNode` | — | Content in the fixed 44×44pt left slot |
+| rightRender | `string \| ReactNode` | — | Content on the right edge. Strings auto-styled as muted text |
+| leftIcon | `string` | — | Icon name for left slot. Takes precedence over `leftRender` |
+| rightIcon | `string` | — | Icon name for right slot. Takes precedence over `rightRender` |
+| leftIconColor | `string` | — | Override left icon color (default: `foreground`) |
+| rightIconColor | `string` | — | Override right icon color (default: `foregroundMuted`) |
+| variant | `'plain' \| 'card'` | `'plain'` | `plain`: no background. `card`: surface with border and shadow |
+| showChevron | `boolean` | `false` | Right-pointing chevron. Ignored when `rightRender` is set |
+| showSeparator | `boolean` | `false` | Hairline separator at bottom. Useful for stacking plain items |
+| onPress | `() => void` | — | Makes row pressable (scale animation + haptics) |
 | disabled | `boolean` | — | Reduces opacity to 0.45 |
-| style | `ViewStyle` | — | Style applied to the outer container |
-| titleStyle | `TextStyle` | — | Style override for the title text |
-| subtitleStyle | `TextStyle` | — | Style override for the subtitle text |
-| captionStyle | `TextStyle` | — | Style override for the caption text |
+| style | `ViewStyle` | — | Outer container style |
+| titleStyle | `TextStyle` | — | Override title text style |
+| subtitleStyle | `TextStyle` | — | Override subtitle text style |
+| captionStyle | `TextStyle` | — | Override caption text style |
 | icon | `ReactNode` | — | **Deprecated** — use `leftRender` |
 | trailing | `string \| ReactNode` | — | **Deprecated** — use `rightRender` |
 
-**Animation:** Scale springs to 0.97 on press-in, back to 1.0 on press-out (only when `onPress` is provided).
+**Slots:**
+- `leftRender` / `leftIcon` — 44×44pt fixed container, centered. Good for Avatar, icons, thumbnails
+- `rightRender` / `rightIcon` — max 160pt wide, right-aligned. Good for Badge, price text, Switch
+- `showChevron` — `›` chevron, 24pt, `foregroundMuted` color. Only shows when `rightRender` is absent
+
+**Separator inset:** Aligns to text block — `marginLeft` adjusts to skip over left slot when present.
+
+**Animation:** Scale springs to 0.97 on press (subtler than Button's 0.95).
 
-**Example:**
+**Haptics:** `selectionAsync` on press.
+
+**Examples:**
 ```tsx
-// Simple row with chevron
+// Simple settings row
+<ListItem title="Profile" showChevron onPress={() => navigate('profile')} />
+
+// With subtitle and chevron
 <ListItem
-  title="Profile"
-  subtitle="Manage your account"
+  title="Notifications"
+  subtitle="Push, email, and SMS"
   showChevron
-  onPress={() => navigate('profile')}
+  onPress={() => navigate('notifications')}
 />
 
-// Rich row: avatar + title/subtitle/caption + price + badge
+// Icon left slot + chevron
+<ListItem title="Profile" leftIcon="user" showChevron onPress={() => navigate('profile')} />
+
+// Icon left + badge right
 <ListItem
-  leftRender={<Avatar src={item.avatar} fallback={item.initials} size="md" />}
-  title={item.name}
-  subtitle={item.date}
-  caption={item.category}
+  leftIcon="bell"
+  title="Notifications"
+  subtitle="3 unread"
+  rightRender={<Badge label="3" variant="destructive" size="sm" />}
+  onPress={() => navigate('notifications')}
+/>
+
+// Avatar + full text stack + right content
+<ListItem
+  leftRender={<Avatar src={user.avatar} fallback={user.initials} status="online" />}
+  title={user.name}
+  subtitle={user.role}
+  caption="Active 2 min ago"
   rightRender={
     <View style={{ alignItems: 'flex-end', gap: 4 }}>
-      <Text variant="label">${item.amount}</Text>
-      <Badge label={item.status} variant="secondary" size="sm" />
+      <Text variant="title-sm">${amount}</Text>
+      <Badge label={status} variant="warningOutline" size="sm" />
     </View>
   }
-  onPress={() => navigate('detail', { id: item.id })}
+  onPress={() => navigate('user', { id: user.id })}
 />
 
-// Icon name props (no manual imports needed)
-<ListItem title="Profile" leftIcon="user" rightIcon="chevron-right" onPress={() => {}} />
-<ListItem title="Notifications" leftIcon="bell" subtitle="3 unread" showChevron />
+// Switch in right slot
+<ListItem
+  leftIcon="moon"
+  title="Dark mode"
+  rightRender={<Switch checked={darkMode} onCheckedChange={setDarkMode} />}
+/>
 
 // Card variant (standalone surface)
 <ListItem
   variant="card"
   leftIcon="credit-card"
-  title="Balance"
-  subtitle="Available funds"
+  title="Checking account"
+  subtitle="Available balance"
   rightRender="$12.500"
 />
 
@@ -1183,114 +2143,173 @@ function MyComponent() {
 {transactions.map((t, i) => (
   <ListItem
     key={t.id}
-    title={t.name}
+    leftRender={<Avatar fallback={t.merchant[0]} size="sm" />}
+    title={t.merchant}
     subtitle={t.date}
-    rightRender={t.amount}
+    rightRender={
+      <Text variant="title-sm" color={t.amount < 0 ? colors.destructive : colors.success}>
+        {t.amount < 0 ? '-' : '+'}${Math.abs(t.amount)}
+      </Text>
+    }
     showSeparator={i < transactions.length - 1}
-    onPress={() => navigate('detail', { id: t.id })}
+    onPress={() => navigate('transaction', { id: t.id })}
   />
 ))}
 ```
 
-**Notes:**
-- `leftRender` renders inside a fixed 44×44pt container (centered) — no need to wrap in a sized View
-- `rightRender` container has `maxWidth: 160` and aligns content to the right edge
-- The separator inset aligns to the text block: `marginLeft: 16 + 44 + 12` when `leftRender` is set, `marginLeft: 16` otherwise
-
 ---
 
 ### Chip / ChipGroup
 
 **Import:** `import { Chip, ChipGroup } from '@retray-dev/ui-kit'`
-**When to use:** Filter pills, single-select options displayed inline. Use `ChipGroup` for managed single-selection; use `Chip` standalone for custom logic.
+
+**When to use:** Inline filter options, quick selections, multi-select toggles. Use `Chip` for standalone custom logic; use `ChipGroup` for managed selection (single or multi).
 
 **`Chip` Props:**
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
 | label | `string` | required | — |
-| selected | `boolean` | `false` | Controls fill color |
+| selected | `boolean` | `false` | Controls fill style |
 | onPress | `() => void` | — | — |
-| icon | `ReactNode` | — | Custom icon rendered before the label |
-| iconName | `string` | — | Icon name from `@expo/vector-icons`. Takes precedence over `icon` |
+| icon | `ReactNode` | — | Custom icon before label |
+| iconName | `string` | — | Icon name. Takes precedence over `icon` |
 | style | `ViewStyle` | — | — |
 
 **`ChipGroup` Props:**
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| options | `ChipOption[]` | required | Each: `{ label: string, value: string \| number }` |
-| value | `string \| number \| (string \| number)[]` | — | Currently selected value (single mode) or array of selected values (multi mode) |
-| onValueChange | `(value: string \| number \| (string \| number)[]) => void` | — | — |
-| multiSelect | `boolean` | `false` | When `true`, allows multiple chips to be selected simultaneously |
-| style | `ViewStyle` | — | Applied to the wrapping row |
+| options | `ChipOption[]` | required | `{ label: string, value: string \| number }` |
+| value | `string \| number \| (string \| number)[]` | — | Selected value(s) |
+| onValueChange | `(value: ...) => void` | — | Returns single value or array depending on `multiSelect` |
+| multiSelect | `boolean` | `false` | Allow multiple chips selected simultaneously |
+| style | `ViewStyle` | — | Wrapping row style |
+
+**Styling:** Pill-shaped (borderRadius: 9999), 14px horizontal + 5px vertical padding, 1px border. Unselected: `surface` bg / `foreground` text / `border` border. Selected: `primary` bg / `primaryForeground` text / `primary` border.
 
-**Animation:** Background, text, and border colors animate via `Animated.timing` (150ms) between unselected (`secondary`/`border`/`foreground`) and selected (`primary`/`primary`/`primaryForeground`) states.
+**Animation:** Spring scale 0.95 on press; background/text/border color transitions (150ms timing) on selection change.
 
-**Example:**
+**Haptics:** `selectionAsync` on change.
+
+**Examples:**
 ```tsx
-// Single select
+// Single select percentage
 const [pct, setPct] = useState(50)
-
 <ChipGroup
-  options={[
-    { label: '40%', value: 40 },
-    { label: '50%', value: 50 },
-    { label: '100%', value: 100 },
-  ]}
+  options={[{ label: '25%', value: 25 }, { label: '50%', value: 50 }, { label: '100%', value: 100 }]}
   value={pct}
   onValueChange={setPct}
 />
 
-// Multi select
+// Multi select categories
 const [categories, setCategories] = useState<number[]>([1, 3])
-
 <ChipGroup
   multiSelect
   options={[
     { label: 'Food', value: 1 },
     { label: 'Transport', value: 2 },
     { label: 'Entertainment', value: 3 },
+    { label: 'Health', value: 4 },
   ]}
   value={categories}
   onValueChange={setCategories}
 />
+
+// Standalone chips (custom logic)
+<View style={{ flexDirection: 'row', gap: SPACING.sm, flexWrap: 'wrap' }}>
+  {filters.map((f) => (
+    <Chip
+      key={f.value}
+      label={f.label}
+      selected={activeFilter === f.value}
+      onPress={() => setActiveFilter(f.value)}
+    />
+  ))}
+</View>
 ```
 
 ---
 
-### ConfirmDialog
+### CategoryStrip
 
-**Import:** `import { ConfirmDialog } from '@retray-dev/ui-kit'`
-**When to use:** Confirmation prompts before irreversible or destructive actions (delete, send, discard).
+**Import:** `import { CategoryStrip } from '@retray-dev/ui-kit'`
+
+**When to use:** Horizontal scrollable filter/category bar at the top of browse screens — marketplace categories, content type filters, location tabs. Airbnb-style pill chips that scroll horizontally.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| visible | `boolean` | required | Controls modal visibility |
-| title | `string` | required | Dialog heading |
-| description | `string` | — | Supporting text below the title |
-| confirmLabel | `string` | `'Confirm'` | Label for the confirm button |
-| cancelLabel | `string` | `'Cancel'` | Label for the cancel button |
-| confirmVariant | `'primary' \| 'destructive'` | `'primary'` | Button variant for the confirm action |
-| onConfirm | `() => void` | required | Called when confirm is tapped |
-| onCancel | `() => void` | required | Called when cancel is tapped or backdrop is pressed |
+| categories | `CategoryItem[]` | required | Category definitions |
+| value | `string \| string[]` | — | Selected category value(s) |
+| onValueChange | `(value: string \| string[]) => void` | — | Called with new selection |
+| multiSelect | `boolean` | `false` | Allow multiple simultaneous selections |
+| style | `ViewStyle` | — | ScrollView content container style |
+| itemStyle | `ViewStyle` | — | Style applied to each chip's wrapper |
+
+**CategoryItem type:**
+```ts
+{
+  label: string
+  value: string
+  icon?: ReactNode | string   // Icon or icon name (16px, auto-colored)
+  badge?: number              // Count badge on chip, capped at 99
+}
+```
 
-**Notes:**
-- Powered by `@gorhom/bottom-sheet` with `enableDynamicSizing` — height auto-fits content, no snap points.
-- Swipe down or tap backdrop to cancel (calls `onCancel`).
-- Cancel and confirm buttons are full-width stacked vertically.
-- Requires `BottomSheetModalProvider` at app root (same as `Sheet`).
+**Single select behavior:** Pressing selected item again deselects it (value becomes `''`).
+
+**Multi select behavior:** Toggles item in/out of value array.
 
-**Example:**
+**Styling:** Pill-shaped chips (`borderRadius: RADIUS.full = 9999`), 14px horizontal + 8px vertical padding, 8px gap between chips. Selected: `primary` bg + `primaryForeground` text. Unselected: `surface` bg + `foregroundSubtle` text + `border` border.
+
+**Animation:** Scale spring 0.95 on press.
+
+**Haptics:** `selectionAsync` on change.
+
+**Web:** Horizontal scroll with `showsHorizontalScrollIndicator={false}`.
+
+**Examples:**
 ```tsx
-<ConfirmDialog
-  visible={showDelete}
-  title="¿Eliminar gasto?"
-  description="$45.000 · Mercado · 12 mar"
-  confirmLabel="Eliminar"
-  confirmVariant="destructive"
-  onConfirm={handleDelete}
-  onCancel={() => setShowDelete(false)}
+// Basic category filter
+<CategoryStrip
+  categories={[
+    { label: 'All', value: '' },
+    { label: 'Trips', value: 'trips' },
+    { label: 'Experiences', value: 'experiences' },
+    { label: 'Restaurants', value: 'restaurants' },
+  ]}
+  value={category}
+  onValueChange={setCategory}
+/>
+
+// With icons
+<CategoryStrip
+  categories={[
+    { label: 'Nearby', value: 'nearby', icon: 'map-pin' },
+    { label: 'Popular', value: 'popular', icon: 'trending-up' },
+    { label: 'New', value: 'new', icon: 'star' },
+  ]}
+  value={filter}
+  onValueChange={setFilter}
+/>
+
+// With badge counts
+<CategoryStrip
+  categories={[
+    { label: 'Inbox', value: 'inbox', badge: 3 },
+    { label: 'Sent', value: 'sent' },
+    { label: 'Archived', value: 'archived' },
+  ]}
+  value={tab}
+  onValueChange={setTab}
+/>
+
+// Multi-select
+<CategoryStrip
+  multiSelect
+  categories={amenities}
+  value={selectedAmenities}
+  onValueChange={setSelectedAmenities}
 />
 ```
 
@@ -1299,19 +2318,32 @@ const [categories, setCategories] = useState<number[]>([1, 3])
 ### LabelValue
 
 **Import:** `import { LabelValue } from '@retray-dev/ui-kit'`
-**When to use:** Key-value display rows in receipts, summaries, and detail screens. Label on the left (muted caption), value on the right (medium weight).
+
+**When to use:** Key-value display rows in receipts, transaction details, order summaries, profile information. Label on left (muted caption), value on right (medium weight).
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| label | `string` | required | Caption text on the left |
-| value | `string \| ReactNode` | required | Value on the right. Strings are auto-styled; pass `ReactNode` for custom rendering |
+| label | `string` | required | Caption label on the left |
+| value | `string \| ReactNode` | required | Value on the right. Strings auto-styled; pass `ReactNode` for custom content |
 | style | `ViewStyle` | — | — |
 
-**Example:**
+**Styling:** Row layout, `justifyContent: 'space-between'`. Label: 13pt / Regular / `foregroundMuted`. Value: 14pt / Medium / `foreground`. 12px gap.
+
+**Examples:**
 ```tsx
-<LabelValue label="Fecha" value="12 mar 2025" />
-<LabelValue label="Categoría" value="Mercado" />
-<LabelValue label="Estado" value={<Badge label="Pendiente" variant="secondary" />} />
+<LabelValue label="Date" value="12 mar 2025" />
+<LabelValue label="Category" value="Food & drink" />
+<LabelValue label="Status" value={<Badge label="Pending" variant="warningOutline" size="sm" />} />
+<LabelValue label="Amount" value="$45.000" />
+
+// Transaction detail
+<View style={{ gap: SPACING.sm }}>
+  <LabelValue label="Merchant" value={transaction.merchant} />
+  <LabelValue label="Date" value={formatDate(transaction.date)} />
+  <LabelValue label="Category" value={transaction.category} />
+  <Separator />
+  <LabelValue label="Amount" value={`$${transaction.amount}`} />
+</View>
 ```
 
 ---
@@ -1319,42 +2351,121 @@ const [categories, setCategories] = useState<number[]>([1, 3])
 ### MonthPicker
 
 **Import:** `import { MonthPicker } from '@retray-dev/ui-kit'`
-**When to use:** Compact month/year selector with previous/next navigation. Common in finance apps for filtering by period.
+
+**When to use:** Month/year navigation — finance apps filtering by period, date pickers, reporting periods. Compact left/right navigation UI.
 
 | Prop | Type | Default | Notes |
 |------|------|---------|-------|
-| value | `MonthPickerValue` | required | `{ month: number, year: number }` — `month` is 1–12 |
-| onChange | `(value: MonthPickerValue) => void` | required | Called on each navigation step |
+| value | `MonthPickerValue` | required | `{ month: 1–12, year: number }` |
+| onChange | `(value: MonthPickerValue) => void` | required | Called on navigation |
 | style | `ViewStyle` | — | — |
 
-**`MonthPickerValue`:** `{ month: number, year: number }` — month is 1-indexed (January = 1).
+**MonthPickerValue type:**
+```ts
+{ month: number; year: number }  // month is 1-indexed (January = 1)
+```
+
+**Navigation:** Year wraps correctly at boundaries (December → January increments year, January → December decrements year). Fully controlled — no internal state.
 
-**Navigation:** Arrows wrap correctly at year boundaries (December → January increments the year; January → December decrements it). The component is fully controlled — no internal state.
+**Styling:** Centered row with `←` / `→` buttons (44×44px each). Label: 17pt / Medium / 160px min-width, centered.
 
-**Example:**
+**Haptics:** `selectionAsync` on navigation.
+
+**Examples:**
 ```tsx
-const [period, setPeriod] = useState({ month: new Date().getMonth() + 1, year: new Date().getFullYear() })
+const [period, setPeriod] = useState({
+  month: new Date().getMonth() + 1,
+  year: new Date().getFullYear(),
+})
 
 <MonthPicker value={period} onChange={setPeriod} />
-// Displays: "April 2026"
+// Displays: "May 2026"
+
+// In a transactions header
+<View style={{ flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center' }}>
+  <Text variant="display-md">Transactions</Text>
+  <MonthPicker value={period} onChange={setPeriod} />
+</View>
 ```
 
 ---
 
-## Icon System
+### Pressable
 
-The library ships a built-in icon resolver so you can pass a plain icon name string to any component — no manual imports, no size guessing, no color math.
+**Import:** `import { Pressable } from '@retray-dev/ui-kit'`
 
-### Supported families
+**When to use:** Custom interactive content that needs beautiful spring bounce effect matching MediaCard. Use when you need a pressable wrapper around custom layouts that aren't covered by existing button components.
 
-Icons are resolved by checking each family's glyph map in priority order (first match wins):
+**Extends:** `TouchableOpacityProps` (all native props pass through except `activeOpacity`)
+
+| Prop | Type | Default | Notes |
+|------|------|---------|-------|
+| children | `ReactNode` | required | Content to render inside the pressable |
+| onPress | `() => void` | — | Press handler |
+| pressScale | `number` | `0.98` | Scale value on press (MediaCard-style) |
+| bounciness | `number` | `4` | Spring bounciness on release |
+| haptics | `boolean` | `true` | Enable haptic feedback on press |
+| hoverScale | `number` | `1.02` | Hover scale (web only). Set to `1` to disable |
+| disabled | `boolean` | `false` | Disable interaction |
+| style | `ViewStyle` | — | Animated wrapper style |
+
+**Behavior:**
+- Press: springs to `pressScale` (default 0.98) with `speed: 40, bounciness: 0`
+- Release: springs back to 1.0 with `speed: 40, bounciness: 4`
+- Web: optional hover scale (default 1.02)
+- Haptics: `impactLight` on press (unless `haptics={false}`)
+
+**Use cases:**
+- Custom card layouts
+- Complex pressable rows that need consistent feel
+- Non-standard interactive elements that aren't buttons
+- Wrapping groups of elements as a single pressable unit
+
+**Examples:**
+```tsx
+// Custom card
+<Pressable onPress={() => navigate('detail')} style={{ padding: 16, borderRadius: 12, backgroundColor: colors.card }}>
+  <Text variant="title-md">Custom Card</Text>
+  <Text variant="body-sm">Press me for beautiful bounce effect</Text>
+</Pressable>
+
+// Wrapping complex layout
+<Pressable onPress={handleSelect} pressScale={0.96} bounciness={8}>
+  <View style={{ flexDirection: 'row', alignItems: 'center', gap: 12, padding: 16 }}>
+    <Avatar src={user.avatar} size="md" />
+    <View style={{ flex: 1 }}>
+      <Text variant="title-sm">{user.name}</Text>
+      <Text variant="caption-sm">{user.role}</Text>
+    </View>
+    <Icon name="chevron-right" size={20} color={colors.foregroundMuted} />
+  </View>
+</Pressable>
+
+// Disable haptics
+<Pressable onPress={handleQuickAction} haptics={false}>
+  {/* content */}
+</Pressable>
+
+// Custom press scale (deeper press)
+<Pressable onPress={handlePress} pressScale={0.92} bounciness={6}>
+  {/* content */}
+</Pressable>
+```
+
+---
+
+## 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 of named icons |
+| 4 | `FontAwesome5` | Wide coverage |
 | 5 | `MaterialIcons` | Material-style icons |
 | 6 (lowest) | `Ionicons` | Fallback |
 
@@ -1365,87 +2476,119 @@ Browse all available icons: **https://icons.expo.fyi**
 ```tsx
 import { Icon } from '@retray-dev/ui-kit'
 
-<Icon name="home" size={24} color="#000" />
+<Icon name="home" size={24} color={colors.foreground} />
 <Icon name="star" size={20} color={colors.primary} />
 
-// Force a specific family when the same name exists in multiple families:
+// Force a specific family when same name exists in multiple families:
 <Icon name="heart" size={24} color="red" family="FontAwesome5" />
 ```
 
 **Props:**
 
-| Prop | Type | Required | Description |
-|---|---|---|---|
-| `name` | `string` | Yes | Icon name (e.g. `"home"`, `"star"`, `"arrow-right"`) |
-| `size` | `number` | Yes | Icon size in points |
-| `color` | `string` | Yes | Icon color |
-| `family` | `IconFamily` | No | Override resolved family |
+| 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 the icon name is not found in any family.
+Returns `null` (no crash) if name not found in any family.
 
 ### `renderIcon` helper
 
 ```tsx
 import { renderIcon } from '@retray-dev/ui-kit'
 
-const node = renderIcon('check', 18, colors.primary)
+// Returns ReactNode or null
+const icon = renderIcon('check', 18, colors.primary)
 ```
 
 ### `iconName` props on components
 
-Each component that accepts icon slots now has a corresponding `iconName` prop. Pass the icon name as a string and the library resolves size and color automatically.
+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.
 
-| Component | Prop(s) | Slot | Default size | Default color |
-|---|---|---|---|---|
-| `Button` | `iconName`, `iconColor` | Left or right of label | sm=16 / md=18 / lg=20 | Variant label color |
-| `IconButton` | `iconName`, `iconColor` | Center (icon-only) | sm=18 / md=20 / lg=24 | Variant foreground color |
-| `Input` | `prefixIcon`, `prefixIconColor` | Before input text | 20 | `mutedForeground` |
-| `Input` | `suffixIcon`, `suffixIconColor` | After input text | 20 | `mutedForeground` |
-| `ListItem` | `leftIcon`, `leftIconColor` | Left 44×44 slot | 24 | `foreground` |
-| `ListItem` | `rightIcon`, `rightIconColor` | Right slot | 24 | `mutedForeground` |
-| `Badge` | `iconName`, `iconColor` | Before label | sm=10 / md=12 / lg=14 | Variant foreground |
-| `Toggle` | `iconName`, `iconColor` | When not pressed | sm=16 / md=18 / lg=20 | `mutedForeground` |
-| `Toggle` | `activeIconName`, `activeIconColor` | When pressed | sm=16 / md=18 / lg=20 | `primary` |
-| `AlertBanner` | `iconName`, `iconColor` | Left of content | 18 | Variant title color |
-| `EmptyState` | `iconName`, `iconColor` | Center icon slot | default=48 / compact=32 | `mutedForeground` |
-| `Toast` | `iconName`, `iconColor` | Left of message | 22 | Variant text color |
-
-**Precedence:** `iconName` takes precedence over the corresponding ReactNode prop (`icon`, `prefix`, `suffix`, etc.) when both are supplied.
+---
 
-**Backward compatibility:** All existing `icon`, `prefix`, `suffix`, `leftRender`, `rightRender` ReactNode props continue to work exactly as before.
+## Hover Support (Web)
 
-**Example — Button with icon:**
 ```tsx
-<Button label="Continue" iconName="arrow-right" iconPosition="right" />
-<Button label="Delete" variant="destructive" iconName="trash-2" />
-```
+import { useHover } from '@retray-dev/ui-kit'
 
-**Example — Input with icons:**
-```tsx
-<Input placeholder="Search..." prefixIcon="search" />
-<Input placeholder="Amount" prefixIcon="dollar-sign" suffixIcon="check" />
-```
+function MyHoverableComponent() {
+  const { hovered, hoverHandlers } = useHover()
 
-**Example — ListItem with icons:**
-```tsx
-<ListItem title="Profile" leftIcon="user" rightIcon="chevron-right" />
-<ListItem title="Notifications" leftIcon="bell" subtitle="3 unread" showChevron />
+  return (
+    <View
+      {...hoverHandlers}
+      style={[
+        styles.container,
+        hovered && { backgroundColor: colors.surfaceStrong }
+      ]}
+    />
+  )
+}
 ```
 
-**Example — Badge with icon:**
-```tsx
-<Badge label="Active" variant="default" iconName="check" size="sm" />
-<Badge label="Error" variant="destructive" iconName="alert-circle" />
-```
+- **Web:** Returns `{ hovered: boolean, hoverHandlers: { onMouseEnter, onMouseLeave } }`
+- **Native:** Always returns `{ hovered: false, hoverHandlers: {} }` — no-op, no crashes
 
-**Example — Toast with icon:**
-```tsx
-const { toast } = useToast()
-toast({ title: "Saved", variant: "success", iconName: "check-circle" })
-toast({ title: "Oops", variant: "destructive", iconName: "x-circle" })
-```
+Built-in web hover: `MediaCard` (shadow lift), interactive components use this internally.
 
-**Example — EmptyState with icon:**
-```tsx
-<EmptyState iconName="inbox" title="No messages" description="You're all caught up." />
-```
+---
+
+## 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.