@thewhileloop/whileui 4.2.3 → 4.4.0

package/README.md

@@ -1,26 +1,35 @@
 # WhileUI Native
 
-> Copy-paste components for React Native. You own the code.
+> Accessible, themeable React Native components for iOS, Android and the web.
 
-Beautiful, accessible, themeable components built with [Uniwind](https://uniwind.dev) + Tailwind CSS v4.
+Components and blocks built with [Uniwind](https://uniwind.dev) + Tailwind CSS v4. Every
+one takes `className` and exports its `tv()` variants for extension, and the look comes
+from design tokens in your `global.css`, so a new theme needs no component changes. Auth
+and profile screens are copy-paste templates in
+[`apps/showcase/catalog/templates`](apps/showcase/catalog/templates) rather than package
+exports: copy them and make them yours.
 
-**Requirements:** React 19.3+, React Native 0.88+, Expo 58+ (if using Expo). Supports React Native Web.
-
-WhileUI has one renderer: React Native. iOS, Android and React Native Web are all
-production targets — iOS and Android set the interaction baseline. See
-[ROADMAP.md](./ROADMAP.md) for the product boundary and extraction rules, and
-[PLAN.md](./PLAN.md) for the supported stack and production contracts.
+**Requirements:** React 19.3+, React Native 0.88+, Expo 58+ (if using Expo). See
+[ROADMAP.md](./ROADMAP.md) for what the package owns and [PLAN.md](./PLAN.md) for the
+supported stack.
 
 ## See it in action
 
-One React Native component contract across native and web, with semantic typography,
-token-driven light and dark themes, accessible controls, and application-owned chat
-composition. The same component tree can feel airy and atmospheric or compact and
-editorial by changing tokens alone.
+The same app code on an iPhone simulator, an Android emulator and the web, running the
+same tour side by side.
+
+**The catalog** — every component and block, in light and dark
+([`apps/showcase/catalog`](apps/showcase/catalog)):
+
+<p align="center">
+  <img src="./docs/assets/whileui-catalog.gif" width="760" alt="The WhileUI component catalog running side by side on iPhone, Android and web: scrolling the components, switching from light to dark theme, and opening the Controls tab" />
+</p>
+
+**Clayhouse** — a made-up ceramics studio app built only from WhileUI, with its own theme
+and fonts ([`apps/showcase/clayhouse`](apps/showcase/clayhouse)):
 
 <p align="center">
-  <img src="./docs/assets/whileui-showcase.gif" width="300" alt="WhileUI Cosmic Aura mobile theme demonstrating light and dark modes, controls, Select, and composable chat" />
-  <img src="./docs/assets/whileui-showcase-atelier.gif" width="300" alt="WhileUI Atelier mobile theme demonstrating compact controls, authentication forms, Select, and composable chat" />
+  <img src="./docs/assets/whileui-clayhouse.gif" width="760" alt="Clayhouse, a made-up ceramics studio app, running side by side on iPhone, Android and web: a live kiln temperature and firing curve, the glaze library, switching to night mode, and the member screen" />
 </p>
 
 ## Installation
@@ -57,75 +66,19 @@ module.exports = withWhileUIMetro(config, {
 > `expo-font` and `@expo/vector-icons` on the real `react-native`. Without that, Uniwind's
 > import rewrite leaves every icon glyph silently missing on iOS and Android while web
 > renders fine. Pass `exemptFromUniwindRewrite: ['pkg']` for any other package that
-> imports a non-component export from `react-native`. It must be the outermost wrapper.
+> imports a `react-native` export Uniwind's wrapper lacks. It must be the outermost wrapper.
 
-2. **global.css** at app root:
+2. **global.css** at app root, imported from `App.tsx`:
 
 ```css
 @import 'tailwindcss';
 @import 'uniwind';
 
-/* Required when WhileUI is installed from npm. Tailwind does not scan
-   node_modules, so without this its class names are never detected and every
-   component renders unstyled. */
+/* Required when installed from npm: Tailwind does not scan node_modules, so without
+   this line every component renders unstyled. */
 @source './node_modules/@thewhileloop/whileui/dist';
 
-/* WhileUI Noir theme - copy this or create your own */
-@layer theme {
-  :root {
-    @variant light {
-      --color-background: oklch(1 0 0);
-      --color-foreground: oklch(0.1316 0.0041 17.69);
-      --color-card: oklch(1 0 0);
-      --color-card-foreground: oklch(0.1316 0.0041 17.69);
-      --color-primary: oklch(0.1316 0.0041 17.69);
-      --color-primary-foreground: oklch(0.98 0 0);
-      --color-secondary: oklch(0.9598 0.0017 17.69);
-      --color-secondary-foreground: oklch(0.1316 0.0041 17.69);
-      --color-muted: oklch(0.9598 0.0017 17.69);
-      --color-muted-foreground: oklch(0.5415 0.0135 17.69);
-      --color-accent: oklch(0.9598 0.0017 17.69);
-      --color-accent-foreground: oklch(0.1316 0.0041 17.69);
-      --color-destructive: oklch(0.5 0.19 27);
-      --color-destructive-foreground: oklch(0.98 0 0);
-      --color-border: oklch(0.9039 0.0034 17.69);
-      --color-input: oklch(0.9039 0.0034 17.69);
-      --color-ring: oklch(0.1316 0.0041 17.69);
-      --color-success: oklch(0.59 0.16 145);
-      --color-success-foreground: oklch(0.98 0 0);
-      --color-warning: oklch(0.75 0.18 85);
-      --color-warning-foreground: oklch(0.1316 0.0041 17.69);
-      --color-info: oklch(0.65 0.15 245);
-      --color-info-foreground: oklch(0.98 0 0);
-    }
-
-    @variant dark {
-      --color-background: oklch(0.1316 0.0041 17.69);
-      --color-foreground: oklch(0.98 0 0);
-      --color-card: oklch(0.1316 0.0041 17.69);
-      --color-card-foreground: oklch(0.98 0 0);
-      --color-primary: oklch(0.98 0 0);
-      --color-primary-foreground: oklch(0.1316 0.0041 17.69);
-      --color-secondary: oklch(0.2104 0.0084 17.69);
-      --color-secondary-foreground: oklch(0.98 0 0);
-      --color-muted: oklch(0.2104 0.0084 17.69);
-      --color-muted-foreground: oklch(0.6961 0.0174 17.69);
-      --color-accent: oklch(0.2104 0.0084 17.69);
-      --color-accent-foreground: oklch(0.98 0 0);
-      --color-destructive: oklch(0.45 0.18 27);
-      --color-destructive-foreground: oklch(0.98 0 0);
-      --color-border: oklch(0.2104 0.0084 17.69);
-      --color-input: oklch(0.2104 0.0084 17.69);
-      --color-ring: oklch(0.8267 0.0206 17.69);
-      --color-success: oklch(0.59 0.16 145);
-      --color-success-foreground: oklch(0.98 0 0);
-      --color-warning: oklch(0.75 0.18 85);
-      --color-warning-foreground: oklch(0.1316 0.0041 17.69);
-      --color-info: oklch(0.65 0.15 245);
-      --color-info-foreground: oklch(0.98 0 0);
-    }
-  }
-}
+/* Then your theme: generate it (Theming, below) rather than writing tokens by hand. */
 ```
 
 3. **App.tsx**:
@@ -145,13 +98,11 @@ export default function App() {
 }
 ```
 
-> **Note:** If you use Select, Popover, Tooltip, or HoverCard, add `<PortalHost />` at the root of your app (as the last child).
-
-Inside a Dialog, AlertDialog, Sheet, ConfirmActionSheet, DrawerMenu, menu or picker, those
-four render into that overlay's own layer automatically, so a Select in a sheet opens above
-the sheet. Android back and Escape on web close the innermost open layer first. Pass
-`portalHost` on their content only to target a `PortalHost` you placed yourself, such as
-inside a navigation-presented modal screen that WhileUI does not host.
+`PortalHost` (last child of the root) is where Select, Popover, Tooltip and HoverCard
+render. Inside a Dialog, Sheet, menu or picker they use that overlay's own layer
+automatically, and Android back or Escape closes the innermost layer first. Pass
+`portalHost` only to target a host you placed yourself, such as in a modal screen your
+navigator presents.
 
 ### Vite + React Native Web + WhileUI setup
 
@@ -215,36 +166,37 @@ function MyScreen() {
 }
 ```
 
-## Blocks Strategy: Core vs Templates
+## AI agents
 
-**Core package** exports:
+Every release ships its docs for agents inside the package, so an agent reads the docs for
+the version you have installed, not whatever a website currently shows:
 
-- **Primitives** — Button, Input, Card, Text, etc.
-- **Generic layout blocks** — EmptyState, ErrorState, LoadingScreen, ContentSkeleton, PageSkeleton, ScreenSkeleton
-- **Layout infrastructure** — FormModalScreen, ConfirmActionSheet, SmartInput, ActionBar
-- **Navigation, Chat, Lists, Commerce, Media, DatePicker** — Blocks that rarely need app-specific customization
+- `node_modules/@thewhileloop/whileui/dist/agent/llms.txt` — rules, composition grammar
+  and every component in one page. `llms-components.txt` adds each API section;
+  `llms-full.txt` is this README.
+- [`@thewhileloop/whileui-mcp`](packages/mcp/README.md) serves the same catalog over MCP
+  (`list_components`, `get_component_docs`, `get_theme_tokens`, `get_guide`):
 
-**Opinionated blocks** (auth, profile) are **copy-paste templates** in the showcase app:
+  ```bash
+  claude mcp add whileui -- npx -y @thewhileloop/whileui-mcp
+  ```
 
-- **Auth:** `apps/showcase/templates/auth/` — SignInForm, SignUpForm, ForgotPasswordForm, ResetPasswordForm, VerifyEmailForm, SocialConnections, UserMenu
-- **Profile:** `apps/showcase/templates/profile/` — ProfileHeader, SettingsSection, SettingsItem, AccountCard
+- A [skill](skills/whileui/SKILL.md) for Claude Code, Cursor, Codex and other agents
+  that load skills: setup traps, how to compose and theme, and how to check a screen. It
+  points at the installed docs rather than copying them, and the build fails if it names
+  an API, MCP tool or file that no longer exists. Install it with
+  `npx skills add whileloophq/whileui`, or copy `skills/whileui` into your agent's skills
+  folder (for Claude Code, `.claude/skills/`).
 
-**To use auth or profile blocks:** Copy the template file(s) from `apps/showcase/templates/` into your app. Customize as needed (error handling, loading state, social auth slot, branding). Each template imports primitives from `@thewhileloop/whileui`.
-
-## Philosophy
-
-- **Copy-Paste Ownership** — Components live in _your_ project. No `node_modules` lock-in.
-- **Beautiful by Default** — OKLCH color system, light/dark themes, polished out of the box.
-- **Fully Customizable** — Every component uses `tv()` variants and accepts `className` overrides.
-- **Accessible** — Proper ARIA roles, keyboard support, controlled/uncontrolled state.
-- **Tree-Shakeable** — Only imports what you use. `sideEffects: false`.
+The docs and catalog are generated from this README at build time, and the build fails if
+a component named here is not exported.
 
 ## Quick Reference (AI / Code Generation)
 
 - **Full-screen:** `AppShell` + `Header` in `header` + `BottomNav` in `bottomNav` + content in `children`
 - **No-jump loading:** keep `AppShell` mounted, set `loading` + `skeleton` (e.g., `PageSkeleton`/`ScreenSkeleton`)
 - **Layout:** `Stack` (vertical), `Row` (horizontal) — both support `gap`, `align`, `justify`
-- **Auth callbacks:** Auth templates use objects: `onSubmit({ email, password })`, `onSubmit({ firstName, lastName, email, password })`, etc. Copy templates from `apps/showcase/templates/auth/`.
+- **Auth callbacks:** Auth templates use objects: `onSubmit({ email, password })`, `onSubmit({ firstName, lastName, email, password })`, etc. Copy templates from `apps/showcase/catalog/templates/auth/`.
 - **PortalHost:** Add `<PortalHost />` at app root for Select, Popover, Tooltip, HoverCard.
   Inside any WhileUI overlay they render into that overlay's layer without configuration.
 - **Motion:** Wrap the root in `<MotionProvider>`; use `useMotionPolicy()` for semantic
@@ -255,7 +207,7 @@ function MyScreen() {
   `@source './node_modules/@thewhileloop/whileui/dist';` or every component renders unstyled.
 - **States:** `LoadingState`, `EmptyState` and `ErrorState` share one shape; `ErrorState`
   takes `onRetry`. `Text variant="eyebrow"` is the muted section label above a title.
-- **Reference:** Block props in `packages/ui/src/blocks` (core) and `apps/showcase/templates/` (auth, profile); flow patterns in README "Flow Patterns" section.
+- **Reference:** Block props in `packages/ui/src/blocks` (core) and `apps/showcase/catalog/templates/` (auth, profile); flow patterns in README "Flow Patterns" section.
 
 ### Composition grammar
 
@@ -360,7 +312,7 @@ function MyScreen() {
 
 ### Auth (Copy from showcase templates)
 
-Copy from `apps/showcase/templates/auth/`:
+Copy from `apps/showcase/catalog/templates/auth/`:
 
 | Block                  | File                       | Description                           |
 | ---------------------- | -------------------------- | ------------------------------------- |
@@ -418,7 +370,7 @@ Copy from `apps/showcase/templates/auth/`:
 
 ### Profile & Settings (Copy from showcase templates)
 
-Copy from `apps/showcase/templates/profile/`:
+Copy from `apps/showcase/catalog/templates/profile/`:
 
 | Block               | File                   | Description                         |
 | ------------------- | ---------------------- | ----------------------------------- |
@@ -525,6 +477,10 @@ const icons = useIconColors();
 `FABGroup` stacks secondary actions above one. Sizes start at 48dp, so a FAB never
 needs `hitSlop`.
 
+A floating FAB covers whatever scrolls under it, so a list behind one ends with room for
+it: `contentContainerStyle={{ paddingBottom: fabClearance() }}`, passing the FAB's `size`
+when it is not the default.
+
 ## Layout Primitives (Stack, Row)
 
 Use `Stack` for vertical layouts, `Row` for horizontal layouts. Both support `gap`, `align`, and `justify` variants.
@@ -545,11 +501,17 @@ import { Stack, Row } from '@thewhileloop/whileui';
 </Stack>;
 ```
 
-| Prop    | Stack/Row                                                           | Values                   |
-| ------- | ------------------------------------------------------------------- | ------------------------ |
-| gap     | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`           | Spacing between children |
-| align   | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'`           | Cross-axis alignment     |
-| justify | `'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'` | Main-axis alignment      |
+<!-- api:Row -->
+
+| Prop      | Type                                                                | Default    | Description |
+| --------- | ------------------------------------------------------------------- | ---------- | ----------- |
+| className | `string`                                                            | —          |             |
+| gap       | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`           | `'md'`     |             |
+| align     | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'`           | `'center'` |             |
+| justify   | `'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'` | `'start'`  |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Row -->
 
 ### Container
 
@@ -561,11 +523,16 @@ controls drift apart.
 <Container size="lg">{children}</Container>
 ```
 
-| Prop        | Type                                   | Default | Notes                       |
-| ----------- | -------------------------------------- | ------- | --------------------------- |
-| `size`      | `sm` \| `md` \| `lg` \| `xl` \| `full` | `md`    | `sm` forms, `lg` dashboards |
-| `fill`      | `boolean`                              | `false` | `flex-1`, for a screen root |
-| `className` | `string`                               | —       | Merged after the variant    |
+<!-- api:Container -->
+
+| Prop      | Type                                     | Default | Description |
+| --------- | ---------------------------------------- | ------- | ----------- |
+| className | `string`                                 | —       |             |
+| size      | `'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`  |             |
+| fill      | `boolean`                                | `false` |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Container -->
 
 No platform branch, and none is needed: every size is wider than any phone, so on iOS
 and Android the cap never engages and it renders as a plain full-width `View`. The same
@@ -630,142 +597,66 @@ Blocks with `loading` support: ProductCard, ListItem, NotificationItem, MetricCa
 
 Block props: see TypeScript interfaces in `packages/ui/src/blocks`.
 
-## Quick Start
-
-```bash
-bun install
-cd apps/showcase
-bun run dev
-# Or: npx expo start --web
-```
-
-## Project Structure
-
-```
-whileui/
-├── packages/
-│   └── ui/
-│       └── src/
-│           ├── components/    # All components (copy these!)
-│           │   ├── button/
-│           │   ├── card/
-│           │   ├── form-field/
-│           │   ├── numeric-input/
-│           │   ├── segmented-control/
-│           │   ├── data-row/
-│           │   ├── dialog/
-│           │   └── ...
-│           ├── blocks/        # Pre-built screens (core only)
-│           │   ├── chat/
-│           │   ├── navigation/
-│           │   ├── layout/
-│           │   ├── lists/
-│           │   ├── commerce/
-│           │   ├── splash/
-│           │   └── media/
-│           ├── lib/           # Utilities
-│           │   ├── cn.ts      # clsx + tailwind-merge
-│           │   ├── tv.ts      # tailwind-variants re-export
-│           │   ├── font-context.ts
-│           │   └── theme-bridge.ts
-│           └── index.ts       # Barrel export
-├── apps/
-│   └── showcase/              # Expo demo app
-│       ├── templates/         # Copy-paste templates (auth, profile)
-│       │   ├── auth/
-│       │   └── profile/
-│       ├── App.tsx            # Component showcase
-│       ├── global.css         # Theme variables (OKLCH) — at app root!
-│       └── metro.config.js    # Uniwind + monorepo config
-└── package.json               # bun monorepo root
-```
-
 ## Theming
 
-Themes are defined in `global.css` using CSS variables with OKLCH colors:
-
-```css
-@variant light {
-  --color-primary: oklch(0.6 0.2 160);
-  --color-background: oklch(1 0 0);
-  /* ... */
-}
-
-@variant dark {
-  --color-primary: oklch(0.6 0.2 160);
-  --color-background: oklch(0.145 0 0);
-  /* ... */
-}
-```
-
-### Strict Theme Token Contract
-
-The WhileUI token contract is strict for cross-app reuse. Define these in **every** theme variant (`@variant light`, `@variant dark`, and custom variants):
-
-- Required core tokens: `background`, `foreground`, `card`, `card-foreground`, `popover`, `popover-foreground`, `primary`, `primary-foreground`, `secondary`, `secondary-foreground`, `muted`, `muted-foreground`, `accent`, `accent-foreground`, `destructive`, `destructive-foreground`, `border`, `input`, `ring`
-- Optional status tokens: `success`, `success-foreground`, `warning`, `warning-foreground`, `info`, `info-foreground`
-- Optional effect tokens: `overlay`, `overlay-strong`, `surface-elevated`, `surface-border`, `surface-highlight`, `surface-translucent`, `surface-translucent-border`, `state-hover`, `state-pressed`, `state-disabled`
-- Optional visual tokens, generated from a preset: `--ui-blur-intensity-subtle`, `--ui-blur-intensity-medium`, `--ui-blur-intensity-strong`, `--ui-blur-saturation-pct`, `--ui-frosted-highlight-height`, `--ui-frosted-backdrop-blur-intensity`, `--ui-frosted-backdrop-blur-scale`, `--ui-frosted-android-tint-alpha-scale`, `--ui-frosted-android-experimental-blur`, `--ui-drawer-frosted-inset`, `--ui-drawer-frosted-radius`, `--ui-drawer-content-top-padding`
-- Optional scale tokens: spacing (`--spacing`, `--spacing-*`), typography (`--text-*`, `--leading-*`, `--tracking-*`), radius (`--radius-*`), elevation (`--shadow-*`)
+A theme is a set of CSS variables in `global.css`, in OKLCH, with a `light` and a `dark`
+variant. Every component reads the same contract, so a theme must define **every** token
+in both modes: a missing one silently falls back to an unstyled value at runtime.
 
-Minimal contract example:
+### Generate a theme
 
-```css
-@layer theme {
-  :root {
-    @variant light {
-      --color-background: oklch(1 0 0);
-      --color-foreground: oklch(0.15 0 0);
-      --color-card: oklch(1 0 0);
-      --color-card-foreground: oklch(0.15 0 0);
-      --color-popover: oklch(1 0 0);
-      --color-popover-foreground: oklch(0.15 0 0);
-      --color-primary: oklch(0.2 0 0);
-      --color-primary-foreground: oklch(0.98 0 0);
-      --color-secondary: oklch(0.95 0 0);
-      --color-secondary-foreground: oklch(0.15 0 0);
-      --color-muted: oklch(0.95 0 0);
-      --color-muted-foreground: oklch(0.45 0 0);
-      --color-accent: oklch(0.9 0.05 180);
-      --color-accent-foreground: oklch(0.15 0 0);
-      --color-destructive: oklch(0.58 0.2 26);
-      --color-destructive-foreground: oklch(0.98 0 0);
-      --color-border: oklch(0.9 0 0);
-      --color-input: oklch(0.92 0 0);
-      --color-ring: oklch(0.22 0 0);
-    }
-  }
-}
-```
-
-Switch themes at runtime via Uniwind:
+`themeFromSeeds` builds a complete light and dark theme from three colours, and
+`themePresetToCss` writes every token, including the hex fallbacks React Native APIs need,
+ready to paste into `global.css`:
 
-```tsx
-import { Uniwind } from 'uniwind';
+```ts
+import { checkThemeContrast, themeFromSeeds, themePresetToCss } from '@thewhileloop/whileui/tokens';
+
+const theme = themeFromSeeds({
+  name: 'studio',
+  description: 'Bone paper and burnt amber',
+  light: { background: '#f0ede9', foreground: '#13161c', primary: '#b65400' },
+  // optional: `dark` seeds (otherwise a dark page with the brand lifted to read on it),
+  // `overrides` for any base colour, `visual` for radius and density tokens
+});
 
-Uniwind.setTheme('dark'); // or 'light' or 'system'
+checkThemeContrast(theme.light).filter((c) => !c.pass);
+// [{ pair: 'primary on background', ratio: 4.23, min: 4.5, pass: false }, …]
+const css = themePresetToCss(theme); // paste into global.css
 ```
 
-### Frosted / Translucent Theme
-
-Some apps want a frosted or translucent look for floating panels (modals, sheets, toolbars). WhileUI stays neutral — no "glass" in core token names. Apps that want this effect opt in by overriding surface tokens in their theme.
+Seeds are kept as given; the colours it derives (muted text, text on each fill, status
+colours) are tuned to WCAG AA. `checkThemeContrast` checks any palette, hand-written ones
+included: every text pairing at 4.5:1 and the focus ring at 3:1. A failing seed is
+reported, never changed, because a brand colour is a brand decision. The built-in presets,
+`WHILEUI_PRESET_SOFT` and `WHILEUI_PRESET_ATELIER`, go through `themePresetToCss` the same
+way.
 
-**Option A — Override in existing light/dark:** In your `@variant light` and `@variant dark` blocks, set surface tokens to semi-transparent values:
+Switch at runtime with `Uniwind.setTheme('dark')` (or `'light'`, `'system'`), or let
+`useThemeBridge` hold the choice. It returns the chosen `mode`, the `resolvedTheme` on
+screen, `setMode`, `toggleTheme` and `cycleMode`. A sun/moon button calls `toggleTheme`,
+which always flips what is on screen; `cycleMode` steps light → dark → system and suits
+a control that shows all three, because a step into `system` that resolves to the
+current theme looks like a dead tap. Pass an `adapter` to keep the choice across launches:
 
-```css
-@variant light {
-  /* ... other tokens ... */
-  --color-surface-elevated: oklch(0.98 0.01 95 / 0.4);
-  --color-surface-border: oklch(1 0 0 / 0.25);
-  --color-surface-highlight: oklch(1 0 0 / 0.4);
-}
+```tsx
+const { resolvedTheme, toggleTheme } = useThemeBridge({
+  adapter: {
+    loadThemeMode: () => storage.getItem('theme') as ThemeMode | null,
+    saveThemeMode: (mode) => storage.setItem('theme', mode),
+  },
+});
 ```
 
-**Option B — Separate frosted theme:** Register `extraThemes: ['frosted']` and define `:root.frosted` with the same structure as your base theme, but with translucent surface values. Then `Uniwind.setTheme('frosted')` when desired.
+A named extra theme is registered with `extraThemes: ['name']` in `metro.config.js` and
+defined with `@variant name`. The full token list, with each default, is in `theme-contract.ts`,
+and agents can read it from the MCP server's `get_theme_tokens`.
 
-**Optional:** Add `expo-blur` and register its `BlurView` once at app startup for full frosted blur. For tint-only (no blur), translucent surface tokens are sufficient.
+### Frosted surfaces
 
-**Android note:** frosted panels usually need denser tint than iOS/web. WhileUI now scales frosted tint alpha on Android with `--ui-frosted-android-tint-alpha-scale` (default `1.18`). Set it to `1` to match other platforms exactly, or raise it if your Android surfaces still feel washed out.
+Cards and overlays take `frosted`, `blurIntensity` and `blurTintToken`
+(`'surfaceElevated' | 'surfaceTranslucent' | 'card' | 'popover'`). Without a blur view
+they tint only; register `expo-blur` once for real blur:
 
 ```tsx
 import { BlurView } from 'expo-blur';
@@ -774,62 +665,40 @@ import { registerFrostedBlurView } from '@thewhileloop/whileui';
 registerFrostedBlurView(BlurView);
 ```
 
-Optional generic tokens: `surface-translucent`, `surface-translucent-border` — use them if you need a distinct token from `surface-elevated` for overlay panels.
-
-Built-in overlays and cards support opt-in frosted mode via:
-
-- `frosted?: boolean`
-- `blurIntensity?: number`
-- `blurTintToken?: 'surfaceElevated' | 'surfaceTranslucent' | 'card' | 'popover'`
-
-Default blur presets map to CSS visual tokens:
+For a frosted look across a whole theme, make `surface-elevated`, `surface-border` and
+`surface-highlight` translucent, in your light and dark variants or in a separate theme.
+The tuning tokens:
 
-- subtle: `--ui-blur-intensity-subtle` (default `18`)
-- medium: `--ui-blur-intensity-medium` (default `22`)
-- strong: `--ui-blur-intensity-strong` (default `28`)
+| Token                                                                     | Default      | Effect                                                         |
+| ------------------------------------------------------------------------- | ------------ | -------------------------------------------------------------- |
+| `--ui-blur-intensity-subtle` / `-medium` / `-strong`                      | 18 / 26 / 34 | The three blur presets                                         |
+| `--ui-frosted-android-tint-alpha-scale`                                   | 1.18         | Android needs denser tint; `1` matches iOS and web             |
+| `--ui-frosted-android-experimental-blur`                                  | 1            | Uses `expo-blur`'s experimental Android blur; `0` turns it off |
+| `--ui-frosted-highlight-height`                                           | 2            | Top sheen in px; `0` removes it                                |
+| `--ui-blur-saturation-pct`                                                | 145          | Web saturation multiplier                                      |
+| `--ui-frosted-backdrop-blur-intensity`, `-scale`                          | 22, 0.72     | Backdrop blur, and its ratio when a component overrides blur   |
+| `--ui-drawer-frosted-inset`, `-radius`, `--ui-drawer-content-top-padding` | 10, 34, 0    | Frosted drawer shell                                           |
 
-Additional frosted tuning tokens:
+### Colours for React Native APIs
 
-- `--ui-blur-saturation-pct` (web fallback saturation multiplier)
-- `--ui-frosted-highlight-height` (top highlight strip height in px, set `0` to disable hard top sheen)
-- `--ui-frosted-backdrop-blur-intensity` (default backdrop blur amount)
-- `--ui-frosted-backdrop-blur-scale` (ratio used when component blur is overridden)
-- `--ui-frosted-android-tint-alpha-scale` (Android-only alpha multiplier applied to frosted tint and backdrop layers)
-- `--ui-frosted-android-experimental-blur` (`1` enables `expo-blur` Android experimental path)
-- `--ui-drawer-frosted-inset` (floating inset for frosted drawer shells)
-- `--ui-drawer-frosted-radius` (drawer corner radius in px)
-- `--ui-drawer-content-top-padding` (drawer content top spacing baseline)
-
-### Theme Colors for RN Primitives
-
-Some React Native APIs require native color strings (hex/rgb/hsl/rgba/named). Use `useThemeColors` or `useIconColors` to read from your `global.css` theme. If your theme uses `oklch(...)`, add `--app-color-*` fallbacks — `useThemeColors` will use them when `--color-*` is not RN-native.
+Icons, `ActivityIndicator` and other native APIs need hex or rgb, not OKLCH.
+`useThemeColors()` returns the whole palette as React Native colours, falling back to the
+`--app-color-*` tokens a generated theme includes; `useIconColors()` is the subset icons
+use, with `muted` mapped to `mutedForeground`.
 
 ```tsx
-import { useThemeColors, useIconColors } from '@thewhileloop/whileui';
-import { Feather } from '@expo/vector-icons';
-
-// Full palette (core semantic colors + status + overlay/effect tokens)
-const colors = useThemeColors();
-
-// Shorthand for icons: foreground, muted, primary, primaryForeground, accent, destructive
-const iconColors = useIconColors();
-
-<Feather name="heart" size={20} color={iconColors.muted} />
-<Spinner color={colors.foreground} />  // Spinner defaults to this when color not passed
+const icons = useIconColors();
+<Feather name="heart" size={20} color={icons.muted} />;
 ```
 
-- **useThemeColors** / **useThemeTokens** — Returns RN-safe color strings (hex/rgb/rgba) for semantic tokens (`background`, `card`, `popover`, `primary`, `secondary`, `muted`, `accent`, `destructive`, status colors) plus effect tokens (`overlay`, `overlayStrong`, `surfaceElevated`, `surfaceTranslucent`, `surfaceTranslucentBorder`, etc.). Falls back to `--app-color-*` when `--color-*` is missing/non-RN-native.
-- **useIconColors** — Subset for icons. Maps `muted` → `mutedForeground` (readable on backgrounds).
-
-Input, Textarea, NumericInput, SmartInput, Spinner, and LoadingScreen default to theme colors when you omit `placeholderTextColor` or `spinnerColor`.
+Input, Textarea, NumericInput, SmartInput, Spinner and LoadingScreen pick theme colours
+when you omit `placeholderTextColor` or `spinnerColor`.
 
 ### Interaction and motion
 
 Press opacity, disabled opacity, motion durations, the responsive spring, and the drawer
 open and close durations are package constants on `INTERACTION_TOKENS`. They are not CSS
-variables and they do not change with a preset. Delete any `--ui-press-*`,
-`--ui-disabled-*`, `--ui-inactive-opacity`, `--ui-motion-*`, or `--ui-drawer-open-duration`
-/ `--ui-drawer-close-duration` declarations from a theme: nothing reads them.
+variables, so a theme does not change them.
 
 For a custom control, read that table:
 
@@ -853,118 +722,6 @@ motion.durations.normal;
 motion.springs.responsive;
 ```
 
-Optional RN fallback tokens (hex/rgb/hsl/named):
-
-```css
-@layer theme {
-  :root {
-    @variant light {
-      --app-color-primary: #000000;
-      --app-color-primary-foreground: #ffffff;
-      --app-color-foreground: #000000;
-      --app-color-background: #ffffff;
-      --app-color-card: #ffffff;
-      --app-color-card-foreground: #000000;
-      --app-color-popover: #ffffff;
-      --app-color-popover-foreground: #000000;
-      --app-color-secondary: #f5f5f5;
-      --app-color-secondary-foreground: #171717;
-      --app-color-muted: #f5f5f5;
-      --app-color-muted-foreground: #737373;
-      --app-color-border: #e5e5e5;
-      --app-color-input: #e5e5e5;
-      --app-color-ring: #94a3b8;
-      --app-color-accent: #22c55e;
-      --app-color-accent-foreground: #0a0a0a;
-      --app-color-destructive: #dc2626;
-      --app-color-destructive-foreground: #ffffff;
-      --app-color-success: #16a34a;
-      --app-color-success-foreground: #ffffff;
-      --app-color-warning: #f59e0b;
-      --app-color-warning-foreground: #111827;
-      --app-color-info: #3b82f6;
-      --app-color-info-foreground: #ffffff;
-      --app-color-overlay: rgba(0, 0, 0, 0.4);
-      --app-color-overlay-strong: rgba(0, 0, 0, 0.55);
-      --app-color-surface-elevated: #ffffff;
-      --app-color-surface-translucent: rgba(255, 255, 255, 0.5);
-      --app-color-surface-translucent-border: rgba(255, 255, 255, 0.18);
-      --app-color-surface-border: rgba(255, 255, 255, 0.3);
-      --app-color-surface-highlight: rgba(255, 255, 255, 0.3);
-      --app-color-state-hover: rgba(0, 0, 0, 0.05);
-      --app-color-state-pressed: rgba(0, 0, 0, 0.12);
-      --app-color-state-disabled: rgba(0, 0, 0, 0.4);
-    }
-    @variant dark {
-      --app-color-primary: #ffffff;
-      --app-color-primary-foreground: #000000;
-      --app-color-foreground: #ffffff;
-      --app-color-background: #000000;
-      --app-color-card: #0f0f10;
-      --app-color-card-foreground: #ffffff;
-      --app-color-popover: #121214;
-      --app-color-popover-foreground: #ffffff;
-      --app-color-secondary: #2e2e2e;
-      --app-color-secondary-foreground: #ffffff;
-      --app-color-muted: #2e2e2e;
-      --app-color-muted-foreground: #999999;
-      --app-color-border: #3d3d3d;
-      --app-color-input: #3d3d3d;
-      --app-color-ring: #7c889a;
-      --app-color-accent: #22c55e;
-      --app-color-accent-foreground: #0a0a0a;
-      --app-color-destructive: #dc2626;
-      --app-color-destructive-foreground: #ffffff;
-      --app-color-success: #22c55e;
-      --app-color-success-foreground: #0a0a0a;
-      --app-color-warning: #fbbf24;
-      --app-color-warning-foreground: #111827;
-      --app-color-info: #60a5fa;
-      --app-color-info-foreground: #111827;
-      --app-color-overlay: rgba(0, 0, 0, 0.5);
-      --app-color-overlay-strong: rgba(0, 0, 0, 0.7);
-      --app-color-surface-elevated: #111315;
-      --app-color-surface-translucent: rgba(17, 19, 21, 0.45);
-      --app-color-surface-translucent-border: rgba(255, 255, 255, 0.18);
-      --app-color-surface-border: rgba(255, 255, 255, 0.18);
-      --app-color-surface-highlight: rgba(255, 255, 255, 0.18);
-      --app-color-state-hover: rgba(255, 255, 255, 0.08);
-      --app-color-state-pressed: rgba(255, 255, 255, 0.15);
-      --app-color-state-disabled: rgba(255, 255, 255, 0.4);
-    }
-  }
-}
-```
-
-Or use the first-party theme bridge with optional persistence. The hook owns theme
-state and exposes event-driven setters:
-
-```tsx
-import { useThemeBridge, type ThemeBridgeAdapter } from '@thewhileloop/whileui';
-
-const adapter: ThemeBridgeAdapter = {
-  loadThemeMode: async () => 'system',
-  saveThemeMode: async (mode) => {
-    await storage.setItem('theme-mode', mode);
-  },
-};
-
-const { mode, resolvedTheme, setMode, cycleMode } = useThemeBridge({ adapter });
-```
-
-The bridge loads a new adapter before saving into it. If a user changes the mode while
-storage is still loading, that explicit choice wins over the late persisted value.
-
-When another store already owns the mode, mount the controlled bridge once near the
-application root. Change `mode` in the owning event handler; the bridge applies and
-persists it without mirroring state back through a callback effect.
-
-```tsx
-import { ThemeBridge } from '@thewhileloop/whileui';
-
-<ThemeBridge mode={mode} adapter={adapter} />;
-```
-
 ## Focus rings
 
 Every interactive component draws a themed focus ring on web. It uses `:focus-visible`,
@@ -992,14 +749,6 @@ supplies a themed replacement in the same class. The one exemption is a visually
 input, where a visible proxy shows the focus instead — `OTPInput` does this with its
 blinking cursor.
 
-## Tech Stack
-
-- **Styling**: [Uniwind](https://uniwind.dev) (free tier) + Tailwind CSS v4
-- **Variants**: [tailwind-variants](https://www.tailwind-variants.org/) (`tv()`)
-- **Merging**: [clsx](https://github.com/lukeed/clsx) + [tailwind-merge](https://github.com/dcastil/tailwind-merge)
-- **Expo**: SDK 54
-- **Monorepo**: bun + Turborepo
-
 # API Reference
 
 ## Pressable
@@ -1022,12 +771,17 @@ import { Pressable, Text } from '@thewhileloop/whileui';
 `style` contracts. Feedback changes opacity without changing layout. Native press state
 comes directly from React Native; web adds a motion-policy-aware opacity transition.
 
-| Prop             | Type                                        | Default     | Description                                |
-| ---------------- | ------------------------------------------- | ----------- | ------------------------------------------ |
-| feedback         | `'none' \| 'default' \| 'strong'`           | `'none'`    | Semantic pressed opacity                   |
-| disabledFeedback | `'none' \| 'default' \| 'soft' \| 'subtle'` | `'default'` | Semantic unavailable opacity               |
-| loading          | `boolean`                                   | `false`     | Expose busy/disabled state and block input |
-| className        | `string`                                    | —           | Additional Tailwind classes                |
+<!-- api:Pressable -->
+
+| Prop             | Type              | Default     | Description                                                                 |
+| ---------------- | ----------------- | ----------- | --------------------------------------------------------------------------- |
+| className        | `string`          | —           | Additional Tailwind classes.                                                |
+| feedback         | `PressedVariant`  | `'none'`    | Semantic press feedback. `none` preserves a plain React Native Pressable.   |
+| disabledFeedback | `DisabledVariant` | `'default'` | Opacity used while the control is unavailable.                              |
+| loading          | `boolean`         | `false`     | Loading controls are busy and non-interactive, just like disabled controls. |
+
+Also accepts the props of React Native's `PressableProps`.
+<!-- /api:Pressable -->
 
 ## Button
 
@@ -1046,13 +800,20 @@ import { Button, ButtonText, ButtonIcon } from '@thewhileloop/whileui';
 </Button>;
 ```
 
-| Prop      | Type                                                                          | Default     | Description                                        |
-| --------- | ----------------------------------------------------------------------------- | ----------- | -------------------------------------------------- |
-| variant   | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` | Button style variant                               |
-| size      | `'default' \| 'sm' \| 'lg' \| 'icon'`                                         | `'default'` | Button size                                        |
-| disabled  | `boolean`                                                                     | `false`     | Disable the button                                 |
-| loading   | `boolean`                                                                     | `false`     | Show a spinner, expose busy state, and block input |
-| className | `string`                                                                      | —           | Additional Tailwind classes                        |
+<!-- api:Button -->
+
+| Prop             | Type                                                                          | Default     | Description                                                             |
+| ---------------- | ----------------------------------------------------------------------------- | ----------- | ----------------------------------------------------------------------- |
+| children         | `React.ReactNode`                                                             | —           |                                                                         |
+| className        | `string`                                                                      | —           | Additional Tailwind classes.                                            |
+| disabled         | `boolean`                                                                     | `false`     | Disable the button.                                                     |
+| loading          | `boolean`                                                                     | `false`     | Shows a centered spinner, exposes busy state, and prevents interaction. |
+| disabledFeedback | `DisabledVariant`                                                             | —           | Opacity used while the control is unavailable.                          |
+| size             | `'sm' \| 'lg' \| 'default' \| 'icon'`                                         | `'default'` |                                                                         |
+| variant          | `'default' \| 'destructive' \| 'outline' \| 'secondary' \| 'ghost' \| 'link'` | `'default'` |                                                                         |
+
+Also accepts the props of `PressableProps`.
+<!-- /api:Button -->
 
 ## Text
 
@@ -1060,28 +821,51 @@ import { Button, ButtonText, ButtonIcon } from '@thewhileloop/whileui';
 classes are unnecessary for normal hierarchy. `heading` also sets
 `accessibilityRole="header"` unless the caller supplies another role.
 
-| Prop    | Type                                                                                                       | Default     |
-| ------- | ---------------------------------------------------------------------------------------------------------- | ----------- |
-| variant | `'default' \| 'heading' \| 'title' \| 'subtitle' \| 'body' \| 'caption' \| 'label' \| 'eyebrow' \| 'code'` | `'default'` |
-| size    | `'xs' \| 'sm' \| 'base' \| 'lg' \| 'xl' \| '2xl' \| '3xl'`                                                 | by variant  |
+<!-- api:Text -->
+
+| Prop      | Type                                                                                                       | Default     | Description |
+| --------- | ---------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
+| className | `string`                                                                                                   | —           |             |
+| size      | `'base' \| 'xs' \| 'sm' \| 'lg' \| 'xl' \| '2xl' \| '3xl'`                                                 | —           |             |
+| variant   | `'default' \| 'heading' \| 'title' \| 'subtitle' \| 'body' \| 'caption' \| 'label' \| 'eyebrow' \| 'code'` | `'default'` |             |
+
+Also accepts the props of React Native's `TextProps`.
+<!-- /api:Text -->
 
 ## Input
 
 ```tsx
-import { Input } from '@thewhileloop/whileui';
+import { Input, useIconColors } from '@thewhileloop/whileui';
+import { Feather } from '@expo/vector-icons';
+
+const icons = useIconColors();
 
 <Input placeholder="Email" variant="default" value={value} onChangeText={setValue} />;
+
+<Input
+  placeholder="Search"
+  prefix={<Feather name="search" size={16} color={icons.muted} aria-hidden />}
+/>;
 ```
 
-On web, filled Input, Textarea, NumericInput, and SmartInput surfaces preserve their
-themed background, foreground, and caret when the browser autofills them.
+On iOS and Android, Input, Textarea, NumericInput and SmartInput draw the caret and
+selection in the theme's primary colour; pass `selectionColor` (and `cursorColor` on
+Android) to override it. On web, filled surfaces keep their themed background,
+foreground and caret when the browser autofills them.
 
-| Prop                 | Type                              | Default     | Description                                                           |
-| -------------------- | --------------------------------- | ----------- | --------------------------------------------------------------------- |
-| variant              | `'default' \| 'error' \| 'plain'` | `'default'` | Input style; `plain` drops border and fill for a large display figure |
-| placeholder          | `string`                          | —           | Placeholder text                                                      |
-| placeholderTextColor | `string`                          | —           | Hex for placeholder; defaults to theme `mutedForeground`              |
-| editable             | `boolean`                         | `true`      | Whether input is editable                                             |
+<!-- api:Input -->
+
+| Prop           | Type                              | Default     | Description                                                                                                                                          |
+| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| aria-invalid   | `boolean`                         | —           |                                                                                                                                                      |
+| className      | `string`                          | —           |                                                                                                                                                      |
+| prefix         | `React.ReactNode`                 | —           | Shown before the text. A decorative icon here needs `aria-hidden`; screen readers otherwise stop on it as a separate element and read out its glyph. |
+| suffix         | `React.ReactNode`                 | —           | Shown after the text: a unit, or a control such as a clear button.                                                                                   |
+| inputClassName | `string`                          | —           |                                                                                                                                                      |
+| variant        | `'default' \| 'error' \| 'plain'` | `'default'` |                                                                                                                                                      |
+
+Also accepts the props of `TextInputProps`.
+<!-- /api:Input -->
 
 ## NumericInput
 
@@ -1100,15 +884,28 @@ import { NumericInput } from '@thewhileloop/whileui';
 />;
 ```
 
-| Prop                 | Type                              | Default     | Description                       |
-| -------------------- | --------------------------------- | ----------- | --------------------------------- |
-| variant              | `'default' \| 'error'`            | `'default'` | Input style                       |
-| size                 | `'default' \| 'compact'`          | `'default'` | Density size                      |
-| value                | `number \| null`                  | —           | Controlled numeric value          |
-| onValueChange        | `(value: number \| null) => void` | —           | Numeric value change callback     |
-| placeholderTextColor | `string`                          | —           | Hex for placeholder               |
-| prefix / suffix      | `ReactNode`                       | —           | Left/right slots                  |
-| showSteppers         | `boolean`                         | `false`     | Show decrement/increment controls |
+<!-- api:NumericInput -->
+
+| Prop           | Type                              | Default     | Description                                                                                                            |
+| -------------- | --------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| aria-invalid   | `boolean`                         | —           |                                                                                                                        |
+| className      | `string`                          | —           |                                                                                                                        |
+| inputClassName | `string`                          | —           |                                                                                                                        |
+| prefix         | `React.ReactNode`                 | —           |                                                                                                                        |
+| suffix         | `React.ReactNode`                 | —           |                                                                                                                        |
+| value          | `number \| null`                  | —           | Controlled numeric value.                                                                                              |
+| defaultValue   | `number`                          | —           |                                                                                                                        |
+| onValueChange  | `(value: number \| null) => void` | —           | Numeric value change callback.                                                                                         |
+| min            | `number`                          | —           |                                                                                                                        |
+| max            | `number`                          | —           |                                                                                                                        |
+| step           | `number`                          | `1`         |                                                                                                                        |
+| showSteppers   | `boolean`                         | `false`     | Show decrement/increment controls.                                                                                     |
+| unstyled       | `boolean`                         | `false`     | Drop the field shell (border, background, radius, padding) for embedding inside another field shell like LabeledField. |
+| size           | `'default' \| 'compact'`          | `'default'` |                                                                                                                        |
+| variant        | `'default' \| 'error'`            | `'default'` |                                                                                                                        |
+
+Also accepts the props of `TextInputProps`.
+<!-- /api:NumericInput -->
 
 ## OTPInput
 
@@ -1124,16 +921,23 @@ import { OTPInput } from '@thewhileloop/whileui';
 />;
 ```
 
-| Prop          | Type                      | Default     | Description                       |
-| ------------- | ------------------------- | ----------- | --------------------------------- |
-| length        | `number`                  | `6`         | Number of digit cells             |
-| value         | `string`                  | —           | Controlled value                  |
-| onValueChange | `(value: string) => void` | —           | Called on each digit change       |
-| onComplete    | `(code: string) => void`  | —           | Called when all digits are filled |
-| variant       | `'default' \| 'error'`    | `'default'` | Error variant triggers shake      |
-| size          | `'default' \| 'compact'`  | `'default'` | Cell size                         |
-| secure        | `boolean`                 | `false`     | Mask digits with dots             |
-| autoFocus     | `boolean`                 | `false`     | Focus first cell on mount         |
+<!-- api:OTPInput -->
+
+| Prop          | Type                      | Default     | Description                        |
+| ------------- | ------------------------- | ----------- | ---------------------------------- |
+| length        | `number`                  | `6`         | Number of digit cells.             |
+| value         | `string`                  | —           | Controlled value.                  |
+| onValueChange | `(value: string) => void` | —           | Called on each digit change.       |
+| onComplete    | `(code: string) => void`  | —           | Called when all digits are filled. |
+| variant       | `'default' \| 'error'`    | `'default'` | Error variant triggers shake.      |
+| size          | `'default' \| 'compact'`  | `'default'` | Cell size.                         |
+| secure        | `boolean`                 | `false`     | Mask digits with dots.             |
+| disabled      | `boolean`                 | `false`     |                                    |
+| autoFocus     | `boolean`                 | `false`     | Focus first cell on mount.         |
+| className     | `string`                  | —           |                                    |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:OTPInput -->
 
 ## FormField
 
@@ -1161,6 +965,10 @@ import {
 custom controls; labels, hints, messages, density, and required indicators remain part
 of the compound field rather than each input.
 
+`FormLabel` names the `Input`, `Textarea` or `NumericInput` beside it for assistive
+technology (`aria-labelledby` on web and Android; `useFormFieldState().labelId` gives a
+custom control the same id). A label passed to the control itself wins.
+
 ## Surface
 
 ```tsx
@@ -1171,14 +979,22 @@ import { Surface } from '@thewhileloop/whileui';
 </Surface>;
 ```
 
-| Prop     | Type                                  | Default     | Description                         |
-| -------- | ------------------------------------- | ----------- | ----------------------------------- |
-| level    | `'base' \| 'raised' \| 'overlay'`     | `'base'`    | Semantic background and depth tier  |
-| padding  | `'none' \| 'sm' \| 'default' \| 'lg'` | `'default'` | Token-backed interior spacing       |
-| radius   | `'sm' \| 'md' \| 'lg' \| 'xl'`        | `'xl'`      | Token-backed corner radius          |
-| bordered | `boolean`                             | `true`      | Draw the theme hairline border      |
-| shadow   | `'none' \| 'sm' \| 'md' \| 'lg'`      | by level    | Override the level's depth          |
-| frosted  | `boolean`                             | `false`     | Enable the optional frosted overlay |
+<!-- api:Surface -->
+
+| Prop          | Type                           | Default             | Description                          |
+| ------------- | ------------------------------ | ------------------- | ------------------------------------ |
+| level         | `SurfaceLevel`                 | `'base'`            | Semantic background and depth tier.  |
+| padding       | `SurfacePaddingSize`           | `'default'`         | Token-backed interior spacing.       |
+| radius        | `'sm' \| 'md' \| 'lg' \| 'xl'` | `'xl'`              | Token-backed corner radius.          |
+| bordered      | `boolean`                      | `true`              | Draw the theme hairline border.      |
+| shadow        | `ShadowTier`                   | —                   | Override the level's depth.          |
+| className     | `string`                       | —                   |                                      |
+| frosted       | `boolean`                      | `false`             | Enable the optional frosted overlay. |
+| blurIntensity | `number`                       | subtle preset       | Override blur amount directly.       |
+| blurTintToken | `FrostedTintToken`             | `LEVEL_TINT[level]` | Tint token used for frosted mode.    |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Surface -->
 
 ## LabeledField
 
@@ -1220,9 +1036,24 @@ import {
 </SegmentedControl>;
 ```
 
-| Prop    | Type                  | Default     | Description               |
-| ------- | --------------------- | ----------- | ------------------------- |
-| variant | `'default' \| 'pill'` | `'default'` | Pill = rounded-full items |
+When the labels do not fit a phone, `wrap="scroll"` keeps them on one row at full width
+and scrolls sideways, instead of wrapping or truncating them.
+
+<!-- api:SegmentedControl -->
+
+| Prop          | Type                            | Default     | Description                                                                                                                                                                                                                                                                |
+| ------------- | ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| value         | `string`                        | —           |                                                                                                                                                                                                                                                                            |
+| defaultValue  | `string`                        | `''`        |                                                                                                                                                                                                                                                                            |
+| onValueChange | `(value: string) => void`       | —           |                                                                                                                                                                                                                                                                            |
+| variant       | `'default' \| 'pill'`           | `'default'` | Pill = rounded-full items.                                                                                                                                                                                                                                                 |
+| wrap          | `boolean \| 'auto' \| 'scroll'` | `'auto'`    | `true` wraps segments onto more rows; `false` keeps one row and shares its width. `'scroll'` keeps one row with each segment as wide as its label and scrolls sideways when they do not fit — for labels a phone cannot show in full. `'auto'` wraps above three segments. |
+| size          | `'default' \| 'compact'`        | `'default'` |                                                                                                                                                                                                                                                                            |
+| disabled      | `boolean`                       | `false`     |                                                                                                                                                                                                                                                                            |
+| className     | `string`                        | —           |                                                                                                                                                                                                                                                                            |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:SegmentedControl -->
 
 ## DataRow
 
@@ -1281,13 +1112,20 @@ import {
 </Card>;
 ```
 
-| Prop          | Type                                                               | Default      | Description                         |
-| ------------- | ------------------------------------------------------------------ | ------------ | ----------------------------------- |
-| padding       | `'none' \| 'sm' \| 'default' \| 'lg'`                              | `'default'`  | Card interior padding               |
-| unstyled      | `boolean`                                                          | `false`      | Remove built-in card surface styles |
-| frosted       | `boolean`                                                          | `false`      | Enables frosted tint + blur layer   |
-| blurIntensity | `number`                                                           | token preset | Override blur amount directly       |
-| blurTintToken | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | `'card'`     | Tint token used for frosted mode    |
+<!-- api:Card -->
+
+| Prop          | Type                                  | Default     | Description                                             |
+| ------------- | ------------------------------------- | ----------- | ------------------------------------------------------- |
+| shadow        | `ShadowTier`                          | `'sm'`      | Elevation tier; 'sm' by default, 'none' for flat cards. |
+| className     | `string`                              | —           |                                                         |
+| padding       | `'none' \| 'sm' \| 'lg' \| 'default'` | `'default'` |                                                         |
+| unstyled      | `boolean`                             | `false`     |                                                         |
+| frosted       | `boolean`                             | `false`     | Enable the optional frosted overlay.                    |
+| blurIntensity | `number`                              | —           | Override blur amount directly.                          |
+| blurTintToken | `FrostedTintToken`                    | —           | Tint token used for frosted mode.                       |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Card -->
 
 ## Badge
 
@@ -1299,9 +1137,15 @@ import { Badge, BadgeText } from '@thewhileloop/whileui';
 </Badge>;
 ```
 
-| Prop    | Type                                                                                         | Default     |
-| ------- | -------------------------------------------------------------------------------------------- | ----------- |
-| variant | `'default' \| 'secondary' \| 'destructive' \| 'outline' \| 'success' \| 'warning' \| 'info'` | `'default'` |
+<!-- api:Badge -->
+
+| Prop      | Type                                                                                                                                                                                                | Default     | Description |
+| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ----------- |
+| className | `string`                                                                                                                                                                                            | —           |             |
+| variant   | `'default' \| 'soft' \| 'destructive' \| 'outline' \| 'secondary' \| 'success' \| 'warning' \| 'info' \| 'soft-secondary' \| 'soft-destructive' \| 'soft-success' \| 'soft-warning' \| 'soft-info'` | `'default'` |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Badge -->
 
 ## Alert
 
@@ -1312,11 +1156,24 @@ import { Alert, AlertTitle, AlertDescription } from '@thewhileloop/whileui';
   <AlertTitle>Heads up!</AlertTitle>
   <AlertDescription>Something happened.</AlertDescription>
 </Alert>;
+
+// Shown after a failed submit: also spoken on iOS when it appears.
+<Alert variant="destructive" announce>
+  <AlertTitle>Could not save</AlertTitle>
+  <AlertDescription>Check your connection and try again.</AlertDescription>
+</Alert>;
 ```
 
-| Prop    | Type                                                   | Default     |
-| ------- | ------------------------------------------------------ | ----------- |
-| variant | `'default' \| 'destructive' \| 'success' \| 'warning'` | `'default'` |
+<!-- api:Alert -->
+
+| Prop      | Type                                                             | Default     | Description                                                                                                                                                                                                                                                                                                        |
+| --------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 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. |
+| className | `string`                                                         | —           |                                                                                                                                                                                                                                                                                                                    |
+| variant   | `'default' \| 'destructive' \| 'success' \| 'warning' \| 'info'` | `'default'` |                                                                                                                                                                                                                                                                                                                    |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Alert -->
 
 ## Dialog
 
@@ -1357,11 +1214,17 @@ import {
 
 `DialogContent` supports frosted props:
 
-| Prop          | Type                                                               | Default                | Description                      |
-| ------------- | ------------------------------------------------------------------ | ---------------------- | -------------------------------- |
-| frosted       | `boolean`                                                          | `false`                | Enables frosted tint + blur      |
-| blurIntensity | `number`                                                           | medium preset          | Override blur amount             |
-| blurTintToken | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | `'surfaceTranslucent'` | Tint token used for frosted mode |
+<!-- api:DialogContent -->
+
+| Prop          | Type               | Default                | Description                          |
+| ------------- | ------------------ | ---------------------- | ------------------------------------ |
+| className     | `string`           | —                      |                                      |
+| frosted       | `boolean`          | `false`                | Enable the optional frosted overlay. |
+| blurIntensity | `number`           | medium preset          | Override blur amount directly.       |
+| blurTintToken | `FrostedTintToken` | `'surfaceTranslucent'` | Tint token used for frosted mode.    |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:DialogContent -->
 
 ## AlertDialog
 
@@ -1399,12 +1262,18 @@ import {
 
 `AlertDialogContent` supports the same frosted props as `DialogContent`.
 
-| Prop          | Type                               | Default   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ------------- | ---------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| presentation  | `'modal' \| 'native' \| 'overlay'` | `'modal'` | **`modal`** — themed card in an RN `Modal` (iOS `overFullScreen`). **`native`** — `Alert.alert` on iOS/Android (system UI); use when a second `Modal` won’t stack; ignored on web. **`overlay`** — same themed card as `modal`, but absolutely positioned **inside the parent view** (no second `Modal`). Nest `<AlertDialog>` under your fullscreen sheet’s root so the confirm matches app styling. **Web:** `'native'` is ignored; `overlay` behaves like `modal`. |
-| frosted       | `boolean`                          | `false`   | Same as `DialogContent`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| blurIntensity | `number`                           | —         | Same as `DialogContent`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| blurTintToken | `'surfaceElevated' \| …`           | —         | Same as `DialogContent`                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+<!-- api:AlertDialogContent -->
+
+| Prop          | Type                      | Default                | Description                                                                                                                                                                                                                          |
+| ------------- | ------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| className     | `string`                  | —                      |                                                                                                                                                                                                                                      |
+| 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`). |
+| frosted       | `boolean`                 | `false`                | Enable the optional frosted overlay.                                                                                                                                                                                                 |
+| blurIntensity | `number`                  | medium preset          | Override blur amount directly.                                                                                                                                                                                                       |
+| blurTintToken | `FrostedTintToken`        | `'surfaceTranslucent'` | Tint token used for frosted mode.                                                                                                                                                                                                    |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:AlertDialogContent -->
 
 ### React Native: stacked modals
 
@@ -1423,11 +1292,18 @@ import { Checkbox } from '@thewhileloop/whileui';
 <Checkbox checked={checked} onCheckedChange={setChecked} />;
 ```
 
-| Prop            | Type                         | Default |
-| --------------- | ---------------------------- | ------- |
-| checked         | `boolean`                    | `false` |
-| onCheckedChange | `(checked: boolean) => void` | —       |
-| disabled        | `boolean`                    | `false` |
+<!-- api:Checkbox -->
+
+| Prop            | Type                         | Default | Description |
+| --------------- | ---------------------------- | ------- | ----------- |
+| checked         | `boolean`                    | —       |             |
+| defaultChecked  | `boolean`                    | `false` |             |
+| onCheckedChange | `(checked: boolean) => void` | —       |             |
+| disabled        | `boolean`                    | `false` |             |
+| className       | `string`                     | —       |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Checkbox -->
 
 ## Switch
 
@@ -1437,10 +1313,18 @@ import { Switch } from '@thewhileloop/whileui';
 <Switch checked={checked} onCheckedChange={setChecked} />;
 ```
 
-| Prop            | Type                         | Default |
-| --------------- | ---------------------------- | ------- |
-| checked         | `boolean`                    | `false` |
-| onCheckedChange | `(checked: boolean) => void` | —       |
+<!-- api:Switch -->
+
+| Prop            | Type                         | Default | Description |
+| --------------- | ---------------------------- | ------- | ----------- |
+| checked         | `boolean`                    | —       |             |
+| defaultChecked  | `boolean`                    | `false` |             |
+| onCheckedChange | `(checked: boolean) => void` | —       |             |
+| disabled        | `boolean`                    | `false` |             |
+| className       | `string`                     | —       |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Switch -->
 
 ## RadioGroup
 
@@ -1481,13 +1365,25 @@ selected values stay on one line and truncate without displacing the trigger che
 For popover presentation on web, the options panel matches the trigger width, caps
 itself to the collision-available viewport, and wraps long option labels inside it.
 
+Opening a Select, or a Popover, closes the on-screen keyboard first, so options opened
+from a form are never hidden behind it. Both draw in a portal, where the platform would
+otherwise leave the keyboard up; the Modal-hosted overlays close it on their own.
+
 `SelectContent` supports optional frosted props:
 
-| Prop          | Type                                                               | Default       |
-| ------------- | ------------------------------------------------------------------ | ------------- |
-| frosted       | `boolean`                                                          | `false`       |
-| blurIntensity | `number`                                                           | subtle preset |
-| blurTintToken | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | `'popover'`   |
+<!-- api:SelectContent -->
+
+| Prop          | Type                                                               | Default       | Description                          |
+| ------------- | ------------------------------------------------------------------ | ------------- | ------------------------------------ |
+| className     | `string`                                                           | —             |                                      |
+| portalHost    | `string`                                                           | —             |                                      |
+| insets        | `{ top?: number; bottom?: number; left?: number; right?: number }` | —             |                                      |
+| frosted       | `boolean`                                                          | `false`       | Enable the optional frosted overlay. |
+| blurIntensity | `number`                                                           | subtle preset | Override blur amount directly.       |
+| blurTintToken | `FrostedTintToken`                                                 | `'popover'`   | Tint token used for frosted mode.    |
+
+Also accepts the props of the underlying primitive.
+<!-- /api:SelectContent -->
 
 `SelectContent` keeps its listbox inside the safe area by default; pass `insets` only to
 change that margin. A list taller than the screen scrolls inside the listbox on every
@@ -1536,10 +1432,17 @@ import {
 </Accordion>;
 ```
 
-| Prop        | Type                     | Default    |
-| ----------- | ------------------------ | ---------- |
-| type        | `'single' \| 'multiple'` | `'single'` |
-| collapsible | `boolean`                | `false`    |
+<!-- api:Accordion -->
+
+| Prop         | Type                 | Default    | Description |
+| ------------ | -------------------- | ---------- | ----------- |
+| type         | `AccordionType`      | `'single'` |             |
+| defaultValue | `string \| string[]` | —          |             |
+| collapsible  | `boolean`            | `true`     |             |
+| className    | `string`             | —          |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Accordion -->
 
 ## Avatar
 
@@ -1552,9 +1455,15 @@ import { Avatar, AvatarImage, AvatarFallback } from '@thewhileloop/whileui';
 </Avatar>;
 ```
 
-| Prop | Type                        | Default     |
-| ---- | --------------------------- | ----------- |
-| size | `'sm' \| 'default' \| 'lg'` | `'default'` |
+<!-- api:Avatar -->
+
+| Prop      | Type                                | Default     | Description |
+| --------- | ----------------------------------- | ----------- | ----------- |
+| className | `string`                            | —           |             |
+| size      | `'sm' \| 'lg' \| 'xl' \| 'default'` | `'default'` |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Avatar -->
 
 `AvatarImage` keeps `AvatarFallback` visible while loading or after an error. Its
 `onLoadingStatusChange` callback reports `'loading'`, `'loaded'`, and `'error'`, including
@@ -1568,10 +1477,17 @@ import { Progress } from '@thewhileloop/whileui';
 <Progress value={50} size="default" />;
 ```
 
-| Prop  | Type                        | Default     |
-| ----- | --------------------------- | ----------- |
-| value | `number`                    | `0`         |
-| size  | `'sm' \| 'default' \| 'lg'` | `'default'` |
+<!-- api:Progress -->
+
+| Prop               | Type                        | Default     | Description |
+| ------------------ | --------------------------- | ----------- | ----------- |
+| value              | `number`                    | `0`         |             |
+| indicatorClassName | `string`                    | —           |             |
+| className          | `string`                    | —           |             |
+| size               | `'sm' \| 'lg' \| 'default'` | `'default'` |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Progress -->
 
 ## Toast
 
@@ -1599,6 +1515,11 @@ toast({ title: 'Success', description: 'Saved!', variant: 'success' });
 Each toast owns its duration from the moment it appears; adding or dismissing another
 toast does not restart timers already in progress.
 
+Every variant sits on the theme's `popover` surface; `success` and `destructive` mark the
+toast with a status dot and tinted border rather than a solid fill. The stack is capped
+at `max-w-md` and centred, which never engages on a phone. A toast is announced politely
+to screen readers without taking focus, and its slide-in follows the motion policy.
+
 ## Popover
 
 ```tsx
@@ -1618,11 +1539,19 @@ import { Popover, PopoverTrigger, PopoverContent } from '@thewhileloop/whileui';
 
 `PopoverContent` supports frosted props:
 
-| Prop          | Type                                                               | Default       |
-| ------------- | ------------------------------------------------------------------ | ------------- |
-| frosted       | `boolean`                                                          | `false`       |
-| blurIntensity | `number`                                                           | subtle preset |
-| blurTintToken | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | `'popover'`   |
+<!-- api:PopoverContent -->
+
+| Prop          | Type                     | Default       | Description                                                                                           |
+| ------------- | ------------------------ | ------------- | ----------------------------------------------------------------------------------------------------- |
+| className     | `string`                 | —             |                                                                                                       |
+| portalHost    | `string`                 | —             |                                                                                                       |
+| insets        | `Partial<OverlayInsets>` | —             | Collision padding. Defaults to safe area plus a margin so the panel never sits flush against an edge. |
+| frosted       | `boolean`                | `false`       | Enable the optional frosted overlay.                                                                  |
+| blurIntensity | `number`                 | subtle preset | Override blur amount directly.                                                                        |
+| blurTintToken | `FrostedTintToken`       | `'popover'`   | Tint token used for frosted mode.                                                                     |
+
+Also accepts the props of the underlying primitive.
+<!-- /api:PopoverContent -->
 
 ## DropdownMenu
 
@@ -1710,7 +1639,7 @@ announces as a heading to assistive technology — as do `DropdownMenuLabel` and
 ## SignInForm
 
 Copy `sign-in-form.tsx` and its sibling `auth-form-footer.tsx` from
-`apps/showcase/templates/auth/`, then:
+`apps/showcase/catalog/templates/auth/`, then:
 
 ```tsx
 import { SignInForm } from './templates/auth'; // or your path
@@ -1735,7 +1664,7 @@ import { SignInForm } from './templates/auth'; // or your path
 ## SignUpForm
 
 Copy `sign-up-form.tsx` and its sibling `auth-form-footer.tsx` from
-`apps/showcase/templates/auth/`, then:
+`apps/showcase/catalog/templates/auth/`, then:
 
 ```tsx
 import { SignUpForm } from './templates/auth'; // or your path
@@ -1789,14 +1718,20 @@ import { AppShell, PageSkeleton } from '@thewhileloop/whileui';
 </AppShell>;
 ```
 
-| Prop        | Type        | Default | Description                                         |
-| ----------- | ----------- | ------- | --------------------------------------------------- |
-| `header`    | `ReactNode` | —       | Header slot                                         |
-| `footer`    | `ReactNode` | —       | Footer slot                                         |
-| `bottomNav` | `ReactNode` | —       | Bottom navigation slot                              |
-| `safeArea`  | `boolean`   | `true`  | Wrap in SafeAreaView                                |
-| `loading`   | `boolean`   | `false` | Show `skeleton` in content area, keep shell mounted |
-| `skeleton`  | `ReactNode` | —       | Content placeholder rendered when `loading=true`    |
+<!-- api:AppShell -->
+
+| Prop      | Type              | Default | Description                                               |
+| --------- | ----------------- | ------- | --------------------------------------------------------- |
+| header    | `React.ReactNode` | —       | Header slot.                                              |
+| footer    | `React.ReactNode` | —       | Footer slot.                                              |
+| bottomNav | `React.ReactNode` | —       | Bottom navigation slot.                                   |
+| safeArea  | `boolean`         | `true`  | Wrap in SafeAreaView.                                     |
+| loading   | `boolean`         | `false` | Keep shell mounted while swapping content with skeleton.  |
+| skeleton  | `React.ReactNode` | —       | Optional custom loading placeholder for the content area. |
+| className | `string`          | —       |                                                           |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:AppShell -->
 
 ## ActionBar
 
@@ -1840,7 +1775,7 @@ import { SmartInput, Button, ButtonText } from '@thewhileloop/whileui';
   onChangeText={setMessage}
   placeholderExamples={['Log breakfast', 'Add a 30 minute walk', 'Set weight to 72 kg']}
   leftSlot={
-    <Button variant="ghost" size="icon">
+    <Button variant="ghost" size="icon" accessibilityLabel="Add">
       <Icon name="add" />
     </Button>
   }
@@ -1897,24 +1832,37 @@ const [value, setValue] = useState('');
   onSuggestionPress={(text) => setValue(text)}
   emptyTitle="How can I help?"
   emptyDescription="Ask anything."
-  leftSlot={<Button variant="ghost" size="icon"><Icon name="paperclip" /></Button>}
-  rightSlot={<Button size="icon" onPress={handleSend}><Icon name="send" /></Button>}
+  leftSlot={<Button variant="ghost" size="icon" accessibilityLabel="Attach"><Icon name="paperclip" /></Button>}
+  rightSlot={<Button size="icon" accessibilityLabel="Send" onPress={handleSend}><Icon name="send" /></Button>}
 />;
 ```
 
-| Prop                     | Type                 | Description                                       |
-| ------------------------ | -------------------- | ------------------------------------------------- |
-| `messages`               | `ChatMessage[]`      | `{ id, role, content, secondary?, contentSize? }` |
-| `value`                  | `string`             | Input value                                       |
-| `onChangeText`           | `(text) => void`     | Input change                                      |
-| `onSend`                 | `() => void`         | Send handler                                      |
-| `suggestions`            | `string[]`           | Chips when empty                                  |
-| `leftSlot` / `rightSlot` | `ReactNode`          | Attach, send, etc.                                |
-| `exampleMessage`         | `ChatMessage`        | Shown in empty state                              |
-| `renderMessage`          | `(msg) => ReactNode` | Custom message (markdown, code, images)           |
-| `loadingIndicator`       | `ReactNode`          | Shown when loading (typing dots)                  |
-| `inputSafeArea`          | `boolean`            | SmartInput safe-area (default `true`)             |
-| `keyboardVerticalOffset` | `number`             | For header offset when keyboard opens             |
+<!-- api:Chat -->
+
+| Prop                    | Type                                        | Default             | Description                                                                              |
+| ----------------------- | ------------------------------------------- | ------------------- | ---------------------------------------------------------------------------------------- |
+| messages (required)     | `ChatMessage[]`                             | —                   | Messages to show, each `{ id, role, content, secondary?, contentSize? }`.                |
+| value (required)        | `string`                                    | —                   | Input value.                                                                             |
+| onChangeText (required) | `(text: string) => void`                    | —                   | Input change.                                                                            |
+| onSend (required)       | `() => void`                                | —                   | Send handler.                                                                            |
+| placeholder             | `string`                                    | `'Message...'`      |                                                                                          |
+| suggestions             | `string[]`                                  | `EMPTY_SUGGESTIONS` | Chips when empty.                                                                        |
+| onSuggestionPress       | `(text: string) => void`                    | —                   |                                                                                          |
+| leftSlot                | `React.ReactNode`                           | —                   |                                                                                          |
+| rightSlot               | `React.ReactNode`                           | —                   |                                                                                          |
+| loading                 | `boolean`                                   | `false`             |                                                                                          |
+| header                  | `React.ReactNode`                           | —                   |                                                                                          |
+| emptyTitle              | `string`                                    | —                   |                                                                                          |
+| emptyDescription        | `string`                                    | —                   |                                                                                          |
+| exampleMessage          | `ChatMessage`                               | —                   | Example message shown in empty state so users see the bubble UI.                         |
+| renderMessage           | `(message: ChatMessage) => React.ReactNode` | —                   | Custom message renderer (markdown, code, images). Falls back to ChatMessageBubble.       |
+| loadingIndicator        | `React.ReactNode`                           | —                   | Shown at bottom when loading (typing indicator).                                         |
+| inputSafeArea           | `boolean`                                   | `true`              | Passed to SmartInput. Use false when Chat is in a contained demo.                        |
+| keyboardVerticalOffset  | `number`                                    | `0`                 | Offset for KeyboardAvoidingView when Chat has a header (e.g. StatusBar + header height). |
+| className               | `string`                                    | —                   |                                                                                          |
+| messagesClassName       | `string`                                    | —                   |                                                                                          |
+
+<!-- /api:Chat -->
 
 `ChatConversation` extends React Native `ScrollViewProps`, forwards its ref, and adds `contentContainerClassName` to style the constrained inner column. Caller `onScroll` and `onContentSizeChange` callbacks are preserved.
 
@@ -1949,18 +1897,24 @@ import { SmartImage } from '@thewhileloop/whileui';
 />;
 ```
 
-| Prop                | Type                                               | Default   |
-| ------------------- | -------------------------------------------------- | --------- |
-| `source`            | `ImageProps['source']`                             | required  |
-| `alt`               | `string`                                           | required  |
-| `fallbackSource`    | `ImageProps['source']`                             | —         |
-| `skeleton`          | `boolean`                                          | `true`    |
-| `skeletonClassName` | `string`                                           | —         |
-| `transition`        | `number`                                           | `200`     |
-| `radius`            | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`    |
-| `objectFit`         | `'cover' \| 'contain' \| 'fill' \| 'scale-down'`   | `'cover'` |
-| `onLoad`            | `() => void`                                       | —         |
-| `onError`           | `() => void`                                       | —         |
+<!-- api:SmartImage -->
+
+| Prop              | Type                                               | Default   | Description |
+| ----------------- | -------------------------------------------------- | --------- | ----------- |
+| className         | `string`                                           | —         |             |
+| source (required) | `ImageProps['source']`                             | —         |             |
+| alt (required)    | `string`                                           | —         |             |
+| skeleton          | `boolean`                                          | `true`    |             |
+| skeletonClassName | `string`                                           | —         |             |
+| transition        | `number`                                           | `200`     |             |
+| onLoad            | `() => void`                                       | —         |             |
+| onError           | `() => void`                                       | —         |             |
+| fallbackSource    | `ImageProps['source']`                             | —         |             |
+| radius            | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'md'`    |             |
+| objectFit         | `'fill' \| 'cover' \| 'contain' \| 'scale-down'`   | `'cover'` |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:SmartImage -->
 
 The skeleton returns whenever the primary image starts loading again. A failed primary
 source switches to `fallbackSource` when supplied without re-entering a primary/fallback
@@ -2030,19 +1984,26 @@ const [time, setTime] = useState<string | null>(null);
 />;
 ```
 
-| Prop                    | Type                                                               | Description                            |
-| ----------------------- | ------------------------------------------------------------------ | -------------------------------------- |
-| `value`                 | `string \| null` / `DateRange \| null`                             | Selected date(s) YYYY-MM-DD            |
-| `onValueChange`         | `(date) => void`                                                   | Change handler                         |
-| `open` / `onOpenChange` | —                                                                  | Modal state (modal variants)           |
-| `trigger`               | `ReactNode`                                                        | Custom trigger (modal variants)        |
-| `minDate` / `maxDate`   | `string`                                                           | YYYY-MM-DD bounds                      |
-| `theme`                 | `CalendarTheme`                                                    | Override calendar colors               |
-| `hourCycle`             | `'h12' \| 'h23'`                                                   | Time picker wheels; defaults to locale |
-| `minuteStep`            | `number`                                                           | Minutes between options (default 1)    |
-| `frosted`               | `boolean`                                                          | Enable frosted surface for modal panel |
-| `blurIntensity`         | `number`                                                           | Override blur amount                   |
-| `blurTintToken`         | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | Tint token for frosted panel           |
+<!-- api:DatePickerModal -->
+
+| Prop                    | Type                             | Default                | Description                                               |
+| ----------------------- | -------------------------------- | ---------------------- | --------------------------------------------------------- |
+| value                   | `string \| null`                 | —                      | Controlled: selected date in YYYY-MM-DD                   |
+| onValueChange           | `(date: string \| null) => void` | —                      | Controlled: change handler                                |
+| open (required)         | `boolean`                        | —                      | Modal open state                                          |
+| onOpenChange (required) | `(open: boolean) => void`        | —                      | Modal open change handler                                 |
+| minDate                 | `string`                         | —                      | Minimum selectable date YYYY-MM-DD                        |
+| maxDate                 | `string`                         | —                      | Maximum selectable date YYYY-MM-DD                        |
+| theme                   | `CalendarTheme`                  | —                      | Override calendar theme (RN color strings)                |
+| trigger                 | `React.ReactNode`                | —                      | Trigger element. If not provided, no trigger is rendered. |
+| title                   | `string`                         | `'Select date'`        | Title shown in modal header                               |
+| confirmLabel            | `string`                         | `'Done'`               | Button label for confirm                                  |
+| className               | `string`                         | —                      |                                                           |
+| frosted                 | `boolean`                        | `false`                | Enable the optional frosted overlay.                      |
+| blurIntensity           | `number`                         | medium preset          | Override blur amount directly.                            |
+| blurTintToken           | `FrostedTintToken`               | `'surfaceTranslucent'` | Tint token used for frosted mode.                         |
+
+<!-- /api:DatePickerModal -->
 
 ## ConfirmActionSheet
 
@@ -2060,11 +2021,27 @@ import { ConfirmActionSheet } from '@thewhileloop/whileui';
 />;
 ```
 
-| Prop            | Type                                                               | Default                |
-| --------------- | ------------------------------------------------------------------ | ---------------------- |
-| `frosted`       | `boolean`                                                          | `false`                |
-| `blurIntensity` | `number`                                                           | medium preset          |
-| `blurTintToken` | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | `'surfaceTranslucent'` |
+<!-- api:ConfirmActionSheet -->
+
+| Prop                    | Type                         | Default                | Description                          |
+| ----------------------- | ---------------------------- | ---------------------- | ------------------------------------ |
+| open (required)         | `boolean`                    | —                      |                                      |
+| onOpenChange (required) | `(open: boolean) => void`    | —                      |                                      |
+| title (required)        | `string`                     | —                      |                                      |
+| description             | `string`                     | —                      |                                      |
+| actions                 | `ConfirmActionSheetAction[]` | —                      |                                      |
+| confirmLabel            | `string`                     | `'Confirm'`            |                                      |
+| cancelLabel             | `string`                     | `'Cancel'`             |                                      |
+| onConfirm               | `() => void`                 | —                      |                                      |
+| onCancel                | `() => void`                 | —                      |                                      |
+| destructive             | `boolean`                    | `true`                 |                                      |
+| className               | `string`                     | —                      |                                      |
+| frosted                 | `boolean`                    | `false`                | Enable the optional frosted overlay. |
+| blurIntensity           | `number`                     | medium preset          | Override blur amount directly.       |
+| blurTintToken           | `FrostedTintToken`           | `'surfaceTranslucent'` | Tint token used for frosted mode.    |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:ConfirmActionSheet -->
 
 ## Sheet
 
@@ -2094,15 +2071,20 @@ import {
 </Sheet>;
 ```
 
-| Prop          | Type                                                               | Default                |
-| ------------- | ------------------------------------------------------------------ | ---------------------- |
-| open          | `boolean`                                                          | —                      |
-| onOpenChange  | `(open: boolean) => void`                                          | —                      |
-| maxHeight     | `'half' \| 'full' \| number`                                       | `'full'`               |
-| maxWidth      | `number`                                                           | `360`                  |
-| frosted       | `boolean`                                                          | `false`                |
-| blurIntensity | `number`                                                           | medium preset          |
-| blurTintToken | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | `'surfaceTranslucent'` |
+<!-- api:Sheet -->
+
+| Prop                    | Type                         | Default                | Description                                                 |
+| ----------------------- | ---------------------------- | ---------------------- | ----------------------------------------------------------- |
+| open (required)         | `boolean`                    | —                      |                                                             |
+| onOpenChange (required) | `(open: boolean) => void`    | —                      |                                                             |
+| children (required)     | `React.ReactNode`            | —                      |                                                             |
+| maxHeight               | `'half' \| 'full' \| number` | `'full'`               | Max height: 'half' \| 'full' \| number (px). Default 'full' |
+| maxWidth                | `number`                     | —                      | Web: max width. Default ~360 for mobile-first.              |
+| frosted                 | `boolean`                    | `false`                | Enable the optional frosted overlay.                        |
+| blurIntensity           | `number`                     | medium preset          | Override blur amount directly.                              |
+| blurTintToken           | `FrostedTintToken`           | `'surfaceTranslucent'` | Tint token used for frosted mode.                           |
+
+<!-- /api:Sheet -->
 
 `SheetContent` is a `ScrollView` and accepts its props. It enables nested scrolling and
 keeps taps on inputs while the keyboard is open (`keyboardShouldPersistTaps="handled"`).
@@ -2143,11 +2125,22 @@ import { SplashScreen } from '@thewhileloop/whileui';
 />;
 ```
 
-| Prop        | Type                           | Default   |
-| ----------- | ------------------------------ | --------- |
-| variant     | `'fade' \| 'scale' \| 'slide'` | `'scale'` |
-| duration    | `number`                       | `800`     |
-| showLoading | `boolean`                      | `false`   |
+<!-- api:SplashScreen -->
+
+| Prop                | Type                           | Default   | Description                                     |
+| ------------------- | ------------------------------ | --------- | ----------------------------------------------- |
+| appName             | `string`                       | —         | App name displayed below logo                   |
+| tagline             | `string`                       | —         | Tagline displayed below app name                |
+| logo                | `React.ReactNode`              | —         | Logo element (icon, image, or custom component) |
+| variant             | `'fade' \| 'scale' \| 'slide'` | `'scale'` | Animation variant                               |
+| duration            | `number`                       | `800`     | Animation duration in ms                        |
+| onAnimationComplete | `() => void`                   | —         | Callback when animation completes               |
+| showLoading         | `boolean`                      | `false`   | Whether to show loading indicator               |
+| loadingText         | `string`                       | —         | Loading text                                    |
+| className           | `string`                       | —         |                                                 |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:SplashScreen -->
 
 ## ContentSkeleton
 
@@ -2161,10 +2154,16 @@ import { ContentSkeleton } from '@thewhileloop/whileui';
 <ContentSkeleton variant="generic" />
 ```
 
-| Prop    | Type                            | Default  | Description                             |
-| ------- | ------------------------------- | -------- | --------------------------------------- |
-| variant | `'list' \| 'card' \| 'generic'` | `'list'` | Layout preset                           |
-| rows    | `number`                        | `4`      | Number of list rows (list variant only) |
+<!-- api:ContentSkeleton -->
+
+| Prop      | Type                            | Default  | Description                                                                                                |
+| --------- | ------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------- |
+| variant   | `'list' \| 'card' \| 'generic'` | `'list'` | Layout preset. `list` = avatar + lines rows, `card` = card with image/body, `generic` = simple page lines. |
+| rows      | `number`                        | `4`      | Number of list rows (list variant only). Default 4.                                                        |
+| className | `string`                        | —        |                                                                                                            |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:ContentSkeleton -->
 
 ## PageSkeleton
 
@@ -2183,14 +2182,19 @@ import { PageSkeleton } from '@thewhileloop/whileui';
 <PageSkeleton variant="list" padding="none" className="flex-1" />
 ```
 
-| Prop                | Type                                                         | Default                | Description                                   |
-| ------------------- | ------------------------------------------------------------ | ---------------------- | --------------------------------------------- |
-| `variant`           | `'dashboard' \| 'list' \| 'settings' \| 'card' \| 'generic'` | required               | Layout preset                                 |
-| `count`             | `number`                                                     | 3 (list), 4 (settings) | Rows/items for list or settings variant       |
-| `padding`           | `'none' \| 'sm' \| 'default' \| 'lg'`                        | `'default'`            | Container padding                             |
-| `header`            | `ReactNode`                                                  | —                      | Optional real header slot above content       |
-| `headerPlaceholder` | `boolean \| 'compact' \| 'default'`                          | `false`                | Skeleton header when real header is not ready |
-| `className`         | `string`                                                     | —                      | Outer container classes                       |
+<!-- api:PageSkeleton -->
+
+| Prop               | Type                                       | Default     | Description                                                         |
+| ------------------ | ------------------------------------------ | ----------- | ------------------------------------------------------------------- |
+| variant (required) | `PageSkeletonVariant`                      | —           | Layout preset.                                                      |
+| count              | `number`                                   | `3`         | Rows/items for list (default 3) or settings (default 4) variant.    |
+| padding            | `PageSkeletonPadding`                      | `'default'` | Container padding.                                                  |
+| header             | `ReactNode`                                | —           | Optional header slot rendered above skeleton content.               |
+| headerPlaceholder  | `boolean \| PageSkeletonHeaderPlaceholder` | `false`     | Optional placeholder header (when no real header is available yet). |
+| className          | `string`                                   | —           |                                                                     |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:PageSkeleton -->
 
 ## ScreenSkeleton
 
@@ -2203,13 +2207,19 @@ import { ScreenSkeleton } from '@thewhileloop/whileui';
 <ScreenSkeleton variant="list" count={5} header={<Header title="Projects" />} />
 ```
 
-| Prop                | Type                                | Default     | Description                           |
-| ------------------- | ----------------------------------- | ----------- | ------------------------------------- |
-| `variant`           | `PageSkeletonVariant`               | `'generic'` | Skeleton content preset               |
-| `count`             | `number`                            | —           | Rows/items for list/settings variants |
-| `padding`           | `PageSkeletonPadding`               | `'default'` | Inner content padding                 |
-| `header`            | `ReactNode`                         | —           | Real header slot                      |
-| `headerPlaceholder` | `boolean \| 'compact' \| 'default'` | `'default'` | Placeholder header                    |
+<!-- api:ScreenSkeleton -->
+
+| Prop              | Type                                       | Default     | Description                            |
+| ----------------- | ------------------------------------------ | ----------- | -------------------------------------- |
+| variant           | `PageSkeletonVariant`                      | `'generic'` | Skeleton content preset.               |
+| count             | `number`                                   | —           | Rows/items for list/settings variants. |
+| padding           | `PageSkeletonPadding`                      | `'default'` | Inner content padding.                 |
+| header            | `ReactNode`                                | —           | Real header slot.                      |
+| headerPlaceholder | `boolean \| PageSkeletonHeaderPlaceholder` | `'default'` | Placeholder header.                    |
+| className         | `string`                                   | —           |                                        |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:ScreenSkeleton -->
 
 ## ErrorBoundary
 
@@ -2223,10 +2233,15 @@ import { ErrorBoundary } from '@thewhileloop/whileui';
 </ErrorBoundary>;
 ```
 
-| Prop     | Type                                       | Description                             |
-| -------- | ------------------------------------------ | --------------------------------------- |
-| fallback | `ReactNode \| (error, reset) => ReactNode` | Custom fallback; defaults to ErrorState |
-| onError  | `(error, errorInfo) => void`               | Called when error is caught             |
+<!-- api:ErrorBoundary -->
+
+| Prop                | Type                                                            | Default | Description                                        |
+| ------------------- | --------------------------------------------------------------- | ------- | -------------------------------------------------- |
+| children (required) | `ReactNode`                                                     | —       |                                                    |
+| fallback            | `ReactNode \| ((error: Error, reset: () => void) => ReactNode)` | —       | Custom fallback. If not provided, uses ErrorState. |
+| onError             | `(error: Error, errorInfo: ErrorInfo) => void`                  | —       | Called when error is caught.                       |
+
+<!-- /api:ErrorBoundary -->
 
 ## PullToRefreshScrollView
 
@@ -2240,11 +2255,17 @@ import { PullToRefreshScrollView } from '@thewhileloop/whileui';
 </PullToRefreshScrollView>;
 ```
 
-| Prop         | Type                          | Description                                                                                                     |
-| ------------ | ----------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| refreshing   | `boolean`                     | Whether refresh is in progress                                                                                  |
-| onRefresh    | `() => void \| Promise<void>` | Called when user pulls to refresh. Not awaited — drive the spinner with `refreshing`, and catch your own errors |
-| refreshColor | `string`                      | Optional hex override; defaults to primary                                                                      |
+<!-- api:PullToRefreshScrollView -->
+
+| Prop                  | Type                          | Default | Description                                                                                                                                                                                                     |
+| --------------------- | ----------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| refreshing (required) | `boolean`                     | —       | Whether refresh is in progress.                                                                                                                                                                                 |
+| 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. |
+| refreshColor          | `string`                      | —       | Override tint/colors. Defaults to theme primary.                                                                                                                                                                |
+| className             | `string`                      | —       |                                                                                                                                                                                                                 |
+
+Also accepts the props of `ScrollViewProps`.
+<!-- /api:PullToRefreshScrollView -->
 
 The scroll view owns the refresh gesture; don't pass `refreshControl`. It bounces even
 when content is shorter than the screen, so a short list can still be pulled. Screen
@@ -2276,14 +2297,20 @@ import { LoadingState } from '@thewhileloop/whileui';
 The in-flow counterpart of `EmptyState` and `ErrorState` for a section that is still
 fetching. The spinner is named for assistive technology by `label` (default "Loading").
 
-| Prop  | Type                        | Default     |
-| ----- | --------------------------- | ----------- |
-| label | `string`                    | `'Loading'` |
-| size  | `'sm' \| 'default' \| 'lg'` | `'default'` |
+<!-- api:LoadingState -->
+
+| Prop      | Type                        | Default     | Description                                                                    |
+| --------- | --------------------------- | ----------- | ------------------------------------------------------------------------------ |
+| label     | `string`                    | —           | Read by assistive technology as the spinner's name; shown under it when given. |
+| size      | `'sm' \| 'default' \| 'lg'` | `'default'` |                                                                                |
+| className | `string`                    | —           |                                                                                |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:LoadingState -->
 
 ## ProfileHeader
 
-Copy from `apps/showcase/templates/profile/profile-header.tsx`, then:
+Copy from `apps/showcase/catalog/templates/profile/profile-header.tsx`, then:
 
 ```tsx
 import { ProfileHeader } from './templates/profile'; // or your path
@@ -2305,7 +2332,7 @@ import { ProfileHeader } from './templates/profile'; // or your path
 
 ## SettingsSection / SettingsItem
 
-Copy from `apps/showcase/templates/profile/`, then:
+Copy from `apps/showcase/catalog/templates/profile/`, then:
 
 ```tsx
 import { SettingsSection, SettingsItem } from './templates/profile'; // or your path
@@ -2340,10 +2367,25 @@ import { ProductCard } from '@thewhileloop/whileui';
 />;
 ```
 
-| Prop    | Type                         | Default      |
-| ------- | ---------------------------- | ------------ |
-| variant | `'vertical' \| 'horizontal'` | `'vertical'` |
-| loading | `boolean`                    | `false`      |
+<!-- api:ProductCard -->
+
+| Prop             | Type                         | Default      | Description                                     |
+| ---------------- | ---------------------------- | ------------ | ----------------------------------------------- |
+| imageUrl         | `string`                     | —            |                                                 |
+| title (required) | `string`                     | —            |                                                 |
+| description      | `string`                     | —            |                                                 |
+| price (required) | `string`                     | —            |                                                 |
+| originalPrice    | `string`                     | —            |                                                 |
+| badge            | `string`                     | —            |                                                 |
+| rating           | `number`                     | —            |                                                 |
+| reviewCount      | `number`                     | —            |                                                 |
+| inStock          | `boolean`                    | `true`       |                                                 |
+| variant          | `'vertical' \| 'horizontal'` | `'vertical'` |                                                 |
+| loading          | `boolean`                    | `false`      | Show a skeleton placeholder instead of content. |
+| className        | `string`                     | —            |                                                 |
+
+Also accepts the props of `PressableProps`.
+<!-- /api:ProductCard -->
 
 ## PricingCard
 
@@ -2382,16 +2424,24 @@ import { SubscriptionCard } from '@thewhileloop/whileui';
 />;
 ```
 
-| Prop        | Type         | Description                 |
-| ----------- | ------------ | --------------------------- |
-| `planName`  | `string`     | Current plan label          |
-| `price`     | `string`     | Plan price                  |
-| `period`    | `string`     | Billing period label        |
-| `expiresAt` | `string`     | Renewal/expiry date text    |
-| `isActive`  | `boolean`    | Active/inactive badge state |
-| `onManage`  | `() => void` | Manage action               |
-| `onUpgrade` | `() => void` | Upgrade action              |
-| `loading`   | `boolean`    | Show skeleton placeholder   |
+<!-- api:SubscriptionCard -->
+
+| Prop                | Type         | Default         | Description                                     |
+| ------------------- | ------------ | --------------- | ----------------------------------------------- |
+| planName (required) | `string`     | —               | Current plan label.                             |
+| price (required)    | `string`     | —               | Plan price.                                     |
+| period              | `string`     | `'/month'`      | Billing period label.                           |
+| expiresAt           | `string`     | —               | Renewal/expiry date text.                       |
+| isActive            | `boolean`    | `true`          | Active/inactive badge state.                    |
+| onManage            | `() => void` | —               | Manage action.                                  |
+| onUpgrade           | `() => void` | —               | Upgrade action.                                 |
+| manageLabel         | `string`     | `'Manage plan'` |                                                 |
+| upgradeLabel        | `string`     | `'Upgrade'`     |                                                 |
+| loading             | `boolean`    | `false`         | Show a skeleton placeholder instead of content. |
+| className           | `string`     | —               |                                                 |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:SubscriptionCard -->
 
 ## FeatureGate
 
@@ -2416,12 +2466,18 @@ import { UsageBar } from '@thewhileloop/whileui';
 <UsageBar label="AI generations" used={8} limit={20} />;
 ```
 
-| Prop      | Type                                   | Default | Description                    |
-| --------- | -------------------------------------- | ------- | ------------------------------ |
-| `label`   | `string`                               | —       | Usage label                    |
-| `used`    | `number`                               | —       | Used amount                    |
-| `limit`   | `number`                               | —       | Quota limit                    |
-| `variant` | `'default' \| 'warning' \| 'exceeded'` | auto    | Optional explicit visual state |
+<!-- api:UsageBar -->
+
+| Prop             | Type              | Default | Description                     |
+| ---------------- | ----------------- | ------- | ------------------------------- |
+| label (required) | `string`          | —       | Usage label.                    |
+| used (required)  | `number`          | —       | Used amount.                    |
+| limit (required) | `number`          | —       | Quota limit.                    |
+| variant          | `UsageBarVariant` | —       | Optional explicit visual state. |
+| className        | `string`          | —       |                                 |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:UsageBar -->
 
 ## PlanToggle
 
@@ -2474,48 +2530,600 @@ import { DrawerMenu } from '@thewhileloop/whileui';
 />;
 ```
 
-| Prop            | Type                                                               | Default                |
-| --------------- | ------------------------------------------------------------------ | ---------------------- |
-| `frosted`       | `boolean`                                                          | `false`                |
-| `blurIntensity` | `number`                                                           | medium preset          |
-| `blurTintToken` | `'surfaceElevated' \| 'surfaceTranslucent' \| 'card' \| 'popover'` | `'surfaceTranslucent'` |
+<!-- api:DrawerMenu -->
+
+| Prop                | Type                    | Default                | Description                                                 |
+| ------------------- | ----------------------- | ---------------------- | ----------------------------------------------------------- |
+| visible (required)  | `boolean`               | —                      |                                                             |
+| onClose (required)  | `() => void`            | —                      |                                                             |
+| sections (required) | `DrawerMenuSection[]`   | —                      |                                                             |
+| activeKey           | `string`                | —                      |                                                             |
+| onSelect            | `(key: string) => void` | —                      |                                                             |
+| header              | `React.ReactNode`       | —                      |                                                             |
+| footer              | `React.ReactNode`       | —                      |                                                             |
+| maxWidth            | `number`                | —                      | Max width in px. On web, defaults to 360 when not provided. |
+| className           | `string`                | —                      |                                                             |
+| style               | `StyleProp<ViewStyle>`  | —                      |                                                             |
+| frosted             | `boolean`               | `false`                | Enable the optional frosted overlay.                        |
+| blurIntensity       | `number`                | medium preset          | Override blur amount directly.                              |
+| blurTintToken       | `FrostedTintToken`      | `'surfaceTranslucent'` | Tint token used for frosted mode.                           |
+
+<!-- /api:DrawerMenu -->
 
 Closes from the backdrop, an item, Android back or Escape on web. It is hosted in a modal
 on every platform, so keyboard focus stays inside it while it is open.
 
-## Roadmap
+## More components
+
+The rest of the catalog: what each is for and the props its type declares.
+
+### View
+
+Themed view wrapper
+
+```tsx
+import { View } from '@thewhileloop/whileui';
+```
+
+<!-- api:View -->
+
+| Prop      | Type     | Default | Description |
+| --------- | -------- | ------- | ----------- |
+| className | `string` | —       |             |
+
+Also accepts the props of React Native's `ViewProps`.
+<!-- /api:View -->
+
+### Stack
+
+Vertical flex layout with gap
+
+```tsx
+import { Stack } from '@thewhileloop/whileui';
+```
+
+<!-- api:Stack -->
+
+| Prop      | Type                                                                | Default     | Description |
+| --------- | ------------------------------------------------------------------- | ----------- | ----------- |
+| className | `string`                                                            | —           |             |
+| gap       | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'`           | `'md'`      |             |
+| align     | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'`           | `'stretch'` |             |
+| justify   | `'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'` | `'start'`   |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Stack -->
+
+### MotionProvider
+
+System reduced motion, explicit preview modes, and deterministic testing
+
+```tsx
+import { MotionProvider } from '@thewhileloop/whileui';
+```
+
+<!-- api:MotionProvider -->
+
+| Prop                | Type              | Default    | Description |
+| ------------------- | ----------------- | ---------- | ----------- |
+| children (required) | `React.ReactNode` | —          |             |
+| mode                | `MotionMode`      | `'system'` |             |
+
+<!-- /api:MotionProvider -->
+
+### Textarea
+
+Multi-line text input
 
-Tracked work items for future releases.
+```tsx
+import { Textarea } from '@thewhileloop/whileui';
+```
+
+<!-- api:Textarea -->
+
+| Prop         | Type                        | Default     | Description |
+| ------------ | --------------------------- | ----------- | ----------- |
+| aria-invalid | `boolean`                   | —           |             |
+| className    | `string`                    | —           |             |
+| size         | `'sm' \| 'lg' \| 'default'` | `'default'` |             |
+
+Also accepts the props of `TextInputProps`.
+<!-- /api:Textarea -->
+
+### Label
+
+Form field label
+
+```tsx
+import { Label } from '@thewhileloop/whileui';
+```
+
+<!-- api:Label -->
+
+| Prop      | Type     | Default | Description |
+| --------- | -------- | ------- | ----------- |
+| className | `string` | —       |             |
+
+Also accepts the props of `TextProps`.
+<!-- /api:Label -->
+
+### Toggle
+
+ToggleText sub-component
+
+```tsx
+import { Toggle } from '@thewhileloop/whileui';
+```
+
+<!-- api:Toggle -->
+
+| Prop            | Type                                             | Default     | Description |
+| --------------- | ------------------------------------------------ | ----------- | ----------- |
+| pressed         | `boolean`                                        | `false`     |             |
+| defaultPressed  | `boolean`                                        | `false`     |             |
+| onPressedChange | `(pressed: boolean) => void`                     | —           |             |
+| variant         | `VariantProps<typeof toggleVariants>['variant']` | `'default'` |             |
+| size            | `VariantProps<typeof toggleVariants>['size']`    | `'default'` |             |
+| className       | `string`                                         | —           |             |
+| children        | `React.ReactNode`                                | —           |             |
+
+Also accepts the props of `PressableProps`.
+<!-- /api:Toggle -->
+
+### ToggleGroup
+
+Group of toggle items
+
+```tsx
+import { ToggleGroup } from '@thewhileloop/whileui';
+```
+
+<!-- api:ToggleGroup -->
+
+| Prop          | Type                                  | Default     | Description |
+| ------------- | ------------------------------------- | ----------- | ----------- |
+| type          | `ToggleGroupType`                     | `'single'`  |             |
+| defaultValue  | `string \| string[]`                  | —           |             |
+| value         | `string \| string[]`                  | —           |             |
+| onValueChange | `(value: string \| string[]) => void` | —           |             |
+| variant       | `'default' \| 'outline'`              | `'default'` |             |
+| size          | `'default' \| 'sm' \| 'lg'`           | `'default'` |             |
+| className     | `string`                              | —           |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:ToggleGroup -->
+
+### Separator
+
+Themed divider
+
+```tsx
+import { Separator } from '@thewhileloop/whileui';
+```
+
+<!-- api:Separator -->
+
+| Prop        | Type                         | Default        | Description |
+| ----------- | ---------------------------- | -------------- | ----------- |
+| orientation | `'horizontal' \| 'vertical'` | `'horizontal'` |             |
+| className   | `string`                     | —              |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Separator -->
+
+### Spinner
+
+ActivityIndicator wrapper
+
+```tsx
+import { Spinner } from '@thewhileloop/whileui';
+```
+
+<!-- api:Spinner -->
+
+| Prop      | Type                        | Default     | Description |
+| --------- | --------------------------- | ----------- | ----------- |
+| className | `string`                    | —           |             |
+| size      | `'sm' \| 'lg' \| 'default'` | `'default'` |             |
+
+Also accepts the props of `ActivityIndicatorProps`.
+<!-- /api:Spinner -->
+
+### Skeleton
+
+Loading placeholder (pulse = opacity fade, shimmer = sweep)
+
+```tsx
+import { Skeleton } from '@thewhileloop/whileui';
+```
+
+<!-- api:Skeleton -->
+
+| Prop      | Type                   | Default   | Description |
+| --------- | ---------------------- | --------- | ----------- |
+| className | `string`               | —         |             |
+| variant   | `'pulse' \| 'shimmer'` | `'pulse'` |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Skeleton -->
+
+### AspectRatio
+
+Maintain aspect ratio container
+
+```tsx
+import { AspectRatio } from '@thewhileloop/whileui';
+```
+
+<!-- api:AspectRatio -->
+
+| Prop      | Type     | Default | Description |
+| --------- | -------- | ------- | ----------- |
+| ratio     | `number` | `1`     |             |
+| className | `string` | —       |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:AspectRatio -->
+
+### Collapsible
+
+CollapsibleTrigger, CollapsibleContent
+
+```tsx
+import { Collapsible } from '@thewhileloop/whileui';
+```
+
+<!-- api:Collapsible -->
+
+| Prop         | Type                      | Default | Description |
+| ------------ | ------------------------- | ------- | ----------- |
+| defaultOpen  | `boolean`                 | `false` |             |
+| open         | `boolean`                 | —       |             |
+| onOpenChange | `(open: boolean) => void` | —       |             |
+| disabled     | `boolean`                 | `false` |             |
+| className    | `string`                  | —       |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:Collapsible -->
+
+### Tooltip
+
+Position-aware tooltip (requires PortalHost)
+
+```tsx
+import { Tooltip } from '@thewhileloop/whileui';
+```
+
+<!-- api:Tooltip -->
+
+| Prop                    | Type                      | Default | Description |
+| ----------------------- | ------------------------- | ------- | ----------- |
+| onOpenChange            | `(open: boolean) => void` | —       |             |
+| delayDuration           | `number`                  | —       |             |
+| skipDelayDuration       | `number`                  | —       |             |
+| disableHoverableContent | `boolean`                 | —       |             |
+| children (required)     | `React.ReactNode`         | —       |             |
+
+<!-- /api:Tooltip -->
+
+### FloatingBottomNav
+
+Elevated bottom nav with safe area support
+
+```tsx
+import { FloatingBottomNav } from '@thewhileloop/whileui';
+```
+
+<!-- api:FloatingBottomNav -->
+
+| Prop                 | Type                      | Default | Description |
+| -------------------- | ------------------------- | ------- | ----------- |
+| items (required)     | `FloatingBottomNavItem[]` | —       |             |
+| activeKey (required) | `string`                  | —       |             |
+| onSelect (required)  | `(key: string) => void`   | —       |             |
+| className            | `string`                  | —       |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:FloatingBottomNav -->
+
+### TabBar
+
+Top tab bar with indicator
+
+```tsx
+import { TabBar } from '@thewhileloop/whileui';
+```
+
+<!-- api:TabBar -->
 
-### New Components
+| Prop                 | Type                                  | Default     | Description |
+| -------------------- | ------------------------------------- | ----------- | ----------- |
+| items (required)     | `TabBarItem[]`                        | —           |             |
+| activeKey (required) | `string`                              | —           |             |
+| onSelect (required)  | `(key: string) => void`               | —           |             |
+| variant              | `'default' \| 'pills' \| 'underline'` | `'default'` |             |
+| scrollable           | `boolean`                             | `false`     |             |
+| className            | `string`                              | —           |             |
 
-- [ ] **Chip / Tag** — selectable, dismissible, multi-select with `tv()` variants, loading skeleton
-- [ ] **Rating / Stars** — interactive + read-only, half-star precision, swipe gesture, pairs with ProductCard
-- [ ] **Slider** — single + range (two thumbs), step marks, labels, Reanimated gesture, haptic on snap
-- [ ] **Carousel** — Reanimated-powered, auto-play, pagination dots, snap-to-item
-- [ ] **FAB (Floating Action Button)** — expandable action menu, Reanimated spring, auto-hide on scroll
-- [ ] **Combobox** — searchable select with keyboard navigation, empty state, async loading
-- [ ] **Data Table** — sortable headers, skeleton loading rows, row actions, responsive stacking
-- [ ] **Banner** — dismissible info/warning/success/destructive bar with icon + action, auto-dismiss timer
-- [ ] **Pagination** — compact (dots) + expanded (numbers) variants, edge-aware ellipsis, 44px touch targets
-- [ ] **Inline Calendar** — standalone calendar view reusing DatePicker logic, range selection
+Also accepts the props of `ViewProps`.
+<!-- /api:TabBar -->
 
-### Component-Level Loading (`loading` prop)
+### FormModalScreen
 
-- [x] ProductCard, ListItem, NotificationItem, MetricCard, SubscriptionCard, PricingCard
-- [x] AppShell, Chat, FormModalScreen, CheckoutSummary (already had `loading`)
-- [ ] Add `loading` to remaining blocks: Header, BottomNav, DrawerMenu, TimelineFeed
+Modal scaffold for forms with loading states
 
-### Documentation Gaps
+```tsx
+import { FormModalScreen } from '@thewhileloop/whileui';
+```
+
+<!-- api:FormModalScreen -->
+
+| Prop                | Type              | Default       | Description                                                                               |
+| ------------------- | ----------------- | ------------- | ----------------------------------------------------------------------------------------- |
+| className           | `string`          | —             |                                                                                           |
+| title (required)    | `string`          | —             |                                                                                           |
+| subtitle            | `string`          | —             |                                                                                           |
+| leftSlot            | `React.ReactNode` | —             |                                                                                           |
+| rightSlot           | `React.ReactNode` | —             |                                                                                           |
+| onClose             | `() => void`      | —             |                                                                                           |
+| loading             | `boolean`         | `false`       |                                                                                           |
+| saving              | `boolean`         | `false`       |                                                                                           |
+| savingText          | `string`          | `'Saving...'` |                                                                                           |
+| loadingSpinnerColor | `string`          | —             | Hex color for spinner in loading state. ActivityIndicator requires hex.                   |
+| savingSpinnerColor  | `string`          | —             | Hex color for spinner in saving banner. Defaults to platform (Android blue) when not set. |
+| scrollEnabled       | `boolean`         | `true`        |                                                                                           |
+| children (required) | `React.ReactNode` | —             |                                                                                           |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:FormModalScreen -->
+
+### ErrorState
+
+Error display with retry
+
+```tsx
+import { ErrorState } from '@thewhileloop/whileui';
+```
+
+<!-- api:ErrorState -->
+
+| Prop        | Type              | Default                  | Description |
+| ----------- | ----------------- | ------------------------ | ----------- |
+| icon        | `React.ReactNode` | —                        |             |
+| title       | `string`          | `'Something went wrong'` |             |
+| description | `string`          | —                        |             |
+| error       | `Error \| string` | —                        |             |
+| onRetry     | `() => void`      | —                        |             |
+| retryLabel  | `string`          | `'Try again'`            |             |
+| className   | `string`          | —                        |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:ErrorState -->
+
+### LoadingScreen
+
+Full-screen loading indicator
+
+```tsx
+import { LoadingScreen } from '@thewhileloop/whileui';
+```
+
+<!-- api:LoadingScreen -->
+
+| Prop         | Type                   | Default | Description                                            |
+| ------------ | ---------------------- | ------- | ------------------------------------------------------ |
+| message      | `string`               | —       |                                                        |
+| size         | `'sm' \| 'md' \| 'lg'` | `'md'`  |                                                        |
+| spinnerColor | `string`               | —       | Hex color for spinner. ActivityIndicator requires hex. |
+| className    | `string`               | —       |                                                        |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:LoadingScreen -->
+
+### MinimalSplash
+
+Minimal monochrome splash
+
+```tsx
+import { MinimalSplash } from '@thewhileloop/whileui';
+```
+
+<!-- api:MinimalSplash -->
+
+| Prop                | Type              | Default | Description                                     |
+| ------------------- | ----------------- | ------- | ----------------------------------------------- |
+| className           | `string`          | —       |                                                 |
+| appName             | `string`          | —       | App name displayed below logo                   |
+| tagline             | `string`          | —       | Tagline displayed below app name                |
+| logo                | `React.ReactNode` | —       | Logo element (icon, image, or custom component) |
+| duration            | `number`          | `800`   | Animation duration in ms                        |
+| onAnimationComplete | `() => void`      | —       | Callback when animation completes               |
+| showLoading         | `boolean`         | `false` | Whether to show loading indicator               |
+| loadingText         | `string`          | —       | Loading text                                    |
+
+Also accepts the props of `SplashScreenProps`.
+<!-- /api:MinimalSplash -->
+
+### BrandedSplash
+
+Splash with brand imagery
+
+```tsx
+import { BrandedSplash } from '@thewhileloop/whileui';
+```
+
+<!-- api:BrandedSplash -->
+
+| Prop                | Type              | Default | Description                                     |
+| ------------------- | ----------------- | ------- | ----------------------------------------------- |
+| className           | `string`          | —       |                                                 |
+| appName             | `string`          | —       | App name displayed below logo                   |
+| tagline             | `string`          | —       | Tagline displayed below app name                |
+| logo                | `React.ReactNode` | —       | Logo element (icon, image, or custom component) |
+| duration            | `number`          | `800`   | Animation duration in ms                        |
+| onAnimationComplete | `() => void`      | —       | Callback when animation completes               |
+| loadingText         | `string`          | —       | Loading text                                    |
+
+Also accepts the props of `SplashScreenProps`.
+<!-- /api:BrandedSplash -->
+
+### ChatMessageBubble
+
+One message in a `Chat`, rendered on its own when a screen composes the conversation itself.
+
+```tsx
+import { ChatMessageBubble } from '@thewhileloop/whileui';
+```
+
+<!-- api:ChatMessageBubble -->
+
+| Prop               | Type          | Default | Description                                                     |
+| ------------------ | ------------- | ------- | --------------------------------------------------------------- |
+| message (required) | `ChatMessage` | —       | The message to render; its `role` decides alignment and colour. |
+| contentClassName   | `string`      | —       | Classes for the bubble's content wrapper.                       |
+
+<!-- /api:ChatMessageBubble -->
+
+### ChatSuggestions
+
+Suggestion chips when empty
+
+```tsx
+import { ChatSuggestions } from '@thewhileloop/whileui';
+```
+
+<!-- api:ChatSuggestions -->
+
+| Prop                   | Type                     | Default             | Description |
+| ---------------------- | ------------------------ | ------------------- | ----------- |
+| suggestions (required) | `string[]`               | `EMPTY_SUGGESTIONS` |             |
+| onSelect (required)    | `(text: string) => void` | —                   |             |
+| className              | `string`                 | —                   |             |
+
+<!-- /api:ChatSuggestions -->
+
+### ListItem
+
+Title/subtitle row
+
+```tsx
+import { ListItem } from '@thewhileloop/whileui';
+```
+
+<!-- api:ListItem -->
+
+| Prop             | Type              | Default | Description                                     |
+| ---------------- | ----------------- | ------- | ----------------------------------------------- |
+| icon             | `React.ReactNode` | —       |                                                 |
+| title (required) | `string`          | —       |                                                 |
+| subtitle         | `string`          | —       |                                                 |
+| description      | `string`          | —       |                                                 |
+| rightIcon        | `React.ReactNode` | —       |                                                 |
+| rightText        | `string`          | —       |                                                 |
+| action           | `React.ReactNode` | —       |                                                 |
+| showBorder       | `boolean`         | `true`  |                                                 |
+| compact          | `boolean`         | `false` |                                                 |
+| loading          | `boolean`         | `false` | Show a skeleton placeholder instead of content. |
+| className        | `string`          | —       |                                                 |
+
+Also accepts the props of `PressableProps`.
+<!-- /api:ListItem -->
+
+### NotificationItem
+
+Notification row with metadata
+
+```tsx
+import { NotificationItem } from '@thewhileloop/whileui';
+```
+
+<!-- api:NotificationItem -->
+
+| Prop               | Type              | Default | Description                                     |
+| ------------------ | ----------------- | ------- | ----------------------------------------------- |
+| icon               | `React.ReactNode` | —       |                                                 |
+| avatarUrl          | `string`          | —       |                                                 |
+| avatarFallback     | `string`          | —       |                                                 |
+| title (required)   | `string`          | —       |                                                 |
+| message (required) | `string`          | —       |                                                 |
+| time (required)    | `string`          | —       |                                                 |
+| read               | `boolean`         | `false` |                                                 |
+| showDot            | `boolean`         | `true`  |                                                 |
+| loading            | `boolean`         | `false` | Show a skeleton placeholder instead of content. |
+| className          | `string`          | —       |                                                 |
+
+Also accepts the props of `PressableProps`.
+<!-- /api:NotificationItem -->
+
+### TimelineFeed
+
+Vertical feed with connecting lines
+
+```tsx
+import { TimelineFeed } from '@thewhileloop/whileui';
+```
+
+<!-- api:TimelineFeed -->
+
+| Prop             | Type             | Default | Description |
+| ---------------- | ---------------- | ------- | ----------- |
+| className        | `string`         | —       |             |
+| items (required) | `TimelineItem[]` | —       |             |
+| showConnector    | `boolean`        | `true`  |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:TimelineFeed -->
+
+### CheckoutSummary
+
+Cart summary with line items
+
+```tsx
+import { CheckoutSummary } from '@thewhileloop/whileui';
+```
+
+<!-- api:CheckoutSummary -->
+
+| Prop                | Type                 | Default      | Description |
+| ------------------- | -------------------- | ------------ | ----------- |
+| items (required)    | `CheckoutLineItem[]` | —            |             |
+| subtotal (required) | `string`             | —            |             |
+| shipping            | `string`             | —            |             |
+| tax                 | `string`             | —            |             |
+| discount            | `string`             | —            |             |
+| total (required)    | `string`             | —            |             |
+| buttonLabel         | `string`             | `'Checkout'` |             |
+| onCheckout          | `() => void`         | —            |             |
+| loading             | `boolean`            | `false`      |             |
+| className           | `string`             | —            |             |
+
+Also accepts the props of `ViewProps`.
+<!-- /api:CheckoutSummary -->
+
+### MetricCard
+
+Stats/progress card for dashboards
+
+```tsx
+import { MetricCard } from '@thewhileloop/whileui';
+```
 
-- [ ] Add `## API` sections for: Textarea, Toggle, ToggleGroup, Label, Separator, Skeleton, AspectRatio, Collapsible, Text, View
-- [ ] Add `## API` sections for blocks: FloatingBottomNav, TabBar, FormModalScreen, ErrorState, LoadingScreen, ListItem, NotificationItem, MetricCard, TimelineFeed
+<!-- api:MetricCard -->
 
-### Infrastructure
+| Prop             | Type                                 | Default     | Description                                     |
+| ---------------- | ------------------------------------ | ----------- | ----------------------------------------------- |
+| className        | `string`                             | —           |                                                 |
+| label (required) | `string`                             | —           |                                                 |
+| value (required) | `string \| number`                   | —           |                                                 |
+| subtitle         | `string`                             | —           |                                                 |
+| progress         | `number`                             | —           |                                                 |
+| segments         | `{ value: number; color: string }[]` | —           |                                                 |
+| icon             | `React.ReactNode`                    | —           |                                                 |
+| loading          | `boolean`                            | `false`     | Show a skeleton placeholder instead of content. |
+| variant          | `'default' \| 'outlined'`            | `'default'` |                                                 |
 
-- [ ] Publish to npm (`@thewhileloop/whileui`)
-- [ ] CI: typecheck + format check on PR
-- [ ] Automated visual regression tests (screenshot comparison)
+Also accepts the props of `ViewProps`.
+<!-- /api:MetricCard -->
 
 ## License