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

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 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).