ui-components: Instructions file for Codex

beUI v2 — agent guide

React motion component library plus its docs site, distributed as copy-paste source via shadcn-compatible registry endpoints. Stack: Next.js 15 (App Router), React 19, Tailwind CSS 4, motion (framer-motion) v11, TypeScript strict, Bun, Biome. Live at beui.dev.

Commands

bun install
bun run dev             # local site
bun run typecheck       # tsc --noEmit
bun run lint            # biome
bun run check:registry  # every registry component can publish its files
bun run check           # typecheck, lint, and registry validation
bun test                # accessibility tests only

Prefer typecheck + lint for quick verification. Do not start the dev server or run bun run build unless explicitly asked.

Testing policy

• Keep the automated test suite accessibility-only. Do not add or restore general unit, interaction, calculation, snapshot, styling, or animation-timing tests unless the user explicitly requests them.
• Keep accessibility audits in tests/a11y.test.tsx or focused tests/*.a11y.test.tsx files, using tests/setup.ts. Add coverage for meaningful accessible states, including open overlays where relevant; avoid duplicate cases.
• Run bun run check and bun test before committing. TypeScript, lint, and registry validation remain required and are separate from the accessibility suite.
• Verify changed interactions and visual behavior in the browser, including keyboard/focus behavior, touch where applicable, responsive layout, and reduced motion. Automated axe checks do not establish animation quality or complete accessibility. Report what was checked and any verification limits; the dev-server restriction above still applies.

Layout

• components/motion/, components/charts/, and components/agents/ — the library. One file per component; multi-file widgets get a folder (swap/, button/, loading-states/).
• components/previews/ — demo per component, registered in components/previews/index.tsx. Previews ship through the registry too. When an interactive preview uses internal demo helpers, set the registry entry's usageFile to a separate public composition so the Usage tab stays copyable.
• components/app/ — site chrome (header, hero, dock, code blocks). Not part of the library.
• lib/registry.ts — component catalog (slugs, files, examples). Five categories: motion (display name "Components", primitives), agents (AI and agent interface primitives), charts (data visualizations at /charts, with detail pages at /charts/<slug>), casino (games at /casino, with detail pages at /casino/<slug>), and blocks (composed widgets: swap, dynamic island, command palette, expandable action bar). Top-level sections are listed in TOP_LEVEL_CATEGORIES (lib/component-paths.ts). Blocks and casino emit registry:block shadcn items. Preview files live under components/previews/<category>/. lib/registry-server.ts builds registry items by following each file's @/ and relative imports and bundling everything it finds. Internal imports are therefore safe and encouraged; a component that imports @/lib/ease ships lib/ease.ts with it.
• app/r/* — registry endpoints (shadcn items, raw source, index). beUI is listed in shadcn's official registry directory as the @beui namespace with URL template https://beui.dev/r/{name}.json — that path shape and existing install slugs are public contract; never break or rename them.
• lib/ease.ts — all motion tokens.
• scripts/check-registry.ts — validates the catalog.
• lib/native/catalog.json — beUI Native (React Native) components and source, synced from the beui-native repo by bun scripts/sync-native.ts (never edit by hand). The same script uploads the showcase clips and posters to the beui-native R2 bucket, served from media.beui.dev with content-hashed names; don't add clips to public/. Native components have their own pages for search: /react-native lists them by group and /react-native/[slug] shows one (clip, Expo Go QR, CLI and manual install, its README, related native components), with its own metadata, JSON-LD, OG card (/api/og?native=) and sitemap entries (lib/native-seo.ts). A web component page with a native version links to it. The Web/React Native switch (components/app/docs/native/platform-switch.tsx), at the top of the right sidebar and inline below xl, navigates between a page's two URLs, falling back to the other platform's list; on /react-native pages the left sidebar lists native components by group (lib/native/nav.json). Agents read /native/r and /native/r/{slug} (lib/native-registry.ts), the llms.txt native section, and the MCP list_native_components and get_native_component tools.