@thewhileloop/whileui 4.2.3 → 4.3.0

package/dist/agent/catalog.json

@@ -0,0 +1,1737 @@
+{
+  "package": "@thewhileloop/whileui",
+  "version": "4.3.0",
+  "guides": {
+    "quickReference": "## Quick Reference (AI / Code Generation)\n\n- **Full-screen:** `AppShell` + `Header` in `header` + `BottomNav` in `bottomNav` + content in `children`\n- **No-jump loading:** keep `AppShell` mounted, set `loading` + `skeleton` (e.g., `PageSkeleton`/`ScreenSkeleton`)\n- **Layout:** `Stack` (vertical), `Row` (horizontal) — both support `gap`, `align`, `justify`\n- **Auth callbacks:** Auth templates use objects: `onSubmit({ email, password })`, `onSubmit({ firstName, lastName, email, password })`, etc. Copy templates from `apps/showcase/catalog/templates/auth/`.\n- **PortalHost:** Add `<PortalHost />` at app root for Select, Popover, Tooltip, HoverCard.\n  Inside any WhileUI overlay they render into that overlay's layer without configuration.\n- **Motion:** Wrap the root in `<MotionProvider>`; use `useMotionPolicy()` for semantic\n  durations, the responsive spring, and reduced-motion behavior.\n- **Metro:** `withWhileUIMetro(config, { cssEntryFile: './global.css' })` from\n  `@thewhileloop/whileui/metro` — wraps Uniwind and keeps icon fonts loading on device.\n  `global.css` at app root, imported in `App.tsx`. Installing from npm also needs\n  `@source './node_modules/@thewhileloop/whileui/dist';` or every component renders unstyled.\n- **States:** `LoadingState`, `EmptyState` and `ErrorState` share one shape; `ErrorState`\n  takes `onRetry`. `Text variant=\"eyebrow\"` is the muted section label above a title.\n- **Reference:** Block props in `packages/ui/src/blocks` (core) and `apps/showcase/catalog/templates/` (auth, profile); flow patterns in README \"Flow Patterns\" section.\n\n### Composition grammar\n\n- Start with one page canvas and flat sections. Add a `Surface` only when grouping or\n  elevation communicates something; do not wrap every section in a card.\n- Use `level=\"base\"` for grouped content, `raised` for selectable or floating regions,\n  and `overlay` for content above the page. Avoid nesting more than one surfaced level.\n- Express hierarchy through `Text` variants before custom font-size classes. Keep one\n  primary action per region and constrain long-form content with `Container`.\n- Forms use `FormField`; its disabled and invalid state flows into `Input`, `Textarea`,\n  `NumericInput`, and `Select`. Pass a control prop only to override that inherited state.\n- Chat mechanics belong to `ChatConversation` + `SmartInput`. Message payloads, tools,\n  reasoning, approvals, sources, and action rows are application-owned compositions.\n- Import Markdown and code rendering from their optional subpaths. Do not make the root\n  package pay for content rendering when the screen does not use it.",
+    "compositionGrammar": "### Composition grammar\n\n- Start with one page canvas and flat sections. Add a `Surface` only when grouping or\n  elevation communicates something; do not wrap every section in a card.\n- Use `level=\"base\"` for grouped content, `raised` for selectable or floating regions,\n  and `overlay` for content above the page. Avoid nesting more than one surfaced level.\n- Express hierarchy through `Text` variants before custom font-size classes. Keep one\n  primary action per region and constrain long-form content with `Container`.\n- Forms use `FormField`; its disabled and invalid state flows into `Input`, `Textarea`,\n  `NumericInput`, and `Select`. Pass a control prop only to override that inherited state.\n- Chat mechanics belong to `ChatConversation` + `SmartInput`. Message payloads, tools,\n  reasoning, approvals, sources, and action rows are application-owned compositions.\n- Import Markdown and code rendering from their optional subpaths. Do not make the root\n  package pay for content rendering when the screen does not use it.",
+    "installation": "## Installation\n\n```bash\nbun add @thewhileloop/whileui\nbun add react@^19.3.0 react-native@^0.88.0 uniwind@^1.12.2 tailwindcss@^4.0.0 react-native-reanimated react-native-safe-area-context react-native-screens\n# Only if you use Select, Popover, Tooltip, or HoverCard:\nbun add @rn-primitives/portal @rn-primitives/hooks @rn-primitives/slot @rn-primitives/select @rn-primitives/popover @rn-primitives/tooltip @rn-primitives/hover-card\n# Only if you import @thewhileloop/whileui/markdown:\nbun add markdown-it\n```\n\nUse `npm install` instead of `bun add` if you prefer npm.\n\n### Setup Uniwind (required)\n\n1. **metro.config.js** (wrap with `withWhileUIMetro`):\n\n```js\nconst { getDefaultConfig } = require('expo/metro-config');\nconst { withWhileUIMetro } = require('@thewhileloop/whileui/metro');\n\n/** @type {import('expo/metro-config').MetroConfig} */\nconst config = getDefaultConfig(__dirname);\n\nmodule.exports = withWhileUIMetro(config, {\n  cssEntryFile: './global.css',\n});\n```\n\n> `withWhileUIMetro` calls Uniwind's `withUniwindConfig(config, options)` for you — same\n> options, config first, `cssEntryFile` a relative path — and keeps `expo-asset`,\n> `expo-font` and `@expo/vector-icons` on the real `react-native`. Without that, Uniwind's\n> import rewrite leaves every icon glyph silently missing on iOS and Android while web\n> renders fine. Pass `exemptFromUniwindRewrite: ['pkg']` for any other package that\n> imports a `react-native` export Uniwind's wrapper lacks. It must be the outermost wrapper.\n\n2. **global.css** at app root, imported from `App.tsx`:\n\n```css\n@import 'tailwindcss';\n@import 'uniwind';\n\n/* Required when installed from npm: Tailwind does not scan node_modules, so without\n   this line every component renders unstyled. */\n@source './node_modules/@thewhileloop/whileui/dist';\n\n/* Then your theme: generate it (Theming, below) rather than writing tokens by hand. */\n```\n\n3. **App.tsx**:\n\n```tsx\nimport './global.css';\nimport { MotionProvider, PortalHost } from '@thewhileloop/whileui';\nimport { Button, ButtonText } from '@thewhileloop/whileui';\n\nexport default function App() {\n  return (\n    <MotionProvider>\n      {/* Your app content */}\n      <PortalHost />\n    </MotionProvider>\n  );\n}\n```\n\n`PortalHost` (last child of the root) is where Select, Popover, Tooltip and HoverCard\nrender. Inside a Dialog, Sheet, menu or picker they use that overlay's own layer\nautomatically, and Android back or Escape closes the innermost layer first. Pass\n`portalHost` only to target a host you placed yourself, such as in a modal screen your\nnavigator presents.\n\n### Vite + React Native Web + WhileUI setup\n\nUse the WhileUI Vite compatibility helper when your app includes portal-based primitives.\n\n1. Install Vite + RN web basics:\n\n```bash\nbun add react-dom react-native-web\nbun add -d vite @vitejs/plugin-react\n```\n\n2. `vite.config.ts`:\n\n```ts\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\nimport { withWhileUIViteCompat } from '@thewhileloop/whileui/vite';\n\nexport default defineConfig(withWhileUIViteCompat({ plugins: [react()] }));\n```\n\n3. Keep `PortalHost` at app root when using Select/Popover/Tooltip/HoverCard.\n\nTroubleshooting:\n\n| Symptom                                                  | Likely cause                                              | Fix                                                                                                 |\n| -------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |\n| `Unexpected token <` from `@rn-primitives/*/dist/*.mjs`  | rn-primitives ships raw JSX in dist for some packages     | Use `withWhileUIViteCompat(...)` in `vite.config.ts`                                                |\n| `className` rejected on RN primitives in consumer TS app | RN `className` augmentation not loaded from package entry | Import components from `@thewhileloop/whileui` (or side-effect import the package entry before use) |\n| Theme token resolves differently on native/web           | Missing `--app-color-*` fallback for non-RN-native values | Add `--app-color-*` fallbacks in `global.css` for any `oklch(...)` token used by native APIs        |",
+    "theming": "## Theming\n\nA theme is a set of CSS variables in `global.css`, in OKLCH, with a `light` and a `dark`\nvariant. Every component reads the same contract, so a theme must define **every** token\nin both modes: a missing one silently falls back to an unstyled value at runtime.\n\n### Generate a theme\n\n`themeFromSeeds` builds a complete light and dark theme from three colours, and\n`themePresetToCss` writes every token, including the hex fallbacks React Native APIs need,\nready to paste into `global.css`:\n\n```ts\nimport { checkThemeContrast, themeFromSeeds, themePresetToCss } from '@thewhileloop/whileui/tokens';\n\nconst theme = themeFromSeeds({\n  name: 'studio',\n  description: 'Bone paper and burnt amber',\n  light: { background: '#f0ede9', foreground: '#13161c', primary: '#b65400' },\n  // optional: `dark` seeds (otherwise a dark page with the brand lifted to read on it),\n  // `overrides` for any base colour, `visual` for radius and density tokens\n});\n\ncheckThemeContrast(theme.light).filter((c) => !c.pass);\n// [{ pair: 'primary on background', ratio: 4.23, min: 4.5, pass: false }, …]\nconst css = themePresetToCss(theme); // paste into global.css\n```\n\nSeeds are kept as given; the colours it derives (muted text, text on each fill, status\ncolours) are tuned to WCAG AA. `checkThemeContrast` checks any palette, hand-written ones\nincluded: every text pairing at 4.5:1 and the focus ring at 3:1. A failing seed is\nreported, never changed, because a brand colour is a brand decision. The built-in presets,\n`WHILEUI_PRESET_SOFT` and `WHILEUI_PRESET_ATELIER`, go through `themePresetToCss` the same\nway.\n\nSwitch at runtime with `Uniwind.setTheme('dark')` (or `'light'`, `'system'`). A named\nextra theme is registered with `extraThemes: ['name']` in `metro.config.js` and defined\nwith `@variant name`. The full token list, with each default, is in `theme-contract.ts`,\nand agents can read it from the MCP server's `get_theme_tokens`.\n\n### Frosted surfaces\n\nCards and overlays take `frosted`, `blurIntensity` and `blurTintToken`\n(`'surfaceElevated' | 'surfaceTranslucent' | 'card' | 'popover'`). Without a blur view\nthey tint only; register `expo-blur` once for real blur:\n\n```tsx\nimport { BlurView } from 'expo-blur';\nimport { registerFrostedBlurView } from '@thewhileloop/whileui';\n\nregisterFrostedBlurView(BlurView);\n```\n\nFor a frosted look across a whole theme, make `surface-elevated`, `surface-border` and\n`surface-highlight` translucent, in your light and dark variants or in a separate theme.\nThe tuning tokens:\n\n| Token                                                                     | Default      | Effect                                                         |\n| ------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------- |\n| `--ui-blur-intensity-subtle` / `-medium` / `-strong`                      | 18 / 26 / 34 | The three blur presets                                         |\n| `--ui-frosted-android-tint-alpha-scale`                                   | 1.18         | Android needs denser tint; `1` matches iOS and web             |\n| `--ui-frosted-android-experimental-blur`                                  | 1            | Uses `expo-blur`'s experimental Android blur; `0` turns it off |\n| `--ui-frosted-highlight-height`                                           | 2            | Top sheen in px; `0` removes it                                |\n| `--ui-blur-saturation-pct`                                                | 145          | Web saturation multiplier                                      |\n| `--ui-frosted-backdrop-blur-intensity`, `-scale`                          | 22, 0.72     | Backdrop blur, and its ratio when a component overrides blur   |\n| `--ui-drawer-frosted-inset`, `-radius`, `--ui-drawer-content-top-padding` | 10, 34, 0    | Frosted drawer shell                                           |\n\n### Colours for React Native APIs\n\nIcons, `ActivityIndicator` and other native APIs need hex or rgb, not OKLCH.\n`useThemeColors()` returns the whole palette as React Native colours, falling back to the\n`--app-color-*` tokens a generated theme includes; `useIconColors()` is the subset icons\nuse, with `muted` mapped to `mutedForeground`.\n\n```tsx\nconst icons = useIconColors();\n<Feather name=\"heart\" size={20} color={icons.muted} />;\n```\n\nInput, Textarea, NumericInput, SmartInput, Spinner and LoadingScreen pick theme colours\nwhen you omit `placeholderTextColor` or `spinnerColor`.\n\n### Interaction and motion\n\nPress opacity, disabled opacity, motion durations, the responsive spring, and the drawer\nopen and close durations are package constants on `INTERACTION_TOKENS`. They are not CSS\nvariables, so a theme does not change them.\n\nFor a custom control, read that table:\n\n```tsx\nimport { useInteractionTokens, withInteractivePressableStyle } from '@thewhileloop/whileui';\n```\n\nWrap the application in `MotionProvider` to coordinate system reduced motion, an explicit\npreview mode, and deterministic animation-free tests. The provider is optional. Without\nit `useMotionPolicy` reports the durations and spring from `INTERACTION_TOKENS`, and\nReanimated follows the system setting. `reduced` preserves non-spatial feedback while asking Reanimated to skip motion;\n`disabled` also resolves semantic durations to zero.\n\n```tsx\nimport { MotionProvider, useMotionPolicy } from '@thewhileloop/whileui';\n\n<MotionProvider mode=\"system\">{/* application */}</MotionProvider>;\n\nconst motion = useMotionPolicy();\nmotion.durations.normal;\nmotion.springs.responsive;\n```"
+  },
+  "components": [
+    {
+      "name": "Text",
+      "category": "Primitives",
+      "kind": "package",
+      "summary": "Themed text with variant support",
+      "docs": "## Text\n\n`Text` maps semantic roles to the active visual typography tokens; custom font-size\nclasses are unnecessary for normal hierarchy. `heading` also sets\n`accessibilityRole=\"header\"` unless the caller supplies another role.\n\n\n| Prop      | Type                                                                                                       | Default     | Description |\n| --------- | ---------------------------------------------------------------------------------------------------------- | ----------- | ----------- |\n| className | `string`                                                                                                   | —           |             |\n| size      | `'base' \\| 'xs' \\| 'sm' \\| 'lg' \\| 'xl' \\| '2xl' \\| '3xl'`                                                 | —           |             |\n| variant   | `'default' \\| 'heading' \\| 'title' \\| 'subtitle' \\| 'body' \\| 'caption' \\| 'label' \\| 'eyebrow' \\| 'code'` | `'default'` |             |\n\nAlso accepts the props of React Native's `TextProps`."
+    },
+    {
+      "name": "Surface",
+      "category": "Primitives",
+      "kind": "package",
+      "summary": "Token-backed base, raised, and overlay container",
+      "docs": "## Surface\n\n```tsx\nimport { Surface } from '@thewhileloop/whileui';\n\n<Surface level=\"raised\" padding=\"default\">\n  {/* grouped content */}\n</Surface>;\n```\n\n\n| Prop          | Type                           | Default             | Description                          |\n| ------------- | ------------------------------ | ------------------- | ------------------------------------ |\n| level         | `SurfaceLevel`                 | `'base'`            | Semantic background and depth tier.  |\n| padding       | `SurfacePaddingSize`           | `'default'`         | Token-backed interior spacing.       |\n| radius        | `'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'xl'`              | Token-backed corner radius.          |\n| bordered      | `boolean`                      | `true`              | Draw the theme hairline border.      |\n| shadow        | `ShadowTier`                   | —                   | Override the level's depth.          |\n| className     | `string`                       | —                   |                                      |\n| frosted       | `boolean`                      | `false`             | Enable the optional frosted overlay. |\n| blurIntensity | `number`                       | subtle preset       | Override blur amount directly.       |\n| blurTintToken | `FrostedTintToken`             | `LEVEL_TINT[level]` | Tint token used for frosted mode.    |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "View",
+      "category": "Primitives",
+      "kind": "package",
+      "summary": "Themed view wrapper",
+      "docs": "### View\n\nThemed view wrapper\n\n```tsx\nimport { View } from '@thewhileloop/whileui';\n```\n\n\n| Prop      | Type     | Default | Description |\n| --------- | -------- | ------- | ----------- |\n| className | `string` | —       |             |\n\nAlso accepts the props of React Native's `ViewProps`."
+    },
+    {
+      "name": "Pressable",
+      "category": "Primitives",
+      "kind": "package",
+      "summary": "Themed pressable wrapper",
+      "docs": "## Pressable\n\n```tsx\nimport { Pressable, Text } from '@thewhileloop/whileui';\n\n<Pressable\n  accessibilityRole=\"button\"\n  feedback=\"strong\"\n  disabledFeedback=\"default\"\n  loading={false}\n  onPress={() => {}}\n>\n  <Text>Open</Text>\n</Pressable>;\n```\n\n`Pressable` preserves React Native's event, ref, accessibility, and function-style\n`style` contracts. Feedback changes opacity without changing layout. Native press state\ncomes directly from React Native; web adds a motion-policy-aware opacity transition.\n\n\n| Prop             | Type              | Default     | Description                                                                 |\n| ---------------- | ----------------- | ----------- | --------------------------------------------------------------------------- |\n| className        | `string`          | —           | Additional Tailwind classes.                                                |\n| feedback         | `PressedVariant`  | `'none'`    | Semantic press feedback. `none` preserves a plain React Native Pressable.   |\n| disabledFeedback | `DisabledVariant` | `'default'` | Opacity used while the control is unavailable.                              |\n| loading          | `boolean`         | `false`     | Loading controls are busy and non-interactive, just like disabled controls. |\n\nAlso accepts the props of React Native's `PressableProps`."
+    },
+    {
+      "name": "Stack",
+      "category": "Primitives",
+      "kind": "package",
+      "summary": "Vertical flex layout with gap",
+      "docs": "### Stack\n\nVertical flex layout with gap\n\n```tsx\nimport { Stack } from '@thewhileloop/whileui';\n```\n\n\n| Prop      | Type                                                                | Default     | Description |\n| --------- | ------------------------------------------------------------------- | ----------- | ----------- |\n| className | `string`                                                            | —           |             |\n| gap       | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`           | `'md'`      |             |\n| align     | `'start' \\| 'center' \\| 'end' \\| 'stretch' \\| 'baseline'`           | `'stretch'` |             |\n| justify   | `'start' \\| 'center' \\| 'end' \\| 'between' \\| 'around' \\| 'evenly'` | `'start'`   |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Row",
+      "category": "Primitives",
+      "kind": "package",
+      "summary": "Horizontal flex layout with gap",
+      "docs": "## Layout Primitives (Stack, Row)\n\nUse `Stack` for vertical layouts, `Row` for horizontal layouts. Both support `gap`, `align`, and `justify` variants.\n\n```tsx\nimport { Stack, Row } from '@thewhileloop/whileui';\n\n<Stack gap=\"lg\">\n  <Text>Title</Text>\n  <Row gap=\"md\" justify=\"between\">\n    <Button>\n      <ButtonText>Cancel</ButtonText>\n    </Button>\n    <Button>\n      <ButtonText>Save</ButtonText>\n    </Button>\n  </Row>\n</Stack>;\n```\n\n\n| Prop      | Type                                                                | Default    | Description |\n| --------- | ------------------------------------------------------------------- | ---------- | ----------- |\n| className | `string`                                                            | —          |             |\n| gap       | `'none' \\| 'xs' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| '2xl'`           | `'md'`     |             |\n| align     | `'start' \\| 'center' \\| 'end' \\| 'stretch' \\| 'baseline'`           | `'center'` |             |\n| justify   | `'start' \\| 'center' \\| 'end' \\| 'between' \\| 'around' \\| 'evenly'` | `'start'`  |             |\n\nAlso accepts the props of `ViewProps`.\n\n### Container\n\nCaps content width and centres it. Phone-first layouts stretch to the viewport, which\nis right at 390px and wrong at 1600px — line lengths become unreadable and related\ncontrols drift apart.\n\n```tsx\n<Container size=\"lg\">{children}</Container>\n```\n\n\n| Prop      | Type                                     | Default | Description |\n| --------- | ---------------------------------------- | ------- | ----------- |\n| className | `string`                                 | —       |             |\n| size      | `'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| 'full'` | `'md'`  |             |\n| fill      | `boolean`                                | `false` |             |\n\nAlso accepts the props of `ViewProps`.\n\nNo platform branch, and none is needed: every size is wider than any phone, so on iOS\nand Android the cap never engages and it renders as a plain full-width `View`. The same\ncomponent is a no-op on native and the whole fix on desktop.\n\nFor a scroll view, put the column on the content container so the scrollbar stays at\nthe window edge:\n\n```tsx\n<ScrollView contentContainerClassName=\"w-full max-w-5xl self-center\" />\n```"
+    },
+    {
+      "name": "MotionProvider",
+      "category": "Root Providers",
+      "kind": "package",
+      "summary": "System reduced motion, explicit preview modes, and deterministic testing",
+      "docs": "### MotionProvider\n\nSystem reduced motion, explicit preview modes, and deterministic testing\n\n```tsx\nimport { MotionProvider } from '@thewhileloop/whileui';\n```\n\n\n| Prop                | Type              | Default    | Description |\n| ------------------- | ----------------- | ---------- | ----------- |\n| children (required) | `React.ReactNode` | —          |             |\n| mode                | `MotionMode`      | `'system'` |             |"
+    },
+    {
+      "name": "Button",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "4 sizes, ButtonText & ButtonIcon sub-components",
+      "docs": "## Button\n\n```tsx\nimport { Button, ButtonText, ButtonIcon } from '@thewhileloop/whileui';\n\n<Button variant=\"default\" size=\"default\" disabled={false} loading={false} onPress={() => {}}>\n  <ButtonIcon>\n    <Icon />\n  </ButtonIcon>\n  <ButtonText>Click me</ButtonText>\n  {/* Placement is child order — a trailing ButtonIcon renders after the label. */}\n  <ButtonIcon>\n    <Icon />\n  </ButtonIcon>\n</Button>;\n```\n\n\n| Prop             | Type                                                                          | Default     | Description                                                             |\n| ---------------- | ----------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |\n| children         | `React.ReactNode`                                                             | —           |                                                                         |\n| className        | `string`                                                                      | —           | Additional Tailwind classes.                                            |\n| disabled         | `boolean`                                                                     | `false`     | Disable the button.                                                     |\n| loading          | `boolean`                                                                     | `false`     | Shows a centered spinner, exposes busy state, and prevents interaction. |\n| disabledFeedback | `DisabledVariant`                                                             | —           | Opacity used while the control is unavailable.                          |\n| size             | `'sm' \\| 'lg' \\| 'default' \\| 'icon'`                                         | `'default'` |                                                                         |\n| variant          | `'default' \\| 'destructive' \\| 'outline' \\| 'secondary' \\| 'ghost' \\| 'link'` | `'default'` |                                                                         |\n\nAlso accepts the props of `PressableProps`."
+    },
+    {
+      "name": "Input",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "TextInput wrapper with themed styling",
+      "docs": "## Input\n\n```tsx\nimport { Input } from '@thewhileloop/whileui';\n\n<Input placeholder=\"Email\" variant=\"default\" value={value} onChangeText={setValue} />;\n```\n\nOn web, filled Input, Textarea, NumericInput, and SmartInput surfaces preserve their\nthemed background, foreground, and caret when the browser autofills them.\n\n\n| Prop           | Type                              | Default     | Description |\n| -------------- | --------------------------------- | ----------- | ----------- |\n| aria-invalid   | `boolean`                         | —           |             |\n| className      | `string`                          | —           |             |\n| prefix         | `React.ReactNode`                 | —           |             |\n| suffix         | `React.ReactNode`                 | —           |             |\n| inputClassName | `string`                          | —           |             |\n| variant        | `'default' \\| 'error' \\| 'plain'` | `'default'` |             |\n\nAlso accepts the props of `TextInputProps`."
+    },
+    {
+      "name": "NumericInput",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "Numeric input with prefix/suffix slots, optional steppers, and compact size",
+      "docs": "## NumericInput\n\n```tsx\nimport { NumericInput } from '@thewhileloop/whileui';\n\n<NumericInput\n  value={amount}\n  onValueChange={setAmount}\n  prefix={<Text className=\"text-muted-foreground\">$</Text>}\n  suffix={<Text className=\"text-muted-foreground\">USD</Text>}\n  min={0}\n  step={0.5}\n  showSteppers\n  size=\"compact\"\n/>;\n```\n\n\n| Prop           | Type                              | Default     | Description                                                                                                            |\n| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |\n| aria-invalid   | `boolean`                         | —           |                                                                                                                        |\n| className      | `string`                          | —           |                                                                                                                        |\n| inputClassName | `string`                          | —           |                                                                                                                        |\n| prefix         | `React.ReactNode`                 | —           |                                                                                                                        |\n| suffix         | `React.ReactNode`                 | —           |                                                                                                                        |\n| value          | `number \\| null`                  | —           | Controlled numeric value.                                                                                              |\n| defaultValue   | `number`                          | —           |                                                                                                                        |\n| onValueChange  | `(value: number \\| null) => void` | —           | Numeric value change callback.                                                                                         |\n| min            | `number`                          | —           |                                                                                                                        |\n| max            | `number`                          | —           |                                                                                                                        |\n| step           | `number`                          | `1`         |                                                                                                                        |\n| showSteppers   | `boolean`                         | `false`     | Show decrement/increment controls.                                                                                     |\n| unstyled       | `boolean`                         | `false`     | Drop the field shell (border, background, radius, padding) for embedding inside another field shell like LabeledField. |\n| size           | `'default' \\| 'compact'`          | `'default'` |                                                                                                                        |\n| variant        | `'default' \\| 'error'`            | `'default'` |                                                                                                                        |\n\nAlso accepts the props of `TextInputProps`."
+    },
+    {
+      "name": "OTPInput",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "Verification code input with auto-focus, paste, secure mask, loading skeleton, error shake",
+      "docs": "## OTPInput\n\n```tsx\nimport { OTPInput } from '@thewhileloop/whileui';\n\n<OTPInput\n  value={otp}\n  onValueChange={setOtp}\n  onComplete={(code) => verify(code)}\n  length={6}\n  variant=\"default\"\n/>;\n```\n\n\n| Prop          | Type                      | Default     | Description                        |\n| ------------- | ------------------------- | ----------- | ---------------------------------- |\n| length        | `number`                  | `6`         | Number of digit cells.             |\n| value         | `string`                  | —           | Controlled value.                  |\n| onValueChange | `(value: string) => void` | —           | Called on each digit change.       |\n| onComplete    | `(code: string) => void`  | —           | Called when all digits are filled. |\n| variant       | `'default' \\| 'error'`    | `'default'` | Error variant triggers shake.      |\n| size          | `'default' \\| 'compact'`  | `'default'` | Cell size.                         |\n| secure        | `boolean`                 | `false`     | Mask digits with dots.             |\n| disabled      | `boolean`                 | `false`     |                                    |\n| autoFocus     | `boolean`                 | `false`     | Focus first cell on mount.         |\n| className     | `string`                  | —           |                                    |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "FormField",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "Compound API: FormField, FormLabel, FormControl, FormHint, FormMessage",
+      "docs": "## FormField\n\n```tsx\nimport {\n  FormField,\n  FormLabel,\n  FormControl,\n  FormHint,\n  FormMessage,\n  Input,\n} from '@thewhileloop/whileui';\n\n<FormField required invalid={Boolean(error)}>\n  <FormLabel>Email</FormLabel>\n  <FormControl>\n    <Input placeholder=\"you@example.com\" />\n  </FormControl>\n  {error ? <FormMessage>{error}</FormMessage> : <FormHint>We'll never share your email.</FormHint>}\n</FormField>;\n```\n\n`invalid` and `disabled` are inherited by `Input`, `Textarea`, `NumericInput`, and\n`Select`. An explicit control prop wins. `useFormFieldState()` exposes the same state for\ncustom controls; labels, hints, messages, density, and required indicators remain part\nof the compound field rather than each input.\n\n`FormLabel` names the `Input`, `Textarea` or `NumericInput` beside it for assistive\ntechnology (`aria-labelledby` on web and Android; `useFormFieldState().labelId` gives a\ncustom control the same id). A label passed to the control itself wins."
+    },
+    {
+      "name": "LabeledField",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "Field wrapper with label/helper/error plus left/right slots",
+      "docs": "## LabeledField\n\n```tsx\nimport { LabeledField, LabeledFieldControl, Input } from '@thewhileloop/whileui';\n\n<LabeledField\n  label=\"Username\"\n  hint=\"3-20 characters\"\n  leftSlot={<Icon />}\n  rightSlot={\n    <Button size=\"sm\">\n      <ButtonText>Check</ButtonText>\n    </Button>\n  }\n>\n  <LabeledFieldControl>\n    <Input className=\"border-0 bg-transparent px-0\" />\n  </LabeledFieldControl>\n</LabeledField>;\n```"
+    },
+    {
+      "name": "Textarea",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "Multi-line text input",
+      "docs": "### Textarea\n\nMulti-line text input\n\n```tsx\nimport { Textarea } from '@thewhileloop/whileui';\n```\n\n\n| Prop         | Type                        | Default     | Description |\n| ------------ | --------------------------- | ----------- | ----------- |\n| aria-invalid | `boolean`                   | —           |             |\n| className    | `string`                    | —           |             |\n| size         | `'sm' \\| 'lg' \\| 'default'` | `'default'` |             |\n\nAlso accepts the props of `TextInputProps`."
+    },
+    {
+      "name": "Checkbox",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "Controlled/uncontrolled, accessibility roles",
+      "docs": "## Checkbox\n\n```tsx\nimport { Checkbox } from '@thewhileloop/whileui';\n\n<Checkbox checked={checked} onCheckedChange={setChecked} />;\n```\n\n\n| Prop            | Type                         | Default | Description |\n| --------------- | ---------------------------- | ------- | ----------- |\n| checked         | `boolean`                    | —       |             |\n| defaultChecked  | `boolean`                    | `false` |             |\n| onCheckedChange | `(checked: boolean) => void` | —       |             |\n| disabled        | `boolean`                    | `false` |             |\n| className       | `string`                     | —       |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Switch",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "Controlled/uncontrolled, accessibility roles",
+      "docs": "## Switch\n\n```tsx\nimport { Switch } from '@thewhileloop/whileui';\n\n<Switch checked={checked} onCheckedChange={setChecked} />;\n```\n\n\n| Prop            | Type                         | Default | Description |\n| --------------- | ---------------------------- | ------- | ----------- |\n| checked         | `boolean`                    | —       |             |\n| defaultChecked  | `boolean`                    | `false` |             |\n| onCheckedChange | `(checked: boolean) => void` | —       |             |\n| disabled        | `boolean`                    | `false` |             |\n| className       | `string`                     | —       |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "RadioGroup",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "RadioGroup + RadioGroupItem",
+      "docs": "## RadioGroup\n\n```tsx\nimport { RadioGroup, RadioGroupItem } from '@thewhileloop/whileui';\n\n<RadioGroup value={value} onValueChange={setValue}>\n  <RadioGroupItem value=\"option1\" />\n  <RadioGroupItem value=\"option2\" />\n</RadioGroup>;\n```"
+    },
+    {
+      "name": "Select",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "Uses `SelectOption` type `{value, label}`. Includes SelectGroup, SelectLabel, SelectSeparator",
+      "docs": "## Select\n\n```tsx\nimport {\n  Select,\n  SelectTrigger,\n  SelectValue,\n  SelectContent,\n  SelectItem,\n} from '@thewhileloop/whileui';\n\n<Select value={value} onValueChange={setValue}>\n  <SelectTrigger>\n    <SelectValue placeholder=\"Select...\" />\n  </SelectTrigger>\n  <SelectContent frosted blurIntensity={24} blurTintToken=\"surfaceTranslucent\">\n    <SelectItem label=\"Option 1\" value=\"1\" />\n    <SelectItem label=\"Option 2\" value=\"2\" />\n  </SelectContent>\n</Select>;\n```\n\nFocused and pressed options use the subtle interaction-state tokens; the primary token\nmarks the selected indicator without replacing the option's foreground colour. Long\nselected values stay on one line and truncate without displacing the trigger chevron.\nFor popover presentation on web, the options panel matches the trigger width, caps\nitself to the collision-available viewport, and wraps long option labels inside it.\n\n`SelectContent` supports optional frosted props:\n\n\n| Prop          | Type                                                               | Default       | Description                          |\n| ------------- | ------------------------------------------------------------------ | ------------- | ------------------------------------ |\n| className     | `string`                                                           | —             |                                      |\n| portalHost    | `string`                                                           | —             |                                      |\n| insets        | `{ top?: number; bottom?: number; left?: number; right?: number }` | —             |                                      |\n| frosted       | `boolean`                                                          | `false`       | Enable the optional frosted overlay. |\n| blurIntensity | `number`                                                           | subtle preset | Override blur amount directly.       |\n| blurTintToken | `FrostedTintToken`                                                 | `'popover'`   | Tint token used for frosted mode.    |\n\nAlso accepts the props of the underlying primitive.\n\n`SelectContent` keeps its listbox inside the safe area by default; pass `insets` only to\nchange that margin. A list taller than the screen scrolls inside the listbox on every\nplatform. Inside a Dialog, Sheet or other WhileUI overlay it renders in that\noverlay's layer automatically. Option values must be non-empty strings: the web\nprimitive rejects `\"\"`, so model \"none\" as an explicit value such as `'none'`."
+    },
+    {
+      "name": "Label",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "Form field label",
+      "docs": "### Label\n\nForm field label\n\n```tsx\nimport { Label } from '@thewhileloop/whileui';\n```\n\n\n| Prop      | Type     | Default | Description |\n| --------- | -------- | ------- | ----------- |\n| className | `string` | —       |             |\n\nAlso accepts the props of `TextProps`."
+    },
+    {
+      "name": "SegmentedControl",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "SegmentedControl, SegmentedControlItem, SegmentedControlItemText with wrapping layout support",
+      "docs": "## SegmentedControl\n\n```tsx\nimport {\n  SegmentedControl,\n  SegmentedControlItem,\n  SegmentedControlItemText,\n} from '@thewhileloop/whileui';\n\n<SegmentedControl value={unit} onValueChange={setUnit} variant=\"pill\" wrap>\n  <SegmentedControlItem value=\"metric\">\n    <SegmentedControlItemText>Metric</SegmentedControlItemText>\n  </SegmentedControlItem>\n  <SegmentedControlItem value=\"imperial\">\n    <SegmentedControlItemText>Imperial</SegmentedControlItemText>\n  </SegmentedControlItem>\n</SegmentedControl>;\n```\n\n\n| Prop          | Type                      | Default     | Description                |\n| ------------- | ------------------------- | ----------- | -------------------------- |\n| value         | `string`                  | —           |                            |\n| defaultValue  | `string`                  | `''`        |                            |\n| onValueChange | `(value: string) => void` | —           |                            |\n| variant       | `'default' \\| 'pill'`     | `'default'` | Pill = rounded-full items. |\n| wrap          | `boolean \\| 'auto'`       | `true`      |                            |\n| size          | `'default' \\| 'compact'`  | `'default'` |                            |\n| disabled      | `boolean`                 | `false`     |                            |\n| className     | `string`                  | —           |                            |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Toggle",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "ToggleText sub-component",
+      "docs": "### Toggle\n\nToggleText sub-component\n\n```tsx\nimport { Toggle } from '@thewhileloop/whileui';\n```\n\n\n| Prop            | Type                                             | Default     | Description |\n| --------------- | ------------------------------------------------ | ----------- | ----------- |\n| pressed         | `boolean`                                        | `false`     |             |\n| defaultPressed  | `boolean`                                        | `false`     |             |\n| onPressedChange | `(pressed: boolean) => void`                     | —           |             |\n| variant         | `VariantProps<typeof toggleVariants>['variant']` | `'default'` |             |\n| size            | `VariantProps<typeof toggleVariants>['size']`    | `'default'` |             |\n| className       | `string`                                         | —           |             |\n| children        | `React.ReactNode`                                | —           |             |\n\nAlso accepts the props of `PressableProps`."
+    },
+    {
+      "name": "ToggleGroup",
+      "category": "Form Controls",
+      "kind": "package",
+      "summary": "Group of toggle items",
+      "docs": "### ToggleGroup\n\nGroup of toggle items\n\n```tsx\nimport { ToggleGroup } from '@thewhileloop/whileui';\n```\n\n\n| Prop          | Type                                  | Default     | Description |\n| ------------- | ------------------------------------- | ----------- | ----------- |\n| type          | `ToggleGroupType`                     | `'single'`  |             |\n| defaultValue  | `string \\| string[]`                  | —           |             |\n| value         | `string \\| string[]`                  | —           |             |\n| onValueChange | `(value: string \\| string[]) => void` | —           |             |\n| variant       | `'default' \\| 'outline'`              | `'default'` |             |\n| size          | `'default' \\| 'sm' \\| 'lg'`           | `'default'` |             |\n| className     | `string`                              | —           |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Card",
+      "category": "Display",
+      "kind": "package",
+      "summary": "Compound: Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter",
+      "docs": "## Card\n\n```tsx\nimport {\n  Card,\n  CardHeader,\n  CardTitle,\n  CardDescription,\n  CardContent,\n  CardFooter,\n} from '@thewhileloop/whileui';\n\n<Card padding=\"default\">\n  <CardHeader>\n    <CardTitle>Title</CardTitle>\n    <CardDescription>Description</CardDescription>\n  </CardHeader>\n  <CardContent>{/* Content */}</CardContent>\n  <CardFooter>{/* Footer */}</CardFooter>\n</Card>;\n\n<Card unstyled padding=\"none\" className=\"rounded-xl border border-border bg-card\">\n  {/* advanced custom layouts */}\n</Card>;\n```\n\n\n| Prop          | Type                                  | Default     | Description                                             |\n| ------------- | ------------------------------------- | ----------- | ------------------------------------------------------- |\n| shadow        | `ShadowTier`                          | `'sm'`      | Elevation tier; 'sm' by default, 'none' for flat cards. |\n| className     | `string`                              | —           |                                                         |\n| padding       | `'none' \\| 'sm' \\| 'lg' \\| 'default'` | `'default'` |                                                         |\n| unstyled      | `boolean`                             | `false`     |                                                         |\n| frosted       | `boolean`                             | `false`     | Enable the optional frosted overlay.                    |\n| blurIntensity | `number`                              | —           | Override blur amount directly.                          |\n| blurTintToken | `FrostedTintToken`                    | —           | Tint token used for frosted mode.                       |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Surface",
+      "category": "Display",
+      "kind": "package",
+      "summary": "Shared radius, padding, border, shadow, and optional frosted treatment",
+      "docs": "## Surface\n\n```tsx\nimport { Surface } from '@thewhileloop/whileui';\n\n<Surface level=\"raised\" padding=\"default\">\n  {/* grouped content */}\n</Surface>;\n```\n\n\n| Prop          | Type                           | Default             | Description                          |\n| ------------- | ------------------------------ | ------------------- | ------------------------------------ |\n| level         | `SurfaceLevel`                 | `'base'`            | Semantic background and depth tier.  |\n| padding       | `SurfacePaddingSize`           | `'default'`         | Token-backed interior spacing.       |\n| radius        | `'sm' \\| 'md' \\| 'lg' \\| 'xl'` | `'xl'`              | Token-backed corner radius.          |\n| bordered      | `boolean`                      | `true`              | Draw the theme hairline border.      |\n| shadow        | `ShadowTier`                   | —                   | Override the level's depth.          |\n| className     | `string`                       | —                   |                                      |\n| frosted       | `boolean`                      | `false`             | Enable the optional frosted overlay. |\n| blurIntensity | `number`                       | subtle preset       | Override blur amount directly.       |\n| blurTintToken | `FrostedTintToken`             | `LEVEL_TINT[level]` | Tint token used for frosted mode.    |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Badge",
+      "category": "Display",
+      "kind": "package",
+      "summary": "BadgeText sub-component",
+      "docs": "## Badge\n\n```tsx\nimport { Badge, BadgeText } from '@thewhileloop/whileui';\n\n<Badge variant=\"default\">\n  <BadgeText>New</BadgeText>\n</Badge>;\n```\n\n\n| Prop      | Type                                                                                                                                                                                                | Default     | Description |\n| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |\n| className | `string`                                                                                                                                                                                            | —           |             |\n| variant   | `'default' \\| 'soft' \\| 'destructive' \\| 'outline' \\| 'secondary' \\| 'success' \\| 'warning' \\| 'info' \\| 'soft-secondary' \\| 'soft-destructive' \\| 'soft-success' \\| 'soft-warning' \\| 'soft-info'` | `'default'` |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "FAB",
+      "category": "Display",
+      "kind": "package",
+      "summary": "Floating action button. `label` required; pass your own icon as children",
+      "docs": "### FAB\n\nOne primary action, raised above the content. It owns no icon dependency — pass the\nglyph as children and colour it from `useIconColors()`, because icon libraries need a\nconcrete colour rather than a class.\n\n```tsx\nimport { FAB, useIconColors } from '@thewhileloop/whileui';\nimport { Feather } from '@expo/vector-icons';\n\nconst icons = useIconColors();\n\n<FAB label=\"New group\" onPress={create}>\n  <Feather name=\"plus\" size={24} color={icons.primaryForeground} />\n</FAB>;\n```\n\n| Prop        | Type                                             | Default    | Notes                                   |\n| ----------- | ------------------------------------------------ | ---------- | --------------------------------------- |\n| `label`     | `string`                                         | —          | Required. The accessible name           |\n| `variant`   | `default \\| secondary \\| destructive \\| surface` | `default`  |                                         |\n| `size`      | `sm \\| default \\| lg`                            | `default`  | 48 / 56 / 64 — all clear touch minimums |\n| `placement` | `floating \\| floating-left \\| inline`            | `floating` | `inline` lets the caller position it    |\n\n`FABGroup` stacks secondary actions above one. Sizes start at 48dp, so a FAB never\nneeds `hitSlop`."
+    },
+    {
+      "name": "Alert",
+      "category": "Display",
+      "kind": "package",
+      "summary": "AlertTitle & AlertDescription",
+      "docs": "## Alert\n\n```tsx\nimport { Alert, AlertTitle, AlertDescription } from '@thewhileloop/whileui';\n\n<Alert variant=\"default\">\n  <AlertTitle>Heads up!</AlertTitle>\n  <AlertDescription>Something happened.</AlertDescription>\n</Alert>;\n\n// Shown after a failed submit: also spoken on iOS when it appears.\n<Alert variant=\"destructive\" announce>\n  <AlertTitle>Could not save</AlertTitle>\n  <AlertDescription>Check your connection and try again.</AlertDescription>\n</Alert>;\n```\n\n\n| Prop      | Type                                                             | Default     | Description                                                                                                                                                                                                                                                                                                        |\n| --------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| announce  | `boolean`                                                        | `false`     | Speak the alert when it appears, for alerts shown in response to an action such as a failed submit. Android and the web already read it through the live region; iOS has none, so this announces its text once. Leave it off for alerts that are part of a screen's content, or every visit would read them aloud. |\n| className | `string`                                                         | —           |                                                                                                                                                                                                                                                                                                                    |\n| variant   | `'default' \\| 'destructive' \\| 'success' \\| 'warning' \\| 'info'` | `'default'` |                                                                                                                                                                                                                                                                                                                    |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Avatar",
+      "category": "Display",
+      "kind": "package",
+      "summary": "AvatarImage + AvatarFallback",
+      "docs": "## Avatar\n\n```tsx\nimport { Avatar, AvatarImage, AvatarFallback } from '@thewhileloop/whileui';\n\n<Avatar size=\"default\">\n  <AvatarImage source={{ uri: 'https://...' }} />\n  <AvatarFallback>JD</AvatarFallback>\n</Avatar>;\n```\n\n\n| Prop      | Type                                | Default     | Description |\n| --------- | ----------------------------------- | ----------- | ----------- |\n| className | `string`                            | —           |             |\n| size      | `'sm' \\| 'lg' \\| 'xl' \\| 'default'` | `'default'` |             |\n\nAlso accepts the props of `ViewProps`.\n\n`AvatarImage` keeps `AvatarFallback` visible while loading or after an error. Its\n`onLoadingStatusChange` callback reports `'loading'`, `'loaded'`, and `'error'`, including\nwhen a changed source begins loading, while the standard image event callbacks still run."
+    },
+    {
+      "name": "DataRow",
+      "category": "Display",
+      "kind": "package",
+      "summary": "DataRow, DataRowLeft/Center/Right, DataRowLabel/Description/Value",
+      "docs": "## DataRow\n\n```tsx\nimport {\n  DataRow,\n  DataRowLeft,\n  DataRowCenter,\n  DataRowRight,\n  DataRowLabel,\n  DataRowDescription,\n  DataRowValue,\n  Avatar,\n  AvatarFallback,\n} from '@thewhileloop/whileui';\n\n<DataRow>\n  <DataRowLeft>\n    <Avatar size=\"sm\">\n      <AvatarFallback>JD</AvatarFallback>\n    </Avatar>\n  </DataRowLeft>\n  <DataRowCenter>\n    <DataRowLabel>Jane Doe</DataRowLabel>\n    <DataRowDescription>Product Designer</DataRowDescription>\n  </DataRowCenter>\n  <DataRowRight>\n    <DataRowValue>Owner</DataRowValue>\n  </DataRowRight>\n</DataRow>;\n```"
+    },
+    {
+      "name": "Separator",
+      "category": "Display",
+      "kind": "package",
+      "summary": "Themed divider",
+      "docs": "### Separator\n\nThemed divider\n\n```tsx\nimport { Separator } from '@thewhileloop/whileui';\n```\n\n\n| Prop        | Type                         | Default        | Description |\n| ----------- | ---------------------------- | -------------- | ----------- |\n| orientation | `'horizontal' \\| 'vertical'` | `'horizontal'` |             |\n| className   | `string`                     | —              |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Progress",
+      "category": "Display",
+      "kind": "package",
+      "summary": "Value-based progress bar with accessibility",
+      "docs": "## Progress\n\n```tsx\nimport { Progress } from '@thewhileloop/whileui';\n\n<Progress value={50} size=\"default\" />;\n```\n\n\n| Prop               | Type                        | Default     | Description |\n| ------------------ | --------------------------- | ----------- | ----------- |\n| value              | `number`                    | `0`         |             |\n| indicatorClassName | `string`                    | —           |             |\n| className          | `string`                    | —           |             |\n| size               | `'sm' \\| 'lg' \\| 'default'` | `'default'` |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Spinner",
+      "category": "Display",
+      "kind": "package",
+      "summary": "ActivityIndicator wrapper",
+      "docs": "### Spinner\n\nActivityIndicator wrapper\n\n```tsx\nimport { Spinner } from '@thewhileloop/whileui';\n```\n\n\n| Prop      | Type                        | Default     | Description |\n| --------- | --------------------------- | ----------- | ----------- |\n| className | `string`                    | —           |             |\n| size      | `'sm' \\| 'lg' \\| 'default'` | `'default'` |             |\n\nAlso accepts the props of `ActivityIndicatorProps`."
+    },
+    {
+      "name": "Skeleton",
+      "category": "Display",
+      "kind": "package",
+      "summary": "Loading placeholder (pulse = opacity fade, shimmer = sweep)",
+      "docs": "### Skeleton\n\nLoading placeholder (pulse = opacity fade, shimmer = sweep)\n\n```tsx\nimport { Skeleton } from '@thewhileloop/whileui';\n```\n\n\n| Prop      | Type                   | Default   | Description |\n| --------- | ---------------------- | --------- | ----------- |\n| className | `string`               | —         |             |\n| variant   | `'pulse' \\| 'shimmer'` | `'pulse'` |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "AspectRatio",
+      "category": "Display",
+      "kind": "package",
+      "summary": "Maintain aspect ratio container",
+      "docs": "### AspectRatio\n\nMaintain aspect ratio container\n\n```tsx\nimport { AspectRatio } from '@thewhileloop/whileui';\n```\n\n\n| Prop      | Type     | Default | Description |\n| --------- | -------- | ------- | ----------- |\n| ratio     | `number` | `1`     |             |\n| className | `string` | —       |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Tabs",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "TabsList, TabsTrigger, TabsContent",
+      "docs": "## Tabs\n\n```tsx\nimport { Tabs, TabsList, TabsTrigger, TabsContent } from '@thewhileloop/whileui';\n\n<Tabs defaultValue=\"tab1\">\n  <TabsList>\n    <TabsTrigger value=\"tab1\">\n      <Text>Tab 1</Text>\n    </TabsTrigger>\n    <TabsTrigger value=\"tab2\">\n      <Text>Tab 2</Text>\n    </TabsTrigger>\n  </TabsList>\n  <TabsContent value=\"tab1\">{/* Content 1 */}</TabsContent>\n  <TabsContent value=\"tab2\">{/* Content 2 */}</TabsContent>\n</Tabs>;\n```"
+    },
+    {
+      "name": "Accordion",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "AccordionItem, AccordionTrigger, Content",
+      "docs": "## Accordion\n\n```tsx\nimport {\n  Accordion,\n  AccordionItem,\n  AccordionTrigger,\n  AccordionContent,\n} from '@thewhileloop/whileui';\n\n<Accordion type=\"single\" collapsible>\n  <AccordionItem value=\"item1\">\n    <AccordionTrigger>\n      <Text>Section 1</Text>\n    </AccordionTrigger>\n    <AccordionContent>\n      <Text>Content 1</Text>\n    </AccordionContent>\n  </AccordionItem>\n</Accordion>;\n```\n\n\n| Prop         | Type                 | Default    | Description |\n| ------------ | -------------------- | ---------- | ----------- |\n| type         | `AccordionType`      | `'single'` |             |\n| defaultValue | `string \\| string[]` | —          |             |\n| collapsible  | `boolean`            | `true`     |             |\n| className    | `string`             | —          |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Collapsible",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "CollapsibleTrigger, CollapsibleContent",
+      "docs": "### Collapsible\n\nCollapsibleTrigger, CollapsibleContent\n\n```tsx\nimport { Collapsible } from '@thewhileloop/whileui';\n```\n\n\n| Prop         | Type                      | Default | Description |\n| ------------ | ------------------------- | ------- | ----------- |\n| defaultOpen  | `boolean`                 | `false` |             |\n| open         | `boolean`                 | —       |             |\n| onOpenChange | `(open: boolean) => void` | —       |             |\n| disabled     | `boolean`                 | `false` |             |\n| className    | `string`                  | —       |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Container",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Centred content column with a max width",
+      "docs": "### Container\n\nCaps content width and centres it. Phone-first layouts stretch to the viewport, which\nis right at 390px and wrong at 1600px — line lengths become unreadable and related\ncontrols drift apart.\n\n```tsx\n<Container size=\"lg\">{children}</Container>\n```\n\n\n| Prop      | Type                                     | Default | Description |\n| --------- | ---------------------------------------- | ------- | ----------- |\n| className | `string`                                 | —       |             |\n| size      | `'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| 'full'` | `'md'`  |             |\n| fill      | `boolean`                                | `false` |             |\n\nAlso accepts the props of `ViewProps`.\n\nNo platform branch, and none is needed: every size is wider than any phone, so on iOS\nand Android the cap never engages and it renders as a plain full-width `View`. The same\ncomponent is a no-op on native and the whole fix on desktop.\n\nFor a scroll view, put the column on the content container so the scrollbar stays at\nthe window edge:\n\n```tsx\n<ScrollView contentContainerClassName=\"w-full max-w-5xl self-center\" />\n```"
+    },
+    {
+      "name": "Dialog",
+      "category": "Overlays & Menus",
+      "kind": "package",
+      "summary": "Modal dialog with Header, Footer, Title, Description",
+      "docs": "## Dialog\n\n```tsx\nimport {\n  Dialog,\n  DialogTrigger,\n  DialogContent,\n  DialogHeader,\n  DialogTitle,\n  DialogDescription,\n  DialogFooter,\n  DialogClose,\n} from '@thewhileloop/whileui';\n\n<Dialog>\n  <DialogTrigger asChild>\n    <Button>\n      <ButtonText>Open</ButtonText>\n    </Button>\n  </DialogTrigger>\n  <DialogContent>\n    <DialogHeader>\n      <DialogTitle>Title</DialogTitle>\n      <DialogDescription>Description</DialogDescription>\n    </DialogHeader>\n    {/* Content */}\n    <DialogFooter>\n      <DialogClose asChild>\n        <Button>\n          <ButtonText>Close</ButtonText>\n        </Button>\n      </DialogClose>\n    </DialogFooter>\n  </DialogContent>\n</Dialog>;\n```\n\n`DialogContent` supports frosted props:\n\n\n| Prop          | Type               | Default                | Description                          |\n| ------------- | ------------------ | ---------------------- | ------------------------------------ |\n| className     | `string`           | —                      |                                      |\n| frosted       | `boolean`          | `false`                | Enable the optional frosted overlay. |\n| blurIntensity | `number`           | medium preset          | Override blur amount directly.       |\n| blurTintToken | `FrostedTintToken` | `'surfaceTranslucent'` | Tint token used for frosted mode.    |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "AlertDialog",
+      "category": "Overlays & Menus",
+      "kind": "package",
+      "summary": "Confirmation dialog with Action/Cancel buttons",
+      "docs": "## AlertDialog\n\n```tsx\nimport {\n  AlertDialog,\n  AlertDialogTrigger,\n  AlertDialogContent,\n  AlertDialogHeader,\n  AlertDialogTitle,\n  AlertDialogDescription,\n  AlertDialogFooter,\n  AlertDialogAction,\n  AlertDialogCancel,\n} from '@thewhileloop/whileui';\n\n<AlertDialog>\n  <AlertDialogTrigger asChild>\n    <Button variant=\"destructive\">\n      <ButtonText>Delete</ButtonText>\n    </Button>\n  </AlertDialogTrigger>\n  <AlertDialogContent>\n    <AlertDialogHeader>\n      <AlertDialogTitle>Are you sure?</AlertDialogTitle>\n      <AlertDialogDescription>This action cannot be undone.</AlertDialogDescription>\n    </AlertDialogHeader>\n    <AlertDialogFooter>\n      <AlertDialogCancel>Cancel</AlertDialogCancel>\n      <AlertDialogAction>Delete</AlertDialogAction>\n    </AlertDialogFooter>\n  </AlertDialogContent>\n</AlertDialog>;\n```\n\n`AlertDialogContent` supports the same frosted props as `DialogContent`.\n\n\n| Prop          | Type                      | Default                | Description                                                                                                                                                                                                                          |\n| ------------- | ------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| className     | `string`                  | —                      |                                                                                                                                                                                                                                      |\n| presentation  | `AlertDialogPresentation` | `'modal'`              | `modal` — RN `Modal` + themed card (default). `native` — `Alert.alert` on iOS/Android (system chrome); ignored on web. `overlay` — same themed card as `modal`, but absolute fill inside the parent view (nest inside your `Modal`). |\n| frosted       | `boolean`                 | `false`                | Enable the optional frosted overlay.                                                                                                                                                                                                 |\n| blurIntensity | `number`                  | medium preset          | Override blur amount directly.                                                                                                                                                                                                       |\n| blurTintToken | `FrostedTintToken`        | `'surfaceTranslucent'` | Tint token used for frosted mode.                                                                                                                                                                                                    |\n\nAlso accepts the props of `ViewProps`.\n\n### React Native: stacked modals\n\nRender a confirmation **inside** the overlay it belongs to. An `AlertDialog` or `Dialog`\nnested in a `Sheet` opens above it, and Android back or Escape closes the confirmation\nbefore the sheet. If `AlertDialog` must be a **sibling** of another fullscreen `Modal`, iOS\noften fails to show a second `Modal` on top; use **`presentation=\"overlay\"`** inside that\n`Modal`, or **`presentation=\"native\"`** for a system `Alert.alert` when themed UI is not\nrequired."
+    },
+    {
+      "name": "Popover",
+      "category": "Overlays & Menus",
+      "kind": "package",
+      "summary": "Position-aware popover (requires PortalHost)",
+      "docs": "## Popover\n\n```tsx\nimport { Popover, PopoverTrigger, PopoverContent } from '@thewhileloop/whileui';\n\n<Popover>\n  <PopoverTrigger asChild>\n    <Button>\n      <ButtonText>Open</ButtonText>\n    </Button>\n  </PopoverTrigger>\n  <PopoverContent>\n    <Text>Popover content</Text>\n  </PopoverContent>\n</Popover>;\n```\n\n`PopoverContent` supports frosted props:\n\n\n| Prop          | Type                     | Default       | Description                                                                                           |\n| ------------- | ------------------------ | ------------- | ----------------------------------------------------------------------------------------------------- |\n| className     | `string`                 | —             |                                                                                                       |\n| portalHost    | `string`                 | —             |                                                                                                       |\n| insets        | `Partial<OverlayInsets>` | —             | Collision padding. Defaults to safe area plus a margin so the panel never sits flush against an edge. |\n| frosted       | `boolean`                | `false`       | Enable the optional frosted overlay.                                                                  |\n| blurIntensity | `number`                 | subtle preset | Override blur amount directly.                                                                        |\n| blurTintToken | `FrostedTintToken`       | `'popover'`   | Tint token used for frosted mode.                                                                     |\n\nAlso accepts the props of the underlying primitive."
+    },
+    {
+      "name": "Tooltip",
+      "category": "Overlays & Menus",
+      "kind": "package",
+      "summary": "Position-aware tooltip (requires PortalHost)",
+      "docs": "### Tooltip\n\nPosition-aware tooltip (requires PortalHost)\n\n```tsx\nimport { Tooltip } from '@thewhileloop/whileui';\n```\n\n\n| Prop                    | Type                      | Default | Description |\n| ----------------------- | ------------------------- | ------- | ----------- |\n| onOpenChange            | `(open: boolean) => void` | —       |             |\n| delayDuration           | `number`                  | —       |             |\n| skipDelayDuration       | `number`                  | —       |             |\n| disableHoverableContent | `boolean`                 | —       |             |\n| children (required)     | `React.ReactNode`         | —       |             |"
+    },
+    {
+      "name": "DropdownMenu",
+      "category": "Overlays & Menus",
+      "kind": "package",
+      "summary": "DropdownMenuTrigger, Content, Item, Label, Separator",
+      "docs": "## DropdownMenu\n\n```tsx\nimport {\n  DropdownMenu,\n  DropdownMenuTrigger,\n  DropdownMenuContent,\n  DropdownMenuItem,\n  DropdownMenuLabel,\n  DropdownMenuSeparator,\n} from '@thewhileloop/whileui';\n\n<DropdownMenu>\n  <DropdownMenuTrigger asChild>\n    <Button>\n      <ButtonText>Menu</ButtonText>\n    </Button>\n  </DropdownMenuTrigger>\n  <DropdownMenuContent>\n    <DropdownMenuLabel>Actions</DropdownMenuLabel>\n    <DropdownMenuSeparator />\n    <DropdownMenuItem>\n      <Text>Edit</Text>\n    </DropdownMenuItem>\n    <DropdownMenuItem>\n      <Text>Delete</Text>\n    </DropdownMenuItem>\n  </DropdownMenuContent>\n</DropdownMenu>;\n```\n\n`DropdownMenuContent`, `ContextMenuContent`, and `MenubarContent` support the same frosted props as `PopoverContent` (default blur preset: medium)."
+    },
+    {
+      "name": "ContextMenu",
+      "category": "Overlays & Menus",
+      "kind": "package",
+      "summary": "Long-press context menu",
+      "docs": "## ContextMenu\n\n`ContextMenuContent` supports the same frosted props as `PopoverContent` (default blur preset: medium)."
+    },
+    {
+      "name": "HoverCard",
+      "category": "Overlays & Menus",
+      "kind": "package",
+      "summary": "Position-aware hover card (requires PortalHost)",
+      "docs": "## HoverCard\n\n`HoverCardContent` supports the same frosted props as `PopoverContent` (default blur preset: subtle)."
+    },
+    {
+      "name": "Menubar",
+      "category": "Overlays & Menus",
+      "kind": "package",
+      "summary": "Horizontal menu bar",
+      "docs": "## Menubar\n\n```tsx\nimport {\n  Menubar,\n  MenubarMenu,\n  MenubarTrigger,\n  MenubarContent,\n  MenubarLabel,\n  MenubarItem,\n  MenubarSeparator,\n} from '@thewhileloop/whileui';\n\n<Menubar>\n  <MenubarMenu>\n    <MenubarTrigger>\n      <Text className=\"text-foreground text-sm\">File</Text>\n    </MenubarTrigger>\n    <MenubarContent>\n      <MenubarLabel>Project</MenubarLabel>\n      <MenubarItem>\n        <Text className=\"text-foreground\">New Project</Text>\n      </MenubarItem>\n      <MenubarSeparator />\n      <MenubarItem>\n        <Text className=\"text-foreground\">Export</Text>\n      </MenubarItem>\n    </MenubarContent>\n  </MenubarMenu>\n</Menubar>;\n```\n\n`MenubarLabel` is a non-interactive section heading. It takes a string or elements, and\nannounces as a heading to assistive technology — as do `DropdownMenuLabel` and\n`ContextMenuLabel`.\n\n`MenubarContent` supports the same frosted props as `PopoverContent` (default blur preset: medium).\n\n---\n\n# Blocks API"
+    },
+    {
+      "name": "Toast",
+      "category": "Feedback",
+      "kind": "package",
+      "summary": "ToastProvider, ToastContainer, useToast() hook",
+      "docs": "## Toast\n\n```tsx\nimport { ToastProvider, ToastContainer, useToast } from '@thewhileloop/whileui';\n\n// Wrap app\n<ToastProvider>\n  <App />\n  <ToastContainer position=\"top\" />\n</ToastProvider>;\n\n// Use in component\nconst { toast } = useToast();\ntoast({ title: 'Success', description: 'Saved!', variant: 'success' });\n```\n\n| Toast Options | Type                                      |\n| ------------- | ----------------------------------------- |\n| title         | `string`                                  |\n| description   | `string`                                  |\n| variant       | `'default' \\| 'success' \\| 'destructive'` |\n| duration      | `number` (ms)                             |\n\nEach toast owns its duration from the moment it appears; adding or dismissing another\ntoast does not restart timers already in progress.\n\nEvery variant sits on the theme's `popover` surface; `success` and `destructive` mark the\ntoast with a status dot and tinted border rather than a solid fill. The stack is capped\nat `max-w-md` and centred, which never engages on a phone. A toast is announced politely\nto screen readers without taking focus, and its slide-in follows the motion policy."
+    },
+    {
+      "name": "SignInForm",
+      "category": "Auth",
+      "kind": "template",
+      "summary": "Email/password sign in with callbacks",
+      "docs": "## SignInForm\n\nCopy `sign-in-form.tsx` and its sibling `auth-form-footer.tsx` from\n`apps/showcase/catalog/templates/auth/`, then:\n\n```tsx\nimport { SignInForm } from './templates/auth'; // or your path\n\n<SignInForm\n  onSubmit={({ email, password }) => signIn(email, password)}\n  onForgotPassword={() => navigate('ForgotPassword')}\n  onSignUp={() => navigate('SignUp')}\n  onGooglePress={() => signInWithGoogle()}\n  onApplePress={() => signInWithApple()}\n/>;\n```\n\n| Prop             | Type                                  | Description                  |\n| ---------------- | ------------------------------------- | ---------------------------- |\n| onSubmit         | `(data: { email, password }) => void` | Called on sign-in submit     |\n| onForgotPassword | `() => void`                          | Called when \"Forgot?\" tapped |\n| onSignUp         | `() => void`                          | Called when \"Sign Up\" tapped |\n| onGooglePress    | `() => void`                          | Called when Google tapped    |\n| onApplePress     | `() => void`                          | Called when Apple tapped     |",
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "SignUpForm",
+      "category": "Auth",
+      "kind": "template",
+      "summary": "Registration form with callbacks",
+      "docs": "## SignUpForm\n\nCopy `sign-up-form.tsx` and its sibling `auth-form-footer.tsx` from\n`apps/showcase/catalog/templates/auth/`, then:\n\n```tsx\nimport { SignUpForm } from './templates/auth'; // or your path\n\n<SignUpForm\n  onSubmit={({ firstName, lastName, email, password }) =>\n    signUp(firstName, lastName, email, password)\n  }\n  onSignIn={() => navigate('SignIn')}\n  onGooglePress={() => signInWithGoogle()}\n  onApplePress={() => signInWithApple()}\n/>;\n```\n\n| Prop          | Type                                                       | Description                  |\n| ------------- | ---------------------------------------------------------- | ---------------------------- |\n| onSubmit      | `(data: { firstName, lastName, email, password }) => void` | Called on registration       |\n| onSignIn      | `() => void`                                               | Called when \"Sign In\" tapped |\n| onGooglePress | `() => void`                                               | Called when Google tapped    |\n| onApplePress  | `() => void`                                               | Called when Apple tapped     |",
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "ForgotPasswordForm",
+      "category": "Auth",
+      "kind": "template",
+      "summary": "Password reset request",
+      "docs": null,
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "ResetPasswordForm",
+      "category": "Auth",
+      "kind": "template",
+      "summary": "Set new password",
+      "docs": null,
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "VerifyEmailForm",
+      "category": "Auth",
+      "kind": "template",
+      "summary": "Email verification code input",
+      "docs": null,
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "SocialConnections",
+      "category": "Auth",
+      "kind": "template",
+      "summary": "OAuth provider buttons",
+      "docs": null,
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "UserMenu",
+      "category": "Auth",
+      "kind": "template",
+      "summary": "Profile dropdown for auth flows",
+      "docs": null,
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "AppShell",
+      "category": "Navigation",
+      "kind": "package",
+      "summary": "Layout shell with header/footer/bottomNav slots",
+      "docs": "## AppShell\n\nLayout shell for full-screen pages. Keep shell chrome mounted and swap only content via `loading` + `skeleton`.\n\n```tsx\nimport { AppShell, PageSkeleton } from '@thewhileloop/whileui';\n\n<AppShell\n  header={<Header title=\"Settings\" />}\n  bottomNav={<BottomNav items={[...]} activeKey=\"settings\" onSelect={setTab} />}\n  loading={loading}\n  skeleton={<PageSkeleton variant=\"settings\" headerPlaceholder />}\n>\n  <ScrollView className=\"flex-1 p-4\">{/* Content */}</ScrollView>\n</AppShell>;\n```\n\n\n| Prop      | Type              | Default | Description                                               |\n| --------- | ----------------- | ------- | --------------------------------------------------------- |\n| header    | `React.ReactNode` | —       | Header slot.                                              |\n| footer    | `React.ReactNode` | —       | Footer slot.                                              |\n| bottomNav | `React.ReactNode` | —       | Bottom navigation slot.                                   |\n| safeArea  | `boolean`         | `true`  | Wrap in SafeAreaView.                                     |\n| loading   | `boolean`         | `false` | Keep shell mounted while swapping content with skeleton.  |\n| skeleton  | `React.ReactNode` | —       | Optional custom loading placeholder for the content area. |\n| className | `string`          | —       |                                                           |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Header",
+      "category": "Navigation",
+      "kind": "package",
+      "summary": "Top app bar with back/actions",
+      "docs": "## Header\n\n```tsx\nimport { Header, HeaderBackButton } from '@thewhileloop/whileui';\n\n<Header\n  title=\"Settings\"\n  subtitle=\"Manage preferences\"\n  leftAction={<HeaderBackButton onPress={() => {}} />}\n  rightActions={[\n    { key: 'search', icon: <Icon />, onPress: () => {}, accessibilityLabel: 'Search' },\n  ]}\n/>;\n```"
+    },
+    {
+      "name": "BottomNav",
+      "category": "Navigation",
+      "kind": "package",
+      "summary": "Tab-style bottom navigation bar",
+      "docs": "## BottomNav\n\n```tsx\nimport { BottomNav } from '@thewhileloop/whileui';\n\n<BottomNav\n  items={[\n    { key: 'home', label: 'Home', icon: <Icon /> },\n    { key: 'profile', label: 'Profile', icon: <Icon />, badge: 3 },\n  ]}\n  activeKey=\"home\"\n  onSelect={(key) => {}}\n/>;\n```"
+    },
+    {
+      "name": "FloatingBottomNav",
+      "category": "Navigation",
+      "kind": "package",
+      "summary": "Elevated bottom nav with safe area support",
+      "docs": "### FloatingBottomNav\n\nElevated bottom nav with safe area support\n\n```tsx\nimport { FloatingBottomNav } from '@thewhileloop/whileui';\n```\n\n\n| Prop                 | Type                      | Default | Description |\n| -------------------- | ------------------------- | ------- | ----------- |\n| items (required)     | `FloatingBottomNavItem[]` | —       |             |\n| activeKey (required) | `string`                  | —       |             |\n| onSelect (required)  | `(key: string) => void`   | —       |             |\n| className            | `string`                  | —       |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "TabBar",
+      "category": "Navigation",
+      "kind": "package",
+      "summary": "Top tab bar with indicator",
+      "docs": "### TabBar\n\nTop tab bar with indicator\n\n```tsx\nimport { TabBar } from '@thewhileloop/whileui';\n```\n\n\n| Prop                 | Type                                  | Default     | Description |\n| -------------------- | ------------------------------------- | ----------- | ----------- |\n| items (required)     | `TabBarItem[]`                        | —           |             |\n| activeKey (required) | `string`                              | —           |             |\n| onSelect (required)  | `(key: string) => void`               | —           |             |\n| variant              | `'default' \\| 'pills' \\| 'underline'` | `'default'` |             |\n| scrollable           | `boolean`                             | `false`     |             |\n| className            | `string`                              | —           |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "DrawerMenu",
+      "category": "Navigation",
+      "kind": "package",
+      "summary": "Drawer with sections and items",
+      "docs": "## DrawerMenu\n\n```tsx\nimport { DrawerMenu } from '@thewhileloop/whileui';\n\n<DrawerMenu\n  visible={open}\n  onClose={() => setOpen(false)}\n  sections={[\n    {\n      title: 'Menu',\n      items: [\n        { key: 'home', label: 'Home', icon: <Icon /> },\n        { key: 'settings', label: 'Settings', icon: <Icon /> },\n      ],\n    },\n  ]}\n  activeKey=\"home\"\n  onSelect={(key) => {}}\n  header={<View>...</View>}\n  footer={<Text>v1.0</Text>}\n/>;\n```\n\n\n| Prop                | Type                    | Default                | Description                                                 |\n| ------------------- | ----------------------- | ---------------------- | ----------------------------------------------------------- |\n| visible (required)  | `boolean`               | —                      |                                                             |\n| onClose (required)  | `() => void`            | —                      |                                                             |\n| sections (required) | `DrawerMenuSection[]`   | —                      |                                                             |\n| activeKey           | `string`                | —                      |                                                             |\n| onSelect            | `(key: string) => void` | —                      |                                                             |\n| header              | `React.ReactNode`       | —                      |                                                             |\n| footer              | `React.ReactNode`       | —                      |                                                             |\n| maxWidth            | `number`                | —                      | Max width in px. On web, defaults to 360 when not provided. |\n| className           | `string`                | —                      |                                                             |\n| style               | `StyleProp<ViewStyle>`  | —                      |                                                             |\n| frosted             | `boolean`               | `false`                | Enable the optional frosted overlay.                        |\n| blurIntensity       | `number`                | medium preset          | Override blur amount directly.                              |\n| blurTintToken       | `FrostedTintToken`      | `'surfaceTranslucent'` | Tint token used for frosted mode.                           |\n\n\nCloses from the backdrop, an item, Android back or Escape on web. It is hosted in a modal\non every platform, so keyboard focus stays inside it while it is open."
+    },
+    {
+      "name": "ActionBar",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Sticky bottom action row with safe-area padding",
+      "docs": "## ActionBar\n\n```tsx\nimport { ActionBar, Button, ButtonText } from '@thewhileloop/whileui';\n\n<ActionBar>\n  <Button variant=\"outline\" className=\"flex-1\">\n    <ButtonText>Cancel</ButtonText>\n  </Button>\n  <Button className=\"flex-1\">\n    <ButtonText>Save</ButtonText>\n  </Button>\n</ActionBar>;\n```"
+    },
+    {
+      "name": "ConfirmActionSheet",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Reusable destructive confirmation sheet",
+      "docs": "## ConfirmActionSheet\n\n```tsx\nimport { ConfirmActionSheet } from '@thewhileloop/whileui';\n\n<ConfirmActionSheet\n  open={open}\n  onOpenChange={setOpen}\n  title=\"Delete project?\"\n  description=\"This action cannot be undone.\"\n  confirmLabel=\"Delete\"\n  destructive\n  onConfirm={() => deleteProject()}\n/>;\n```\n\n\n| Prop                    | Type                         | Default                | Description                          |\n| ----------------------- | ---------------------------- | ---------------------- | ------------------------------------ |\n| open (required)         | `boolean`                    | —                      |                                      |\n| onOpenChange (required) | `(open: boolean) => void`    | —                      |                                      |\n| title (required)        | `string`                     | —                      |                                      |\n| description             | `string`                     | —                      |                                      |\n| actions                 | `ConfirmActionSheetAction[]` | —                      |                                      |\n| confirmLabel            | `string`                     | `'Confirm'`            |                                      |\n| cancelLabel             | `string`                     | `'Cancel'`             |                                      |\n| onConfirm               | `() => void`                 | —                      |                                      |\n| onCancel                | `() => void`                 | —                      |                                      |\n| destructive             | `boolean`                    | `true`                 |                                      |\n| className               | `string`                     | —                      |                                      |\n| frosted                 | `boolean`                    | `false`                | Enable the optional frosted overlay. |\n| blurIntensity           | `number`                     | medium preset          | Override blur amount directly.       |\n| blurTintToken           | `FrostedTintToken`           | `'surfaceTranslucent'` | Tint token used for frosted mode.    |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "Sheet",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Bottom sheet modal with header/content/footer slots",
+      "docs": "## Sheet\n\nBottom sheet modal with slide animation. Slots: `SheetHeader`, `SheetContent`, `SheetFooter`, `SheetClose`.\n\n```tsx\nimport {\n  Sheet,\n  SheetHeader,\n  SheetContent,\n  SheetFooter,\n  SheetClose,\n  Button,\n  ButtonText,\n} from '@thewhileloop/whileui';\n\n<Sheet open={open} onOpenChange={setOpen} maxHeight=\"half\">\n  <SheetHeader title=\"Settings\" description=\"Adjust preferences\" />\n  <SheetContent>{/* Scrollable body */}</SheetContent>\n  <SheetFooter>\n    <SheetClose asChild>\n      <Button>\n        <ButtonText>Save</ButtonText>\n      </Button>\n    </SheetClose>\n  </SheetFooter>\n</Sheet>;\n```\n\n\n| Prop                    | Type                         | Default                | Description                                                 |\n| ----------------------- | ---------------------------- | ---------------------- | ----------------------------------------------------------- |\n| open (required)         | `boolean`                    | —                      |                                                             |\n| onOpenChange (required) | `(open: boolean) => void`    | —                      |                                                             |\n| children (required)     | `React.ReactNode`            | —                      |                                                             |\n| maxHeight               | `'half' \\| 'full' \\| number` | `'full'`               | Max height: 'half' \\| 'full' \\| number (px). Default 'full' |\n| maxWidth                | `number`                     | —                      | Web: max width. Default ~360 for mobile-first.              |\n| frosted                 | `boolean`                    | `false`                | Enable the optional frosted overlay.                        |\n| blurIntensity           | `number`                     | medium preset          | Override blur amount directly.                              |\n| blurTintToken           | `FrostedTintToken`           | `'surfaceTranslucent'` | Tint token used for frosted mode.                           |\n\n\n`SheetContent` is a `ScrollView` and accepts its props. It enables nested scrolling and\nkeeps taps on inputs while the keyboard is open (`keyboardShouldPersistTaps=\"handled\"`).\nYour `contentContainerStyle` is merged after the default padding. Tapping the backdrop\ncloses the sheet; a drag across the backdrop does not, so a missed scroll never dismisses\nit. There is no drag-to-dismiss: close with the backdrop, Android back, Escape on web or\n`SheetClose`. A Select, Popover or confirmation Dialog placed inside the sheet opens above\nit, and back or Escape closes that inner layer before the sheet."
+    },
+    {
+      "name": "FormModalScreen",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Modal scaffold for forms with loading states",
+      "docs": "### FormModalScreen\n\nModal scaffold for forms with loading states\n\n```tsx\nimport { FormModalScreen } from '@thewhileloop/whileui';\n```\n\n\n| Prop                | Type              | Default       | Description                                                                               |\n| ------------------- | ----------------- | ------------- | ----------------------------------------------------------------------------------------- |\n| className           | `string`          | —             |                                                                                           |\n| title (required)    | `string`          | —             |                                                                                           |\n| subtitle            | `string`          | —             |                                                                                           |\n| leftSlot            | `React.ReactNode` | —             |                                                                                           |\n| rightSlot           | `React.ReactNode` | —             |                                                                                           |\n| onClose             | `() => void`      | —             |                                                                                           |\n| loading             | `boolean`         | `false`       |                                                                                           |\n| saving              | `boolean`         | `false`       |                                                                                           |\n| savingText          | `string`          | `'Saving...'` |                                                                                           |\n| loadingSpinnerColor | `string`          | —             | Hex color for spinner in loading state. ActivityIndicator requires hex.                   |\n| savingSpinnerColor  | `string`          | —             | Hex color for spinner in saving banner. Defaults to platform (Android blue) when not set. |\n| scrollEnabled       | `boolean`         | `true`        |                                                                                           |\n| children (required) | `React.ReactNode` | —             |                                                                                           |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "ContentSkeleton",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Page/content placeholder with variants (list, card, generic)",
+      "docs": "## ContentSkeleton\n\nPage/content placeholder with layout presets. Use while loading data instead of a spinner when you want to preview the layout.\n\n```tsx\nimport { ContentSkeleton } from '@thewhileloop/whileui';\n\n<ContentSkeleton variant=\"list\" rows={4} />\n<ContentSkeleton variant=\"card\" />\n<ContentSkeleton variant=\"generic\" />\n```\n\n\n| Prop      | Type                            | Default  | Description                                                                                                |\n| --------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |\n| variant   | `'list' \\| 'card' \\| 'generic'` | `'list'` | Layout preset. `list` = avatar + lines rows, `card` = card with image/body, `generic` = simple page lines. |\n| rows      | `number`                        | `4`      | Number of list rows (list variant only). Default 4.                                                        |\n| className | `string`                        | —        |                                                                                                            |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "PageSkeleton",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Variant-based page layouts (dashboard, list, settings, card, generic)",
+      "docs": "## PageSkeleton\n\nVariant-based page layouts for loading states. Replaces app-specific skeletons with presets for dashboard, list, settings, card, and generic pages.\n\n```tsx\nimport { PageSkeleton } from '@thewhileloop/whileui';\n\n<PageSkeleton variant=\"dashboard\" />\n<PageSkeleton variant=\"list\" count={5} />\n<PageSkeleton variant=\"settings\" count={6} />\n<PageSkeleton variant=\"card\" />\n<PageSkeleton variant=\"generic\" />\n<PageSkeleton variant=\"dashboard\" headerPlaceholder />\n<PageSkeleton variant=\"list\" header={<Header title=\"Loading...\" />} />\n<PageSkeleton variant=\"list\" padding=\"none\" className=\"flex-1\" />\n```\n\n\n| Prop               | Type                                       | Default     | Description                                                         |\n| ------------------ | ------------------------------------------ | ----------- | ------------------------------------------------------------------- |\n| variant (required) | `PageSkeletonVariant`                      | —           | Layout preset.                                                      |\n| count              | `number`                                   | `3`         | Rows/items for list (default 3) or settings (default 4) variant.    |\n| padding            | `PageSkeletonPadding`                      | `'default'` | Container padding.                                                  |\n| header             | `ReactNode`                                | —           | Optional header slot rendered above skeleton content.               |\n| headerPlaceholder  | `boolean \\| PageSkeletonHeaderPlaceholder` | `false`     | Optional placeholder header (when no real header is available yet). |\n| className          | `string`                                   | —           |                                                                     |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "ScreenSkeleton",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Header slot/placeholder + PageSkeleton content in one block",
+      "docs": "## ScreenSkeleton\n\nConvenience block for loading screens that need both header and content continuity.\n\n```tsx\nimport { ScreenSkeleton } from '@thewhileloop/whileui';\n\n<ScreenSkeleton variant=\"dashboard\" headerPlaceholder />\n<ScreenSkeleton variant=\"list\" count={5} header={<Header title=\"Projects\" />} />\n```\n\n\n| Prop              | Type                                       | Default     | Description                            |\n| ----------------- | ------------------------------------------ | ----------- | -------------------------------------- |\n| variant           | `PageSkeletonVariant`                      | `'generic'` | Skeleton content preset.               |\n| count             | `number`                                   | —           | Rows/items for list/settings variants. |\n| padding           | `PageSkeletonPadding`                      | `'default'` | Inner content padding.                 |\n| header            | `ReactNode`                                | —           | Real header slot.                      |\n| headerPlaceholder | `boolean \\| PageSkeletonHeaderPlaceholder` | `'default'` | Placeholder header.                    |\n| className         | `string`                                   | —           |                                        |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "ErrorBoundary",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "React ErrorBoundary that renders ErrorState by default",
+      "docs": "## ErrorBoundary\n\nReact ErrorBoundary that catches render errors and renders ErrorState by default.\n\n```tsx\nimport { ErrorBoundary } from '@thewhileloop/whileui';\n\n<ErrorBoundary onError={(err) => console.error(err)}>\n  <App />\n</ErrorBoundary>;\n```\n\n\n| Prop                | Type                                                            | Default | Description                                        |\n| ------------------- | --------------------------------------------------------------- | ------- | -------------------------------------------------- |\n| children (required) | `ReactNode`                                                     | —       |                                                    |\n| fallback            | `ReactNode \\| ((error: Error, reset: () => void) => ReactNode)` | —       | Custom fallback. If not provided, uses ErrorState. |\n| onError             | `(error: Error, errorInfo: ErrorInfo) => void`                  | —       | Called when error is caught.                       |"
+    },
+    {
+      "name": "EmptyState",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Empty content placeholder",
+      "docs": "## EmptyState\n\n```tsx\nimport { EmptyState } from '@thewhileloop/whileui';\n\n<EmptyState\n  icon={<Icon />}\n  title=\"No items\"\n  description=\"Add your first item.\"\n  action={{ label: 'Add Item', onPress: () => {} }}\n/>;\n```"
+    },
+    {
+      "name": "ErrorState",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Error display with retry",
+      "docs": "### ErrorState\n\nError display with retry\n\n```tsx\nimport { ErrorState } from '@thewhileloop/whileui';\n```\n\n\n| Prop        | Type              | Default                  | Description |\n| ----------- | ----------------- | ------------------------ | ----------- |\n| icon        | `React.ReactNode` | —                        |             |\n| title       | `string`          | `'Something went wrong'` |             |\n| description | `string`          | —                        |             |\n| error       | `Error \\| string` | —                        |             |\n| onRetry     | `() => void`      | —                        |             |\n| retryLabel  | `string`          | `'Try again'`            |             |\n| className   | `string`          | —                        |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "LoadingState",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "In-flow loading placeholder for a section still fetching",
+      "docs": "## LoadingState\n\n```tsx\nimport { LoadingState } from '@thewhileloop/whileui';\n\n<LoadingState label=\"Loading activity\" />;\n```\n\nThe in-flow counterpart of `EmptyState` and `ErrorState` for a section that is still\nfetching. The spinner is named for assistive technology by `label` (default \"Loading\").\n\n\n| Prop      | Type                        | Default     | Description                                                                    |\n| --------- | --------------------------- | ----------- | ------------------------------------------------------------------------------ |\n| label     | `string`                    | —           | Read by assistive technology as the spinner's name; shown under it when given. |\n| size      | `'sm' \\| 'default' \\| 'lg'` | `'default'` |                                                                                |\n| className | `string`                    | —           |                                                                                |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "LoadingScreen",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Full-screen loading indicator",
+      "docs": "### LoadingScreen\n\nFull-screen loading indicator\n\n```tsx\nimport { LoadingScreen } from '@thewhileloop/whileui';\n```\n\n\n| Prop         | Type                   | Default | Description                                            |\n| ------------ | ---------------------- | ------- | ------------------------------------------------------ |\n| message      | `string`               | —       |                                                        |\n| size         | `'sm' \\| 'md' \\| 'lg'` | `'md'`  |                                                        |\n| spinnerColor | `string`               | —       | Hex color for spinner. ActivityIndicator requires hex. |\n| className    | `string`               | —       |                                                        |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "PullToRefreshScrollView",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Themed ScrollView with RefreshControl (useThemeTokens for colors)",
+      "docs": "## PullToRefreshScrollView\n\nThemed ScrollView with RefreshControl. Uses `useThemeTokens` for spinner color.\n\n```tsx\nimport { PullToRefreshScrollView } from '@thewhileloop/whileui';\n\n<PullToRefreshScrollView refreshing={refreshing} onRefresh={fetchData} refreshColor=\"#22c55e\">\n  {content}\n</PullToRefreshScrollView>;\n```\n\n\n| Prop                  | Type                          | Default | Description                                                                                                                                                                                                     |\n| --------------------- | ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| refreshing (required) | `boolean`                     | —       | Whether refresh is in progress.                                                                                                                                                                                 |\n| onRefresh (required)  | `() => void \\| Promise<void>` | —       | Refreshing is almost always async, so the signature says so. Nothing here awaits it — the spinner is driven by `refreshing`, which the owner controls — so a handler that can reject must catch its own errors. |\n| refreshColor          | `string`                      | —       | Override tint/colors. Defaults to theme primary.                                                                                                                                                                |\n| className             | `string`                      | —       |                                                                                                                                                                                                                 |\n\nAlso accepts the props of `ScrollViewProps`.\n\nThe scroll view owns the refresh gesture; don't pass `refreshControl`. It bounces even\nwhen content is shorter than the screen, so a short list can still be pulled. Screen\nreader users get the same refresh as a **Refresh** accessibility action, since they\ncannot pull. It is ignored while `refreshing` is true, and any `accessibilityActions` you\npass are kept."
+    },
+    {
+      "name": "KeyboardAwareScreen",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "One screen-level keyboard policy for bottom-docked controls",
+      "docs": "## KeyboardAwareScreen and DockedInput\n\nUse one keyboard-aware root for the screen, then place the composer in a bottom dock. Feed the dock height into the scroll content inset so the last item remains visible.\n\n```tsx\nimport { DockedInput, KeyboardAwareScreen, SmartInput } from '@thewhileloop/whileui';\n\n<KeyboardAwareScreen>\n  <ScrollView contentContainerStyle={{ paddingBottom: inputHeight }} />\n  <DockedInput onHeightChange={setInputHeight}>\n    <SmartInput variant=\"card\" safeArea={false} />\n  </DockedInput>\n</KeyboardAwareScreen>;\n```"
+    },
+    {
+      "name": "DockedInput",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Safe-area-aware bottom dock that reports its complete height",
+      "docs": "## KeyboardAwareScreen and DockedInput\n\nUse one keyboard-aware root for the screen, then place the composer in a bottom dock. Feed the dock height into the scroll content inset so the last item remains visible.\n\n```tsx\nimport { DockedInput, KeyboardAwareScreen, SmartInput } from '@thewhileloop/whileui';\n\n<KeyboardAwareScreen>\n  <ScrollView contentContainerStyle={{ paddingBottom: inputHeight }} />\n  <DockedInput onHeightChange={setInputHeight}>\n    <SmartInput variant=\"card\" safeArea={false} />\n  </DockedInput>\n</KeyboardAwareScreen>;\n```"
+    },
+    {
+      "name": "SmartInput",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Compose input with slots, variants, and optional rotating examples",
+      "docs": "## SmartInput\n\nCompose input for use inline or inside `DockedInput`. `variant`: \"bar\" or \"card\". Slots: `leftSlot`, `centerSlot` (intent selector), `rightSlot`. `submitBehavior`: \"newline\" (default) or \"submit\"/\"blurAndSubmit\". `placeholderExamples` animates rotating prompts and respects the platform reduced-motion setting. Forwards ref to `TextInput`.\n\n```tsx\nimport { SmartInput, Button, ButtonText } from '@thewhileloop/whileui';\n\n<SmartInput\n  value={message}\n  onChangeText={setMessage}\n  placeholderExamples={['Log breakfast', 'Add a 30 minute walk', 'Set weight to 72 kg']}\n  leftSlot={\n    <Button variant=\"ghost\" size=\"icon\" accessibilityLabel=\"Add\">\n      <Icon name=\"add\" />\n    </Button>\n  }\n  rightSlot={\n    <Button size=\"icon\" onPress={handleSend}>\n      <ButtonText>Send</ButtonText>\n    </Button>\n  }\n/>;\n```"
+    },
+    {
+      "name": "SplashScreen",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Branded splash (fade/scale/slide variants)",
+      "docs": "## SplashScreen\n\n```tsx\nimport { SplashScreen } from '@thewhileloop/whileui';\n\n<SplashScreen\n  logo={<MyLogo />}\n  appName=\"MyApp\"\n  tagline=\"Your tagline\"\n  variant=\"scale\"\n  duration={1500}\n  showLoading\n  onAnimationComplete={() => {}}\n/>;\n```\n\n\n| Prop                | Type                           | Default   | Description                                     |\n| ------------------- | ------------------------------ | --------- | ----------------------------------------------- |\n| appName             | `string`                       | —         | App name displayed below logo                   |\n| tagline             | `string`                       | —         | Tagline displayed below app name                |\n| logo                | `React.ReactNode`              | —         | Logo element (icon, image, or custom component) |\n| variant             | `'fade' \\| 'scale' \\| 'slide'` | `'scale'` | Animation variant                               |\n| duration            | `number`                       | `800`     | Animation duration in ms                        |\n| onAnimationComplete | `() => void`                   | —         | Callback when animation completes               |\n| showLoading         | `boolean`                      | `false`   | Whether to show loading indicator               |\n| loadingText         | `string`                       | —         | Loading text                                    |\n| className           | `string`                       | —         |                                                 |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "MinimalSplash",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Minimal monochrome splash",
+      "docs": "### MinimalSplash\n\nMinimal monochrome splash\n\n```tsx\nimport { MinimalSplash } from '@thewhileloop/whileui';\n```\n\n\n| Prop                | Type              | Default | Description                                     |\n| ------------------- | ----------------- | ------- | ----------------------------------------------- |\n| className           | `string`          | —       |                                                 |\n| appName             | `string`          | —       | App name displayed below logo                   |\n| tagline             | `string`          | —       | Tagline displayed below app name                |\n| logo                | `React.ReactNode` | —       | Logo element (icon, image, or custom component) |\n| duration            | `number`          | `800`   | Animation duration in ms                        |\n| onAnimationComplete | `() => void`      | —       | Callback when animation completes               |\n| showLoading         | `boolean`         | `false` | Whether to show loading indicator               |\n| loadingText         | `string`          | —       | Loading text                                    |\n\nAlso accepts the props of `SplashScreenProps`."
+    },
+    {
+      "name": "BrandedSplash",
+      "category": "Layout",
+      "kind": "package",
+      "summary": "Splash with brand imagery",
+      "docs": "### BrandedSplash\n\nSplash with brand imagery\n\n```tsx\nimport { BrandedSplash } from '@thewhileloop/whileui';\n```\n\n\n| Prop                | Type              | Default | Description                                     |\n| ------------------- | ----------------- | ------- | ----------------------------------------------- |\n| className           | `string`          | —       |                                                 |\n| appName             | `string`          | —       | App name displayed below logo                   |\n| tagline             | `string`          | —       | Tagline displayed below app name                |\n| logo                | `React.ReactNode` | —       | Logo element (icon, image, or custom component) |\n| duration            | `number`          | `800`   | Animation duration in ms                        |\n| onAnimationComplete | `() => void`      | —       | Callback when animation completes               |\n| loadingText         | `string`          | —       | Loading text                                    |\n\nAlso accepts the props of `SplashScreenProps`."
+    },
+    {
+      "name": "Chat",
+      "category": "Chat",
+      "kind": "package",
+      "summary": "Opinionated messages, suggestions, and SmartInput composition",
+      "docs": "### Chat\n\n| Block                 | Description                                                     |\n| --------------------- | --------------------------------------------------------------- |\n| **Chat**              | Opinionated messages, suggestions, and SmartInput composition   |\n| **ChatConversation**  | Constrained conversation viewport that follows streaming output |\n| **ChatMessageBubble** | Message bubble (user/assistant, big/small text)                 |\n| **ChatSuggestions**   | Suggestion chips when empty                                     |"
+    },
+    {
+      "name": "ChatConversation",
+      "category": "Chat",
+      "kind": "package",
+      "summary": "Constrained conversation viewport that follows streaming output",
+      "docs": "## ChatConversation / Chat\n\n`ChatConversation` is the low-level viewport for custom conversation screens. Its content stays constrained on wide windows, follows new or streaming output while the reader is near the bottom, and stops following after the reader scrolls upward. Compose it with `SmartInput`; the application owns message data, streaming, tools, approvals, and sources.\n\nIt is a `ScrollView` for a bounded active transcript. Paginate or window historical messages; use a virtualized list when the full history can grow without a bound.\n\n```tsx\nimport { ChatConversation, SmartInput, View } from '@thewhileloop/whileui';\n\n<View className=\"flex-1\">\n  <ChatConversation contentContainerClassName=\"gap-4 px-4 py-6\">\n    {messages.map((message) => (\n      <ProductMessage key={message.id} message={message} />\n    ))}\n  </ChatConversation>\n  <SmartInput\n    value={value}\n    onChangeText={setValue}\n    onSubmitEditing={send}\n    submitBehavior=\"submit\"\n    leftSlot={<AttachButton />}\n    centerSlot={<ModelSelect />}\n    rightSlot={<SendButton />}\n  />\n</View>;\n```\n\n`Chat` is the opinionated convenience composition: message bubbles, suggestion chips, and `SmartInput` with attach/send slots. It uses semantic tokens; theme via `global.css`. Use `renderMessage` for markdown, code, tool calls, reasoning, or sources, and `loadingIndicator` for streaming feedback.\n\n```tsx\nimport { Chat, type ChatMessage } from '@thewhileloop/whileui';\n\nconst [messages, setMessages] = useState<ChatMessage[]>([...]);\nconst [value, setValue] = useState('');\n\n<Chat\n  messages={messages}\n  value={value}\n  onChangeText={setValue}\n  onSend={() => { /* append user msg, clear input */ }}\n  placeholder=\"Message...\"\n  suggestions={['Summarize this', 'Explain simply', 'Translate']}\n  onSuggestionPress={(text) => setValue(text)}\n  emptyTitle=\"How can I help?\"\n  emptyDescription=\"Ask anything.\"\n  leftSlot={<Button variant=\"ghost\" size=\"icon\" accessibilityLabel=\"Attach\"><Icon name=\"paperclip\" /></Button>}\n  rightSlot={<Button size=\"icon\" accessibilityLabel=\"Send\" onPress={handleSend}><Icon name=\"send\" /></Button>}\n/>;\n```\n\n\n| Prop                    | Type                                        | Default             | Description                                                                              |\n| ----------------------- | ------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------- |\n| messages (required)     | `ChatMessage[]`                             | —                   | Messages to show, each `{ id, role, content, secondary?, contentSize? }`.                |\n| value (required)        | `string`                                    | —                   | Input value.                                                                             |\n| onChangeText (required) | `(text: string) => void`                    | —                   | Input change.                                                                            |\n| onSend (required)       | `() => void`                                | —                   | Send handler.                                                                            |\n| placeholder             | `string`                                    | `'Message...'`      |                                                                                          |\n| suggestions             | `string[]`                                  | `EMPTY_SUGGESTIONS` | Chips when empty.                                                                        |\n| onSuggestionPress       | `(text: string) => void`                    | —                   |                                                                                          |\n| leftSlot                | `React.ReactNode`                           | —                   |                                                                                          |\n| rightSlot               | `React.ReactNode`                           | —                   |                                                                                          |\n| loading                 | `boolean`                                   | `false`             |                                                                                          |\n| header                  | `React.ReactNode`                           | —                   |                                                                                          |\n| emptyTitle              | `string`                                    | —                   |                                                                                          |\n| emptyDescription        | `string`                                    | —                   |                                                                                          |\n| exampleMessage          | `ChatMessage`                               | —                   | Example message shown in empty state so users see the bubble UI.                         |\n| renderMessage           | `(message: ChatMessage) => React.ReactNode` | —                   | Custom message renderer (markdown, code, images). Falls back to ChatMessageBubble.       |\n| loadingIndicator        | `React.ReactNode`                           | —                   | Shown at bottom when loading (typing indicator).                                         |\n| inputSafeArea           | `boolean`                                   | `true`              | Passed to SmartInput. Use false when Chat is in a contained demo.                        |\n| keyboardVerticalOffset  | `number`                                    | `0`                 | Offset for KeyboardAvoidingView when Chat has a header (e.g. StatusBar + header height). |\n| className               | `string`                                    | —                   |                                                                                          |\n| messagesClassName       | `string`                                    | —                   |                                                                                          |\n\n\n`ChatConversation` extends React Native `ScrollViewProps`, forwards its ref, and adds `contentContainerClassName` to style the constrained inner column. Caller `onScroll` and `onContentSizeChange` callbacks are preserved.\n\n### Optional Markdown and code\n\nThese are explicit subpaths so the root package remains independent of a Markdown\nparser. Install `markdown-it` only in applications that render Markdown.\n\n```tsx\nimport { Markdown } from '@thewhileloop/whileui/markdown';\nimport { CodeBlock } from '@thewhileloop/whileui/code';\n\n<Markdown onLinkPress={openLink}>{assistantText}</Markdown>\n<CodeBlock code={source} language=\"TypeScript\" actions={<CopyButton />} />\n```\n\n`Markdown` supports headings, paragraphs, emphasis, links, lists, quotes, rules, inline\ncode, and fenced code. It never opens links or writes to the clipboard itself:\n`onLinkPress` and `codeActions` keep those capabilities in the application. `CodeBlock`\nis dependency-free and accepts an application-owned `actions` slot."
+    },
+    {
+      "name": "ChatMessageBubble",
+      "category": "Chat",
+      "kind": "package",
+      "summary": "Message bubble (user/assistant, big/small text)",
+      "docs": "### ChatMessageBubble\n\nOne message in a `Chat`, rendered on its own when a screen composes the conversation itself.\n\n```tsx\nimport { ChatMessageBubble } from '@thewhileloop/whileui';\n```\n\n\n| Prop               | Type          | Default | Description                                                     |\n| ------------------ | ------------- | ------- | --------------------------------------------------------------- |\n| message (required) | `ChatMessage` | —       | The message to render; its `role` decides alignment and colour. |\n| contentClassName   | `string`      | —       | Classes for the bubble's content wrapper.                       |"
+    },
+    {
+      "name": "ChatSuggestions",
+      "category": "Chat",
+      "kind": "package",
+      "summary": "Suggestion chips when empty",
+      "docs": "### ChatSuggestions\n\nSuggestion chips when empty\n\n```tsx\nimport { ChatSuggestions } from '@thewhileloop/whileui';\n```\n\n\n| Prop                   | Type                     | Default             | Description |\n| ---------------------- | ------------------------ | ------------------- | ----------- |\n| suggestions (required) | `string[]`               | `EMPTY_SUGGESTIONS` |             |\n| onSelect (required)    | `(text: string) => void` | —                   |             |\n| className              | `string`                 | —                   |             |"
+    },
+    {
+      "name": "ProfileHeader",
+      "category": "Profile & Settings",
+      "kind": "template",
+      "summary": "Profile header with stats",
+      "docs": "## ProfileHeader\n\nCopy from `apps/showcase/catalog/templates/profile/profile-header.tsx`, then:\n\n```tsx\nimport { ProfileHeader } from './templates/profile'; // or your path\n\n<ProfileHeader\n  name=\"John Doe\"\n  username=\"johndoe\"\n  bio=\"Designer & Developer\"\n  avatarFallback=\"JD\"\n  avatarUrl=\"https://...\"\n  verified\n  stats={[\n    { label: 'Followers', value: '1.2K' },\n    { label: 'Following', value: 234 },\n  ]}\n  action={{ label: 'Edit Profile', onPress: () => {} }}\n/>;\n```",
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "AccountCard",
+      "category": "Profile & Settings",
+      "kind": "template",
+      "summary": "Account summary card",
+      "docs": null,
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "SettingsSection",
+      "category": "Profile & Settings",
+      "kind": "template",
+      "summary": "Section header with optional action",
+      "docs": "## SettingsSection / SettingsItem\n\nCopy from `apps/showcase/catalog/templates/profile/`, then:\n\n```tsx\nimport { SettingsSection, SettingsItem } from './templates/profile'; // or your path\n\n<SettingsSection title=\"Preferences\">\n  <SettingsItem\n    icon={<Icon />}\n    label=\"Notifications\"\n    type=\"toggle\"\n    toggleValue={enabled}\n    onToggle={setEnabled}\n  />\n  <SettingsItem icon={<Icon />} label=\"Privacy\" value=\"Public\" onPress={() => {}} />\n  <SettingsItem icon={<Icon />} label=\"Sign Out\" type=\"action\" destructive />\n</SettingsSection>;\n```",
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "SettingsItem",
+      "category": "Profile & Settings",
+      "kind": "template",
+      "summary": "Row for toggles/links/settings",
+      "docs": "## SettingsSection / SettingsItem\n\nCopy from `apps/showcase/catalog/templates/profile/`, then:\n\n```tsx\nimport { SettingsSection, SettingsItem } from './templates/profile'; // or your path\n\n<SettingsSection title=\"Preferences\">\n  <SettingsItem\n    icon={<Icon />}\n    label=\"Notifications\"\n    type=\"toggle\"\n    toggleValue={enabled}\n    onToggle={setEnabled}\n  />\n  <SettingsItem icon={<Icon />} label=\"Privacy\" value=\"Public\" onPress={() => {}} />\n  <SettingsItem icon={<Icon />} label=\"Sign Out\" type=\"action\" destructive />\n</SettingsSection>;\n```",
+      "source": "https://github.com/whileloophq/whileui/tree/main/apps/showcase/catalog/templates"
+    },
+    {
+      "name": "ListItem",
+      "category": "Lists",
+      "kind": "package",
+      "summary": "Title/subtitle row",
+      "docs": "### ListItem\n\nTitle/subtitle row\n\n```tsx\nimport { ListItem } from '@thewhileloop/whileui';\n```\n\n\n| Prop             | Type              | Default | Description                                     |\n| ---------------- | ----------------- | ------- | ----------------------------------------------- |\n| icon             | `React.ReactNode` | —       |                                                 |\n| title (required) | `string`          | —       |                                                 |\n| subtitle         | `string`          | —       |                                                 |\n| description      | `string`          | —       |                                                 |\n| rightIcon        | `React.ReactNode` | —       |                                                 |\n| rightText        | `string`          | —       |                                                 |\n| action           | `React.ReactNode` | —       |                                                 |\n| showBorder       | `boolean`         | `true`  |                                                 |\n| compact          | `boolean`         | `false` |                                                 |\n| loading          | `boolean`         | `false` | Show a skeleton placeholder instead of content. |\n| className        | `string`          | —       |                                                 |\n\nAlso accepts the props of `PressableProps`."
+    },
+    {
+      "name": "NotificationItem",
+      "category": "Lists",
+      "kind": "package",
+      "summary": "Notification row with metadata",
+      "docs": "### NotificationItem\n\nNotification row with metadata\n\n```tsx\nimport { NotificationItem } from '@thewhileloop/whileui';\n```\n\n\n| Prop               | Type              | Default | Description                                     |\n| ------------------ | ----------------- | ------- | ----------------------------------------------- |\n| icon               | `React.ReactNode` | —       |                                                 |\n| avatarUrl          | `string`          | —       |                                                 |\n| avatarFallback     | `string`          | —       |                                                 |\n| title (required)   | `string`          | —       |                                                 |\n| message (required) | `string`          | —       |                                                 |\n| time (required)    | `string`          | —       |                                                 |\n| read               | `boolean`         | `false` |                                                 |\n| showDot            | `boolean`         | `true`  |                                                 |\n| loading            | `boolean`         | `false` | Show a skeleton placeholder instead of content. |\n| className          | `string`          | —       |                                                 |\n\nAlso accepts the props of `PressableProps`."
+    },
+    {
+      "name": "TimelineFeed",
+      "category": "Lists",
+      "kind": "package",
+      "summary": "Vertical feed with connecting lines",
+      "docs": "### TimelineFeed\n\nVertical feed with connecting lines\n\n```tsx\nimport { TimelineFeed } from '@thewhileloop/whileui';\n```\n\n\n| Prop             | Type             | Default | Description |\n| ---------------- | ---------------- | ------- | ----------- |\n| className        | `string`         | —       |             |\n| items (required) | `TimelineItem[]` | —       |             |\n| showConnector    | `boolean`        | `true`  |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "ProductCard",
+      "category": "Commerce",
+      "kind": "package",
+      "summary": "Product card with badge/media",
+      "docs": "## ProductCard\n\n```tsx\nimport { ProductCard } from '@thewhileloop/whileui';\n\n<ProductCard\n  title=\"Product Name\"\n  price=\"$99\"\n  originalPrice=\"$129\"\n  badge=\"-23%\"\n  rating={4.5}\n  reviewCount={128}\n  variant=\"vertical\"\n  onPress={() => {}}\n/>;\n```\n\n\n| Prop             | Type                         | Default      | Description                                     |\n| ---------------- | ---------------------------- | ------------ | ----------------------------------------------- |\n| imageUrl         | `string`                     | —            |                                                 |\n| title (required) | `string`                     | —            |                                                 |\n| description      | `string`                     | —            |                                                 |\n| price (required) | `string`                     | —            |                                                 |\n| originalPrice    | `string`                     | —            |                                                 |\n| badge            | `string`                     | —            |                                                 |\n| rating           | `number`                     | —            |                                                 |\n| reviewCount      | `number`                     | —            |                                                 |\n| inStock          | `boolean`                    | `true`       |                                                 |\n| variant          | `'vertical' \\| 'horizontal'` | `'vertical'` |                                                 |\n| loading          | `boolean`                    | `false`      | Show a skeleton placeholder instead of content. |\n| className        | `string`                     | —            |                                                 |\n\nAlso accepts the props of `PressableProps`."
+    },
+    {
+      "name": "PricingCard",
+      "category": "Commerce",
+      "kind": "package",
+      "summary": "Pricing tiers with feature list",
+      "docs": "## PricingCard\n\n```tsx\nimport { PricingCard } from '@thewhileloop/whileui';\n\n<PricingCard\n  name=\"Pro\"\n  description=\"For teams\"\n  price=\"$29\"\n  period=\"/month\"\n  badge=\"Popular\"\n  highlighted\n  features={[\n    { label: 'Unlimited users', included: true },\n    { label: 'Priority support', included: true },\n    { label: 'Custom domain', included: false },\n  ]}\n  onPress={() => {}}\n/>;\n```"
+    },
+    {
+      "name": "CheckoutSummary",
+      "category": "Commerce",
+      "kind": "package",
+      "summary": "Cart summary with line items",
+      "docs": "### CheckoutSummary\n\nCart summary with line items\n\n```tsx\nimport { CheckoutSummary } from '@thewhileloop/whileui';\n```\n\n\n| Prop                | Type                 | Default      | Description |\n| ------------------- | -------------------- | ------------ | ----------- |\n| items (required)    | `CheckoutLineItem[]` | —            |             |\n| subtotal (required) | `string`             | —            |             |\n| shipping            | `string`             | —            |             |\n| tax                 | `string`             | —            |             |\n| discount            | `string`             | —            |             |\n| total (required)    | `string`             | —            |             |\n| buttonLabel         | `string`             | `'Checkout'` |             |\n| onCheckout          | `() => void`         | —            |             |\n| loading             | `boolean`            | `false`      |             |\n| className           | `string`             | —            |             |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "MetricCard",
+      "category": "Commerce",
+      "kind": "package",
+      "summary": "Stats/progress card for dashboards",
+      "docs": "### MetricCard\n\nStats/progress card for dashboards\n\n```tsx\nimport { MetricCard } from '@thewhileloop/whileui';\n```\n\n\n| Prop             | Type                                 | Default     | Description                                     |\n| ---------------- | ------------------------------------ | ----------- | ----------------------------------------------- |\n| className        | `string`                             | —           |                                                 |\n| label (required) | `string`                             | —           |                                                 |\n| value (required) | `string \\| number`                   | —           |                                                 |\n| subtitle         | `string`                             | —           |                                                 |\n| progress         | `number`                             | —           |                                                 |\n| segments         | `{ value: number; color: string }[]` | —           |                                                 |\n| icon             | `React.ReactNode`                    | —           |                                                 |\n| loading          | `boolean`                            | `false`     | Show a skeleton placeholder instead of content. |\n| variant          | `'default' \\| 'outlined'`            | `'default'` |                                                 |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "SubscriptionCard",
+      "category": "Commerce",
+      "kind": "package",
+      "summary": "Current plan card with manage/upgrade actions",
+      "docs": "## SubscriptionCard\n\n```tsx\nimport { SubscriptionCard } from '@thewhileloop/whileui';\n\n<SubscriptionCard\n  planName=\"Pro\"\n  price=\"$29\"\n  period=\"/month\"\n  expiresAt=\"April 18, 2026\"\n  isActive\n  onManage={() => {}}\n  onUpgrade={() => {}}\n/>;\n```\n\n\n| Prop                | Type         | Default         | Description                                     |\n| ------------------- | ------------ | --------------- | ----------------------------------------------- |\n| planName (required) | `string`     | —               | Current plan label.                             |\n| price (required)    | `string`     | —               | Plan price.                                     |\n| period              | `string`     | `'/month'`      | Billing period label.                           |\n| expiresAt           | `string`     | —               | Renewal/expiry date text.                       |\n| isActive            | `boolean`    | `true`          | Active/inactive badge state.                    |\n| onManage            | `() => void` | —               | Manage action.                                  |\n| onUpgrade           | `() => void` | —               | Upgrade action.                                 |\n| manageLabel         | `string`     | `'Manage plan'` |                                                 |\n| upgradeLabel        | `string`     | `'Upgrade'`     |                                                 |\n| loading             | `boolean`    | `false`         | Show a skeleton placeholder instead of content. |\n| className           | `string`     | —               |                                                 |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "FeatureGate",
+      "category": "Commerce",
+      "kind": "package",
+      "summary": "Locked feature state with upgrade CTA",
+      "docs": "## FeatureGate\n\n```tsx\nimport { FeatureGate } from '@thewhileloop/whileui';\n\n<FeatureGate\n  title=\"Advanced export is locked\"\n  description=\"Upgrade to unlock 4K export.\"\n  buttonLabel=\"Upgrade\"\n  onUpgrade={() => {}}\n/>;\n```\n\nUse `children` to show dimmed preview content with an overlay CTA."
+    },
+    {
+      "name": "UsageBar",
+      "category": "Commerce",
+      "kind": "package",
+      "summary": "Quota meter with warning/exceeded states",
+      "docs": "## UsageBar\n\n```tsx\nimport { UsageBar } from '@thewhileloop/whileui';\n\n<UsageBar label=\"AI generations\" used={8} limit={20} />;\n```\n\n\n| Prop             | Type              | Default | Description                     |\n| ---------------- | ----------------- | ------- | ------------------------------- |\n| label (required) | `string`          | —       | Usage label.                    |\n| used (required)  | `number`          | —       | Used amount.                    |\n| limit (required) | `number`          | —       | Quota limit.                    |\n| variant          | `UsageBarVariant` | —       | Optional explicit visual state. |\n| className        | `string`          | —       |                                 |\n\nAlso accepts the props of `ViewProps`."
+    },
+    {
+      "name": "PlanToggle",
+      "category": "Commerce",
+      "kind": "package",
+      "summary": "Monthly vs annual plan switcher",
+      "docs": "## PlanToggle\n\n```tsx\nimport { PlanToggle } from '@thewhileloop/whileui';\n\n<PlanToggle\n  selected=\"monthly\"\n  monthlyLabel=\"Monthly\"\n  annualLabel=\"Annual\"\n  annualDiscount=\"Save 20%\"\n  onChange={(next) => {}}\n/>;\n```"
+    },
+    {
+      "name": "UpgradeBanner",
+      "category": "Commerce",
+      "kind": "package",
+      "summary": "Inline upgrade banner with action/dismiss",
+      "docs": "## UpgradeBanner\n\n```tsx\nimport { UpgradeBanner } from '@thewhileloop/whileui';\n\n<UpgradeBanner\n  message=\"Unlock unlimited exports with Pro.\"\n  actionLabel=\"See plans\"\n  onAction={() => {}}\n  onDismiss={() => {}}\n/>;\n```"
+    },
+    {
+      "name": "SmartImage",
+      "category": "Media",
+      "kind": "package",
+      "summary": "Image with explicit loading, loaded, fallback, and error lifecycle",
+      "docs": "## SmartImage\n\n```tsx\nimport { SmartImage } from '@thewhileloop/whileui';\n\n<SmartImage\n  source={{ uri: imageUrl }}\n  fallbackSource={{ uri: fallbackUrl }}\n  alt=\"Product preview\"\n  className=\"h-48 w-full\"\n/>;\n```\n\n\n| Prop              | Type                                               | Default   | Description |\n| ----------------- | -------------------------------------------------- | --------- | ----------- |\n| className         | `string`                                           | —         |             |\n| source (required) | `ImageProps['source']`                             | —         |             |\n| alt (required)    | `string`                                           | —         |             |\n| skeleton          | `boolean`                                          | `true`    |             |\n| skeletonClassName | `string`                                           | —         |             |\n| transition        | `number`                                           | `200`     |             |\n| onLoad            | `() => void`                                       | —         |             |\n| onError           | `() => void`                                       | —         |             |\n| fallbackSource    | `ImageProps['source']`                             | —         |             |\n| radius            | `'none' \\| 'sm' \\| 'md' \\| 'lg' \\| 'xl' \\| 'full'` | `'md'`    |             |\n| objectFit         | `'fill' \\| 'cover' \\| 'contain' \\| 'scale-down'`   | `'cover'` |             |\n\nAlso accepts the props of `ViewProps`.\n\nThe skeleton returns whenever the primary image starts loading again. A failed primary\nsource switches to `fallbackSource` when supplied without re-entering a primary/fallback\nloop."
+    },
+    {
+      "name": "DatePickerModal",
+      "category": "Date Picker",
+      "kind": "package",
+      "summary": "Bottom sheet modal with calendar, compact trigger",
+      "docs": "## DatePickerModal / DatePickerInline / DateRangePickerModal / TimePickerModal\n\nDate selection blocks using react-native-calendars. Theme-aware via `useCalendarTheme` (Uniwind light/dark). Optional `theme` prop for custom RN color strings (hex/rgb/hsl/named). `CalendarTheme` maps to react-native-calendars Theme and supports `arrowColor`, `disabledArrowColor`, and optional font keys.\n\n**DatePickerModal** — Compact trigger opens bottom sheet with calendar. Use `DatePickerTrigger` as the trigger content.\n\n**DatePickerInline** — Calendar embedded inline for forms or dashboards.\n\n**DateRangePickerModal** — Range selection with period marking. Use `DateRangePickerTrigger` as the trigger content.\n\n**TimePickerModal** — Hour and minute wheels (plus AM/PM under a 12-hour `hourCycle`) in the same bottom sheet, so a form's date and time fields open the same way. `value` is always `HH:MM` in 24-hour form. Each wheel is one `adjustable` element for assistive tech and the keyboard. Use `TimePickerTrigger` as the trigger content.\n\n```tsx\nimport {\n  DatePickerModal,\n  DatePickerTrigger,\n  DatePickerInline,\n  DateRangePickerModal,\n  DateRangePickerTrigger,\n  TimePickerModal,\n  TimePickerTrigger,\n  type DateRange,\n} from '@thewhileloop/whileui';\n\n// Single date (modal)\nconst [date, setDate] = useState<string | null>(null);\nconst [open, setOpen] = useState(false);\n\n<DatePickerModal\n  value={date}\n  onValueChange={setDate}\n  open={open}\n  onOpenChange={setOpen}\n  trigger={<DatePickerTrigger value={date} placeholder=\"Pick a date\" />}\n  title=\"Select date\"\n/>;\n\n// Inline calendar\n<DatePickerInline value={date} onValueChange={setDate} />;\n\n// Date range (modal)\nconst [range, setRange] = useState<DateRange | null>(null);\n\n<DateRangePickerModal\n  value={range}\n  onValueChange={setRange}\n  open={rangeOpen}\n  onOpenChange={setRangeOpen}\n  trigger={<DateRangePickerTrigger value={range} placeholder=\"Pick range\" />}\n/>;\n\n// Time (modal) — \"HH:MM\", 24-hour, whatever the wheels show\nconst [time, setTime] = useState<string | null>(null);\n\n<TimePickerModal\n  value={time}\n  onValueChange={setTime}\n  open={timeOpen}\n  onOpenChange={setTimeOpen}\n  minuteStep={5}\n  trigger={<TimePickerTrigger value={time} placeholder=\"Pick a time\" />}\n/>;\n```\n\n\n| Prop                    | Type                             | Default                | Description                                               |\n| ----------------------- | -------------------------------- | ---------------------- | --------------------------------------------------------- |\n| value                   | `string \\| null`                 | —                      | Controlled: selected date in YYYY-MM-DD                   |\n| onValueChange           | `(date: string \\| null) => void` | —                      | Controlled: change handler                                |\n| open (required)         | `boolean`                        | —                      | Modal open state                                          |\n| onOpenChange (required) | `(open: boolean) => void`        | —                      | Modal open change handler                                 |\n| minDate                 | `string`                         | —                      | Minimum selectable date YYYY-MM-DD                        |\n| maxDate                 | `string`                         | —                      | Maximum selectable date YYYY-MM-DD                        |\n| theme                   | `CalendarTheme`                  | —                      | Override calendar theme (RN color strings)                |\n| trigger                 | `React.ReactNode`                | —                      | Trigger element. If not provided, no trigger is rendered. |\n| title                   | `string`                         | `'Select date'`        | Title shown in modal header                               |\n| confirmLabel            | `string`                         | `'Done'`               | Button label for confirm                                  |\n| className               | `string`                         | —                      |                                                           |\n| frosted                 | `boolean`                        | `false`                | Enable the optional frosted overlay.                      |\n| blurIntensity           | `number`                         | medium preset          | Override blur amount directly.                            |\n| blurTintToken           | `FrostedTintToken`               | `'surfaceTranslucent'` | Tint token used for frosted mode.                         |"
+    },
+    {
+      "name": "DatePickerInline",
+      "category": "Date Picker",
+      "kind": "package",
+      "summary": "Inline calendar for forms or dashboards",
+      "docs": "## DatePickerModal / DatePickerInline / DateRangePickerModal / TimePickerModal\n\nDate selection blocks using react-native-calendars. Theme-aware via `useCalendarTheme` (Uniwind light/dark). Optional `theme` prop for custom RN color strings (hex/rgb/hsl/named). `CalendarTheme` maps to react-native-calendars Theme and supports `arrowColor`, `disabledArrowColor`, and optional font keys.\n\n**DatePickerModal** — Compact trigger opens bottom sheet with calendar. Use `DatePickerTrigger` as the trigger content.\n\n**DatePickerInline** — Calendar embedded inline for forms or dashboards.\n\n**DateRangePickerModal** — Range selection with period marking. Use `DateRangePickerTrigger` as the trigger content.\n\n**TimePickerModal** — Hour and minute wheels (plus AM/PM under a 12-hour `hourCycle`) in the same bottom sheet, so a form's date and time fields open the same way. `value` is always `HH:MM` in 24-hour form. Each wheel is one `adjustable` element for assistive tech and the keyboard. Use `TimePickerTrigger` as the trigger content.\n\n```tsx\nimport {\n  DatePickerModal,\n  DatePickerTrigger,\n  DatePickerInline,\n  DateRangePickerModal,\n  DateRangePickerTrigger,\n  TimePickerModal,\n  TimePickerTrigger,\n  type DateRange,\n} from '@thewhileloop/whileui';\n\n// Single date (modal)\nconst [date, setDate] = useState<string | null>(null);\nconst [open, setOpen] = useState(false);\n\n<DatePickerModal\n  value={date}\n  onValueChange={setDate}\n  open={open}\n  onOpenChange={setOpen}\n  trigger={<DatePickerTrigger value={date} placeholder=\"Pick a date\" />}\n  title=\"Select date\"\n/>;\n\n// Inline calendar\n<DatePickerInline value={date} onValueChange={setDate} />;\n\n// Date range (modal)\nconst [range, setRange] = useState<DateRange | null>(null);\n\n<DateRangePickerModal\n  value={range}\n  onValueChange={setRange}\n  open={rangeOpen}\n  onOpenChange={setRangeOpen}\n  trigger={<DateRangePickerTrigger value={range} placeholder=\"Pick range\" />}\n/>;\n\n// Time (modal) — \"HH:MM\", 24-hour, whatever the wheels show\nconst [time, setTime] = useState<string | null>(null);\n\n<TimePickerModal\n  value={time}\n  onValueChange={setTime}\n  open={timeOpen}\n  onOpenChange={setTimeOpen}\n  minuteStep={5}\n  trigger={<TimePickerTrigger value={time} placeholder=\"Pick a time\" />}\n/>;\n```\n\n\n| Prop                    | Type                             | Default                | Description                                               |\n| ----------------------- | -------------------------------- | ---------------------- | --------------------------------------------------------- |\n| value                   | `string \\| null`                 | —                      | Controlled: selected date in YYYY-MM-DD                   |\n| onValueChange           | `(date: string \\| null) => void` | —                      | Controlled: change handler                                |\n| open (required)         | `boolean`                        | —                      | Modal open state                                          |\n| onOpenChange (required) | `(open: boolean) => void`        | —                      | Modal open change handler                                 |\n| minDate                 | `string`                         | —                      | Minimum selectable date YYYY-MM-DD                        |\n| maxDate                 | `string`                         | —                      | Maximum selectable date YYYY-MM-DD                        |\n| theme                   | `CalendarTheme`                  | —                      | Override calendar theme (RN color strings)                |\n| trigger                 | `React.ReactNode`                | —                      | Trigger element. If not provided, no trigger is rendered. |\n| title                   | `string`                         | `'Select date'`        | Title shown in modal header                               |\n| confirmLabel            | `string`                         | `'Done'`               | Button label for confirm                                  |\n| className               | `string`                         | —                      |                                                           |\n| frosted                 | `boolean`                        | `false`                | Enable the optional frosted overlay.                      |\n| blurIntensity           | `number`                         | medium preset          | Override blur amount directly.                            |\n| blurTintToken           | `FrostedTintToken`               | `'surfaceTranslucent'` | Tint token used for frosted mode.                         |"
+    },
+    {
+      "name": "DateRangePickerModal",
+      "category": "Date Picker",
+      "kind": "package",
+      "summary": "Range selection modal with period marking",
+      "docs": "## DatePickerModal / DatePickerInline / DateRangePickerModal / TimePickerModal\n\nDate selection blocks using react-native-calendars. Theme-aware via `useCalendarTheme` (Uniwind light/dark). Optional `theme` prop for custom RN color strings (hex/rgb/hsl/named). `CalendarTheme` maps to react-native-calendars Theme and supports `arrowColor`, `disabledArrowColor`, and optional font keys.\n\n**DatePickerModal** — Compact trigger opens bottom sheet with calendar. Use `DatePickerTrigger` as the trigger content.\n\n**DatePickerInline** — Calendar embedded inline for forms or dashboards.\n\n**DateRangePickerModal** — Range selection with period marking. Use `DateRangePickerTrigger` as the trigger content.\n\n**TimePickerModal** — Hour and minute wheels (plus AM/PM under a 12-hour `hourCycle`) in the same bottom sheet, so a form's date and time fields open the same way. `value` is always `HH:MM` in 24-hour form. Each wheel is one `adjustable` element for assistive tech and the keyboard. Use `TimePickerTrigger` as the trigger content.\n\n```tsx\nimport {\n  DatePickerModal,\n  DatePickerTrigger,\n  DatePickerInline,\n  DateRangePickerModal,\n  DateRangePickerTrigger,\n  TimePickerModal,\n  TimePickerTrigger,\n  type DateRange,\n} from '@thewhileloop/whileui';\n\n// Single date (modal)\nconst [date, setDate] = useState<string | null>(null);\nconst [open, setOpen] = useState(false);\n\n<DatePickerModal\n  value={date}\n  onValueChange={setDate}\n  open={open}\n  onOpenChange={setOpen}\n  trigger={<DatePickerTrigger value={date} placeholder=\"Pick a date\" />}\n  title=\"Select date\"\n/>;\n\n// Inline calendar\n<DatePickerInline value={date} onValueChange={setDate} />;\n\n// Date range (modal)\nconst [range, setRange] = useState<DateRange | null>(null);\n\n<DateRangePickerModal\n  value={range}\n  onValueChange={setRange}\n  open={rangeOpen}\n  onOpenChange={setRangeOpen}\n  trigger={<DateRangePickerTrigger value={range} placeholder=\"Pick range\" />}\n/>;\n\n// Time (modal) — \"HH:MM\", 24-hour, whatever the wheels show\nconst [time, setTime] = useState<string | null>(null);\n\n<TimePickerModal\n  value={time}\n  onValueChange={setTime}\n  open={timeOpen}\n  onOpenChange={setTimeOpen}\n  minuteStep={5}\n  trigger={<TimePickerTrigger value={time} placeholder=\"Pick a time\" />}\n/>;\n```\n\n\n| Prop                    | Type                             | Default                | Description                                               |\n| ----------------------- | -------------------------------- | ---------------------- | --------------------------------------------------------- |\n| value                   | `string \\| null`                 | —                      | Controlled: selected date in YYYY-MM-DD                   |\n| onValueChange           | `(date: string \\| null) => void` | —                      | Controlled: change handler                                |\n| open (required)         | `boolean`                        | —                      | Modal open state                                          |\n| onOpenChange (required) | `(open: boolean) => void`        | —                      | Modal open change handler                                 |\n| minDate                 | `string`                         | —                      | Minimum selectable date YYYY-MM-DD                        |\n| maxDate                 | `string`                         | —                      | Maximum selectable date YYYY-MM-DD                        |\n| theme                   | `CalendarTheme`                  | —                      | Override calendar theme (RN color strings)                |\n| trigger                 | `React.ReactNode`                | —                      | Trigger element. If not provided, no trigger is rendered. |\n| title                   | `string`                         | `'Select date'`        | Title shown in modal header                               |\n| confirmLabel            | `string`                         | `'Done'`               | Button label for confirm                                  |\n| className               | `string`                         | —                      |                                                           |\n| frosted                 | `boolean`                        | `false`                | Enable the optional frosted overlay.                      |\n| blurIntensity           | `number`                         | medium preset          | Override blur amount directly.                            |\n| blurTintToken           | `FrostedTintToken`               | `'surfaceTranslucent'` | Tint token used for frosted mode.                         |"
+    },
+    {
+      "name": "TimePickerModal",
+      "category": "Date Picker",
+      "kind": "package",
+      "summary": "Hour and minute wheels in the same bottom sheet",
+      "docs": "## DatePickerModal / DatePickerInline / DateRangePickerModal / TimePickerModal\n\nDate selection blocks using react-native-calendars. Theme-aware via `useCalendarTheme` (Uniwind light/dark). Optional `theme` prop for custom RN color strings (hex/rgb/hsl/named). `CalendarTheme` maps to react-native-calendars Theme and supports `arrowColor`, `disabledArrowColor`, and optional font keys.\n\n**DatePickerModal** — Compact trigger opens bottom sheet with calendar. Use `DatePickerTrigger` as the trigger content.\n\n**DatePickerInline** — Calendar embedded inline for forms or dashboards.\n\n**DateRangePickerModal** — Range selection with period marking. Use `DateRangePickerTrigger` as the trigger content.\n\n**TimePickerModal** — Hour and minute wheels (plus AM/PM under a 12-hour `hourCycle`) in the same bottom sheet, so a form's date and time fields open the same way. `value` is always `HH:MM` in 24-hour form. Each wheel is one `adjustable` element for assistive tech and the keyboard. Use `TimePickerTrigger` as the trigger content.\n\n```tsx\nimport {\n  DatePickerModal,\n  DatePickerTrigger,\n  DatePickerInline,\n  DateRangePickerModal,\n  DateRangePickerTrigger,\n  TimePickerModal,\n  TimePickerTrigger,\n  type DateRange,\n} from '@thewhileloop/whileui';\n\n// Single date (modal)\nconst [date, setDate] = useState<string | null>(null);\nconst [open, setOpen] = useState(false);\n\n<DatePickerModal\n  value={date}\n  onValueChange={setDate}\n  open={open}\n  onOpenChange={setOpen}\n  trigger={<DatePickerTrigger value={date} placeholder=\"Pick a date\" />}\n  title=\"Select date\"\n/>;\n\n// Inline calendar\n<DatePickerInline value={date} onValueChange={setDate} />;\n\n// Date range (modal)\nconst [range, setRange] = useState<DateRange | null>(null);\n\n<DateRangePickerModal\n  value={range}\n  onValueChange={setRange}\n  open={rangeOpen}\n  onOpenChange={setRangeOpen}\n  trigger={<DateRangePickerTrigger value={range} placeholder=\"Pick range\" />}\n/>;\n\n// Time (modal) — \"HH:MM\", 24-hour, whatever the wheels show\nconst [time, setTime] = useState<string | null>(null);\n\n<TimePickerModal\n  value={time}\n  onValueChange={setTime}\n  open={timeOpen}\n  onOpenChange={setTimeOpen}\n  minuteStep={5}\n  trigger={<TimePickerTrigger value={time} placeholder=\"Pick a time\" />}\n/>;\n```\n\n\n| Prop                    | Type                             | Default                | Description                                               |\n| ----------------------- | -------------------------------- | ---------------------- | --------------------------------------------------------- |\n| value                   | `string \\| null`                 | —                      | Controlled: selected date in YYYY-MM-DD                   |\n| onValueChange           | `(date: string \\| null) => void` | —                      | Controlled: change handler                                |\n| open (required)         | `boolean`                        | —                      | Modal open state                                          |\n| onOpenChange (required) | `(open: boolean) => void`        | —                      | Modal open change handler                                 |\n| minDate                 | `string`                         | —                      | Minimum selectable date YYYY-MM-DD                        |\n| maxDate                 | `string`                         | —                      | Maximum selectable date YYYY-MM-DD                        |\n| theme                   | `CalendarTheme`                  | —                      | Override calendar theme (RN color strings)                |\n| trigger                 | `React.ReactNode`                | —                      | Trigger element. If not provided, no trigger is rendered. |\n| title                   | `string`                         | `'Select date'`        | Title shown in modal header                               |\n| confirmLabel            | `string`                         | `'Done'`               | Button label for confirm                                  |\n| className               | `string`                         | —                      |                                                           |\n| frosted                 | `boolean`                        | `false`                | Enable the optional frosted overlay.                      |\n| blurIntensity           | `number`                         | medium preset          | Override blur amount directly.                            |\n| blurTintToken           | `FrostedTintToken`               | `'surfaceTranslucent'` | Tint token used for frosted mode.                         |"
+    }
+  ],
+  "themeTokens": [
+    {
+      "key": "primary",
+      "cssVar": "--color-primary",
+      "appVar": "--app-color-primary",
+      "group": "core",
+      "light": "#4457ff",
+      "dark": "#ff5ca8"
+    },
+    {
+      "key": "primaryForeground",
+      "cssVar": "--color-primary-foreground",
+      "appVar": "--app-color-primary-foreground",
+      "group": "core",
+      "light": "#fffdf8",
+      "dark": "#2c1032"
+    },
+    {
+      "key": "foreground",
+      "cssVar": "--color-foreground",
+      "appVar": "--app-color-foreground",
+      "group": "core",
+      "light": "#271f48",
+      "dark": "#fff7eb"
+    },
+    {
+      "key": "background",
+      "cssVar": "--color-background",
+      "appVar": "--app-color-background",
+      "group": "core",
+      "light": "#fff8ef",
+      "dark": "#170f2d"
+    },
+    {
+      "key": "card",
+      "cssVar": "--color-card",
+      "appVar": "--app-color-card",
+      "group": "core",
+      "light": "rgba(255, 255, 255, 0.82)",
+      "dark": "rgba(38, 24, 69, 0.78)"
+    },
+    {
+      "key": "cardForeground",
+      "cssVar": "--color-card-foreground",
+      "appVar": "--app-color-card-foreground",
+      "group": "core",
+      "light": "#271f48",
+      "dark": "#fff7eb"
+    },
+    {
+      "key": "popover",
+      "cssVar": "--color-popover",
+      "appVar": "--app-color-popover",
+      "group": "core",
+      "light": "rgba(255, 252, 248, 0.92)",
+      "dark": "rgba(28, 18, 52, 0.90)"
+    },
+    {
+      "key": "popoverForeground",
+      "cssVar": "--color-popover-foreground",
+      "appVar": "--app-color-popover-foreground",
+      "group": "core",
+      "light": "#271f48",
+      "dark": "#fff7eb"
+    },
+    {
+      "key": "secondary",
+      "cssVar": "--color-secondary",
+      "appVar": "--app-color-secondary",
+      "group": "core",
+      "light": "rgba(255, 123, 92, 0.10)",
+      "dark": "rgba(255, 92, 168, 0.12)"
+    },
+    {
+      "key": "secondaryForeground",
+      "cssVar": "--color-secondary-foreground",
+      "appVar": "--app-color-secondary-foreground",
+      "group": "core",
+      "light": "#41206e",
+      "dark": "#fff3fa"
+    },
+    {
+      "key": "muted",
+      "cssVar": "--color-muted",
+      "appVar": "--app-color-muted",
+      "group": "core",
+      "light": "rgba(74, 55, 122, 0.07)",
+      "dark": "rgba(255, 247, 235, 0.08)"
+    },
+    {
+      "key": "mutedForeground",
+      "cssVar": "--color-muted-foreground",
+      "appVar": "--app-color-muted-foreground",
+      "group": "core",
+      "light": "#645783",
+      "dark": "#c5bad9"
+    },
+    {
+      "key": "border",
+      "cssVar": "--color-border",
+      "appVar": "--app-color-border",
+      "group": "core",
+      "light": "rgba(68, 87, 255, 0.16)",
+      "dark": "rgba(255, 255, 255, 0.12)"
+    },
+    {
+      "key": "input",
+      "cssVar": "--color-input",
+      "appVar": "--app-color-input",
+      "group": "core",
+      "light": "rgba(255, 255, 255, 0.84)",
+      "dark": "rgba(27, 18, 49, 0.86)"
+    },
+    {
+      "key": "ring",
+      "cssVar": "--color-ring",
+      "appVar": "--app-color-ring",
+      "group": "feedback",
+      "light": "#3d8bff",
+      "dark": "#7ff0c5"
+    },
+    {
+      "key": "accent",
+      "cssVar": "--color-accent",
+      "appVar": "--app-color-accent",
+      "group": "core",
+      "light": "#a7f432",
+      "dark": "#7ff0c5"
+    },
+    {
+      "key": "accentForeground",
+      "cssVar": "--color-accent-foreground",
+      "appVar": "--app-color-accent-foreground",
+      "group": "core",
+      "light": "#163218",
+      "dark": "#0f2d24"
+    },
+    {
+      "key": "destructive",
+      "cssVar": "--color-destructive",
+      "appVar": "--app-color-destructive",
+      "group": "status",
+      "light": "#d03d31",
+      "dark": "#ff6b57"
+    },
+    {
+      "key": "destructiveForeground",
+      "cssVar": "--color-destructive-foreground",
+      "appVar": "--app-color-destructive-foreground",
+      "group": "status",
+      "light": "#fff8f6",
+      "dark": "#2c0c0a"
+    },
+    {
+      "key": "success",
+      "cssVar": "--color-success",
+      "appVar": "--app-color-success",
+      "group": "status",
+      "light": "#00864d",
+      "dark": "#39db9b"
+    },
+    {
+      "key": "successForeground",
+      "cssVar": "--color-success-foreground",
+      "appVar": "--app-color-success-foreground",
+      "group": "status",
+      "light": "#f5fff9",
+      "dark": "#06241a"
+    },
+    {
+      "key": "warning",
+      "cssVar": "--color-warning",
+      "appVar": "--app-color-warning",
+      "group": "status",
+      "light": "#ffb224",
+      "dark": "#ffbe42"
+    },
+    {
+      "key": "warningForeground",
+      "cssVar": "--color-warning-foreground",
+      "appVar": "--app-color-warning-foreground",
+      "group": "status",
+      "light": "#3d2200",
+      "dark": "#2d1700"
+    },
+    {
+      "key": "info",
+      "cssVar": "--color-info",
+      "appVar": "--app-color-info",
+      "group": "status",
+      "light": "#2070e1",
+      "dark": "#78a7ff"
+    },
+    {
+      "key": "infoForeground",
+      "cssVar": "--color-info-foreground",
+      "appVar": "--app-color-info-foreground",
+      "group": "status",
+      "light": "#f8fbff",
+      "dark": "#09162d"
+    },
+    {
+      "key": "overlay",
+      "cssVar": "--color-overlay",
+      "appVar": "--app-color-overlay",
+      "group": "surface",
+      "light": "rgba(39, 31, 72, 0.14)",
+      "dark": "rgba(9, 4, 20, 0.50)"
+    },
+    {
+      "key": "overlayStrong",
+      "cssVar": "--color-overlay-strong",
+      "appVar": "--app-color-overlay-strong",
+      "group": "surface",
+      "light": "rgba(39, 31, 72, 0.22)",
+      "dark": "rgba(9, 4, 20, 0.68)"
+    },
+    {
+      "key": "surfaceElevated",
+      "cssVar": "--color-surface-elevated",
+      "appVar": "--app-color-surface-elevated",
+      "group": "surface",
+      "light": "rgba(255, 255, 255, 0.88)",
+      "dark": "rgba(45, 27, 79, 0.80)"
+    },
+    {
+      "key": "surfaceTranslucent",
+      "cssVar": "--color-surface-translucent",
+      "appVar": "--app-color-surface-translucent",
+      "group": "surface",
+      "light": "rgba(255, 255, 255, 0.62)",
+      "dark": "rgba(34, 20, 61, 0.58)"
+    },
+    {
+      "key": "surfaceTranslucentBorder",
+      "cssVar": "--color-surface-translucent-border",
+      "appVar": "--app-color-surface-translucent-border",
+      "group": "surface",
+      "light": "rgba(255, 255, 255, 0.42)",
+      "dark": "rgba(255, 255, 255, 0.12)"
+    },
+    {
+      "key": "surfaceBorder",
+      "cssVar": "--color-surface-border",
+      "appVar": "--app-color-surface-border",
+      "group": "surface",
+      "light": "rgba(68, 87, 255, 0.16)",
+      "dark": "rgba(255, 255, 255, 0.12)"
+    },
+    {
+      "key": "surfaceHighlight",
+      "cssVar": "--color-surface-highlight",
+      "appVar": "--app-color-surface-highlight",
+      "group": "surface",
+      "light": "rgba(255, 255, 255, 0.74)",
+      "dark": "rgba(255, 255, 255, 0.07)"
+    },
+    {
+      "key": "stateHover",
+      "cssVar": "--color-state-hover",
+      "appVar": "--app-color-state-hover",
+      "group": "feedback",
+      "light": "rgba(68, 87, 255, 0.06)",
+      "dark": "rgba(255, 92, 168, 0.08)"
+    },
+    {
+      "key": "statePressed",
+      "cssVar": "--color-state-pressed",
+      "appVar": "--app-color-state-pressed",
+      "group": "feedback",
+      "light": "rgba(68, 87, 255, 0.12)",
+      "dark": "rgba(255, 92, 168, 0.16)"
+    },
+    {
+      "key": "stateDisabled",
+      "cssVar": "--color-state-disabled",
+      "appVar": "--app-color-state-disabled",
+      "group": "feedback",
+      "light": "rgba(100, 87, 131, 0.28)",
+      "dark": "rgba(197, 186, 217, 0.22)"
+    },
+    {
+      "key": "shadow",
+      "cssVar": "--color-shadow",
+      "appVar": "--app-color-shadow",
+      "group": "surface",
+      "light": "#271f48",
+      "dark": "#000000"
+    },
+    {
+      "key": "primaryActive",
+      "cssVar": "--color-primary-active",
+      "appVar": "--app-color-primary-active",
+      "group": "feedback",
+      "light": "#3346e6",
+      "dark": "#ff74b6"
+    },
+    {
+      "key": "secondaryActive",
+      "cssVar": "--color-secondary-active",
+      "appVar": "--app-color-secondary-active",
+      "group": "feedback",
+      "light": "rgba(255, 123, 92, 0.18)",
+      "dark": "rgba(255, 92, 168, 0.20)"
+    },
+    {
+      "key": "destructiveActive",
+      "cssVar": "--color-destructive-active",
+      "appVar": "--app-color-destructive-active",
+      "group": "feedback",
+      "light": "#bb261d",
+      "dark": "#ff8271"
+    },
+    {
+      "key": "primarySoft",
+      "cssVar": "--color-primary-soft",
+      "appVar": "--app-color-primary-soft",
+      "group": "feedback",
+      "light": "rgba(68, 87, 255, 0.13)",
+      "dark": "rgba(255, 92, 168, 0.16)"
+    },
+    {
+      "key": "primarySoftSubtle",
+      "cssVar": "--color-primary-soft-subtle",
+      "appVar": "--app-color-primary-soft-subtle",
+      "group": "feedback",
+      "light": "rgba(68, 87, 255, 0.07)",
+      "dark": "rgba(255, 92, 168, 0.10)"
+    },
+    {
+      "key": "secondarySoft",
+      "cssVar": "--color-secondary-soft",
+      "appVar": "--app-color-secondary-soft",
+      "group": "feedback",
+      "light": "rgba(255, 123, 92, 0.16)",
+      "dark": "rgba(127, 240, 197, 0.08)"
+    },
+    {
+      "key": "mutedSoft",
+      "cssVar": "--color-muted-soft",
+      "appVar": "--app-color-muted-soft",
+      "group": "feedback",
+      "light": "rgba(74, 55, 122, 0.05)",
+      "dark": "rgba(255, 247, 235, 0.05)"
+    },
+    {
+      "key": "destructiveSoft",
+      "cssVar": "--color-destructive-soft",
+      "appVar": "--app-color-destructive-soft",
+      "group": "status",
+      "light": "rgba(208, 61, 49, 0.12)",
+      "dark": "rgba(255, 107, 87, 0.20)"
+    },
+    {
+      "key": "destructiveSoftBorder",
+      "cssVar": "--color-destructive-soft-border",
+      "appVar": "--app-color-destructive-soft-border",
+      "group": "status",
+      "light": "rgba(208, 61, 49, 0.30)",
+      "dark": "rgba(255, 107, 87, 0.40)"
+    },
+    {
+      "key": "successSoft",
+      "cssVar": "--color-success-soft",
+      "appVar": "--app-color-success-soft",
+      "group": "status",
+      "light": "rgba(0, 134, 77, 0.12)",
+      "dark": "rgba(57, 219, 155, 0.20)"
+    },
+    {
+      "key": "successSoftBorder",
+      "cssVar": "--color-success-soft-border",
+      "appVar": "--app-color-success-soft-border",
+      "group": "status",
+      "light": "rgba(0, 134, 77, 0.30)",
+      "dark": "rgba(57, 219, 155, 0.40)"
+    },
+    {
+      "key": "warningSoft",
+      "cssVar": "--color-warning-soft",
+      "appVar": "--app-color-warning-soft",
+      "group": "status",
+      "light": "rgba(255, 178, 36, 0.14)",
+      "dark": "rgba(255, 190, 66, 0.20)"
+    },
+    {
+      "key": "warningSoftBorder",
+      "cssVar": "--color-warning-soft-border",
+      "appVar": "--app-color-warning-soft-border",
+      "group": "status",
+      "light": "rgba(255, 178, 36, 0.34)",
+      "dark": "rgba(255, 190, 66, 0.45)"
+    },
+    {
+      "key": "infoSoft",
+      "cssVar": "--color-info-soft",
+      "appVar": "--app-color-info-soft",
+      "group": "status",
+      "light": "rgba(32, 112, 225, 0.12)",
+      "dark": "rgba(120, 167, 255, 0.20)"
+    },
+    {
+      "key": "infoSoftBorder",
+      "cssVar": "--color-info-soft-border",
+      "appVar": "--app-color-info-soft-border",
+      "group": "status",
+      "light": "rgba(32, 112, 225, 0.30)",
+      "dark": "rgba(120, 167, 255, 0.40)"
+    }
+  ],
+  "visualTokens": [
+    {
+      "key": "radiusSm",
+      "cssVar": "--ui-radius-sm",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 10
+    },
+    {
+      "key": "radiusMd",
+      "cssVar": "--ui-radius-md",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 14
+    },
+    {
+      "key": "radiusLg",
+      "cssVar": "--ui-radius-lg",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 18
+    },
+    {
+      "key": "radiusXl",
+      "cssVar": "--ui-radius-xl",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 24
+    },
+    {
+      "key": "controlHeightSm",
+      "cssVar": "--ui-control-height-sm",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 36
+    },
+    {
+      "key": "controlHeightDefault",
+      "cssVar": "--ui-control-height-default",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 44
+    },
+    {
+      "key": "controlHeightLg",
+      "cssVar": "--ui-control-height-lg",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 52
+    },
+    {
+      "key": "controlPaddingXSm",
+      "cssVar": "--ui-control-padding-x-sm",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 12
+    },
+    {
+      "key": "controlPaddingXDefault",
+      "cssVar": "--ui-control-padding-x-default",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 16
+    },
+    {
+      "key": "controlPaddingXLg",
+      "cssVar": "--ui-control-padding-x-lg",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 24
+    },
+    {
+      "key": "controlPaddingYSm",
+      "cssVar": "--ui-control-padding-y-sm",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 8
+    },
+    {
+      "key": "controlPaddingYDefault",
+      "cssVar": "--ui-control-padding-y-default",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 10
+    },
+    {
+      "key": "controlPaddingYLg",
+      "cssVar": "--ui-control-padding-y-lg",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 14
+    },
+    {
+      "key": "surfacePaddingSm",
+      "cssVar": "--ui-surface-padding-sm",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 16
+    },
+    {
+      "key": "surfacePaddingDefault",
+      "cssVar": "--ui-surface-padding-default",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 24
+    },
+    {
+      "key": "surfacePaddingLg",
+      "cssVar": "--ui-surface-padding-lg",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 32
+    },
+    {
+      "key": "badgeRadius",
+      "cssVar": "--ui-badge-radius",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 999
+    },
+    {
+      "key": "badgePaddingX",
+      "cssVar": "--ui-badge-padding-x",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 10
+    },
+    {
+      "key": "badgePaddingY",
+      "cssVar": "--ui-badge-padding-y",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 4
+    },
+    {
+      "key": "fontSizeXs",
+      "cssVar": "--ui-font-size-xs",
+      "kind": "pixel",
+      "group": "typography",
+      "fallback": 11
+    },
+    {
+      "key": "fontSizeSm",
+      "cssVar": "--ui-font-size-sm",
+      "kind": "pixel",
+      "group": "typography",
+      "fallback": 13
+    },
+    {
+      "key": "fontSizeBase",
+      "cssVar": "--ui-font-size-base",
+      "kind": "pixel",
+      "group": "typography",
+      "fallback": 15
+    },
+    {
+      "key": "fontSizeLg",
+      "cssVar": "--ui-font-size-lg",
+      "kind": "pixel",
+      "group": "typography",
+      "fallback": 17
+    },
+    {
+      "key": "fontSizeXl",
+      "cssVar": "--ui-font-size-xl",
+      "kind": "pixel",
+      "group": "typography",
+      "fallback": 20
+    },
+    {
+      "key": "fontSize2xl",
+      "cssVar": "--ui-font-size-2xl",
+      "kind": "pixel",
+      "group": "typography",
+      "fallback": 24
+    },
+    {
+      "key": "letterSpacingCaption",
+      "cssVar": "--ui-letter-spacing-caption",
+      "kind": "number",
+      "group": "typography",
+      "fallback": 0.2
+    },
+    {
+      "key": "letterSpacingLabel",
+      "cssVar": "--ui-letter-spacing-label",
+      "kind": "number",
+      "group": "typography",
+      "fallback": 0.1
+    },
+    {
+      "key": "letterSpacingBody",
+      "cssVar": "--ui-letter-spacing-body",
+      "kind": "number",
+      "group": "typography",
+      "fallback": 0
+    },
+    {
+      "key": "letterSpacingTitle",
+      "cssVar": "--ui-letter-spacing-title",
+      "kind": "number",
+      "group": "typography",
+      "fallback": -0.2
+    },
+    {
+      "key": "letterSpacingHeadline",
+      "cssVar": "--ui-letter-spacing-headline",
+      "kind": "number",
+      "group": "typography",
+      "fallback": -0.4
+    },
+    {
+      "key": "borderWidthHairline",
+      "cssVar": "--ui-border-width-hairline",
+      "kind": "scalar",
+      "group": "depth",
+      "fallback": 1
+    },
+    {
+      "key": "borderWidthControl",
+      "cssVar": "--ui-border-width-control",
+      "kind": "scalar",
+      "group": "depth",
+      "fallback": 1
+    },
+    {
+      "key": "borderWidthEmphasis",
+      "cssVar": "--ui-border-width-emphasis",
+      "kind": "scalar",
+      "group": "depth",
+      "fallback": 2
+    },
+    {
+      "key": "focusRingWidth",
+      "cssVar": "--ui-focus-ring-width",
+      "kind": "scalar",
+      "group": "depth",
+      "fallback": 2
+    },
+    {
+      "key": "shadowOpacitySm",
+      "cssVar": "--ui-shadow-opacity-sm",
+      "kind": "ratio",
+      "group": "depth",
+      "fallback": 0.06
+    },
+    {
+      "key": "shadowOpacityMd",
+      "cssVar": "--ui-shadow-opacity-md",
+      "kind": "ratio",
+      "group": "depth",
+      "fallback": 0.1
+    },
+    {
+      "key": "shadowOpacityLg",
+      "cssVar": "--ui-shadow-opacity-lg",
+      "kind": "ratio",
+      "group": "depth",
+      "fallback": 0.16
+    },
+    {
+      "key": "shadowRadiusSm",
+      "cssVar": "--ui-shadow-radius-sm",
+      "kind": "pixel",
+      "group": "depth",
+      "fallback": 3
+    },
+    {
+      "key": "shadowRadiusMd",
+      "cssVar": "--ui-shadow-radius-md",
+      "kind": "pixel",
+      "group": "depth",
+      "fallback": 12
+    },
+    {
+      "key": "shadowRadiusLg",
+      "cssVar": "--ui-shadow-radius-lg",
+      "kind": "pixel",
+      "group": "depth",
+      "fallback": 28
+    },
+    {
+      "key": "shadowOffsetYSm",
+      "cssVar": "--ui-shadow-offset-y-sm",
+      "kind": "pixel",
+      "group": "depth",
+      "fallback": 1
+    },
+    {
+      "key": "shadowOffsetYMd",
+      "cssVar": "--ui-shadow-offset-y-md",
+      "kind": "pixel",
+      "group": "depth",
+      "fallback": 4
+    },
+    {
+      "key": "shadowOffsetYLg",
+      "cssVar": "--ui-shadow-offset-y-lg",
+      "kind": "pixel",
+      "group": "depth",
+      "fallback": 12
+    },
+    {
+      "key": "shadowElevationSm",
+      "cssVar": "--ui-shadow-elevation-sm",
+      "kind": "pixel",
+      "group": "depth",
+      "fallback": 1
+    },
+    {
+      "key": "shadowElevationMd",
+      "cssVar": "--ui-shadow-elevation-md",
+      "kind": "pixel",
+      "group": "depth",
+      "fallback": 4
+    },
+    {
+      "key": "shadowElevationLg",
+      "cssVar": "--ui-shadow-elevation-lg",
+      "kind": "pixel",
+      "group": "depth",
+      "fallback": 10
+    },
+    {
+      "key": "touchTargetMinSize",
+      "cssVar": "--ui-touch-target-min-size",
+      "kind": "pixel",
+      "group": "foundation",
+      "fallback": 44
+    },
+    {
+      "key": "drawerWidthRatio",
+      "cssVar": "--ui-drawer-width-ratio",
+      "kind": "ratio",
+      "group": "component",
+      "fallback": 0.84
+    },
+    {
+      "key": "drawerMaxWidthWeb",
+      "cssVar": "--ui-drawer-max-width-web",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 380
+    },
+    {
+      "key": "drawerFrostedInset",
+      "cssVar": "--ui-drawer-frosted-inset",
+      "kind": "pixel",
+      "group": "surface",
+      "fallback": 10
+    },
+    {
+      "key": "drawerFrostedRadius",
+      "cssVar": "--ui-drawer-frosted-radius",
+      "kind": "pixel",
+      "group": "surface",
+      "fallback": 34
+    },
+    {
+      "key": "drawerContentTopPadding",
+      "cssVar": "--ui-drawer-content-top-padding",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 0
+    },
+    {
+      "key": "drawerItemFontSize",
+      "cssVar": "--ui-drawer-item-font-size",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 15
+    },
+    {
+      "key": "drawerBadgeMinWidth",
+      "cssVar": "--ui-drawer-badge-min-width",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 20
+    },
+    {
+      "key": "navSectionTitleFontSize",
+      "cssVar": "--ui-nav-section-title-font-size",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 11
+    },
+    {
+      "key": "navItemBadgeFontSize",
+      "cssVar": "--ui-nav-item-badge-font-size",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 11
+    },
+    {
+      "key": "bottomNavBadgeFontSize",
+      "cssVar": "--ui-bottom-nav-badge-font-size",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 10
+    },
+    {
+      "key": "dataRowCompactDescriptionSize",
+      "cssVar": "--ui-data-row-compact-description-size",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 11
+    },
+    {
+      "key": "dataRowRightMaxWidthRatio",
+      "cssVar": "--ui-data-row-right-max-width-ratio",
+      "kind": "ratio",
+      "group": "component",
+      "fallback": 0.45
+    },
+    {
+      "key": "segmentedWrapBasisRatio",
+      "cssVar": "--ui-segmented-wrap-basis-ratio",
+      "kind": "ratio",
+      "group": "component",
+      "fallback": 0.48
+    },
+    {
+      "key": "textareaMinHeightDefault",
+      "cssVar": "--ui-textarea-min-height-default",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 80
+    },
+    {
+      "key": "textareaMinHeightSm",
+      "cssVar": "--ui-textarea-min-height-sm",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 60
+    },
+    {
+      "key": "textareaMinHeightLg",
+      "cssVar": "--ui-textarea-min-height-lg",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 120
+    },
+    {
+      "key": "chatBubbleMaxWidthRatio",
+      "cssVar": "--ui-chat-bubble-max-width-ratio",
+      "kind": "ratio",
+      "group": "component",
+      "fallback": 0.85
+    },
+    {
+      "key": "chatSystemBubbleMaxWidthRatio",
+      "cssVar": "--ui-chat-system-bubble-max-width-ratio",
+      "kind": "ratio",
+      "group": "component",
+      "fallback": 0.9
+    },
+    {
+      "key": "smartInputMaxHeight",
+      "cssVar": "--ui-smart-input-max-height",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 120
+    },
+    {
+      "key": "formModalContentMinHeightRatio",
+      "cssVar": "--ui-form-modal-content-min-height-ratio",
+      "kind": "ratio",
+      "group": "component",
+      "fallback": 0.4
+    },
+    {
+      "key": "sheetTabletBreakpoint",
+      "cssVar": "--ui-sheet-tablet-breakpoint",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 600
+    },
+    {
+      "key": "sheetMaxWidth",
+      "cssVar": "--ui-sheet-max-width",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 400
+    },
+    {
+      "key": "sheetHalfMaxHeightRatio",
+      "cssVar": "--ui-sheet-half-max-height-ratio",
+      "kind": "ratio",
+      "group": "component",
+      "fallback": 0.56
+    },
+    {
+      "key": "sheetHalfMinHeight",
+      "cssVar": "--ui-sheet-half-min-height",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 340
+    },
+    {
+      "key": "swipeActionWidth",
+      "cssVar": "--ui-swipe-action-width",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 80
+    },
+    {
+      "key": "skeletonShimmerBandWidth",
+      "cssVar": "--ui-skeleton-shimmer-band-width",
+      "kind": "pixel",
+      "group": "component",
+      "fallback": 56
+    },
+    {
+      "key": "blurIntensitySubtle",
+      "cssVar": "--ui-blur-intensity-subtle",
+      "kind": "pixel",
+      "group": "surface",
+      "fallback": 18
+    },
+    {
+      "key": "blurIntensityMedium",
+      "cssVar": "--ui-blur-intensity-medium",
+      "kind": "pixel",
+      "group": "surface",
+      "fallback": 26
+    },
+    {
+      "key": "blurIntensityStrong",
+      "cssVar": "--ui-blur-intensity-strong",
+      "kind": "pixel",
+      "group": "surface",
+      "fallback": 34
+    },
+    {
+      "key": "blurSaturationPct",
+      "cssVar": "--ui-blur-saturation-pct",
+      "kind": "pixel",
+      "group": "surface",
+      "fallback": 145
+    },
+    {
+      "key": "frostedHighlightHeight",
+      "cssVar": "--ui-frosted-highlight-height",
+      "kind": "pixel",
+      "group": "surface",
+      "fallback": 2
+    },
+    {
+      "key": "frostedBackdropBlurIntensity",
+      "cssVar": "--ui-frosted-backdrop-blur-intensity",
+      "kind": "pixel",
+      "group": "surface",
+      "fallback": 22
+    },
+    {
+      "key": "frostedBackdropBlurScale",
+      "cssVar": "--ui-frosted-backdrop-blur-scale",
+      "kind": "ratio",
+      "group": "surface",
+      "fallback": 0.72
+    },
+    {
+      "key": "androidFrostedTintAlphaScale",
+      "cssVar": "--ui-frosted-android-tint-alpha-scale",
+      "kind": "ratio",
+      "group": "surface",
+      "fallback": 1.18
+    },
+    {
+      "key": "androidExperimentalBlurEnabled",
+      "cssVar": "--ui-frosted-android-experimental-blur",
+      "kind": "boolean",
+      "group": "surface",
+      "fallback": 1
+    }
+  ]
+}