# BeeUI — production patterns

> BeeUI's composition guidance and the production Pattern Gallery: 37 screens across 4 packs under apps/showcase/patterns/**. Patterns are executable Showcase evidence and examples — they import public `@beemvp/beeui-ui` APIs and own local domain composition. They are NOT `@beemvp/beeui-ui` exports and are NOT installable via the registry.

STATUS: BeeUI `0.86.2-rc.3` is public on npm under the opt-in `next` dist-tag (observed 2026-09-25T06:25:18.371Z). `latest` currently resolves to `0.86.2-rc.3` and lags `next` until the owner moves it for all four packages. Every release-candidate install should still use `@next` or pin the exact version — do not recommend an unqualified, untagged install, since `latest` lags `next` between an RC publication and the owner's move. `npm install @beemvp/beeui-ui@next @beemvp/beeui-core@next @beemvp/beeui-tokens@next` and `npx @beemvp/beeui-cli@next --help` are live, working registry commands today. The source-ownership CLI (`pnpm beeui add <component>`) remains available from a repository checkout. See [docs/dist-tag-policy.md](docs/dist-tag-policy.md) for the full release/dist-tag mechanics.

## Pattern packs (37 screens total)
- Authentication + Onboarding: 9 screens
- Dashboard + Finance: 8 screens
- Commerce + Social: 12 screens
- Account + Settings: 8 screens

The Showcase opens a local section chooser: Components (interactive playground) and Patterns (declarative Pattern Gallery over the four packs). No router or global store is required. See [README.md](README.md) and [docs/architecture.md](docs/architecture.md).

## Composition guidance for agents
- Compose existing primitives first; keep domain-specific composition local to the app, not in `@beemvp/beeui-ui`. Promote a shared primitive only after repeated or behaviorally complex evidence (the "Rule of Two", [docs/roadmap.md](docs/roadmap.md)).
- App shell: wrap in `BeeUIProvider`; own safe-area edges explicitly with `SafeArea` around `AppHeader` / content / `BottomActionBar`.
- Forms: `Field` composes label/description/error for text entry; `FormGroup` owns structural legend/description/error for related controls without collapsing them into one accessibility element. Controlled selection controls need their change callback.
- Overlays: use `Dialog`/`AlertDialog` for modal-class flows; `Popover`/`DropdownMenu`/`Select`/`Tooltip` for anchored non-modal content; `Sheet` for gesture bottom sheets — on native, mount BeeUI's public `SheetProvider` directly below `BeeUIProvider` (it installs `GestureHandlerRootView` + `BottomSheetModalProvider` itself; do not mount an outer `BottomSheetModalProvider` yourself, ADR-006). `useToast()` for transient notifications.
- Data display: `Table` is a composable primitive family — map your own rows to `TableRow`/`TableCell`; sort/selection state stays caller-owned (ADR-007). `Stat`, `Timeline`, `Badge`, `Avatar`, `DescriptionList` are layout-only.
- Dates: `Calendar`/`DatePicker`/`DateTimePicker` are timezone-free, single-date, `Intl`-driven; the app owns any timezone/business-calendar conversion (ADR-008).

## Where to look
- Executable patterns: apps/showcase/patterns/** (native Showcase inputs).
- Component contracts referenced by patterns: [docs/components.md](docs/components.md).
- Patterns docs page: [apps/docs/src/content/docs/patterns/index.md](apps/docs/src/content/docs/patterns/index.md).

Generated by scripts/generate-llms-txt.mjs from registry/registry.json, packages/ui/src/index.ts, packages/*/package.json, and docs/dist-tag-policy.md. Do not edit by hand; run `pnpm llms:generate`.