@bergetai/ui
Berget's React design system, built on Base UI, Tailwind CSS v4, and the shadcn component conventions. Published to the public npm registry; consumed by console, landing-page, and the Keycloak theme.
Installation
pnpm add @bergetai/ui
Peer dependencies
| Package | Range | Why |
|---|---|---|
react / react-dom | ^19 | App owns the React runtime (single copy) |
tailwindcss | ^4.1 | Utility generation happens in the consumer's build |
lucide-react | ^1 | Icon set |
motion | ^12 | Animation (only where used) |
shiki | ^4 | Syntax highlighting (only @bergetai/ui/shiki) |
three, @react-three/fiber | optional | Only @bergetai/ui/neural-flow (WebGL illustration) |
pnpm ≥ 8 and npm ≥ 7 install peers automatically; nothing extra to manage.
Setup (one stylesheet, imported once)
/* app/globals.css */
@import 'tailwindcss';
@import '@bergetai/ui/styles';
/* No @source needed: the stylesheet scans this package's own dist for you. */
Import order matters: @import 'tailwindcss' first, then @bergetai/ui/styles (tokens, base layer, component keyframes). Do not @import 'tailwindcss' anywhere else.
Why no @source is needed: Tailwind ignores node_modules during content detection, so the shipped stylesheet registers the package's own emitted modules via an @source that resolves relative to itself. If you import the sheet from the monorepo source (Storybook), add your own @source for the package's src/ instead.
Usage
import { Button, Card, CardHeader, CardTitle, CardContent } from '@bergetai/ui';
- RSC-safe. Every interactive module ships a
"use client"prologue; render@bergetai/uicomponents directly from Server Components. - Composition, not wrapping. Base UI semantics apply: use the
renderprop (neverasChild— deprecated), and style<a>elements withbuttonVariants()rather than rendering links throughButton. - Tokens only. Never use raw palette classes (
bg-blue-500), arbitrary values (p-[13px]), or manualdark:colour overrides — dark mode and light mode are entirely token-driven ([data-theme='light']).classNameon a component is for layout (margin, placement, width), not restyling; missing looks belong in the DS as variants. - Subpath exports.
@bergetai/ui(components),@bergetai/ui/styles(CSS tokens),@bergetai/ui/shiki(highlighter),@bergetai/ui/neural-flow(WebGL; pullsthreeas optional peer).
Architecture
src/primitives/— shadcn-generated Base UI primitives (generated vianpx shadcn@latest add, never hand-modified; refreshed with--overwrite)src/components/— branded wrappers: tokens, cva variants,data-slotattributes, public APIsrc/styles/index.css— token source of truth: brand palette (Section A, OKLCH) → semantic tokens (B) → component-scoped tokens (C) → Tailwind@thememapping (D)
Development: pnpm i at the repo root, then pnpm --filter @bergetai/ui dev (build watch), pnpm storybook, pnpm typecheck, pnpm spellcheck. Component work follows the .agents/skills/add-component skill.
Releases: workflow_dispatch on release.yml bumps the version, tags, and publishes to the npm registry via Trusted Publishing (OIDC).