HiveGrid Analytics Dashboard — UI/UX-Prototyp

Gestaltungsvorlage für die Analytics-Dashboards in HiveGrid, fachlich auf einen SHK-/Handwerksbetrieb zugeschnitten. Ziel dieses Repos ist die Übergabe an die Entwicklung — nicht der Produktivbetrieb.

npm install
npm run dev     # http://localhost:4300

---

Was hier drin ist

Bereich	Inhalt
6 Seiten	Übersicht, Finanzen, Aufträge, Kunden, Team, Komponenten
26 KPIs	vollständig definiert in docs/KPI-KATALOG.md
9 Chart-Bausteine	Fläche, Säulen, liegende Balken, Ring, Trichter, Auslastung, Sparkline, Legende, Leerzustand
Filtersystem	Zeitraum + 5 Dimensionen, seitenabhängig relevant, in localStorage persistiert
Demo-Datensatz	deterministisch erzeugt: 420 Kunden, 1.900 Aufträge, ~1.260 Rechnungen, 2,4 Mio. € Jahresumsatz

Alles ist deutschsprachig, weil die Oberfläche deutschsprachig ist — inklusive Bezeichner im Code. Das erspart beim Einbau die ständige Übersetzung zwischen revenue und „Umsatz".

---

Wo was liegt

app/                          Next.js App Router — je Seite nur ein Wrapper
features/dashboard/
  routes/                     Verdrahtung Store → View-Model → Seite (wird beim
                              Einbau durch den Loader ersetzt)
  view-models/                VMState-Vertrag + reine Builder je Seite
  components/
    layout/                   AppShell, PageHeader, PageContainer, Navigation
    cards/                    KPICard, ChartCard, AlertList, StatZeile
    charts/                   alle Visualisierungen + gemeinsamer Tooltip
    filters/                  Filterleiste und Mehrfachauswahl
    tables/                   DataTable (sortieren, suchen, blättern) + Badges
  context/                    Filter-, Widget- und Toast-State
  data/                       types · seed (Dummy-Daten) · calculations · filtering
  hooks/                      useAnalyseDaten
  pages/                      die sechs Seiten — reine Komponenten ({ vm })
  utils/                      chartTheme (Carbon-Tokens), formatters, dateUtils
ui/                           Subframe-Komponentenbibliothek (unverändert übernommen)
docs/                         Design-System, KPI-Katalog, Navigation, Datenmodell,
                              Herkunft, Zielsystem, Leitplanken, Prüffragen
scripts/verify-carbon.mjs     gleicht chartTheme.ts gegen die Carbon-Referenz ab
scripts/verify-layout.mjs     misst Textkollisionen über alle Seiten und Breiten

Wichtigste Dateien für den Einbau: features/dashboard/data/calculations.ts (jede Kennzahl als reine Funktion) und features/dashboard/view-models/ (je Seite ein reiner Builder (daten, filter) → VMState<…>).

Die Seiten unter pages/ sind reine Komponenten — sie bekommen ihr View-Model als Prop und greifen auf keinen Store zu. Das ist genau das Muster, das HiveGrid Cloud verlangt (<XPage vm={} actions={} />): Beim Einbau tritt der Loader an die Stelle des Containers unter routes/, die Seiten selbst bleiben unverändert. Details in docs/ZIELSYSTEM.md Abschnitt 3.1.

---

Grundlagen

Drei Quellen sind hier zusammengeführt:

1. Fachliche Planung (Januar 2026, mit dem Branchenpartner erarbeitet) — Seitenschnitt, KPI-Auswahl, Filtersystem, Zahlen- und Spacing-Regeln.
2. Bestehender Pitch-Prototyp — die Subframe-Komponentenbibliothek unter ui/ und die Gestaltungssprache der Oberfläche.
3. IBM Carbon Data Visualization — Chart-Regeln, Farbpalette, Achsen, Tooltips. Siehe docs/DESIGN-SYSTEM.md.

Welche Quelle was beigesteuert hat — und an welchen Stellen bewusst von der Januar-Planung abgewichen wurde — steht in docs/HERKUNFT.md.

---

Für die Entwicklung

HANDOVER.md listet auf, was echte Logik braucht, was bewusst Attrappe ist und in welcher Reihenfolge der Einbau sinnvoll ist.

Die Seite /komponenten zeigt jeden Baustein isoliert mit Dateipfad — der schnellste Weg, sich zu orientieren.

npm run verify:carbon   # Palette, neutrale Werte, Tooltip, Achsenraster gegen IBM Carbon
npm run verify:layout   # kollidierender oder überlaufender Text, 6 Seiten × 7 Fensterbreiten

verify:layout braucht den laufenden Dev-Server. Es misst jede Textzeile im Browser, weil Layoutfehler nur in bestimmten Fensterbreiten auftreten und auf einem Screenshot deshalb unsichtbar bleiben.

Die Referenzwerte stehen mit Quelle und Version in docs/carbon-referenz.json, gezogen aus dem ausgelieferten Stylesheet von @carbon/charts — nicht aus der Dokumentation, die an mehreren Stellen davon abweicht.

Für die Gestaltungsabnahme: docs/PRUEFFRAGEN.md — Prüffragen mit nachprüfbarem Ja/Nein, für Reviews ohne Designerauge.

---

Zielsystem

Eingebaut wird das hier in HiveGrid Cloud (HiveGrid-Cloud, Gitea toolctrl-labs) — die eigentliche Software: pnpm-Monorepo, React Router 7, Prisma/Postgres, mandantenfähig. Zielort ist der Tenant-Dashboard-Screen unter …/<tenant>/dashboard.

Dort steht bereits eine Implementierung — bewusst als Interim-UI: gebaut aus derselben Subframe-Bibliothek gegen ein stabiles View-Model, damit die Backend-Tickets nicht auf den finalen Screen warten müssen. Die finale Optik ist dort als Nachzug vorgemerkt. Genau die Lücke füllt dieser Prototyp.

Die Ausgangslage ist günstiger als üblich: dasselbe Subframe-Projekt (82 der 86 Komponenten identisch benannt) und dieselbe Chart-Bibliothek (Recharts). Der Einbau ist ein Port, keine Neuimplementierung.

Anzupassen sind vor allem vier Dinge — Daten kommen als View-Model-Prop mit fünf Zuständen statt als Import, Texte laufen über i18n, Diagramme brauchen eine Textalternative für Screenreader, und das App-Chrome dieses Prototyps entfällt, weil die Zielanwendung Shell und Sidebar mitbringt.

Nicht alles in der Zielanwendung sieht heute final aus. HiveGrid Cloud arbeitet designer-first: Für jede Phase gibt es einen Brief mit den benötigten UI-Elementen, den finalen Screen entwirft der Designer in Subframe — Layout und Anordnung sind ausdrücklich dessen Entscheidung. Ein großer Teil dieser Screens ist noch offen und läuft bis dahin auf Interim-UI. Für diesen Prototyp heißt das: Verbindlich zu übergeben sind Kennzahl-Definitionen, Chart-Regeln und Verhalten — die Pixelanordnung ist ein Vorschlag.

Details, Dateipfade und die konkrete Einbau-Liste stehen in docs/ZIELSYSTEM.md. Welche Bereiche der Zielanwendung bereits finale Subframe-Screens tragen — und damit als Leitplanke taugen — steht in docs/LEITPLANKEN.md.