Design-Token-Tool-Fehler: Wenn CSS-Analysen Farben und Stimmungen falsch deuten

Ein kleines Command-Line-Tool namens brandmd analysiert Webseiten und generiert automatisch eine Design-Dokumentation für KI-gestützte Entwicklungsumgebungen wie Cursor oder Gemini CLI. Doch als der Entwickler Yuvaraj Angad Singh kürzlich eine helle, cremefarbene Seite mit dem Tool analysierte, lieferte es überraschende Ergebnisse: Statt „hell und luftig“ wurde die Stimmung als „dunkel und moody“ eingestuft, Farben wurden falsch benannt und selbst einfache CSS-Eigenschaften wie border-radius führten zu absurden Ausgaben wie 3.35544e+07px.

Die Analyse offenbart fünf typische Heuristik-Fehler, die selbst in gut getesteten Tools auftreten – weil sie auf vereinfachten Annahmen basieren, die in der realen Welt nicht funktionieren. Hier sind die Ursachen und wie sie behoben wurden.

1. Die Stimmung einer Seite durch durchschnittliche Helligkeit bestimmen: Warum der Footer alles ruiniert

Die ursprüngliche Methode von brandmd berechnete die „Stimmung“ einer Seite, indem sie die durchschnittliche Helligkeit aller Farben auf der Seite bestimmte. Ein hoher Durchschnittswert sollte „hell und luftig“ bedeuten, ein niedriger „dunkel und moody“. Doch diese Logik versagt, wenn nur wenige Elemente – etwa ein dunkler Footer oder kleine Akzentfarben – die Durchschnittsberechnung verzerren.

In dem analysierten Beispiel hatte die Seite ein helles, cremefarbenes Design mit schwarzem Text und leuchtend blauen Akzenten. Ein dunkler Footer und einige dunkle Elemente zogen den Durchschnitt jedoch so weit nach unten, dass die gesamte Seite fälschlich als „dunkel“ eingestuft wurde – obwohl 90 % der Fläche hell und cremig waren.

Der Fehler lag darin, dass alle Farben gleich gewichtet wurden, unabhängig von ihrer tatsächlichen Fläche auf dem Bildschirm. Die Lösung: Statt den Durchschnitt zu berechnen, wird nun die dominante Hintergrundfarbe ermittelt – also die Farbe, die den größten Teil der sichtbaren Fläche einnimmt. Nur diese Farbe bestimmt die Stimmung. So wird sichergestellt, dass die Analyse die visuelle Wahrnehmung widerspiegelt.

2. Farben nach RGB-Abstand benennen: Warum #F7F6F5 plötzlich „muted orange“ hieß

Ein weiteres Problem betraf die Benennung von Farben. brandmd verglich die RGB-Werte der analysierten Farben mit einer Liste bekannter Farbnamen und wählte den nächstgelegenen Eintrag aus. Bei der Farbe #F7F6F5 – einem warmen, fast weißen Ton – führte dies zu einer falschen Bezeichnung: „Light Muted Orange“.

Die menschliche Wahrnehmung von Farben folgt jedoch anderen Regeln als der reine RGB-Abstand. Farben werden nicht isoliert, sondern in ihrem Kontext wahrgenommen. Eine helle, warme Farbe mit hoher Helligkeit wird eher als „Creme“ oder „Weiß“ wahrgenommen, selbst wenn sie einen leichten Orange-Stich hat.

Die Lösung bestand darin, HSL-Werte (Farbton, Sättigung, Helligkeit) als Grundlage für die Benennung zu nutzen.

• Farben mit einer Helligkeit über 90 % werden als „Weiß“ oder „Creme“ klassifiziert, unabhängig von ihrem Farbton.
• Hochgesättigte Farben in der mittleren Helligkeitsstufe erhalten Präfixe wie „vivid“ (z. B. „vivid blue“).
• Niedriggesättigte Farben in der mittleren Helligkeit werden als „muted“ bezeichnet.

Dank dieser Anpassung heißt #F7F6F5 nun korrekt „off-white“ und #2200FF wird als „vivid blue“ erkannt.

3. Helle Farben werden durch Luminanz-Fehler als „dunkel“ eingestuft

Ein besonders tückischer Fehler betraf die Einstufung von Farben wie #2200FF – einem leuchtend blauen Ton. Obwohl die Farbe subjektiv hell und intensiv wirkt, wurde sie fälschlich als „dunkel“ klassifiziert. Der Grund liegt in der Berechnung der Luminanz, die die Helligkeit einer Farbe bestimmt.

Die standardmäßige Luminanzformel gewichtet die Farbkanäle wie folgt:

Luminanz = 0.2126 * Rot + 0.7152 * Grün + 0.0722 * Blau

Da Blau nur mit 7 % in die Berechnung eingeht, führt eine hochgesättigte blaue Farbe zu einem niedrigen Luminanzwert – obwohl sie subjektiv hell erscheint. Die Farbe #2200FF wurde daher als „dunkel“ eingestuft, obwohl sie visuell alles andere als das ist.

