RhavenUI

Produktionsreifes Glassmorphism UI-Framework für React 19 mit eigener CSS-Engine (kein Tailwind), in TypeScript geschrieben und mit Storybook 9 dokumentiert.

Version: 1.0.0-rc1 · Paket: @rhavenside/rhaven-ui

Als npm-Paket verwenden

npm i @rhavenside/rhaven-ui
# oder
pnpm add @rhavenside/rhaven-ui

react und react-dom (>= 18) sind Peer-Dependencies und müssen im Projekt vorhanden sein.

Die CSS-Engine einmalig global importieren (z. B. in der Root-Layout-/Entry-Datei):

import "@rhavenside/rhaven-ui/styles.css";

Danach Komponenten nutzen:

import { ThemeProvider, AppShell, Button, KpiCard } from "@rhavenside/rhaven-ui";

export function App() {
  return (
    <ThemeProvider>
      <Button variant="primary">Los geht's</Button>
    </ThemeProvider>
  );
}

Hinweis: Komponenten, die auf Bild-Assets verweisen (Logo, Hintergrund), erwarten standardmäßig Pfade wie /branding/logo.png. Diese Assets stellst du in deinem Projekt selbst bereit oder überschreibst den src der Logo-Komponenten.

Voraussetzungen

• Node.js 20+
• pnpm 9+

Schnellstart

pnpm install
pnpm dev

Die App läuft standardmäßig unter http://localhost:3000.

| Route | Beschreibung | |-------|--------------| | / | Landing Page | | /dashboard | Dashboard-Mockup mit AppShell, Widgets, Charts | | /design-system | Interaktive Komponenten-Dokumentation |

Startbefehle

| Befehl | Beschreibung | |--------|--------------| | pnpm dev | Next.js Dev-Server (Turbopack) | | pnpm build | Production-Build | | pnpm start | Production-Server (nach Build) | | pnpm lint | ESLint via Next.js | | pnpm test | Vitest im Watch-Modus | | pnpm test:run | Vitest einmalig (CI) | | pnpm storybook | Storybook Dev-Server (Port 6006) | | pnpm build-storybook | Statischer Storybook-Build | | pnpm generate-branding | PNG-Favicons aus SVG generieren |

Verifikation (Release)

Vor jedem Release alle Checks ausführen:

pnpm build
pnpm lint
pnpm test:run
pnpm build-storybook

Erwartetes Ergebnis:

• Build: Exit 0, keine TypeScript-Fehler
• Lint: 0 Warnungen, 0 Fehler
• Tests: 18/18 grün (6 Test-Suites)
• Storybook: Build nach storybook-static/

Details und 32-Punkte-Audit: siehe RELEASE_CHECKLIST.md.

Nutzung im Projekt

Provider-Stack

RhavenUI erwartet den Provider-Stack aus src/app/layout.tsx:

<ErrorBoundary>
  <ThemeProvider defaultTheme="dark-default">
    <LocaleProvider defaultLocale="de">
      <BackgroundProvider>
        <LogoProvider>
          <ToastProvider>{children}</ToastProvider>
        </LogoProvider>
      </BackgroundProvider>
    </LocaleProvider>
  </ThemeProvider>
</ErrorBoundary>

Komponenten importieren

Alle öffentlichen APIs werden über den Barrel-Export bereitgestellt:

import {
  AppShell,
  Button,
  KpiCard,
  ThemeProvider,
  useTheme,
  useTranslation,
  useToast,
} from "@/design-system";

Der Alias @/ zeigt auf src/ (siehe tsconfig.json).

Beispiel: Dashboard-Shell

import { AppShell, Sidebar, TopCommandBar, Widget, WidgetGrid, KpiCard } from "@/design-system";

<AppShell
  sidebar={<Sidebar items={navItems} activeId="dashboard" variant="expanded" />}
  topbar={<TopCommandBar userName="Demo User" onCreate={() => {}} />}
  main={
    <WidgetGrid>
      <Widget id="kpis" title="Metriken" className="col-span-12">
        <KpiCard title="Umsatz" value="€ 12.4k" changePercent={8.2} />
      </Widget>
    </WidgetGrid>
  }
