@burojs/ui-shadcn

Default UI kit for buro, built on shadcn/ui primitives + Tailwind CSS.

Install

pnpm add @burojs/ui-shadcn @burojs/core @burojs/react @burojs/field-types
pnpm add -D tailwindcss
# plus your bundler's Tailwind v4 plugin — see "Tailwind setup" below

Requires Tailwind v4 (tailwindcss: ^4, declared as a peer dependency) — this package has no v3 build.

Tailwind setup

One import, before your own CSS rules:

@import '@burojs/ui-shadcn/styles.css';

That pulls in Tailwind itself, tw-animate-css (Radix overlay animations), the design tokens, the token→utility mapping, the dark variant, the pinned --font-sans and named-size line-heights, the base layer (border colours, background/foreground, button cursor), and the standard html { font-size: 16px } root — nothing else to configure. There is no tailwind.config.ts, no content array, and no preset: the package declares its own scan of its compiled output, so its class names reach your build without you listing its dist folder anywhere.

The standard 16px root keeps mobile editable text at its native size. The shared Input and Textarea use text-base (16px) on mobile, then md:text-sm (14px) from the medium breakpoint upward for compact desktop controls. This is a responsive control contract, not a global app rescale.

That import alone doesn't run Tailwind, though — you still need Tailwind v4's build plugin for your bundler, installed as its own devDependency:

• Next: pnpm add -D @tailwindcss/postcss, wired into postcss.config.cjs
• Vite: pnpm add -D @tailwindcss/vite, wired into vite.config.ts; no PostCSS config needed
• Anything else: follow Tailwind's own install docs for your bundler, then add the @import above to your stylesheet

→ docs/theming.md has the full setup, how to override a token, and the reasoning behind the base-layer rules and the --destructive colours. examples/vite (Vite) and examples/next (Next) are the working examples to copy from. (This line named apps/playground as the Next example. It was wrong twice over: that application had been a Vite app since 2026-07-31, and SP9 has now deleted it.)

Router setup

Mount your router's RouterAdapterProvider (@burojs/react) above <BuroProvider>: it is the router's only binding, and every route match, active nav item, breadcrumb and framework navigation goes through it. Then give <LinkComponentProvider linkComponent={…}> your router's link component, which only renders anchors. RouterAdapterProvider's docblock has the react-router and Next App Router adapters; examples/vite and examples/next mount them.

Platform

BuroProvider takes the browser's behaviour (persistent storage, drafts, download, clipboard, the ⌘K shortcut, the leave-page guard) from one prop. This package re-exports the factory, so a web app adds one line: <BuroProvider app={app} platform={webPlatform()}> with import { webPlatform } from '@burojs/ui-shadcn'. See docs/platform-guide.md.

App shell

→ docs/app-shell-guide.md covers AppShell, the ready-made application chrome, and how to replace any part of it.

What's included

• Navigation areas: secondary-sidebar and tabs groups work with no layout registration; <AppShell> mounts <NavChrome> (opt out with navChrome={false}), <NavAreaPage> renders the content, defaultNavLayouts is the optional table of the built-ins. See the navigation guide
• Layout: AppLayout, AppSidebar and AppHeader (each slot you omit gets its default — brand, <NavMain /> and <UserMenu />; <HeaderBreadcrumbs />, the palette chip, app actions and refresh — and false empties it), Sidebar, Breadcrumbs, HeaderBreadcrumbs (the header trail of the current route)
• Auth: LoginForm
• Resource views: ResourceList, and <RecordScreen resource mode recordId? …> — a record's show, edit or create screen outside a route, in the built-in frame or in your own layout of its pieces (RecordTitle, RecordActions, CopyId, FormActions)
• Record pages: <RecordPage resource action /> (plus defaults on action="create") — show, edit and create wired to data (useOne, useUpdateOne, useCreateOne), with translated loading / not-found / session-expired / error states and the open panel of a keyed tabs node in the URL (?<tabsKey>=<panelKey>); <ResourcePageRouter> / <NavAreaPage> render it for every record route (a different layout is a frame on the screen, views.<mode>.frame; record overrides were removed in P6); the page draws no breadcrumb trail of its own: <HeaderBreadcrumbs /> in <AppHeader breadcrumbs> draws the record trail there (<RecordBreadcrumbs /> standalone), with the record's title once the page has loaded it and the id while it loads or has failed, and on a page-hosted flow's route ending with the flow's label; each show and edit visit is recorded under the signed-in user for the command palette's Recent group
• Custom pages: a page declared with a body (defineCustomPage({ …, body: (l) => [l.place(block, { key })] })) renders on its route under its label as the <h1>, behind the page's and its groups' visible; a page without body is a nav entry over a route the host owns
• Field renderers: text, number, boolean, date, enum, textarea (display + form input)
• Actions: ActionButton (links, modals and flows), FlowActionButton, AppFlowButton, BulkActionToolbar (bulk flows); useAction from @burojs/react/flows runs a flow from your own control
• Notifications: Toaster (Sonner) — render it inside <BuroProvider>, where it registers itself as the dispatcher's notification sink
• Unsaved-changes dialog: <NavigationGuardDialog>, registered by <AppLayout> (the guard itself is <BuroProvider>'s)
• UI presentation hosts: dialog/sheet chrome for the framework-mounted <UIPresentations/> overlay stack (shadcnPresentationHosts), backing modal actions and the flow host (screens.flow, the buro:flow dialog or sheet)
• Vendored shadcn primitives: Button, Input, Label, Form, Table, Card, Dialog, Sheet, Select, Checkbox, Textarea, Badge

License

MIT