BeautifulUI Upgrade Playbook | PraisonAIUI Docs

BeautifulUI Upgrade PlaybookHow PraisonAIUI vendors BeautifulUI React primitives soupgrades are repeatable and licence obligations are explicit.!!! info "Related planning"Epic #292 (integrationstrategy) and the adapter/pin policy in#294.1. What BeautifulUI isBeautifulUI (MIT, © Shane Levine / Turbo) is a library of React primitives aimed atAI-native interfaces — thinking traces, streaming answers with inline sources,human-in-the-loop approval cards, tool chips, task rows, context chunks, and a referencechat harness.It is a shadcn registry + copy-paste library — not an npm package. There is nopublished beautiful-ui package. You install components by resolving a registry URL, andthe source is copied into your tree (like any other shadcn/ui primitive).Website & registry: <https://www.beautifului.dev/>Upstream source: <https://github.com/slev12397/beautiful-ui>Upstream stack (Next.js 15 · React 19 · Tailwind CSS v4 · TypeScript) is closely alignedwith PraisonAIUI's src/frontend (Vite · React 19 · Tailwind v4 · shadcn/Radix), which iswhy copy-paste vendoring works without a framework shim.2. One-time foundation setupPraisonAIUI already carries the shadcn/ui foundation that BeautifulUI primitives depend on:shadcn config — src/frontend/components.json (style: new-york,baseColor: neutral, iconLibrary: lucide, cssVariables: true). Its registriesmap is where pinned BeautifulUI registry URLs are added (see §3).Theme tokens — src/praisonaiui/themes.py generates the shadcn CSS variables(--background, --foreground, --primary, --radius, …) at build time for all 22official presets, offline. BeautifulUI's foundation CSS (upstream app/globals.css)must only contribute new tokens/utilities; it must not redefine variables thatthemes.py already owns, or theme switching and dark mode break.Rule: when merging upstream app/globals.css, diff it against the variables emitted bythemes.py and keep only the additive slices (new keyframes, component-scoped utilities).Record what was merged in the pin doc (§3).3. Adding or updating a primitive1. Install with a pinned registry URL from src/frontend/:The registry resolves dependencies and CSS slices. Commit the resultingpackage-lock.json change in the same PR.2. Re-export through the adapter — add the component tosrc/frontend/src/components/index.ts (@praisonaiui/react). Consumers never importthe raw vendored path (see §4).3. Update the pin record — create/update docs/frontend/BEAUTIFULUI_UPSTREAM.md with:the upstream git SHA, the date, the registry base URL, and the **componentlist** vendored so far. This file is the single source of truth for "what version arewe on". (It is created the first time a real primitive is vendored — do not add itempty.)4. Rebuild & sync the bundle — the committed frontend bundle must be regenerated:(See AGENTS.md → "Frontend Build".)5. Run frontend CI — .github/workflows/ci.yml (ruff + pytest) must pass, plus thefrontend build step.4. Adapter boundaryConsumers import from @praisonaiui/react only — never from raw vendored paths such as@/components/ui/... or any upstream module.This keeps the upstream surface behind one file (components/index.ts), so a BeautifulUIbump changes vendored source but not consumer imports.5. RollbackBeautifulUI-backed views mount behind a feature flag; the vanilla dashboard views(src/praisonaiui/templates/frontend/plugins/*) remain the fallback and are kept working.To roll back a bad bump: revert the vendoring PR (source + BEAUTIFULUI_UPSTREAM.md +rebuilt bundle move together in one commit), and disable the flag. No consumer importchanges are needed because everything routes through the adapter (§4).6. LicenceBeautifulUI is MIT, © Shane Levine. The full licence text is retained inTHIRD_PARTY_NOTICES.mdat the repository root. Any PR that vendors or bumps BeautifulUI source must keep thatnotice present and current.7. Commercial icons — do not vendorDo not use @central-icons-react without a licence — it is commercial. PraisonAIUIstandardises on lucide-react (iconLibrary: lucide in components.json). If anupstream BeautifulUI primitive imports commercial icons, swap them for lucide equivalentsduring vendoring.