/>

Themes

Vier Themes: dark-default, dark-blue, light-default, light-warm. Wechsel über useTheme() oder Theme-Switcher in der Demo.

i18n

Deutsch (Standard) und Englisch über useTranslation(). Locale-Persistenz in localStorage.

Komponentenübersicht

Alle exportierten Komponenten sind in src/design-system/index.ts definiert. Storybook-Stories liegen neben den jeweiligen Komponenten (*.stories.tsx).

Theme & Infrastruktur

| Modul | Exporte | |-------|---------| | Theme | ThemeProvider, useTheme, themeDefinitions | | i18n | LocaleProvider, useTranslation, useLocale | | Branding | LogoProvider, Logo, LogoIcon, LogoMark | | Background | BackgroundProvider, useBackground | | Motion | fadeIn, slideUp, hoverLift, glowPulse, cardReveal, … | | Tokens | Farben, Spacing, Radius, Shadows, Typography | | A11Y | useStableId, useMergedRef, useRovingTabIndex | | Hooks | useWidgetPersistence |

Layout & Shell

AppShell, Sidebar, TopCommandBar, WorkspaceDock, AppLauncher, RecentApps, WorkspaceSwitcher, BackgroundProvider, CommandPalette

Dashboard

WidgetGrid, Widget, DashboardCard, KpiCard, TaskList, ProjectTable, ActivityPanel, QuickActions, CalendarPanel, MobileDashboardPreview

Basis & Data Display

Button, IconButton, Badge, AvatarStack, ProgressBar, DataGrid, EmptyState

Forms (9 Komponenten)

TextInput, Textarea, SearchInput, Select, MultiSelect, Checkbox, Switch, DatePicker, FormField

Charts

Sparkline, LineChartCard, AreaChartCard, BarChartCard, DonutChartCard, useChartTheme

Overlays & Feedback

Modal, Drawer, ConfirmDialog, NotificationCenter, Toast, ToastProvider, useToast, ErrorBoundary

Loading (Skeleton)

Skeleton, CardSkeleton, ChartSkeleton, TableSkeleton, SidebarSkeleton

Docs (intern)

ComponentDoc, CodeBlock, PropsTable, ThemePreview — für die /design-system-Seite

Projektstruktur

src/
├── app/                    # Next.js App Router (/, /dashboard, /design-system)
├── design-system/          # UI-Framework
│   ├── components/         # React-Komponenten + Stories
│   ├── charts/             # Chart-Karten + Stories
│   ├── forms/              # Formular-Komponenten
│   ├── theme/              # Theme Engine
│   ├── i18n/               # Übersetzungen de/en
│   ├── tokens/             # Design Tokens
│   ├── motion/             # Animations-Utilities
│   ├── branding/           # Logo & Favicon
│   ├── a11y/               # Accessibility-Helfer
│   ├── hooks/              # Custom Hooks
│   ├── docs/               # Doc-Komponenten
│   ├── demo-data.ts        # Mock-Daten
│   └── index.ts            # Barrel-Export
├── demo-data/              # Aliase für Demo-Seiten
└── test/                   # Vitest Setup
.storybook/                 # Storybook-Konfiguration
public/                     # Assets, PWA-Manifest, Branding

Storybook

pnpm storybook          # http://localhost:6006
pnpm build-storybook    # → storybook-static/

52 Stories für alle produktiven UI-Komponenten (Default, Varianten, Loading/Empty/Error wo relevant).

Tests

pnpm test:run

Pflicht-Tests: ThemeProvider, useTranslation, DataGrid, Widget-Persistence, CommandPalette, ToastProvider.

Changelog & Release

• CHANGELOG.md — Versionshistorie
• RELEASE_CHECKLIST.md — 32-Punkte-Audit und Verifikationsprotokoll

Lizenz

Private Projekt-Konfiguration ("private": true in package.json).