@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 | | 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/ui components directly from Server Components.
• Composition, not wrapping. Base UI semantics apply. Style <a> elements with anchorVariants() or the Anchor component (both exported from the package root) — never render links through Button asChild: anchors inherit button semantics that way and Base UI treats them as a native-button violation. Button asChild remains only for real render-composable buttons.
• Tokens only. Never use raw palette classes (bg-blue-500), arbitrary values (p-[13px]), or manual dark: colour overrides — dark mode and light mode are entirely token-driven ([data-theme='light']). className on 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; pulls three as optional peer).

Architecture

• src/primitives/ — shadcn-generated Base UI primitives (generated via npx shadcn@latest add, never hand-modified; refreshed with --overwrite)
• src/components/ — branded wrappers: tokens, cva variants, data-slot attributes, public API
• src/styles/index.css — token source of truth: brand palette (Section A, OKLCH) → semantic tokens (B) → component-scoped tokens (C) → Tailwind @theme mapping (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).