@retray-dev/ui-kit 9.1.0 → 9.2.0

package/DESIGN.md

@@ -0,0 +1,668 @@
+---
+version: 1.0
+name: Retray Design System
+description: A warm, generous consumer-app system anchored on a white canvas and deep ink (#1a1a1a) as primary, with a single coral accent (#d4561d) carrying primary CTAs and interactive moments. Type runs Sohne at modest weights — display sits at 20–28px in weight 600/700 rather than heavy weights; the system trusts whitespace and imagery over typographic muscle. Soft rounded shapes throughout — no hard corners on interactive elements. Built for React Native / Expo.
+
+colors:
+  primary: "#1a1a1a"
+  primary-foreground: "#ffffff"
+  accent: "#d4561d"
+  accent-active: "#b8431a"
+  accent-disabled: "#f0c4b4"
+  accent-foreground: "#ffffff"
+  background: "#ffffff"
+  foreground: "#1a1a1a"
+  card: "#ffffff"
+  border: "#dddddd"
+  foreground-subtle: "#646464"   # derived — ~70% foreground mix
+  foreground-muted: "#767676"    # derived — ~62% foreground mix (WCAG AA 4.5:1)
+  surface: "#f5f5f5"             # derived — background slightly off-canvas
+  surface-strong: "#ebebeb"      # derived — pressed/hover states
+  destructive: "#c72828"
+  destructive-foreground: "#ffffff"
+  success: "#1a7a45"
+  success-foreground: "#ffffff"
+  warning: "#9a5200"
+  warning-foreground: "#ffffff"
+  overlay: "rgba(0,0,0,0.45)"
+
+typography:
+  display-hero:
+    fontFamily: "Sohne-Bold"
+    fontSize: 64px
+    fontWeight: 700
+    lineHeight: 70px
+    letterSpacing: -1px
+  display-xl:
+    fontFamily: "Sohne-Bold"
+    fontSize: 28px
+    fontWeight: 700
+    lineHeight: 40px
+    letterSpacing: 0
+  display-lg:
+    fontFamily: "Sohne-SemiBold"
+    fontSize: 24px
+    fontWeight: 600
+    lineHeight: 32px
+    letterSpacing: -0.3px
+  display-md:
+    fontFamily: "Sohne-SemiBold"
+    fontSize: 20px
+    fontWeight: 600
+    lineHeight: 28px
+    letterSpacing: 0
+  display-sm:
+    fontFamily: "Sohne-SemiBold"
+    fontSize: 18px
+    fontWeight: 600
+    lineHeight: 24px
+    letterSpacing: -0.18px
+  title-md:
+    fontFamily: "Sohne-SemiBold"
+    fontSize: 17px
+    fontWeight: 600
+    lineHeight: 22px
+    letterSpacing: 0
+  title-sm:
+    fontFamily: "Sohne-Medium"
+    fontSize: 15px
+    fontWeight: 500
+    lineHeight: 20px
+    letterSpacing: 0
+  body-md:
+    fontFamily: "Sohne-Regular"
+    fontSize: 16px
+    fontWeight: 400
+    lineHeight: 24px
+    letterSpacing: 0
+  body-sm:
+    fontFamily: "Sohne-Regular"
+    fontSize: 14px
+    fontWeight: 400
+    lineHeight: 20px
+    letterSpacing: 0
+  caption:
+    fontFamily: "Sohne-Medium"
+    fontSize: 14px
+    fontWeight: 500
+    lineHeight: 18px
+    letterSpacing: 0
+  caption-sm:
+    fontFamily: "Sohne-Regular"
+    fontSize: 13px
+    fontWeight: 400
+    lineHeight: 16px
+    letterSpacing: 0
+  badge-text:
+    fontFamily: "Sohne-SemiBold"
+    fontSize: 11px
+    fontWeight: 600
+    lineHeight: 14px
+    letterSpacing: 0
+  badge-text-md:
+    fontFamily: "Sohne-SemiBold"
+    fontSize: 13px
+    fontWeight: 600
+    lineHeight: 16px
+    letterSpacing: 0
+  micro-label:
+    fontFamily: "Sohne-Bold"
+    fontSize: 12px
+    fontWeight: 700
+    lineHeight: 16px
+    letterSpacing: 0
+  uppercase-tag:
+    fontFamily: "Sohne-Bold"
+    fontSize: 11px
+    fontWeight: 700
+    lineHeight: 14px
+    letterSpacing: 0.6px
+    textTransform: uppercase
+  button-lg:
+    fontFamily: "Sohne-Medium"
+    fontSize: 16px
+    fontWeight: 500
+    lineHeight: 22px
+    letterSpacing: 0
+  button-sm:
+    fontFamily: "Sohne-Medium"
+    fontSize: 14px
+    fontWeight: 500
+    lineHeight: 18px
+    letterSpacing: 0
+
+rounded:
+  none: 0px
+  xs: 4px
+  sm: 8px
+  md: 14px
+  lg: 20px
+  xl: 32px
+  full: 9999px
+
+spacing:
+  xxs: 2px
+  xs: 4px
+  sm: 8px
+  md: 12px
+  base: 16px
+  lg: 24px
+  xl: 32px
+  xxl: 48px
+  section: 64px
+
+components:
+  button-primary:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-foreground}"
+    typography: "{typography.button-lg}"
+    rounded: "{rounded.md}"    # 14px — soft rounded rect, not pill
+    paddingV: 10px
+    paddingH: 24px
+    minHeight: 44px
+  button-primary-lg:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-foreground}"
+    rounded: "{rounded.md}"
+    paddingV: 12px
+    minHeight: 48px
+  button-primary-disabled:
+    backgroundColor: "{colors.surface-strong}"
+    textColor: "{colors.foreground-muted}"
+    rounded: "{rounded.md}"
+  button-accent:
+    backgroundColor: "{colors.accent}"
+    textColor: "{colors.accent-foreground}"
+    typography: "{typography.button-lg}"
+    rounded: "{rounded.md}"
+    paddingV: 10px
+    minHeight: 44px
+  button-secondary:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    typography: "{typography.button-lg}"
+    rounded: "{rounded.md}"
+    borderWidth: 1px
+    borderColor: "{colors.border}"
+    paddingV: 10px
+    minHeight: 44px
+  button-ghost:
+    backgroundColor: transparent
+    textColor: "{colors.foreground}"
+    typography: "{typography.button-lg}"
+  button-destructive:
+    backgroundColor: "{colors.destructive}"
+    textColor: "{colors.destructive-foreground}"
+    rounded: "{rounded.md}"
+    paddingV: 10px
+    minHeight: 44px
+  icon-button:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.full}"
+    size: 40px
+  card:
+    backgroundColor: "{colors.card}"
+    rounded: "{rounded.md}"
+    borderWidth: 1px
+    borderColor: "{colors.border}"
+    padding: 16px
+  card-pressable:
+    backgroundColor: "{colors.card}"
+    rounded: "{rounded.md}"
+    pressScale: 0.98
+  text-input:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    typography: "{typography.body-md}"
+    rounded: "{rounded.sm}"
+    paddingV: 11px
+    paddingH: 14px
+    minHeight: 44px
+    borderWidth: 1px
+    borderColor: "{colors.border}"
+    focusBorderColor: "{colors.primary}"
+  badge:
+    rounded: "{rounded.sm}"
+    paddingV: 2px
+    paddingH: 6px
+  chip:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.foreground}"
+    typography: "{typography.button-sm}"
+    rounded: "{rounded.full}"
+    pressScale: 0.94
+  chip-selected:
+    backgroundColor: "{colors.primary}"
+    textColor: "{colors.primary-foreground}"
+    rounded: "{rounded.full}"
+  list-item:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    typography: "{typography.body-md}"
+    minHeight: 44px
+    pressScale: 0.97
+  menu-item:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    typography: "{typography.body-md}"
+    minHeight: 44px
+    pressScale: 0.97
+  tab-trigger:
+    backgroundColor: transparent
+    textColor: "{colors.foreground-muted}"
+    typography: "{typography.button-sm}"
+    pressScale: 0.95
+  tab-trigger-active:
+    textColor: "{colors.foreground}"
+    typography: "{typography.button-sm}"
+  app-header:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground}"
+    typography: "{typography.title-md}"
+    borderColor: "{colors.border}"
+    height: 56px
+  tab-bar:
+    backgroundColor: "{colors.background}"
+    textColor: "{colors.foreground-muted}"
+    activeColor: "{colors.primary}"
+    borderColor: "{colors.border}"
+  sheet:
+    backgroundColor: "{colors.card}"
+    rounded: "{rounded.xl}"    # 32px top corners only
+    handleColor: "{colors.border}"
+  toast:
+    backgroundColor: "{colors.card}"
+    textColor: "{colors.foreground}"
+    rounded: "{rounded.lg}"
+    duration: 4000ms
+  alert-banner:
+    rounded: "{rounded.lg}"
+    padding: 16px
+  checkbox:
+    size: 24px
+    rounded: "{rounded.sm}"
+    pressScale: 0.95
+  switch:
+    trackWidth: 52px
+    trackHeight: 30px
+    thumbSize: 24px
+  toggle:
+    rounded: "{rounded.md}"
+    minHeight-sm: 40px
+    minHeight-md: 44px
+    minHeight-lg: 48px
+    pressScale: 0.95
+  slider:
+    containerHeight: 40px
+    thumbSize: 28px
+  progress:
+    height: 6px
+    rounded: "{rounded.full}"
+    backgroundColor: "{colors.surface-strong}"
+    fillColor: "{colors.primary}"
+  skeleton:
+    backgroundColor: "{colors.surface}"
+    shimmerColor: "{colors.surface-strong}"
+    rounded: "{rounded.md}"
+  separator:
+    color: "{colors.border}"
+    thickness: 1px
+---
+
+## Overview
+
+Retray Design System is a warm, generous mobile-first UI kit for React Native / Expo consumer apps. The base canvas is **pure white** (`{colors.background}` — #ffffff) with deep near-black ink (`{colors.foreground}` — #1a1a1a) for all text and primary interactive elements, and a single coral voltage (`{colors.accent}` — #d4561d) available for brand moments, highlights, and accent CTAs. Most surfaces are 90% white + ink with one accent moment.
+
+Type runs **Sohne** exclusively — a refined geometric sans-serif with 14 weights. Display sits at modest 18–28px / 600–700 weight rather than heavy 800+. The system trusts whitespace and component density for visual hierarchy, not typographic muscle. The full Sohne family ships as `.otf` assets; consuming apps load them via `useFonts(SohneFonts)` from `@retray-dev/ui-kit/fonts`.
+
+Shape language is **soft everywhere**. Buttons use `{rounded.md}` (14px) — a friendly rounded rect, never pill-shaped for primary CTAs. Cards use `{rounded.md}` (14px). Sheet modals use `{rounded.xl}` (32px) on top corners only. Icon buttons are circles (`{rounded.full}`). No hard corner on any interactive element.
+
+**Key characteristics:**
+- Primary (`{colors.primary}` — #1a1a1a) carries all primary CTAs, toggle active states, focus rings, and the default tab indicator.
+- Accent (`{colors.accent}` — #d4561d) is optional — used for brand CTAs, highlighted badges, and semantic color moments. Falls back to primary when unset.
+- Sohne type family. Display weights 600–700. Body weight 400. Modest weight is intentional.
+- 8pt spacing grid with 4pt micro-steps. Section bands at `{spacing.section}` (64px).
+- Maximum two elevation tiers — flat baseline (95% of surfaces) plus one card float tier.
+- Haptics on every interaction via `react-native-pulsar` with `expo-haptics` fallback.
+- Press animations via `pressto` — main-thread, gesture-handler worklets. Color transitions via `react-native-reanimated` v4.
+
+## Colors
+
+### Primary & Foreground
+- **Primary** (`{colors.primary}` — #1a1a1a): Default text color and primary interactive color. Button fills, active tab indicators, focus rings, toggle on-states.
+- **Primary Foreground** (`{colors.primary-foreground}` — #ffffff): Text on primary surfaces.
+- **Foreground** (`{colors.foreground}` — #1a1a1a): All body text and headlines. Same value as primary — intentional.
+- **Foreground Subtle** (`{colors.foreground-subtle}` — ~#646464): Sub-titles, secondary labels, inactive tab text. 5.9:1 contrast on white — WCAG AA ✓.
+- **Foreground Muted** (`{colors.foreground-muted}` — ~#767676): Captions, timestamps, placeholders, empty-state labels. 4.5:1 — WCAG AA minimum ✓.
+
+### Accent
+- **Accent** (`{colors.accent}` — #d4561d): The single brand voltage. Used sparingly — one or two moments per screen. Primary CTAs on accent-themed flows, highlighted chips, brand badges.
+- **Accent Active** (`{colors.accent-active}` — #b8431a): Press / pointer-down variant.
+- **Accent Disabled** (`{colors.accent-disabled}` — #f0c4b4): Pale tint for disabled accent CTAs.
+- **Accent Foreground** (`{colors.accent-foreground}` — #ffffff): White text on accent surfaces.
+
+### Surfaces
+- **Background** (`{colors.background}` — #ffffff): Page/screen floor. Default for all views.
+- **Card** (`{colors.card}` — #ffffff): Card surfaces. Same value as background — components separate via border + shadow, not fill.
+- **Surface** (`{colors.surface}` — ~#f5f5f5): Unselected chip fills, input backgrounds on subtle forms, skeleton placeholder base.
+- **Surface Strong** (`{colors.surface-strong}` — ~#ebebeb): Pressed/hover fill for icon buttons and row highlights.
+
+### Borders
+- **Border** (`{colors.border}` — #dddddd): Default 1px stroke — card borders, input outlines, tab-bar top edge, separator lines.
+
+### Semantic
+- **Destructive** (`{colors.destructive}` — #c72828): Error and destructive states. 5.59:1 on white — WCAG AA ✓.
+- **Success** (`{colors.success}` — #1a7a45): Positive confirmation states.
+- **Warning** (`{colors.warning}` — #9a5200): Caution states. 5.86:1 on white — WCAG AA ✓.
+- All semantic colors have matching `-foreground` (white text) and derived `Tint` / `Border` variants computed by `deriveColors()`.
+
+### Overlay
+- **Overlay** (`{colors.overlay}` — rgba(0,0,0,0.45)): Sheet and dialog backdrop. Applied by `@gorhom/bottom-sheet` and `ConfirmDialog`.
+
+## Typography
+
+### Font Family
+Sohne is the exclusive type family — display, body, captions, buttons, badges. No separate display family. 14 weights ship as `.otf` files in `src/assets/fonts/`. Fallback on web: `-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif`.
+
+**Consuming apps must load fonts before rendering any component:**
+```tsx
+import { useFonts } from 'expo-font'
+import { SohneFonts } from '@retray-dev/ui-kit/fonts'
+
+const [fontsLoaded] = useFonts(SohneFonts)
+if (!fontsLoaded) return null
+```
+
+### Hierarchy
+
+| Token | Size | Weight | Line Height | Letter Spacing | Use |
+|---|---|---|---|---|---|
+| `display-hero` | 64px | 700 | 70px | -1px | Hero numbers, large stat displays |
+| `display-xl` | 28px | 700 | 40px | 0 | Screen titles, onboarding headlines |
+| `display-lg` | 24px | 600 | 32px | -0.3px | Section display heads |
+| `display-md` | 20px | 600 | 28px | 0 | Sub-section heads, sheet titles |
+| `display-sm` | 18px | 600 | 24px | -0.18px | Card primary labels, list group heads |
+| `title-md` | 17px | 600 | 22px | 0 | Item titles, row primary text |
+| `title-sm` | 15px | 500 | 20px | 0 | Secondary titles, sub-labels |
+| `body-md` | 16px | 400 | 24px | 0 | Default running text inside content |
+| `body-sm` | 14px | 400 | 20px | 0 | Card meta, dates, prices, distance text |
+| `caption` | 14px | 500 | 18px | 0 | Input labels, form field labels |
+| `caption-sm` | 13px | 400 | 16px | 0 | Legal text, copyright, footer copy |
+| `badge-text` | 11px | 600 | 14px | 0 | Small badge labels |
+| `badge-text-md` | 13px | 600 | 16px | 0 | Medium badge labels |
+| `micro-label` | 12px | 700 | 16px | 0 | Chip category labels, micro-tags |
+| `uppercase-tag` | 11px | 700 | 14px | 0.6px + uppercase | Section tags, status labels (uppercase) |
+| `button-lg` | 16px | 500 | 22px | 0 | Primary/secondary CTA labels |
+| `button-sm` | 14px | 500 | 18px | 0 | Small button and pill labels |
+
+### Principles
+Display weights stay modest. Screen titles at 28px / 700 feel spacious but not aggressive. Most hierarchy comes from spacing and surface separation, not weight extremes. `display-hero` (64px / 700) is reserved for isolated stat moments — rating displays, large numeric callouts.
+
+All `<Text>` components set `allowFontScaling={true}` for Dynamic Type compliance.
+
+## Spacing
+
+**Base unit:** 8pt grid (4pt micro-steps for tight UI).
+
+| Token | Value | Use |
+|---|---|---|
+| `spacing.xxs` | 2px | Micro gap — icon + label pair |
+| `spacing.xs` | 4px | Badge padding, inline icon gap |
+| `spacing.sm` | 8px | Row internal padding, caption gap |
+| `spacing.md` | 12px | Button vertical padding (sm), card internal gap |
+| `spacing.base` | 16px | Card padding, screen horizontal inset |
+| `spacing.lg` | 24px | Section internal padding, dialog padding |
+| `spacing.xl` | 32px | Between major sections within a screen |
+| `spacing.xxl` | 48px | Between top-level page bands |
+| `spacing.section` | 64px | Major vertical breathing room between primary sections |
+
+## Border Radius
+
+| Token | Value | Use |
+|---|---|---|
+| `rounded.none` | 0 | Separators, divider lines |
+| `rounded.xs` | 4px | — |
+| `rounded.sm` | 8px | Inputs, Textarea, Checkbox, Select list, AlertBanner |
+| `rounded.md` | 14px | Buttons, Cards, Tabs pill, Toggle, Badge (lg) |
+| `rounded.lg` | 20px | Toast, EmptyState, large cards |
+| `rounded.xl` | 32px | Sheet modal top corners |
+| `rounded.full` | 9999px | Chips, IconButton, Avatar, Progress track, PagerDots |
+
+## Elevation
+
+Two tiers — flat baseline and one float:
+
+- **Flat:** All screens, forms, list items, tab bars — 95% of surfaces. No shadow.
+- **Card float:** `shadowColor: #000 / shadowOffset: {0, 2} / shadowOpacity: 0.10 / shadowRadius: 8 / elevation: 5` — applied to Cards on press-release (hover on web), Sheets, ConfirmDialogs, and the account dropdown. This is the `SHADOWS.md` preset.
+- **Modal backdrop:** `{colors.overlay}` (rgba(0,0,0,0.45)) — applied by `@gorhom/bottom-sheet` behind Sheet and ConfirmDialog.
+
+Depth comes from `{rounded.md}` corner clipping and white-on-white surface border separation, not layered shadows.
+
+## Components
+
+### Buttons
+
+**Primary** — Ink fill, white text, 14px radius, 10px vertical padding, 44px min-height. Main screen action: "Continue", "Save", "Confirm". Uses `PressableButton` (scale 0.95) with `impactLight()` haptic.
+
+**Primary (lg)** — Same ink fill, 12px vertical padding, 48px min-height. Full-width CTAs on onboarding and forms.
+
+**Accent** — Coral fill (`{colors.accent}`), white text, 14px radius. Brand moments and highlighted CTA flows where one coral moment per screen is appropriate.
+
+**Secondary** — White fill, ink border (1px), ink text. "Cancel", "Back", inverse actions.
+
+**Ghost** — Transparent, ink text only. Underlined on press. "Show more" links, tertiary actions.
+
+**Destructive** — Red fill, white text. Irreversible actions — delete, remove, block.
+
+**IconButton** — Circle (`{rounded.full}`), surface fill, 40px size. Toolbar actions, floating action buttons.
+
+### Inputs
+
+**Input / Textarea** — White fill, 1px hairline border, 8px radius, 11px vertical / 14px horizontal padding, 44px min-height. On focus: border thickens to 2px and color transitions to `{colors.primary}` via 140ms `useColorTransition`. No glow ring — border is the focus signal.
+
+**Select** — Same dimensions as Input. Opens `@react-native-picker/picker` (native sheet). 1px hairline border, 8px radius.
+
+**Slider** — Native `@react-native-community/slider`, 40px container height, 28px thumb. `selectionAsync()` haptic per step.
+
+### Cards
+
+**Card** — White surface, 1px border, 14px radius, 16px internal padding. Static by default. Use `pressScale: 0.98` when interactive.
+
+**MediaCard** — Photo-first card. Image fills top with 14px corner clipping. Meta block below in body-sm. Uses `PressableCard` (scale 0.98).
+
+**PricingCard** — Highlighted card variant with accent border and feature list.
+
+### Selection Controls
+
+**Checkbox** — 24×24px square, 8px radius, ink fill when checked. Press: `PressableButton` scale 0.95. Haptic: `selectionAsync()`.
+
+**Switch** — 52px track / 30px height / 24px thumb. Single `progress` shared value (0→1) drives thumb translateX via `SPRINGS.elastic`, track color via `interpolateColor`. Haptic: `selectionAsync()`.
+
+**RadioGroup** — 24px circle items. Dot scale + opacity driven by `SPRINGS.elastic`. Haptic: `selectionAsync()`.
+
+**Toggle** — Segmented control. Min-heights: sm=40, md=44, lg=48. Border and fill color via `useColorTransition(TIMINGS.state)`. Haptic: `selectionAsync()`.
+
+**Checkbox / Switch / RadioGroup / Toggle:** All use `PressableButton` (scale 0.95), `enabled={!disabled}`, `rippleColor="transparent"`, `touchSoundDisabled`.
+
+### Chips
+
+**Chip** — `{rounded.full}` pill, surface fill unselected, ink fill selected. `PressableChip` scale 0.94. `selectionAsync()` haptic. `ChipGroup` handles multi-select state.
+
+**CategoryStrip** — Horizontal scrolling strip of chips. Active chip: ink background, white text. Inactive: muted text, transparent fill. Color transitions via `COLOR_TRANSITION`.
+
+### Navigation
+
+**AppHeader** — White background, 56px height, 1px bottom border. Title in `title-md`. Back/action buttons use `IconButton`.
+
+**TabBar** — White background, 1px top border. Active icon/label in `{colors.primary}`. Inactive in `{colors.foreground-muted}`. `selectionAsync()` on tab switch.
+
+**Tabs** — Horizontal segmented tabs with sliding ink pill indicator. Pill slides via `withSpring(SPRINGS.glide)`. `PressableTab` scale 0.95.
+
+**PagerDots** — Row of `{rounded.full}` dots. Active dot scales up and fills with `{colors.primary}`.
+
+### Overlays
+
+**Sheet** — `@gorhom/bottom-sheet` `BottomSheetModal` with `enableDynamicSizing`. Top corners `{rounded.xl}` (32px). `keyboardBehavior="interactive"`. Always use `<SheetTextInput>` (not `<TextInput>`) inside sheets. Requires `BottomSheetModalProvider` at app root.
+
+**ConfirmDialog** — Sheet variant for destructive confirmations. `notificationSuccess()` / `notificationError()` haptic on confirm. `selectionAsync()` on cancel.
+
+**ImageViewer** — Full-screen overlay for photo viewing. Pinch-to-zoom + swipe-to-dismiss via gesture handler.
+
+### Feedback
+
+**Toast** — `sonner-native` `Toaster`. `richColors: false` (colored icon, neutral background). `swipeToDismissDirection="up"`, `duration: 4000`. `{rounded.lg}` (20px). Requires `ToastProvider` at app root.
+
+**AlertBanner** — Inline semantic banner. `{rounded.sm}` (8px), 16px padding. Four variants: default / destructive / success / warning. Uses semantic tint fills from `deriveColors()`.
+
+**Spinner** — Activity indicator. Three sizes matching icon scale.
+
+**Skeleton** — Animated shimmer placeholder. `{rounded.md}` base, 1400ms shimmer cycle via `expo-linear-gradient`. Sub-components: `Skeleton.MediaCard`, `Skeleton.ListItem`.
+
+**Progress** — 6px track, `{rounded.full}`, ink fill. Width animated via `withSpring(SPRINGS.glide)` on value change.
+
+### Data Display
+
+**ListItem / ListGroup** — Row list items, 44px min-height, 0.97 press scale. `selectionAsync()` haptic. `ListGroup` adds Header and Footer sub-components.
+
+**MenuItem / MenuGroup** — Same dimensions as ListItem. Used inside Sheets and dropdowns.
+
+**LabelValue** — Two-column key-value row. Label in `foreground-muted`, value in `foreground`.
+
+**DetailRow** — Single key-value with optional icon. Used in summary and detail screens.
+
+**Badge** — Inline label pill. Sizes: sm (`badge-text` 11px) and md (`badge-text-md` 13px). 8px radius. Four variants: default / success / destructive / warning.
+
+**Avatar** — `{rounded.full}` circle. Three sizes: sm/md/lg. Falls back to initials when no image.
+
+**Separator** — 1px horizontal rule in `{colors.border}`. Inset variant for list spacing.
+
+**VirtualList** — Virtualized scroll list via `FlashList`. Use for long data sets.
+
+**MonthPicker** — Month/year scroll picker using native sheet.
+
+**CurrencyDisplay** — Formatted monetary value with currency symbol. Uses `display-md` for amount.
+
+**CurrencyInput** — Numeric input with currency formatting. Same dimensions as `Input`.
+
+### Form Utilities
+
+**Form / Form.Field / Form.Section / Form.Footer** — Layout wrappers for form screens. Section provides label + helper text above fields. Field wraps an input with error state. Footer holds the primary CTA + legal copy.
+
+### Composition
+
+**Accordion** — Collapsible section. Height animated via `withTiming(TIMINGS.expand/collapse)`. Content uses `position: absolute` for `onLayout` measurement while parent is at `height: 0`. Rotate chevron 180° on expand.
+
+**SelectableGrid** — Grid of tappable option cells. Used for multi-select category/tag picking.
+
+## Animation System
+
+### Press Scales (`PRESS_SCALE` in `animations.ts`)
+| Context | Scale | Components |
+|---|---|---|
+| Button / Toggle / Checkbox | 0.95 | `PressableButton` |
+| Card / MediaCard | 0.98 | `PressableCard` |
+| ListItem / MenuItem | 0.97 | `PressableRow` |
+| Chip | 0.94 | `PressableChip` |
+| Tab trigger | 0.95 | `PressableTab` |
+
+All pressables: `enabled={!disabled}`, `rippleColor="transparent"`, `touchSoundDisabled`.
+
+### Spring Presets (`SPRINGS`)
+| Preset | Stiffness | Damping | Mass | Use |
+|---|---|---|---|---|
+| `pressIn` | 600 | 35 | 0.8 | Button / Toggle / Tabs fast compression |
+| `pressOut` | 280 | 22 | 0.8 | Elastic rebound after press |
+| `surfacePressIn` | 380 | 30 | 0.95 | Card / ListItem softer compression |
+| `surfacePressOut` | 220 | 20 | 0.95 | Card / ListItem softer rebound |
+| `glide` | 380 | 38 | 1.0 | Tabs indicator slide, Progress fill |
+| `elastic` | 320 | 22 | 0.7 | Switch thumb, RadioGroup dot |
+
+### Timing Presets (`TIMINGS`)
+| Preset | Duration | Use |
+|---|---|---|
+| `state` | 160ms | Checkbox/toggle color transitions |
+| `focusIn` | 140ms | Input focus ring appear |
+| `focusOut` | 100ms | Input focus ring dismiss |
+| `expand` | 240ms | Accordion open |
+| `collapse` | 200ms | Accordion close |
+| `shimmer` | 1400ms | Skeleton shimmer pass |
+
+### Easing Presets (`EASINGS`)
+| Preset | Curve | Use |
+|---|---|---|
+| `standard` | bezier(0.2, 0, 0, 1) | General state transitions |
+| `expand` | bezier(0.23, 1, 0.32, 1) | Accordion expand, panel slide |
+| `collapse` | Easing.in(ease) | Accordion collapse |
+
+### EaseView Transitions (for `react-native-ease`)
+- `COLOR_TRANSITION` — 160ms timing, standard easing. Chip/Toggle/CategoryStrip color state.
+- `OPACITY_TRANSITION` — 160ms timing, standard easing. Icon/content crossfades.
+- `SPRING_ELASTIC` — spring stiffness=320, damping=22, mass=0.7. Switch thumb, RadioGroup dot.
+
+## Haptic Feedback
+
+All haptics via `src/utils/haptics.ts` — `react-native-pulsar` with `expo-haptics` fallback. Pulsar loads dynamically via `import()` inside a try/catch; absent in Expo Go, graceful fallback.
+
+| Function | Use |
+|---|---|
+| `selectionAsync()` | Checkbox, Switch, Toggle, RadioGroup, Select (open + pick), Slider (per step), Accordion toggle, ListItem press, MenuItem press, ConfirmDialog cancel |
+| `impactLight()` | Button tap, small action confirmations |
+| `impactMedium()` | Sheet open |
+| `impactHeavy()` | ConfirmDialog open |
+| `notificationSuccess()` | ConfirmDialog confirm (success action) |
+| `notificationError()` | ConfirmDialog confirm (destructive action) |
+| `notificationWarning()` | Form validation error |
+| `richHaptics.hammer()` / `.pulse()` / `.buzz()` / `.flick()` | Enhanced Pulsar presets (fallback to basic haptics in Expo Go) |
+
+## Touch Targets (Apple HIG)
+
+All interactive elements maintain ≥44pt touch height:
+
+| Component | Min Height | Enforcement |
+|---|---|---|
+| Button sm/md | 44px | `paddingV: vs(10)` |
+| Button lg | 48px | `paddingV: vs(12)` |
+| Input / Textarea / Select | 44px | `paddingV: vs(11)` |
+| Checkbox / Radio circle | 24×24px | fixed size |
+| Switch thumb | 24px | `THUMB_SIZE: 24` |
+| Switch track | 52×30px | `TRACK_WIDTH/HEIGHT` |
+| Toggle sm/md/lg | 40/44/48px | `minHeight` |
+| Slider | 40px container | `height: 40` |
+| Slider thumb | 28×28px | native thumb |
+
+## Provider Setup (Consuming Apps)
+
+```tsx
+import { SafeAreaProvider, initialWindowMetrics } from 'react-native-safe-area-context'
+import { GestureHandlerRootView } from 'react-native-gesture-handler'
+import { ThemeProvider, BottomSheetModalProvider, ToastProvider } from '@retray-dev/ui-kit'
+
+<SafeAreaProvider initialMetrics={initialWindowMetrics}>
+  <GestureHandlerRootView style={{ flex: 1 }}>
+    <ThemeProvider>
+      <BottomSheetModalProvider>
+        <ToastProvider>
+          {/* app */}
+        </ToastProvider>
+      </BottomSheetModalProvider>
+    </ThemeProvider>
+  </GestureHandlerRootView>
+</SafeAreaProvider>
+```
+
+`SafeAreaProvider` must be outermost. `initialMetrics={initialWindowMetrics}` required on Android. `GestureHandlerRootView` must wrap all gesture-enabled components.
+
+## Design Philosophy
+
+**Warmth over precision.** Consumer-first. Generous spacing, rounded shapes, friendly weight. Not B2B grid-and-data precision — human marketplace feel.
+
+**Single accent.** 90% of screens are ink + white. One coral moment. Never two accent-colored elements competing.
+
+**Haptics always.** Every interactive element has a haptic. No reduced-motion toggle — animations always run.
+
+**Icon everywhere.** All interactive components support `iconName` (auto-resolved across 6 `@expo/vector-icons` families) and `icon` (custom ReactNode). Icons are first-class — not decorative. They improve scannability and reinforce hierarchy.
+
+**Flat and honest.** Maximum two shadow tiers. Depth from rounded corners + border separation + photography, not layered shadows.
+
+**Mobile HIG.** 44pt minimum touch targets, Dynamic Type (`allowFontScaling={true}`), swipe-to-dismiss on sheets, keyboard-interactive sheet behavior.