dejanandClaude Opus 5
885c7b9609
Sie war als "Referenz fuer den Einbau" ausgeschildert. Das trifft es nicht: Wer den Prototyp einbaut, liest Code und Doku und kann sich keine gerenderte Seite ansehen — die Datei-Pfade und DESIGN-SYSTEM.md tun diese Arbeit ohnehin. Nuetzlich ist die Seite fuer die Abstimmung mit Menschen: Auf den Analyse-Seiten sieht man von jedem Baustein immer nur den Zustand, den die Daten gerade hergeben. Neu ausgeschildert, und die fehlenden Zustaende ergaenzt: - Seitenzustaende (laedt / leer / Fehler). In HiveGrid sind alle fuenf VMState-Zustaende Pflicht, im Prototyp ist keiner davon je zu sehen, weil die Demo-Daten immer liefern. Gestaltet werden muessen sie trotzdem — "laedt", "nichts gefunden" und "kaputt" sind drei verschiedene Aussagen. - Dashboard-Kacheln: Begruessung, WidgetKachel, reservierte Kachel. Das Dashboard benutzt nicht ChartCard, sondern einen eigenen Rahmen; bisher war der in der Galerie gar nicht vertreten. Zwei Fehler dabei gefunden und behoben: - Die Regelliste nannte noch den dunklen Tooltip (#393939). Seit Carbon v11 ist er hell (#ffffff auf #161616); im Code war das laengst umgestellt, auf dieser Seite nicht. Eine Referenzseite, die eine ueberholte Regel behauptet, ist schlimmer als keine. - Die Abschnittstexte beginnen mit einem Dateipfad, und ein Pfad ist ein Wort ohne Trennstelle. Bei 375 px lief "features/dashboard/components/layout/SeitenZustand.tsx" neun Pixel ueber den Rand — von verify:layout gefunden. Die Regel zu den Kartenhoehen aus dem letzten Commit steht jetzt auch hier. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01QPeZNwSeU7qG3RRCwaxEZX
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.
Zwei Features, nicht eines. „Analytics" ist der Analysebereich mit fünf Seiten und einem seitenweiten Filter; „Dashboard" ist der Begrüßungsbildschirm — eine Seite aus Kacheln, jede mit eigenem Zeitraum. Es zeigt die wichtigsten Auswertungen plus anderes (HR-Anträge, Aufgaben, Termine), das noch nicht gebaut ist und im Raster als reservierte Plätze steht. Beide sind gestaltet; offen ist, was aus der Analytics-Übersichtsseite wird, deren Inhalt sich mit dem Dashboard überschneidet. Stand und offene Punkte in
docs/SCOPE-ANALYTICS-DASHBOARD.md.
npm install
npm run dev # http://localhost:4300 → leitet auf /dashboard
Was hier drin ist
| Bereich | Inhalt |
|---|---|
| 5 Analyse-Seiten | Übersicht, Finanzen, Aufträge, Kunden, Team — als Reiter im Menüpunkt Analytics |
| Seitenleiste | spiegelt die von HiveGrid Cloud (dieselbe Komponente, dieselben Gruppen) |
| 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
dashboard/ Kachelraster, Kachelrahmen, Begrüßung (nur /dashboard)
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
· nutzer (Attrappe des angemeldeten Benutzers)
hooks/ useAnalyseDaten, useIstSchmal
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, Scope
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:
- Fachliche Planung (Januar 2026, mit dem Branchenpartner erarbeitet) — Seitenschnitt, KPI-Auswahl, Filtersystem, Zahlen- und Spacing-Regeln.
- Bestehender Pitch-Prototyp — die Subframe-Komponentenbibliothek unter
ui/und die Gestaltungssprache der Oberfläche. - 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.
Rangfolge: Wo dieser Prototyp von HiveGrid abweicht, gilt HiveGrid. Schrift, Größen, Abstände, Farben und App-Shell kommen von dort; aus diesem Repo kommen die Kennzahl-Definitionen, die Diagrammregeln, das Verhalten und die Navigationsstruktur als Verabredung.
Details, Dateipfade und die konkrete Einbau-Liste stehen in
docs/ZIELSYSTEM.md — die Rangfolge in Abschnitt 0. Welche Bereiche der Zielanwendung
bereits finale Subframe-Screens tragen — und damit als Leitplanke taugen — steht
in docs/LEITPLANKEN.md.