@cdx-ui/components 0.2.3 → 0.2.4

package/docs/getting-started/developers/content.md

@@ -0,0 +1,612 @@
+# Installation (https://design.candescent.com/docs/getting-started/developers)
+
+## Expo
+
+### Install packages
+
+Install the core packages in your Expo / React Native project:
+
+```bash
+pnpm add @cdx-ui/components @cdx-ui/icons @cdx-ui/styles @cdx-ui/native uniwind tailwindcss
+# or: npm install @cdx-ui/components @cdx-ui/icons @cdx-ui/styles @cdx-ui/native uniwind tailwindcss
+```
+
+- **`@cdx-ui/styles`** — provides the design token CSS files (`theme.css`, `utilities.css`) imported in `global.css`.
+- **`@cdx-ui/native`** — native platform integration: the Metro config wrapper (`@cdx-ui/native/metro`) and the Expo config plugin that embeds Forge fonts (listed as `"@cdx-ui/native"` in `app.json` plugins). It ships **no root export** — always import from a subpath.
+- **`tailwindcss`** v4 — required by the CSS entry file (`@import 'tailwindcss'`).
+- **`uniwind`** — required by the CSS entry file (`@import 'uniwind'`) and by the Metro transformer for React Native styling.
+
+#### Packages
+
+[@cdx-ui/components](https://www.npmjs.com/package/@cdx-ui/components) — Styled UI components (Button, Input, Dialog, etc.)
+
+[@cdx-ui/icons](https://www.npmjs.com/package/@cdx-ui/icons) — Icon library with Material Symbols SVGs
+
+[@cdx-ui/primitives](https://www.npmjs.com/package/@cdx-ui/primitives) — Unstyled behavioral components (a11y, interactions)
+
+[@cdx-ui/styles](https://www.npmjs.com/package/@cdx-ui/styles) — Design tokens and themes
+
+[@cdx-ui/native](https://www.npmjs.com/package/@cdx-ui/native) — Metro config wrapper and Expo font loading
+
+[@cdx-ui/utils](https://www.npmjs.com/package/@cdx-ui/utils) — Shared helpers (styling utilities, event handlers, refs)
+
+#### Peer dependencies
+
+Make sure the following are already installed (Expo projects include most of them by default):
+
+| Package                          | Version             | Required by                           |
+| -------------------------------- | ------------------- | ------------------------------------- |
+| `react`                          | ^18.2.0 or ^19.0.0  | all packages                          |
+| `react-native`                   | >=0.76.0            | all packages                          |
+| `react-native-svg`               | ^13 / ^14 / ^15     | `@cdx-ui/icons`                       |
+| `react-native-safe-area-context` | >=4.0.0             | `@cdx-ui/components`                  |
+| `react-native-reanimated`        | >=4.0.0 (optional)  | `@cdx-ui/components`                  |
+| `react-native-worklets`          | >=0.4.0 (optional)  | `@cdx-ui/components`                  |
+| `react-native-gesture-handler`   | >=2.0.0 (optional)  | `@cdx-ui/components`                  |
+| `react-native-web`               | >=0.19.0 (optional) | `@cdx-ui/components`                  |
+| `@shopify/flash-list`            | >=2.0.0 (optional)  | `@cdx-ui/components`                  |
+| `react-native-sortables`         | ^1.10.1 (optional)  | `@cdx-ui/components/reorderable-list` |
+| `@dnd-kit/core`                  | ^6.3.0 (optional)   | `@cdx-ui/components/reorderable-list` |
+| `@dnd-kit/sortable`              | ^10.0.0 (optional)  | `@cdx-ui/components/reorderable-list` |
+| `@dnd-kit/utilities`             | ^3.2.0 (optional)   | `@cdx-ui/components/reorderable-list` |
+| `expo`                           | >=52.0.0 (optional) | `@cdx-ui/native`                      |
+| `metro-config`                   | >=0.80.0 (optional) | `@cdx-ui/native`                      |
+| `tailwindcss`                    | v4                  | build tooling                         |
+
+- **`react-native-safe-area-context`** — required by `SafeAreaView` and `useSafeAreaInsets` re-exports; most Expo projects include it. You still need a root `SafeAreaProvider` even when using `ForgeDesignProvider`.
+- **`react-native-reanimated`** / **`react-native-worklets`** — required by animated components (`Dialog`, `AlertDialog`, `Toast`, `BottomSheet`, `Skeleton`, `Carousel`, `Tabs`, and Select overlays). Worklets is Reanimated's companion runtime.
+- **`react-native-gesture-handler`** — required for Dialog/AlertDialog swipe-to-dismiss, Toast swipe gestures, and BottomSheet on native. Wrap the app root in a `GestureHandlerRootView` (see [step 4](#4-import-css-and-wrap-the-app-root)); without it, opening a `Dialog`, `AlertDialog`, `BottomSheet`, or `Toast` on native throws in development.
+- **`react-native-web`** — needed when targeting web; Expo web projects include it automatically.
+- **`@shopify/flash-list`** — only required if using `VirtualizedList`.
+- **`react-native-sortables`** (native) and **`@dnd-kit/core`**, **`@dnd-kit/sortable`**, **`@dnd-kit/utilities`** (web) — only required if you import `ReorderableList` from `@cdx-ui/components/reorderable-list`; the main `@cdx-ui/components` entry never loads them. See [ReorderableList installation](https://design.candescent.com/docs/components/reorderable-list/content.md#installation).
+- **`expo`** — only required by the `@cdx-ui/native` font config plugin; every Expo project already has it. Browser-only apps do not need it: they load fonts through `@cdx-ui/styles/fonts`.
+- **`metro-config`** — only required by `@cdx-ui/native/metro`; every Expo/React Native project already has it.
+
+> [!WARNING]
+>
+> **Uniwind requirement**
+>
+> While the published `peerDependencies` floor is `react-native >=0.76.0`, Forge UI's Tailwind-based styling (via Uniwind) requires **React Native 0.81+** (New Architecture) and **Expo SDK 54+**. Projects on earlier versions will satisfy the peer dep check but cannot use the styling pipeline.
+
+---
+
+### Metro Setup (React Native / Expo)
+
+Forge UI uses Tailwind-based styling via [Uniwind](https://github.com/uni-stack/uniwind). A helper wraps your Metro config so you don't need to configure Uniwind directly.
+
+#### 1. Create a CSS entry file
+
+Create `global.css` in your project root:
+
+```css
+@import 'tailwindcss';
+@import 'uniwind';
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+@import '@cdx-ui/styles/theme.css';
+@import '@cdx-ui/styles/utilities.css';
+@import '@cdx-ui/components/styles.css';
+```
+
+- **`@import 'uniwind'`** — Registers Uniwind's CSS transforms and plugins with Tailwind. Must appear immediately after `@import 'tailwindcss'` — before any other directives or theme imports.
+- **`@custom-variant dark`** — Switches Tailwind v4's dark mode from `@media (prefers-color-scheme)` to class-based activation. Required for `ScopedTheme` to work on web. Harmless if you don't use `ScopedTheme` — global dark mode continues to work via `Uniwind.setTheme()`.
+- **`@cdx-ui/styles/theme.css`** — Design tokens (colors, spacing, radii, shadows, fonts) as a Tailwind v4 `@theme static` block, plus light/dark mode and platform font overrides via `@variant`.
+- **`@cdx-ui/styles/utilities.css`** — Composite typography utilities (`heading-xl`…`heading-xs`, `body-xl`…`body-xs`, `label-sm`, `label-xs`) used by `Heading`, `Text`, and `Link`. Each has a `-size` companion (`body-sm-size`) that sets only the font size, line height, and letter spacing, so nested text can change size and keep its inherited font family and weight.
+- **`@cdx-ui/components/styles.css`** — `@source` directive telling Tailwind where to scan for component utility classes.
+
+> [!NOTE]
+>
+> **Non-Tailwind consumers**
+>
+> Import `@cdx-ui/styles/vanilla.css` for a plain CSS file with `:root` variables and utility
+> classes — no Tailwind `@theme`/`@variant` syntax required.
+
+> [!WARNING]
+>
+> **Web consumers: @cdx-ui/styles/web.css is required**
+>
+> Every browser app must import `@cdx-ui/styles/web.css` as a **separate JS import** — not via `@import` in your CSS file — after your Tailwind CSS entry. It bridges a cascade-layer gap in Tailwind v4's `@theme static` output (unlayered `:root` beats anything inside `@layer theme`), and carries the unlayered `.dark`/`.light` overrides the layered output cannot, for apps that toggle dark mode via a `.dark` class (for example with `next-themes` or a manual toggle).
+>
+> ```tsx
+> import './global.css'; // Tailwind + Uniwind CSS entry
+> import '@cdx-ui/styles/web.css'; // Unlayered token overrides — MUST be after Tailwind
+> ```
+
+#### 2. Configure Metro
+
+In `metro.config.js`, wrap your config with `withForgeMetroConfig`:
+
+```js
+const { getDefaultConfig } = require('expo/metro-config');
+const { withForgeMetroConfig } = require('@cdx-ui/native/metro');
+
+const config = getDefaultConfig(__dirname);
+
+module.exports = withForgeMetroConfig(config, {
+  cssEntryFile: './global.css',
+  generatedTypesFile: './uniwind-types.d.ts', // optional, enables className autocomplete
+});
+```
+
+> [!NOTE]
+>
+> `withForgeMetroConfig` must be the **outermost** wrapper if you compose multiple Metro config
+> helpers.
+
+#### 3. Add the font config plugin
+
+Add `@cdx-ui/native` to the `plugins` array in `app.json`, then rebuild the native app (`npx expo prebuild`, `expo run:ios` / `expo run:android`, or an EAS build):
+
+```json
+{
+  "expo": {
+    "plugins": ["@cdx-ui/native"]
+  }
+}
+```
+
+The plugin embeds every Forge font family into the iOS and Android builds, each registered as one family carrying all of its faces. That is what lets `font-medium`, `font-semibold`, `font-bold`, and `italic` select a real face on native, the same way `font-weight` and `font-style` do in a browser. Fonts are part of the binary, so there is no loading state to wait for. Config plugins need a [development build](https://docs.expo.dev/develop/development-builds/introduction/); Expo Go cannot load them.
+
+Font selection is handled entirely by the CSS variable layer, including a `ThemeOverride` that switches the Display family at runtime.
+
+> [!NOTE]
+>
+> **Upgrading from useForgeFonts**
+>
+> `useForgeFonts` loaded fonts at runtime through `expo-font`, which registers each face as a separate family. On Android that shape cannot carry weight or italic. It is deprecated and now always reports `loaded`: add the plugin, rebuild, and remove the hook along with any rendering gate on it. An Expo app that also exports to web keeps calling `loadForgeWebFonts` from [`@cdx-ui/styles/fonts`](#fonts-on-web), which is inert off the browser.
+
+#### 4. Import CSS and wrap the app root
+
+In your root layout (e.g. `app/_layout.tsx`), import the CSS entry file and wrap the tree with `GestureHandlerRootView`, `SafeAreaProvider`, and `ForgeDesignProvider`.
+
+> [!NOTE]
+>
+> The example below uses [Expo Router](https://docs.expo.dev/router/introduction/) (`expo-router`)
+> for navigation. If your project uses a different router, replace the `Stack` import with your own
+> root navigator.
+
+```tsx
+import '../global.css';
+
+import { Stack } from 'expo-router';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { ForgeDesignProvider } from '@cdx-ui/components';
+
+export default function RootLayout() {
+  return (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <SafeAreaProvider>
+        <ForgeDesignProvider>
+          <Stack />
+        </ForgeDesignProvider>
+      </SafeAreaProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+`GestureHandlerRootView` must sit above `ForgeDesignProvider`. Overlays render through the provider's portal host, so the `Dialog`, `AlertDialog`, `BottomSheet`, and `Toast` gestures need the root view as an ancestor of that host, not just of the screen that opens them.
+
+`ForgeDesignProvider` mounts shared app-root services:
+
+- `PortalHost` — required for `Dialog` / `AlertDialog` (without a host, overlays fail silently)
+- `ToastProvider` — required for `useToast()` (disable with `config={{ toast: false }}` if unused)
+- Global animation settings and text scaling props (`config.animation`, `config.textProps`)
+- `SafeAreaListener` → keeps Uniwind insets in sync
+
+It does **not** replace `SafeAreaProvider`. If you skip `ForgeDesignProvider`, mount one `<PortalHost />` from `@cdx-ui/primitives` (and `ToastProvider` when using toasts) yourself — and do not add a second host when the provider is already in the tree.
+
+---
+
+### Minimal Example
+
+```tsx
+import { Button, Heading, Text, VStack } from '@cdx-ui/components';
+
+export default function HomeScreen() {
+  return (
+    <VStack space="lg" className="flex-1 p-6">
+      <Heading>Welcome</Heading>
+      <Text>Get started with Forge UI.</Text>
+      <Button onPress={() => {}}>
+        <Button.Label>Continue</Button.Label>
+      </Button>
+    </VStack>
+  );
+}
+```
+
+Components carry their own look, so the example sets no colors or typography. Before you style a screen, read [Styling and customization](https://design.candescent.com/docs/getting-started/developers/styling/content.md).
+
+---
+
+### React Native re-exports
+
+`@cdx-ui/components` re-exports several core React Native components and hooks so consuming apps can import everything from a single package:
+
+```tsx
+import {
+  View,
+  ScrollView,
+  KeyboardAvoidingView,
+  SafeAreaView,
+  useSafeAreaInsets,
+} from '@cdx-ui/components';
+```
+
+| Export                 | Source                           |
+| ---------------------- | -------------------------------- |
+| `View`                 | `react-native`                   |
+| `ScrollView`           | `react-native`                   |
+| `KeyboardAvoidingView` | `react-native`                   |
+| `SafeAreaView`         | `react-native-safe-area-context` |
+| `useSafeAreaInsets`    | `react-native-safe-area-context` |
+
+These are convenience re-exports of the underlying packages — not Uniwind wrappers. `className` works on RN views when Uniwind's Metro pipeline is configured; importing from `@cdx-ui/components` vs `react-native` does not change that.
+
+---
+
+### Next steps
+
+[Components reference](https://design.candescent.com/docs/components/content.md) — detailed docs for every component\
+[Styling and customization](https://design.candescent.com/docs/getting-started/developers/styling/content.md) — what to style, and what to leave to the components\
+[Accessibility](https://design.candescent.com/docs/getting-started/developers/accessibility/content.md) — what the components handle, and what your screen still provides\
+[Icons](https://design.candescent.com/docs/foundations/expressions/icons/content.md) — using `@cdx-ui/icons`\
+[Link / navigation](https://design.candescent.com/docs/components/link/content.md) — router integration with `LinkProvider`
+
+## Vite
+
+Use this path when you want Forge UI components in a standard Vite + React + TypeScript web app. Forge UI is authored against React Native primitives; on web those resolve through `react-native-web` in the same browser bundle as your existing React components.
+
+### Create a project
+
+Scaffold a new app with the React + TypeScript template:
+
+```bash
+npm create vite@latest my-forge-app -- --template react-ts
+cd my-forge-app
+```
+
+Use `pnpm create vite@latest` or `yarn create vite` if you prefer those package managers.
+
+### Install dependencies
+
+Install all five runtime `@cdx-ui/*` packages at the **same version** — even if you only import from `@cdx-ui/components` directly. Mismatched versions can fork the renderer and cause confusing runtime errors. `@cdx-ui/native` is not needed here: it is the Metro/Expo integration package.
+
+```bash
+pnpm add @cdx-ui/components @cdx-ui/icons @cdx-ui/primitives @cdx-ui/styles @cdx-ui/utils react-native-web react-native-reanimated react-native-worklets react-native-gesture-handler react-native-safe-area-context react-native-svg
+# or: npm install @cdx-ui/components @cdx-ui/icons @cdx-ui/primitives @cdx-ui/styles @cdx-ui/utils react-native-web react-native-reanimated react-native-worklets react-native-gesture-handler react-native-safe-area-context react-native-svg
+```
+
+Add the Forge Vite integration and its build tooling:
+
+```bash
+pnpm add @cdx-ui/web @tailwindcss/vite tailwindcss uniwind react-native -D
+# or: npm install @cdx-ui/web @tailwindcss/vite tailwindcss uniwind react-native -D
+```
+
+`@cdx-ui/components` owns the React Native runtime peer ranges in the first command. Install `@cdx-ui/web` from the same Forge UI release; it owns the Vite integration and declares `vite`, `@tailwindcss/vite`, `tailwindcss`, and `uniwind` as its build-time peers. The Vite scaffold already includes `vite` and `@vitejs/plugin-react`.
+
+| Package                          | Role                                                                                                                    |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `@cdx-ui/web`                    | Build-time Forge UI integration for Vite                                                                                |
+| `react-native-web`               | Web rendering target for React Native primitives                                                                        |
+| `react-native-reanimated`        | Required by animated Forge UI components (`Dialog`, `Toast`, `Skeleton`, `Carousel`, `Tabs`, and related overlays)      |
+| `react-native-worklets`          | Companion runtime for Reanimated 4                                                                                      |
+| `react-native-gesture-handler`   | Gesture support for Dialog swipe-to-dismiss and Toast swipe                                                             |
+| `react-native-safe-area-context` | Required peer of `@cdx-ui/components`                                                                                   |
+| `react-native-svg`               | Required transitively by `@cdx-ui/icons`; resolved to its web entry by `@cdx-ui/web/vite`                               |
+| `uniwind`                        | Compiles `className` strings into CSS on web                                                                            |
+| `react-native` (dev)             | TypeScript types only — the Forge Vite integration resolves `react-native` imports through Uniwind's web implementation |
+
+#### Fonts on web
+
+Browser apps load their own fonts — `@cdx-ui/native` is the Metro/Expo integration and should not be installed here. What Forge provides is the answer to _which_ fonts, generated from the token pipeline so it cannot drift from `theme.css`:
+
+```tsx
+import { forgeWebFontSpec } from '@cdx-ui/styles/fonts';
+
+forgeWebFontSpec.platform; // --font-sans, --font-mono — e.g. Inter, IBM Plex Mono
+forgeWebFontSpec.display; // every Display family a ThemeOverride can select
+```
+
+Each entry is a **base family** with the weights and italics it actually ships (`{ family, normalWeights, italicWeights }`). Register the family once per weight and let `font-weight` select the face — that is how a browser resolves weight, and it is what makes `font-medium`, `font-semibold` and `italic` reach the right file.
+
+Register them statically, in your document head, so the browser's preload scanner finds them while parsing HTML rather than after your bundle evaluates. `buildWebFontProviderUrl` gives you the href:
+
+```tsx
+import { buildWebFontProviderUrl, forgeWebFontSpec } from '@cdx-ui/styles/fonts';
+
+// Log it once, paste the result into index.html. Most apps ship one Display
+// family, so there is no need to request all of them:
+buildWebFontProviderUrl([...forgeWebFontSpec.platform, forgeWebFontSpec.display[0]]);
+```
+
+> [!WARNING]
+>
+> **Ask only for weights a family actually has**
+>
+> A font provider rejects the **entire** request if any family is asked for a weight it does not ship — one bad axis silently drops every font in that URL. Availability differs per family (Libre Caslon Text has 400 and 700 only, with italic at 400 only), which is why the weights travel with the family in `forgeWebFontSpec` rather than being a fixed 400/500/600/700 list.
+
+**Self-hosting.** If your deployment cannot call an external host, write the `@font-face` rules yourself against files you host. The shape that matters is one rule per face, declared under the **base family**, with `font-weight` and `font-style` descriptors:
+
+```css
+@font-face {
+  font-family: 'Inter';
+  src: url('/fonts/Inter-500.woff2') format('woff2');
+  font-weight: 500;
+  font-style: normal;
+  font-display: swap;
+}
+```
+
+Declaring a face under its own family name instead (`font-family: 'Inter Medium'`) will not work — `font-weight` has nothing to select against.
+
+**Fonts chosen at runtime.** If the family is not known until runtime — an FI font picker, or a live theme preview — a static tag cannot cover it. `loadForgeWebFonts` injects the `<link>` and returns a cleanup function:
+
+```tsx
+import { loadForgeWebFonts, forgeWebFontSpec } from '@cdx-ui/styles/fonts';
+
+useEffect(() => loadForgeWebFonts({ families: [selectedDisplayFamily] }), [selectedDisplayFamily]);
+```
+
+> [!NOTE]
+>
+> **Weight and style, not face families**
+>
+> Font tokens name one family per role — `--font-sans`, `--font-body`, `--font-mono`, `--font-display`. On `Text`, set weight and style with the `weight` and `italic` props, which select the right face on every platform:
+>
+> ```tsx
+> <Text weight="semibold" italic />
+> ```
+>
+> Outside `Text`, the `font-medium` / `font-semibold` / `font-bold` / `italic` classes do the same over the family a composite typography utility already applies.
+>
+> Some Display families ship no italic faces, and an FI can switch the Display family at runtime. Style italic Display text with `[font-style:var(--font-display-italic-style)]`, which is `normal` for those families, so it renders upright at the right weight instead of each platform improvising a slant.
+
+### Dependency footprint
+
+Only `react` and `react-native-safe-area-context` are hard-required peers of `@cdx-ui/components`; the remaining React Native runtime peers are optional and enter the bundle according to the components you use.
+
+| Package                          |   min (KB) | gzip (KB) |
+| -------------------------------- | ---------: | --------: |
+| `react-native-web`               |      521.4 |     160.9 |
+| `react-native-reanimated`        |      472.7 |     148.0 |
+| `react-native-gesture-handler`   |      290.2 |      94.3 |
+| `uniwind` (runtime)              |       67.6 |      30.6 |
+| `react-native-worklets`          |       51.1 |      18.6 |
+| `react-native-svg`               |       77.4 |      16.6 |
+| `react-native-safe-area-context` |        0.4 |       0.3 |
+| **RN + styling subtotal**        | **1480.9** | **469.4** |
+
+These measured contributions from a component-heavy production Vite build are an upper bound: React Native Web is the web baseline, while Reanimated is the conditional heavy entry and is currently unoptimized on Vite. At 469.4 KB gzip for the RN + styling subtotal, the footprint is comparable to a mainstream web component kit; these are shipped bytes, not `node_modules` disk sizes.
+
+### Configure Vite
+
+Replace `vite.config.ts` with the following:
+
+```ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { forge } from '@cdx-ui/web/vite';
+
+export default defineConfig({
+  plugins: [forge({ cssEntryFile: 'src/index.css' }), react()],
+});
+```
+
+`forge()` owns the `__DEV__` and `process.env.NODE_ENV` defines, `react-native` and `react-native-svg` aliases, `.web.*` resolution, Tailwind `optimize: false` plus Uniwind ordering, dependency pre-bundling, package deduplication, Rollup compatibility settings, and the React Native Worklets compatibility patch. Keep `react()` after `forge()` so the owned sub-plugins run in the required order.
+
+- **`cssEntryFile`** — Path to the app-owned CSS entry described below; `forge()` passes it to Uniwind but does not create or import the file.
+- **`patchWorklets`** — Controls the React Native Worklets compatibility patch. It defaults to `true`; pass `false` only when you need to disable that patch for your installed Worklets version.
+
+### CSS entry
+
+Replace `src/index.css` with:
+
+```css
+@import 'tailwindcss/theme';
+@import 'tailwindcss/utilities';
+@import 'uniwind';
+
+@custom-variant dark (&:where(.dark, .dark *));
+
+@import '@cdx-ui/styles/theme.css';
+@import '@cdx-ui/styles/utilities.css';
+@import '@cdx-ui/components/styles.css';
+
+body {
+  background-color: var(--color-surface-primary);
+  color: var(--color-content-primary);
+}
+```
+
+Import `theme` and `utilities` separately (not the all-in-one `@import 'tailwindcss'`) so Uniwind can inject its layer between them. The `@cdx-ui/components/styles.css` import is critical — without it, components render unstyled because Tailwind never scans the package for `className` usage. It also reverts React Native Web's `display: inline` reset on root `Text` elements, so text aligns inside plain block containers. If your CSS entry has an older `[class*='css-text-']` override, remove it: it only matches development builds and overrides `numberOfLines` and Tailwind display utilities.
+
+`@custom-variant dark` enables class-based dark mode for `ScopedTheme` on web. Always import `@cdx-ui/styles/web.css` as a **separate JS import** after your CSS entry (see App entry below) — it carries the web font family values and the unlayered `.dark`/`.light` overrides.
+
+### App entry
+
+Import the CSS file as the first line of `src/main.tsx`, then wrap the app with
+`SafeAreaProvider` and `ForgeDesignProvider`:
+
+```tsx
+import './index.css';
+import '@cdx-ui/styles/web.css';
+
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { ForgeDesignProvider } from '@cdx-ui/components';
+import App from './App';
+
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <SafeAreaProvider>
+      <ForgeDesignProvider>
+        <App />
+      </ForgeDesignProvider>
+    </SafeAreaProvider>
+  </StrictMode>,
+);
+```
+
+`SafeAreaProvider` must remain outside `ForgeDesignProvider`. `ForgeDesignProvider` mounts
+`PortalHost` and `ToastProvider` for you. If you prefer not to use the Forge provider, keep
+`SafeAreaProvider` and mount one `<PortalHost />` from `@cdx-ui/primitives` as a sibling of your app
+(and `ToastProvider` when using toasts). Without a host, `Dialog` / `AlertDialog` fail **silently** —
+state updates, nothing appears, and no error is logged. Do not mount a second host when
+`ForgeDesignProvider` is already in the tree.
+
+Select uses React Native Web / native Modal portals and does not require `PortalHost`.
+
+### Runtime shim
+
+Add an inline script to `index.html` **before** the module script. React Native dependencies reference `global`, which is undefined in browsers:
+
+```html
+<body>
+  <script>window.global = window;</script>
+  <div id="root"></div>
+  <script type="module" src="/src/main.tsx"></script>
+</body>
+```
+
+This cannot be moved into a module — some references evaluate before your app code runs.
+
+### TypeScript
+
+Ensure `tsconfig.json` uses bundler resolution (the Vite React + TS template includes this):
+
+```json
+{
+  "compilerOptions": {
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src"]
+}
+```
+
+The Uniwind Vite plugin generates `uniwind-types.d.ts` at the project root on first run. Commit this file so CI typecheck does not depend on running the dev server first.
+
+### Verify
+
+Render a Forge UI component to confirm the pipeline is wired end to end:
+
+```tsx
+import { Button, Heading, Text, VStack } from '@cdx-ui/components';
+
+export default function App() {
+  return (
+    <VStack space="lg" className="p-6">
+      <Heading>Welcome</Heading>
+      <Text>Get started with Forge UI.</Text>
+      <Button onPress={() => {}}>
+        <Button.Label>Continue</Button.Label>
+      </Button>
+    </VStack>
+  );
+}
+```
+
+Then run:
+
+```bash
+npm run dev      # http://localhost:5173 should render styled components
+npm run build    # must succeed with no Rollup errors
+npm run preview  # production bundle should match dev
+```
+
+If the button renders unstyled, check that `@cdx-ui/components/styles.css` is imported in `src/index.css`.
+
+### Testing with Vitest
+
+Use Vitest + React Testing Library for consumer-side **web** tests. Native component tests remain Jest + RNTL inside Forge UI packages.
+
+Do **not** reuse `forge()` in Vitest. Add a dedicated `vitest.config.ts`:
+
+```ts
+import { defineConfig } from 'vitest/config';
+import react from '@vitejs/plugin-react';
+import { forgeVitest } from '@cdx-ui/web/vite';
+
+export default defineConfig({
+  plugins: [react(), forgeVitest()],
+  test: {
+    setupFiles: ['./src/__tests__/setup.ts'],
+  },
+});
+```
+
+Install test dependencies (pin exact versions in apps that follow the example lockfile policy):
+
+```bash
+pnpm add vitest @testing-library/react @testing-library/jest-dom jsdom -D
+# or: npm install vitest @testing-library/react @testing-library/jest-dom jsdom -D
+```
+
+```ts
+// src/__tests__/setup.ts
+import '@testing-library/jest-dom/vitest';
+import { afterEach } from 'vitest';
+import { cleanup } from '@testing-library/react';
+
+afterEach(() => {
+  cleanup();
+});
+```
+
+Render Forge UI inside `ForgeDesignProvider`. Without its portal host, `Dialog` state can open with no popup in the DOM:
+
+```tsx
+import type { ReactElement } from 'react';
+import { render } from '@testing-library/react';
+import { SafeAreaProvider } from 'react-native-safe-area-context';
+import { ForgeDesignProvider } from '@cdx-ui/components';
+
+export function renderWithForgeProviders(ui: ReactElement) {
+  return render(ui, {
+    wrapper: ({ children }) => (
+      <SafeAreaProvider>
+        <ForgeDesignProvider config={{ toast: false }}>{children}</ForgeDesignProvider>
+      </SafeAreaProvider>
+    ),
+  });
+}
+```
+
+jsdom is sufficient for static rendering, controlled interactions (Switch, Checkbox), and Dialog portal behavior. It does **not** prove production CSS, layout, or animation fidelity — `forgeVitest()` substitutes Uniwind, Reanimated, Gesture Handler, and related native packages for that reason.
+
+A copy-paste harness with representative tests lives in the [Forge UI + MUI Vite example](https://github.com/dfh-candescent/forge-design-system/tree/main/examples/forge-ui-mui-vite).
+
+### Troubleshooting
+
+| Symptom                                            | Likely cause                                                                                  |
+| -------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| Components render unstyled                         | Missing `@cdx-ui/components/styles.css` import in `src/index.css`                             |
+| `__DEV__ is not defined`                           | Missing `define` block in `vite.config.ts`                                                    |
+| `global is not defined`                            | Missing `window.global` shim in `index.html`                                                  |
+| Dark mode works in dev but not production          | Ensure `forge()` is present before `react()` and its Tailwind configuration is not overridden |
+| Dialog opens with no visible popup                 | Missing `ForgeDesignProvider` or standalone `PortalHost`                                      |
+| `SyntaxError: Unexpected token 'typeof'` in Vitest | `forge()` is in the Vitest config — use `forgeVitest()` from `@cdx-ui/web/vite` instead       |
+| Build fails on `react-native-svg`                  | Ensure `forge()` is present and its `react-native-svg` alias is not overridden                |
+| "Two copies of Reanimated"                         | Mismatched `@cdx-ui/*` package versions                                                       |
+
+---
+
+### Next steps
+
+[Components reference](https://design.candescent.com/docs/components/content.md) — detailed docs for every component\
+[Styling and customization](https://design.candescent.com/docs/getting-started/developers/styling/content.md) — what to style, and what to leave to the components\
+[Accessibility](https://design.candescent.com/docs/getting-started/developers/accessibility/content.md) — what the components handle, and what your screen still provides\
+[Icons](https://design.candescent.com/docs/foundations/expressions/icons/content.md) — using `@cdx-ui/icons`\
+[Dialog](https://design.candescent.com/docs/components/dialog/content.md) — overlay setup and portal host requirements\
+[Link / navigation](https://design.candescent.com/docs/components/link/content.md) — router integration with `LinkProvider`