# Design-System: Datenvisualisierung Grundlage ist **IBM Carbon Data Visualization**, ergänzt um die Spacing- und Zahlenregeln aus der eigenen Planung (`UI_UX_GUIDELINES.md`, Januar 2026). Die konkreten Farb- und Linienwerte sind aus dem ausgelieferten Stylesheet von `@carbon/charts` (Light Theme) übernommen, nicht aus der Dokumentation abgeschrieben. Alles Folgende ist in `features/dashboard/utils/chartTheme.ts` als Code hinterlegt. ## 0. Was Carbon regelt, und was nicht Wichtig für jeden, der hier etwas anzweifelt: **Carbon regelt Datenvisualisierung nur teilweise.** Die Grenze verläuft so: | Frage | Regelt Carbon? | Wo steht die Antwort | |---|---|---| | Farbpalette, Reihenfolge, Statusfarben | **ja, verbindlich** | ausgeliefertes Stylesheet, CSS-Variablen `--cds-charts-14-1-*` | | Gitter-, Achsen- und Textfarben | **ja** | dieselben Quellen | | Tooltip-Aufbau | **ja** | `.cds--cc--tooltip` im Stylesheet | | Tickanzahl je Achse | **ja** | `configuration.ts` (y: 5, x: 15) | | Wann welcher Diagrammtyp | teilweise, qualitativ | Carbon „Simple/Complex charts" | | **Padding, Margins, Kartenabstände** | **nein** | siehe unten | | Dashboard-Raster, Kartenhöhen | **nein**, nur Prinzipien | siehe unten | Die Carbon-Seiten zu Chart-Anatomie und Dashboards tragen ausdrücklich den Hinweis „this guidance is a work in progress" und enthalten **keine Zahlenwerte** für Abstände. Wer dort nach Paddings sucht, findet Prinzipien („create a clear visual hierarchy", „limit the number of metrics"): richtig, aber nicht nachprüfbar. **Die Abstandswerte in diesem Dokument stammen deshalb nicht von Carbon**, sondern aus zwei anderen Quellen: 1. der **Carbon-Spacing-Skala und dem 2x-Grid** des allgemeinen Design-Systems (4/8/12/16/24/32/48…): dieselbe Skala, aus der auch Davids `INTERIM-UI-DESIGN-STANDARDS.md` im Zielsystem schöpft; 2. der eigenen Planung mit dem Branchenpartner (`UI_UX_GUIDELINES.md`). Beides ist konsistent zueinander. Es ist aber ehrlicher zu sagen: Bei Farben und Achsen folgen wir einer Norm, bei Abständen einer begründeten Hauskonvention. **Nachprüfbar gemacht:** `npm run verify:carbon` gleicht `chartTheme.ts` gegen `docs/carbon-referenz.json` ab: Palette, neutrale Werte, Tooltip, Achsenraster. Die Referenzdatei nennt Quelle, Version und Prüfdatum. Bewusste Abweichungen (Balkenbreite, feste Kategoriefarben) sind dort begründet hinterlegt und werden als Hinweis ausgegeben, nicht als Fehler. --- ## 1. Farben ### Kategoriale Palette (14 Farben, Reihenfolge verbindlich) ``` 1 #6929c4 2 #1192e8 3 #005d5d 4 #9f1853 5 #fa4d56 6 #520408 7 #198038 8 #002d9c 9 #ee5396 10 #b28600 11 #009d9a 12 #012749 13 #8a3800 14 #a56eff ``` Die Reihenfolge ist auf Unterscheidbarkeit optimiert, auch bei Farbfehlsichtigkeit und in Graustufen. Farben deshalb **immer von vorne vergeben**, nie nach Geschmack auswählen und nie umsortieren. **Maximal fünf Kategorien je Chart.** Alles darüber fasst `gruppiereRest()` zu „Sonstige" zusammen. Ein Ring mit zwölf Segmenten ist keine Information mehr, sondern Dekoration. ### Statusfarben (nur für Aussagen, nie für Kategorien) | Bedeutung | Wert | |---|---| | positiv | `#198038` | | Warnung | `#b28600` | | negativ | `#da1e28` | | neutral | `#8d8d8d` | | Information | `#1192e8` | Kategorie- und Statusfarben nie im selben Chart mischen, eine grüne Kategorie neben einem grünen Positiv-Status ist nicht mehr eindeutig lesbar. **Rangfolgen einfarbig.** Top-Kunden oder Aufträge je Mitarbeiter sind keine Kategorien: Dort trägt die Farbe keine Information, und eine bunte Palette erzeugt nur Unruhe. Palette nur, wenn die Farbe etwas bedeutet. ### Feste Farbzuordnung Wiederkehrende Kategorien behalten ihre Farbe über alle Charts und Seiten hinweg (`GEWERK_FARBEN`, `STATUS_KATEGORIE_FARBEN` in `chartTheme.ts`). Sonst ist Heizung im Ring lila und im Balkendiagramm blau, und jede Legende muss neu gelesen werden. | Gewerk | Farbe | | Status | Farbe | |---|---|---|---|---| | Heizung | `#6929c4` | | Verloren / Überfällig | `#fa4d56` / `#da1e28` | | Sanitär | `#1192e8` | | In Arbeit / Bezahlt | `#198038` | | Klima & Lüftung | `#005d5d` | | Beauftragt | `#009d9a` | | Photovoltaik | `#9f1853` | | Angebot | `#6929c4` | | Elektro | `#198038` | | Entwurf / Sonstige | `#8d8d8d` | Bei Statuswerten trägt die Farbe Bedeutung: „Verloren" und „Überfällig" sind rot, „Bezahlt" grün. Eine zufällige Palettenfarbe für „Verloren" würde die Aussage der Grafik verwässern. ### Geordnete Dimensionen Altersklassen, Risikostufen und Ähnliches sind **keine Kategorien**, sondern eine Reihenfolge mit wachsendem Risiko. Dafür gilt die vierstufige Risikorampe (`RISIKO_RAMPE` in `chartTheme.ts`): durchgehend Statusfarben, keine Palettenfarbe dazwischen: | Stufe | Wert | Bedeutung | |---|---|---| | 1 | `#198038` | im Zahlungsziel | | 2 | `#b28600` | beobachten | | 3 | `#ba4e00` | mahnen | | 4 | `#da1e28` | Abschreibungsrisiko | ### Einzelserien | Rolle | Wert | |---|---| | Hauptreihe (Umsatzverlauf o. Ä.) | `#1192e8` | | Vergleichsreihe (Vorjahr) | `#8d8d8d`, gestrichelt | Die Vergleichsreihe ist bewusst neutral: Sie soll einordnen, nicht konkurrieren. --- ## 2. Achsen und Gitter | Element | Wert | Begründung | |---|---|---| | Gitterlinien | `#e0e0e0`, **nur horizontal** | Vertikale Linien zerschneiden den Verlauf | | Achsenlinie | `#8d8d8d`, 1 px | Nur an der X-Achse; die Y-Achse braucht keine | | Tick-Marks | keine | Die Beschriftung reicht als Orientierung | | Beschriftung | 12 px, `#525252` | Carbon-Standard | | Y-Achsen-Breite | 58 px | Platz für „245 T€" ohne Umbruch | Bei mehr als 12 Datenpunkten wird nur jede n-te Beschriftung gezeigt, sonst überlappen sie (`MAX_ACHSENLABELS` in `chartTheme.ts`, eine Konstante für alle Diagrammtypen). **Achsenwerte sind rund.** Recharts leitet Ticks aus `max/(n-1)` ab und rundet den Rohschritt auf; bei 219 T€ ergibt das 0/55/110/165/220. Krumme Achsenwerte kosten den Leser bei jedem Blick eine Rechenoperation. `nettesRaster()` erzwingt deshalb Schrittweiten aus der 1-2-2,5-5-Reihe. **Die Einheit gehört zur Achse, nicht zum Wert.** `achsenFormat(max)` wählt sie einmal aus dem Achsenmaximum. Sonst steht „0 €" neben „10 T€" und die Skala wechselt mitten im Lesen die Einheit; die Nulllinie trägt gar keine Einheit. --- ## 3. Tooltip Einheitlich für alle Charts (`components/charts/ChartTooltip.tsx`), Werte aus `.cds--cc--tooltip` im ausgelieferten Stylesheet: - Fläche `#ffffff` (`--cds-layer-02`), Text `#161616` (`--cds-text-primary`) - abgesetzt allein durch den Schatten `0 1px 6px 0 rgba(0,0,0,.2)`: **kein Rahmen** - Label und Reihenname 12 px in `#525252`, Wert fett in Tabellenziffern - kein Doppelpunkt zwischen Name und Wert, maximal 270 px breit - Farbmarker je Reihe, 10 × 10 px **Achtung bei älteren Quellen:** Bis Carbon v10 war der Tooltip dunkel (`#393939` auf weißem Text). Sehr viele Artikel und Screenshots zeigen noch diesen Stand. Maßgeblich ist das ausgelieferte Stylesheet, nicht die Bildersuche. Ein gemeinsamer Tooltip verhindert, dass jedes Chart eigene Regeln entwickelt. --- ## 4. Balken, Flächen, Ringe | Element | Regel | |---|---| | Balkenbreite | maximal 48 px | | Balkenabstand | mindestens halbe Balkenbreite (`barCategoryGap: 28 %`) | | Balkenecken | 2 px, nur an der Werteseite | | Linienstärke Fläche | 2 px, Verlaufsfüllung 24 % → 2 % | | Interpolation | **linear**, eine Monotone-Kurve erfindet Zwischenwerte zwischen zwei Messpunkten | | Punkte | nur beim Hovern, Radius 4, weißer Rand | | Ring innen/außen | 62 % / 88 %, 2° Segmentabstand | | Ringmitte | Gesamtwert, sonst muss man die Segmente addieren | | Ringlegende | rechts, einzeilig, mit Wert und Prozentanteil | Ringsegmente starten oben (12 Uhr) mit dem größten Wert und laufen im Uhrzeigersinn absteigend. Auch „Sonstige" wird nach Größe einsortiert, nicht ans Ende gehängt. **Ein Ring braucht ein echtes Ganzes.** Beträgt ein Segment über 80 %, trägt die Grafik nichts mehr bei, dann ist die Bezugsgröße falsch gewählt. Beispiel: Der Rechnungsbestand aus zwei Jahren gegen den heutigen Forderungsstand ergibt 92 % „Bezahlt". Richtig ist der offene Bestand allein; dann zeigt der Ring, wie viel davon bereits überfällig ist. ### Werte in einem engen Band: Punkt statt Balken Auslastung liegt betrieblich zwischen etwa 70 und 100 %. Ein Balken **muss** bei Null beginnen, sonst verzerrt seine Länge, und dann sind 74 % und 96 % optisch fast gleich lang. Ein Punkt kodiert über die **Position**, nicht über die Länge, und darf deshalb einen ausgeschnittenen Bereich zeigen. Der Zielkorridor liegt als graues Band hinter den Punkten, die 100-%-Marke als beschriftete Linie, darunter eine Achse. Damit erklärt sich die Grafik ohne Ampel-Legende, und tote Legendeneinträge („Luft frei", wenn niemand darunter liegt) entfallen. --- ## 5. Abstände (8-px-System) | Bereich | Wert | |---|---| | Seitenrand | 24 px | | Abstand zwischen Karten | 16 px | | Innenabstand Karte | 16 px | | Kopf zu Inhalt in der Karte | 12 px | | Label zu Wert in der KPI-Karte | 4 px | | Icon zu Text | 8 px | **Grundregel: innen ≤ außen.** Ist der Innenabstand größer als der Abstand zwischen den Karten, zerfällt das Raster optisch. --- ## 6. Typografie | Rolle | Größe | Gewicht | |---|---|---| | Seitentitel | 22 px | 600 | | KPI-Wert | 28 px | 600 | | Kartentitel | 14 px | 600 | | Fließtext / Tabelle | 13 px | 400 | | Label, Achsen, Legende | 12 px | 400–500 | | Kleinstschrift (Meta) | 11 px | 400 | Eine Schriftfamilie: **Instrument Sans**, selbst gehostet aus denselben Schriftdateien wie die Software (`public/fonts/`, variabel 400–700). Vorher lief der Prototyp auf Inter, während `ui/theme.css` für alle Subframe-Typo-Token bereits „Instrument Sans" verlangte: zwei Schriften auf einer Seite, keine davon die der Software. Zahlen immer in Tabellenziffern (`font-variant-numeric: tabular-nums`, global gesetzt), damit Spalten untereinander stehen. --- ## 7. Zahlenformate (deutsch) | Fall | Ausgabe | |---|---| | Währung, KPI | `238.412 €` | | Währung, kompakt (Achsen, Balken) | `8,4 T€` · `245 T€` · `1,25 Mio. €` | | Prozent | `58,2 %` | | Tage / Stunden | `34,2 Tage` · `7,5 h` | | Datum | `30.07.2026`, kurz `30.07.`, Monat `Jul 26` | Punkt als Tausendertrenner, Komma als Dezimaltrenner. Innerhalb einer Ansicht immer dasselbe Format, nicht in einer Zeile `245.000 €` und in der nächsten `245 T€`. --- ## 8. Zustände Jedes Chart braucht einen **Leerzustand**: Filter können jede Ansicht leer laufen lassen. `ChartLeer` zeigt dann eine gestrichelte Fläche mit Hinweistext statt eines leeren Rechtecks. Hover-Zustände: Karten erhalten einen stärkeren Schatten, Balken und Ringsegmente werden hervorgehoben (die übrigen auf 35–45 % Deckkraft). Tabellenzeilen bekommen **keinen** Hover, solange sie nicht anklickbar sind, ein Hover ohne Ziel verspricht eine Interaktion, die es nicht gibt. ## 9. Textabstände und Umbruch Zwei Regeln, die Carbon nicht als Zahl nennt, ohne die eine Oberfläche aber kaputtgeht: **Mindestens 8 px zwischen benachbarten Textelementen** (Carbon-Spacing-Token `$spacing-03`, der kleinste Abstand der Skala). Alles darunter liest sich als zusammengehörig, bei 0 px kleben Beschriftung und Wert aneinander. **Kein Text läuft aus seinem Kasten.** Die häufigste Ursache ist `min-w-0` zusammen mit `grow` ohne `truncate` oder `break-words`: Der Kasten schrumpft auf null, der Text bleibt stehen und läuft in das Nachbarelement. Deshalb trägt jedes Textfeld, das schrumpfen kann, entweder `truncate` (wenn Kürzen vertretbar ist) oder `break-words` (wenn nicht). Dateipfade und lange Einzelwörter brauchen zwingend `break-words`, sie haben keine Leerzeichen zum Umbrechen. **Legenden weichen nach unten aus.** Carbon sagt, die Legende gehört rechts neben das Diagramm, „when space is plentiful". Ist der Platz nicht reichlich, rutscht sie unter das Diagramm, statt Namen und Werte ineinanderlaufen zu lassen. Gesteuert über **Container-Queries** (`@container` / `@md:`), nicht über den Viewport: Dieselbe Karte nimmt mal ein Drittel und mal die halbe Seitenbreite ein, der Viewport weiß davon nichts. **Nachprüfbar gemacht:** `npm run verify:layout` lädt alle sechs Seiten in sieben Fensterbreiten (1024–1920) und misst jede Textzeile. Kollisionen unter 8 px und Text, der seinen Kasten verlässt, brechen den Lauf ab. Warum das ein eigener Prüfer sein muss: Diese Fehler treten **nur in bestimmten Breiten** auf. Die Ringlegende auf der Finanzseite kollidierte bei 1280 und 1440 px und war bei 1600 px unauffällig: auf einem Screenshot also unsichtbar. Auge und Einzelbild reichen dafür nicht. ## 10. Fokus und Kontrast **Fokus** ist eine einzige Regel in `app/globals.css` statt `focus:`-Klassen an jedem Element: ```css :where(a, button, [role="button"], input, select, textarea, [tabindex]):focus-visible { outline: none; box-shadow: var(--shadow-focus); border-radius: var(--radius-sm); } ``` `:focus-visible` zeigt den Ring nur bei Tastaturbedienung. Overlays (Filter- Dropdown, Karten-Menü) schließen mit **Escape** und geben den Fokus an den auslösenden Knopf zurück. **Kontrast:** `--color-text-neutral-tertiary` liegt auf `neutral-700` (5,15:1 auf Weiß), nicht auf `neutral-600` (3,68:1, unter WCAG AA). Das entspricht dem a11y-Override im Zielsystem. `text-neutral-subtle` ist ein Placeholder-Token und für lesbaren Text nicht geeignet. --- ## Kartenhöhen in einer Zeile **Gestreckt wird nur, wenn die Karten einer Zeile dieselbe Bauart haben.** Zwei Listen, zwei Zeitverläufe, zwei Tabellen: da gibt die eine Karte eine Höhe vor, die die andere ohnehin fast erreicht, und der Rest verteilt sich oben und unten je zur Hälfte (`justify-center` im Kartenkörper). **Steht ein Diagramm mit fester Höhe neben einer Liste, bleibt die Zeile oben bündig.** Dann hört jede Karte dort auf, wo ihr Inhalt aufhört, und der Höhenunterschied wird zu Weißraum auf der Seite. Das ist gemessen, nicht geschätzt. Höhenunterschiede innerhalb einer Zeile bei 1680 px: | Zeile | volle Daten | dünne Daten | |---|---|---| | Vertriebstrichter ∣ Auslastung (zwei Listen) | 0 px | 0 px | | Zahlungseingang ∣ Offener Bestand (zwei Diagramme) | 0 px | 0 px | | Zahlungseingang ∣ Umsatz nach Gewerk (Diagramm ∣ Liste) | 147 px | **315 px** | | Vorgänge nach Status ∣ nach Gewerk (Diagramm ∣ Liste) | 190 px | **358 px** | Der Grund steckt in der Liste: Eine Balkenliste hat keine Mindesthöhe. Fünf Kategorien ergeben 280 px, eine einzige 112 px: daneben liegt ein Zeitverlauf unverändert bei 427 px, weil seine Diagrammfläche fest ist. Diese Zeilen zu strecken hieße, eine Karte mit einem Balken auf 427 px aufzublasen. Das ist schlimmer als die Lücke, die es vermeiden soll: Weißraum auf der Seite liest sich als „hier ist gerade wenig", eine riesige Karte mit einem Balken darin als Fehler. **Zeilen mit Tabellen bleiben ebenfalls oben bündig**, auch wenn zwei Tabellen nebeneinander von Natur aus gleich hoch sind. Eine Tabelle hat eine eigene Fußzeile zum Blättern; sie zu strecken schiebt nur die Blätterleiste nach unten. **Auf dem Dashboard ist die Zeile aus Zeitverlauf und Balkenliste trotzdem gestreckt.** Das ist kein Widerspruch, sondern derselbe Maßstab: Der Unterschied entsteht dort gar nicht erst groß, weil das Dashboard keinen Filter hat, jede Kachel zeigt ihren festen Zeitraum, die Balkenliste hat immer ihre fünf Gewerke, und es bleiben rund 90 px, die sich oben und unten verteilen. In Analytics kann derselbe Unterschied durch einen Filter auf 315 px wachsen. Der Filter ist der Unterschied, nicht die Kachel. Die Karten sind in allen Fällen dynamisch: nirgends steht eine feste Höhe. Kommt mehr Inhalt hinein, wächst die Karte. --- ## Ansprache **Die Anwendung duzt.** „2 Punkte brauchen heute deine Aufmerksamkeit", nicht „Ihre". Das gilt für jeden Text, der den Benutzer anspricht: Begrüßung, Leerzustände, Hinweise, Fehlermeldungen. Halb geduzt liest sich schlechter als durchgehend gesiezt: Sobald zwei Sätze auf derselben Seite unterschiedlich ansprechen, klingt die Anwendung wie von zwei Leuten geschrieben. Beim Einbau gilt im Zweifel die Ansprache von HiveGrid, sie hat nach [ZIELSYSTEM.md](ZIELSYSTEM.md) Abschnitt 0 den Vorrang. **Namen im Prototyp stehen in eckigen Klammern.** Die Begrüßung zeigt „Guten Tag, [Vorname]" und nicht einen erfundenen Namen. Ein fester Name sieht in einer Abnahme aus wie ein fest verdrahteter Wert, und irgendwann fragt jemand, warum dort immer derselbe steht. Die Klammern sagen, was an der Stelle eingesetzt wird; beim Einbau kommt der Wert aus der Sitzung (`data/nutzer.ts` → `requireMember`).