slimabbadi/ui-diff

Was macht ui-diff?

Erfasse eine Seite vor der Bearbeitung, erfasse sie danach erneut und lies, was sich geändert hat. Der Vergleich läuft lokal ab: Pixel werden wie ein Text-Diff ausgerichtet, und jede geänderte Region wird der DOM-Änderung zugeordnet, die sie verursacht hat. Das Modell zahlt nur dann für ein Bild, wenn etwas Sichtbares geändert wurde. Selbst dann enthält das Bild nur die geänderten Elemente, beschnitten auf ein Token-Budget (standardmäßig 400; zwei vollständige Screenshots kosten typischerweise 2.000–5.000).

scripts/ befindet sich neben dieser Datei. Im Folgenden steht $UI_DIFF für node <Pfad zum Skill-Verzeichnis>/scripts/ui-diff.mjs.

Einrichtung (einmal pro Maschine)

1. Stelle agent-browser in den PATH (npm i -g agent-browser, dann agent-browser install für Chromium; unter Linux agent-browser install --with-deps).
2. Installiere die Bildbibliothek: führe npm install innerhalb von <Pfad zum Skill-Verzeichnis>/scripts aus.
3. Optionaler Nachweis, dass die Maschine bereit ist: node <Pfad zum Skill-Verzeichnis>/scripts/selftest/selftest.mjs. Es beendet sich mit Exit-Code 0, wenn alle Szenarien bestanden werden.

Schritte

1. Basislinie vor der ersten Bearbeitung: $UI_DIFF baseline <url> --name <slug>. Verwende einen Slug pro Seite oder Zustand, z. B. home oder checkout-mobile. Eine Basislinie lädt die Seite zweimal, um zu lernen, welche Teile von selbst flackern.
2. Führe die Änderung durch.
3. Prüfung: $UI_DIFF check <url> --name <slug>. Exit-Code 0 bedeutet keine visuelle Änderung, 1 bedeutet eine Änderung wurde gefunden, und 2 bedeutet einen Fehler.
4. Lies zuerst den Textbericht, entscheide dann über das Bild:
   • Jede aufgelistete DOM-Änderung ist eine beabsichtigte und der Bericht zeigt 0 unerklärt: der Text ist der Beweis, also lasse das Bild geschlossen.
   • Der Bericht listet unerklärte Regionen auf (U1.…), oder du musst beurteilen, wie etwas aussieht: öffne den vom Bericht ausgegebenen Pfad zum Überprüfungsbild. Öffne es einmal, am Ende der Arbeit, denn ein Bild, das während der Aufgabe gelesen wird, wird bei jeder späteren Runde erneut berechnet.
5. Iteriere, indem du check erneut gegen dieselbe Basislinie ausführst. Erstelle eine neue Basislinie nur, wenn du den aktuellen Zustand als neue Referenz akzeptierst.

Der Schritt ist abgeschlossen, wenn der Bericht genau die von dir beabsichtigten Änderungen auflistet und jede unerklärte Region entweder verstanden oder korrigiert ist.

Lesen des Berichts

• DOM-Änderungen sind die Ursachen: Elementbezeichnung, dann Eigenschaft vorher -> nachher (Farben als Hex) oder Text „alt“ -> „neu“. Identische Änderungen werden gruppiert (x3). Änderungen, die keine geänderten Pixel berühren, werden nur gezählt.
• Layout listet die Konsequenzen auf: Elemente, die um (dx,dy) verschoben wurden, skalierte Elemente und Pixelzeilen, die mit identischem Inhalt verschoben wurden. Dies sind erwartete Auswirkungen einer Größen- oder Abstandsänderung, daher erhalten sie kein Bild.
• Pixelregionen teilt jeden geänderten Bereich in eine von vier Klassen ein:
  • durch DOM-Änderungen und nur durch Layout sind erklärt.
  • flüchtig bedeutet, dass sich die Seite dort auch zwischen zwei identischen Aufnahmen geändert hat.
  • unerklärt bedeutet, dass sich Pixel geändert haben und nichts im DOM dies erklärt, z. B. Canvas, Bilder oder Pseudoelemente. Unerklärte Regionen sind immer im Bild: Dort verstecken sich Regressionen.
• SUBTILE markiert eine zu schwache Änderung, um sie zu sehen, z. B. eine Design-Token-Anpassung. Vertraue den Hex-Werten im Text mehr als dem Bild.
• Abstandsänderungen (margin, padding, gap) werden nur im Zuschnitt relativ zu Nachbarn angezeigt. Der Text gibt die genauen Werte.

Rauschen und Optionen

• ⚠ Seite hat sich zwischen den Aufnahmen ständig geändert bedeutet Live-Inhalte (Animationen, Karussells, Timer). Verstecke sie mit --hide „<CSS-Selektoren>“ oder begrenze die Prüfung mit --selector <CSS> auf das von dir geänderte Element.
• Einwilligungsbanner und Chat-Widgets gehören in --hide. Ausgeblendete Elemente werden immer im Bericht aufgelistet.
• Projektvorgaben werden in .ui-diff.json im Arbeitsverzeichnis gespeichert, z. B. { „hide“: „#cookie-banner“, „width“: 1440 }. Flags überschreiben diese.
• position:fixed-Elemente werden dort fixiert, wo sie auf der Seite sitzen, sodass sie im Vergleich bleiben.
• Aufnahmen werden im Arbeitsverzeichnis im Ordner .ui-diff/ gespeichert. Dieser Ordner ignoriert sich selbst in git.
• Führe $UI_DIFF ohne Argumente aus, um alle Flags anzuzeigen.