# BeeUI

> BeeUI is a production-oriented, accessibility-first React Native + Web UI system written in TypeScript, for Expo, bare React Native, and React Native Web. Stable behavior, semantic, and variant APIs do not require callers to know the styling engine (currently Uniwind + Tailwind CSS v4). This file is the AI-agent entry point; the links below resolve to real files in the repository.

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.

BeeUI ships 63 public component modules from `@beemvp/beeui-ui` plus a semantic design-token contract (`@beemvp/beeui-tokens`) and engine-neutral helpers (`@beemvp/beeui-core`). It owns UI only: no router, data-fetching, backend, auth, form-library, or chart framework. Two consumption models coexist — centralized packages and file-level source ownership.

## Packages
- `@beemvp/beeui-core` v0.86.2-rc.3 — Engine-neutral utilities (class-name merging, anchored-overlay geometry) shared by @beemvp/beeui-ui. No React, React Native, or Expo dependency. [public on npm under `next` (last observed 0.86.2-rc.3)] ([packages/core/package.json](packages/core/package.json))
- `@beemvp/beeui-tokens` v0.86.2-rc.3 — BeeUI's design-token system: semantic color/spacing/typography/motion contracts and the canonical Uniwind/Tailwind theme CSS. [public on npm under `next` (last observed 0.86.2-rc.3)] ([packages/tokens/package.json](packages/tokens/package.json))
- `@beemvp/beeui-ui` v0.86.2-rc.3 — Typed React Native + Web components built on @beemvp/beeui-core and @beemvp/beeui-tokens, styled through Uniwind/Tailwind. [public on npm under `next` (last observed 0.86.2-rc.3)] ([packages/ui/package.json](packages/ui/package.json))

## Install (both models; centralized is live under `@next`)
- Centralized (public RC, opt in with `@next`): `npm i @beemvp/beeui-ui@next @beemvp/beeui-core@next @beemvp/beeui-tokens@next`, then `import { Button } from '@beemvp/beeui-ui'` and wire the Web theme via `@import '@beemvp/beeui-tokens/theme.css'`. Pin `@0.86.2-rc.3` instead of `@next` for an immutable version in CI. See [docs/decisions/011-distribution-architecture.md](docs/decisions/011-distribution-architecture.md).
- Source ownership (works today, repo-local): `pnpm beeui add <component>` copies component source into the consumer and rewrites `@beemvp/beeui-core` imports. The published CLI is `@beemvp/beeui-cli` (binary `beeui`), invoked `npx @beemvp/beeui-cli@next add <component>` — NOT `npx beeui`. See [docs/registry-cli.md](docs/registry-cli.md) and [docs/distribution-names.md](docs/distribution-names.md).

## Start here
- [README.md](README.md): project overview, quick start, safe-area/overlay/toast foundations.
- [docs/architecture.md](docs/architecture.md): layering, invariants, non-goals, styling-engine boundary.
- [docs/components.md](docs/components.md): canonical per-component contract inventory.
- [docs/roadmap.md](docs/roadmap.md): pre-1.0 plan and hard 1.0 gates.

## Detailed agent surfaces
- [llms-full.txt](llms-full.txt): expanded architecture, setup, compatibility, and contract detail.
- [llms-components.txt](llms-components.txt): the 63 public component modules with exported symbols and source paths.
- [llms-patterns.txt](llms-patterns.txt): production pattern catalog and composition guidance.

## For contributing agents
- [docs/ai-agent-cookbook.md](docs/ai-agent-cookbook.md): AI-agent development contract + task-oriented prompt cookbook (how to consume/build/contribute; current distribution-status rules; ownership boundaries).
- [AGENTS.md](AGENTS.md): code rules (semantic-token-only styling, engine-boundary, accessibility).
- [CONTRIBUTING.md](CONTRIBUTING.md): local setup, required gates, review discipline.
- [docs/agent-execution-contract.md](docs/agent-execution-contract.md): implementation-agent protocol for BeeUI 1.0.

## Optional
- [docs/compatibility-matrix.md](docs/compatibility-matrix.md): pinned/tested React/RN/Expo/tooling versions.
- [docs/theming.md](docs/theming.md): semantic tokens, density, high contrast, branding.
- [docs/anchored-overlays.md](docs/anchored-overlays.md): shared overlay geometry/runtime/portal contract.
- [registry/registry.json](registry/registry.json): machine-readable source-ownership registry.

**`Sheet` on native requires `SheetProvider`** mounted below `BeeUIProvider` (`BeeUIProvider > SheetProvider > app`) — see llms-full.txt's "Provider and safe-area setup" and [apps/docs/src/content/docs/components/sheet.md](apps/docs/src/content/docs/components/sheet.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`.