# 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 is pre-1.0 and UNPUBLISHED. No `@beemvp/beeui-*` package or CLI is on npm, no `v1.0.0` tag or GitHub Release exists, and the repository is private by owner decision. Package/CLI names and install commands below are release-ready-but-not-published targets, not live registry commands. Do not tell a user to `npm install @beemvp/beeui-ui` or `npx @beemvp/beeui-cli` yet — those resolve to nothing today. The working, in-repo path is the source-ownership CLI (`pnpm beeui -- add <component>`).

## 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 (requires `GestureHandlerRootView` + `BottomSheetModalProvider` at the app root on native, 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, and packages/*/package.json. Do not edit by hand; run `pnpm llms:generate`.