@bardioc/ui

Bardioc UI component library for BardiocOS apps. Combines a custom Bardioc component layer with Shadcn/Radix primitives on top of Tailwind CSS 4.

Installation

pnpm add @bardioc/ui
# peers (provide in the consumer app)
pnpm add react react-dom @bardioc/i18n-core

Entry points

@bardioc/ui ships only subpath exports. Import the surface you need rather than the package root.

| Subpath | Purpose | | -------------------------------- | ------------------------------------------------------------- | | @bardioc/ui/components | Bardioc components (canonical non-chart surface) | | @bardioc/ui/components/charts | Bardioc chart components (Recharts-backed) | | @bardioc/ui/components/metrics | Bardioc metric components | | @bardioc/ui/shadcn | Shadcn/Radix primitives (non-chart) — use as namespace import | | @bardioc/ui/shadcn/chart | Shadcn chart primitives (Recharts-backed) | | @bardioc/ui/hooks | Reusable React hooks | | @bardioc/ui/lib | Utility functions (cn, color helpers, pagination, ...) | | @bardioc/ui/types | Shared TypeScript types | | @bardioc/ui/consts | Shared constants | | @bardioc/ui/icons | SVG icon components | | @bardioc/ui/styles/* | CSS entry points (globals.css, component stylesheets) | | @bardioc/ui/postcss.config | PostCSS preset for consumers |

Component priority chain

When picking a component, check in this order:

1. Bardioc component (@bardioc/ui/components) — always prefer
2. Bardioc chart/metric component (@bardioc/ui/components/charts, @bardioc/ui/components/metrics) — use for Recharts-backed surfaces
3. Shadcn primitive (@bardioc/ui/shadcn) — only if no Bardioc alternative exists; import as a namespace
4. Shadcn chart primitive (@bardioc/ui/shadcn/chart) — only for low-level chart composition
5. HTML element — only for layout or when no component exists

Shadcn primitives are read-only

Files under src/components/shadcn/ are managed by the shadcn CLI. Do not hand-edit them. To change visuals or behavior, create or edit a Bardioc component under src/components/bardioc/<category>/ that overrides or composes the primitive.

Build

tsup bundles each public subpath into a single ESM file with declarations, externalizes runtime dependencies, and resolves #-aliases and extensionless relative imports during the build.

React Server Components

The shadcn source files include 'use client' directives, but bundling strips them — the published artifacts do not carry the directive. When consuming @bardioc/ui/{components,shadcn,hooks} from a React Server Components environment (e.g. Next.js App Router), mark the consuming file with 'use client' yourself:

'use client';
import { Command } from '@bardioc/ui/shadcn';

Non-RSC environments (Vite, plain Webpack, Storybook, Vitest) need no special handling.

Usage

import { Button, DataTable } from '@bardioc/ui/components';
import { RevenueChart } from '@bardioc/ui/components/metrics';
import * as Shadcn from '@bardioc/ui/shadcn';
import { ChartContainer } from '@bardioc/ui/shadcn/chart';
import { cn } from '@bardioc/ui/lib';
import '@bardioc/ui/styles/bardioc-ui.css'; // pre-compiled theme + utilities

Styles

Components in this package style themselves with Tailwind utility classes (className="bg-primary text-primary-foreground rounded-md ..."). Tailwind classes are not real CSS — they are tokens that Tailwind translates into CSS rules at build time. Without that translation, the markup has class attributes that mean nothing to the browser, and components render unstyled.

To make components render correctly, import the pre-compiled CSS bundle once in your app's entry file:

// src/main.tsx (or app/layout.tsx, etc. — once per app)
import '@bardioc/ui/styles/bardioc-ui.css';

That bundle (~200 KB minified) contains:

• The full Tailwind v4 runtime base layer
• Every utility class actually used by Bardioc and shadcn components (tree-shaken at our build — unused utilities are excluded)
• Bardioc theme variables and color palette
• The shadcn theme layer (CSS custom properties for --background, --primary, --ring, etc., in both light and dark modes)
• tw-animate-css animation utilities
• Per-component custom CSS that lives alongside our components

Consumers do not need Tailwind installed to use the library. They do not need to configure @source or a content array. The single CSS import provides everything our components reference.

Two CSS entry points — which to use

| Entry | When to use | | ----------------------------------- | -------------------------------------------------------------------------------------- | | @bardioc/ui/styles/bardioc-ui.css | External consumers (npm install). Pre-compiled, fully self-contained. Default. | | @bardioc/ui/styles/globals.css | Monorepo siblings only. Source-style; you run Tailwind yourself and add @source. |

globals.css contains @import 'tailwindcss' plus @source '../../../../packages/**/...' directives that resolve only within this monorepo. It exists so siblings can extend Tailwind with their own app-specific class names while still sharing our theme tokens. In a node_modules install, those @source paths point at nonsense and the file does not work. Use bardioc-ui.css instead.

How the CSS is produced

The package build runs in three steps:

1. tsup bundles each JS/TSX entry to dist/ (no CSS handling).
2. node scripts/copy-assets.mjs copies the raw source CSS files (globals.css, shadcn.css, components/*.css, etc.) into dist/styles/ for monorepo-sibling consumers.
3. tailwindcss -i src/styles/build-bundle.css -o dist/styles/bardioc-ui.css --minify runs the Tailwind v4 CLI: it scans packages/ui/src/**/*.{ts,tsx} for class names referenced in our JSX, generates only the matching utility CSS, prepends the theme layer, and writes the single minified bundle.

The Tailwind compile step is what lets external consumers skip the toolchain entirely. The build artifact is portable, framework-agnostic CSS — the same file works in Next.js, Vite, plain HTML, or any bundler that supports CSS imports.

Theme overrides

bardioc-ui.css defines tokens as CSS custom properties (e.g. --primary, --background). Override them in consumer CSS after importing the bundle:

@import '@bardioc/ui/styles/bardioc-ui.css';

:root {
  --primary: oklch(0.6 0.2 250);
  --radius: 0.5rem;
}

For deeper theming (adding new utility colors, custom breakpoints, etc.), use the source-style globals.css path from a monorepo sibling and extend Tailwind directly.

Development

pnpm --filter @bardioc/ui build         # tsup + copy CSS + tailwind compile
pnpm --filter @bardioc/ui check-types
pnpm --filter @bardioc/ui test
pnpm --filter @bardioc/ui pack:check    # inspect what would be published

The package emits ESM JavaScript with declaration files. Tests live in packages/ui/tests/unit/ and are excluded from dist.