Dashboard/docs/DESIGN-SYSTEM.md

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:

: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

Karten einer Zeile sind gleich hoch, aber nicht gleich voll. Die Höhe gibt die inhaltsreichste Karte vor; die übrigen strecken sich mit und verteilen den Überschuss oben und unten je zur Hälfte (justify-center im Kartenkörper).

Vorher waren die Zeilen oben bündig (items-start), und jede Karte endete dort, wo ihr Inhalt endete. Bei ähnlich vollen Karten fiel das nicht auf. Bei dünner Datenlage schon: Ein Balkendiagramm mit einer einzigen Kategorie war 112 px hoch und stand neben einem Zeitverlauf mit 427 px — 315 px Seitenhintergrund als Loch dazwischen. Das liest sich nicht als „wenig Daten", sondern als „etwas ist kaputt".

Die Leere verschwindet dadurch nicht — sie zieht aus dem Seitenhintergrund in die Karte. Das ist der Unterschied zwischen einem Raster mit Lücken und einer Karte, in der gerade wenig steht.

Die Karten bleiben dabei dynamisch. Es gibt keine feste Höhe: Kommt mehr Inhalt hinein, wächst die Karte und mit ihr die ganze Zeile.

Ausnahme: Zeilen mit Tabellen. Eine Tabelle hat ein natürliches Ende und eine eigene Fußzeile zum Blättern. Sie zu strecken schiebt nur die Blätterleiste nach unten. Solche Zeilen bleiben oben bündig — im Prototyp die Reaktivierungs- und Zahlungsmoral-Tabellen auf der Kundenseite.