0 Fork 0

Files

T

dejanandClaude Opus 5 0875ae2688 feat(carbon): Carbon-Konformität nachprüfbar machen statt behaupten

Recherche an der Quelle statt an der Dokumentation. Zwei Ergebnisse:

1. Carbon regelt Datenvisualisierung nur teilweise. Farben, Gitter, Achsen,
   Tooltip und Tickanzahl sind verbindlich festgelegt — Paddings, Margins und
   Dashboard-Raster dagegen NICHT. Die Carbon-Seiten zu Chart-Anatomie und
   Dashboards tragen ausdrücklich den Hinweis "this guidance is a work in
   progress" und enthalten keine Zahlenwerte. Unsere Abstandswerte stammen
   deshalb aus der Carbon-Spacing-Skala und der Planung mit dem Branchenpartner,
   nicht aus der Data-Viz-Norm. Das steht jetzt so in DESIGN-SYSTEM.md §0.

2. Eine echte Abweichung gefunden: Der Tooltip ist seit Carbon v11 hell
   (--cds-layer-02 #ffffff auf --cds-text-primary #161616, abgesetzt allein
   durch den Schatten). Unser Theme führte den dunklen v10-Stand (#393939) und
   berief sich dabei auf das ausgelieferte Stylesheet — die Angabe war veraltet.
   Korrigiert.

Neu:
- docs/carbon-referenz.json — kanonische Werte mit Quelle, Version und
  Prüfdatum, gezogen aus @carbon/charts 1.23.0 styles.min.css und
  configuration.ts. Bewusste Abweichungen (Balkenbreite 48 statt 16, feste
  Kategoriefarben statt n-Serien-Paletten) sind dort begründet.
- scripts/verify-carbon.mjs + npm run verify:carbon — gleicht chartTheme.ts
  gegen die Referenz ab und bricht bei Drift ab.
- docs/PRUEFFRAGEN.md — Prüffragen für die Gestaltungsabnahme mit
  nachprüfbarem Ja/Nein, plus Leseliste (FT Visual Vocabulary, IBCS,
  Cleveland & McGill, Few, Datawrapper Academy).

Die 14er-Palette wurde gegen die CSS-Variablen --cds-charts-14-1-* geprüft und
stimmt exakt; ebenso Gitter #e0e0e0, Achse #8d8d8d und Achsentext #525252.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QPeZNwSeU7qG3RRCwaxEZX

2026-08-29 17:53:51 +02:00

6.3 KiB

Raw Blame History

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

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

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.

6.3 KiB Raw Blame History