Die Lösung: Statt die Luminanz zu nutzen, wird nun die HSL-Helligkeit verwendet. Diese behandelt alle Farbkanäle gleichberechtigt und kombiniert sie mit der Sättigung, um eine realistischere Einschätzung der wahrgenommenen Helligkeit zu erhalten. So wird #2200FF korrekt als mittelheller, hochgesättigter Ton erkannt.

4. Wissenschaftliche Notation in Design-Dokumenten: Wenn border-radius zu absurden Werten führt

Ein weiteres Kuriosum betraf die Ausgabe von border-radius-Werten. Bei einem Button mit der Stildefinition border-radius: 9999px – also einer vollkommen abgerundeten Form – lieferte die CSS-Analyse den Wert 3.35544e+07px. Dieser Wert stammt aus der internen Berechnung des Browsers, der die Absicht „vollständig abgerundet“ in einen extrem großen Pixelwert umwandelt.

brandmd gab diesen Wert direkt in die generierte Design-Dokumentation aus, was zu absurden Beschreibungen wie „stark abgerundet und freundlich“ führte – obwohl die Seite ansonsten scharfe Kanten hatte.

Die Lösung bestand aus zwei Schritten:

• Alle border-radius-Werte über 999px werden auf 9999px (pill) normalisiert, um eine lesbare Ausgabe zu gewährleisten.
• Werte, die auf eine vollkommen abgerundete Form hindeuten, werden bei der Analyse der Seitenform nicht berücksichtigt. Stattdessen wird der größte nicht-pillenförmige Radius herangezogen, um die tatsächliche Form der Seite zu bewerten.

5. Subpixel-Schriftgrößen als Design-System-Rauschen

Das letzte Problem betraf die Schriftgrößen. Statt klarer Stufen wie 11px, 12px und 13px lieferte die Analyse Werte wie 11.05px, 11.5px und 12.75px. Diese subpixel-genauen Angaben sind jedoch kein bewusstes Design, sondern Artefakte durch Zoom, Anti-Aliasing oder Rendering-Engine.

Die Lösung: Alle Schriftgrößen werden auf die nächste 0,5px-Grenze gerundet, bevor sie analysiert werden. Anschließend werden doppelten Werte entfernt. Aus sieben scheinbar unterschiedlichen Größen entstanden so drei klare Stufen, die das tatsächliche Design-System widerspiegeln.

Das wichtigste Learning: Nicht die Anzahl der Elemente, sondern ihre Fläche zählt

Während der Fehlerbehebung stieß der Entwickler auf ein grundlegendes Problem: Die Anzahl der Elemente, die eine Farbe nutzen, ist ein schlechter Indikator für ihre visuelle Dominanz.

In dem analysierten Beispiel nutzte ein dunkler Overlay mit 6 % Deckkraft auf kleinen Akzent-Elementen häufig die gleiche Farbe. Da diese Farbe in vielen Elementen vorkam, wurde sie fälschlich als primäre Farbe eingestuft – obwohl sie subjektiv kaum sichtbar war. Gleichzeitig ignorierte die Analyse die tatsächliche Hintergrundfarbe, die den größten Teil der Bildschirmfläche einnahm.

Die Lösung: Statt die Häufigkeit einer Farbe zu zählen, wird nun ihre Fläche auf dem Bildschirm gewichtet. So wird sichergestellt, dass nur Farben berücksichtigt werden, die tatsächlich dominant sind. Eine einfache Zeile Code reichte aus, um die Farbpalette korrekt zu priorisieren.

Fazit: Warum Design-Tools mehr Kontext brauchen

Die Analyse zeigt, wie komplex die automatisierte Bewertung visueller Elemente ist – selbst wenn Algorithmen auf den ersten Blick einfach erscheinen. Heuristiken, die in isolierten Tests funktionieren, scheitern oft an der Realität.

Mit den Anpassungen in brandmd v0.12 ist das Tool nun in der Lage, Design-Systeme präziser zu analysieren und für KI-gestützte Entwicklungsumgebungen nutzbar zu machen. Dennoch bleibt eine zentrale Erkenntnis: Automatisierte Tools können menschliche Wahrnehmung nicht vollständig ersetzen. Sie sind hilfreich, um erste Eindrücke zu gewinnen – die finale Entscheidung über Stimmungen, Farben und Formen sollte jedoch immer einem menschlichen Designer vorbehalten sein.

Wer die Unterschiede selbst nachvollziehen möchte, kann die alte und neue Version von brandmd direkt testen:

npx brandmd@0.11.1 
npx brandmd@0.12.0 

Das vollständige Changelog und der Quellcode sind auf GitHub verfügbar, falls Entwickler ihr eigenes Design-System für KI-Agenten dokumentieren möchten.