Communitygithub.com

ui-diff

Zeigt die visuellen / UI / UX-Auswirkungen eines Pull Requests an. Rendert die betroffenen Seiten einer Web-App mit Basis- und Head-Commit, erstellt Pixel-Diffs der Screenshots, misst genaue Stiländerungen (Farben, Abstände, Typografie, Kontraste), schreibt eine verständliche Zusammenfassung für Designer und Reviewer und postet Vorher-/Nachher-Bilder direkt als Kommentar oder in die PR-Beschreibung.

Was ist ui-diff?

Dieses Skill automatisiert die visuelle Regression und das visuelle Review von Pull Requests für Webanwendungen. Es rendert betroffene Seiten sowohl mit dem Basis- als auch dem Head-Commit eines PRs, vergleicht die Screenshots pixelgenau und misst präzise Stiländerungen wie Farben, Abstände, Schriftgrößen und Kontraste. Das Skill wählt intelligent die relevanten Seiten aus – basierend auf geänderten Dateien, Routen, Komponenten und Layouts – und unterstützt gängige Frameworks wie React, Next.js, Vue, Nuxt, Svelte, Angular, Astro sowie reines HTML. Es erstellt eine für Designer und Product Manager verständliche Zusammenfassung, die nicht nur die Änderungen auflistet, sondern auch auf potenzielle Probleme wie Kontrastfehler, Überlauf, verschobene Layouts oder zu kleine Touch-Ziele hinweist. Nach der Analyse werden die Vorher-/Nachher-Bilder in den PR als Kommentar oder in die Beschreibung gepostet, wobei das Tool automatisch erkennt, ob es sich um einen Fork handelt und dann eine manuelle Variante anbietet. Das Skill ist als einzelnes Skript (run.sh) mit Playwright und Chromium im Cache implementiert, benötigt keine Abhängigkeiten im Projekt und kann sowohl PR-spezifisch als auch für laufende Arbeiten (Working Tree) verwendet werden.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/davidamunga/ui-diff/tree/main/skills/ui-diff

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

UI diff

Reviewer können einen CSS-Diff lesen, aber sie können ihn nicht sehen. Dieses Skill rendert die App mit dem Basis- und Head-Commit des PRs, vergleicht sie und platziert Vorher-/Nachher-Bilder auf dem PR. Daneben geht eine kurze Zusammenfassung, was sich für Benutzer geändert hat, untermauert mit gemessenen Werten.

Die mechanische Arbeit erledigt ein einzelnes Skript. Ihre Aufgabe sind die Teile, die Urteilsvermögen erfordern: welche Seiten geprüft werden sollen, was die Änderungen bedeuten und wo gepostet wird.

$SKILL unten bezeichnet das Verzeichnis, das diese SKILL.md enthält. Setzen Sie es einmal, z. B. SKILL=/pfad/zu/skills/ui-diff. Alles wird in .ui-diff/ im Repo-Root geschrieben, was das Skript lokal in .gitignore ignoriert, sodass sich nichts Versioniertes ändert.

1. Kontext

github pr view --json number,url,baseRefName,headRefOid,body 2>/dev/null; git status --short

Lesen Sie .ui-diff.json im Repo-Root, falls vorhanden. Es kann Routen, den Dev-Befehl, Masken und Authentifizierung enthalten (siehe references/config.md).

Welcher Head gerendert wird, hängt davon ab, was der Benutzer tut:

  • Posten in einen PR: Rendern Sie genau das, was gepusht wurde, indem Sie --head <headRefOid> übergeben. Andernfalls landen nicht-committete lokale Änderungen in einem Bericht, der vorgibt, den PR zu zeigen. Wenn der Workspace schmutzig ist oder ungepushte Commits enthält, erwähnen Sie, dass diese Änderungen nicht erscheinen.
  • Überprüfen des Arbeitsfortschritts („sieht das richtig aus?“): Verwenden Sie den Workspace (die Standardeinstellung, ohne --head). Der Bericht kennzeichnet ihn als „+ uncommittete Änderungen“.\n\n## 2. Seiten auswählen
node $SKILL/scripts/routes.cjs --base <base> --log   # fügen Sie --head <sha> hinzu, wenn Sie es an run.sh übergeben

Es ordnet die geänderten Dateien Routen zu: Seitendateien, Routen unter einem geänderten Layout, Seiten, die eine geänderte Komponente importieren (folgt Aliassen und Workspace-Paketen), sowie die Startseite und einige wenige gut verlinkte Seiten für App-weite Stile. Es gibt JSON aus mit den Gründen und der Konfidenz jeder Route, needsExample (dynamische Routen, die es nicht ausfüllen kann) und unmatched (UI-Dateien, die es nicht zuordnen konnte). Behandeln Sie es als Startliste und wenden Sie Ihr Urteilsvermögen mit references/route-mapping.md an: Verwerfen Sie Low-Confidence-Auswahlen, die der Diff nicht unterstützt, finden Sie IDs für needsExample und platzieren Sie unmatched-Dateien selbst. Wenn sich nichts UI-bezogenes geändert hat (alle Dateien ignored), sagen Sie das und brechen Sie ab. Erstellen Sie keinen leeren Bericht.

Storybook-Projekte (ein .storybook/-Ordner oder ein storybook-Skript): Wenn die Änderung hauptsächlich Komponenten betrifft, diff-en Sie deren Stories anstelle von Seiten mit run.sh --storybook; es wählt die Stories selbst aus den geänderten Dateien aus. Bleiben Sie bei Seiten für Routen, Layouts und App-weite Stile. Siehe den Storybook-Abschnitt von references/route-mapping.md.

Teilen Sie dem Benutzer in ein bis zwei Zeilen mit, welche Routen Sie erfassen und warum, und fahren Sie dann fort. Fragen Sie nur, wenn Sie keine Route finden können oder wenn eine dynamische Route eine ID benötigt, die Sie nicht finden können. Behalten Sie Routen im Auge, die betroffen, aber nicht erfasst sind (zu viele zum Prüfen, erfordern Login, einen Modal-Zustand). Diese kommen in die Zusammenfassung, damit „keine visuelle Änderung“ nicht als Entwarnung gelesen wird.

3. Ausführen

bash $SKILL/scripts/run.sh --routes "/,/preise" [--head <sha>] [--base <ref>] \
  [--viewports "desktop:1440x900,mobil:iPhone 13"] [--schemes hell,dunkel] [--dev "<Befehl mit {port}>"]

(--auto-routes fügt die Routen hinzu, die routes.cjs auswählt, protokolliert mit Gründen; verwenden Sie es, wenn Sie keine Korrekturen vornehmen müssen.)

In einem Durchlauf:

  • Installiert die Werkzeuge bei erster Nutzung (Playwright + Chromium in ~/.cache/ui-diff, etwa eine Minute; die Abhängigkeiten des Projekts bleiben unberührt);
  • Checkt Basis und Head, falls --head angegeben, in Git-Worktrees aus und kopiert unversionierte .env*-Dateien hinein;
  • Verwendet installierte Abhängigkeiten wieder, wenn die Lockfile übereinstimmt, mit pro-Checkout-Build-Caches, und installiert sie andernfalls;
  • Startet beide Dev-Server auf freien Ports in eigenen Prozessgruppen. Nur diese werden danach gestoppt, sodass die Server des Benutzers nie berührt werden;
  • Erfasst jede Route × Viewport. Mobil verwendet echte Geräteemulation (Touch, Mobile UA). Animationen werden eingefroren und Framework-Dev-Overlays ausgeblendet;
  • Erstellt Pixel-Diffs der Screenshots (results.json, Vollseiten- und Zoombilder) und führt einen Computed-Style-Diff durch (measured.md).

Storybook-Modus (--storybook oder --stories "button--primary,card--*" zur eigenen Auswahl) startet Storybook anstelle des Dev-Servers, protokolliert welche Stories ausgewählt wurden und warum, und benennt Ergebnisse nach Story-ID. Wenn keine Story passt, wird beendet und IDs vorgeschlagen.

Es gibt Zählungen wie {"changed":2,"added":1,"unchanged":3,...} aus. Standardwerte: Basis = der Basis-Branch des PRs (ansonsten der Standard-Branch), Viewports = Desktop 1440×900 + iPhone 13, Hellmodus. Fügen Sie --schemes hell,dunkel hinzu, wenn die Änderung Theme, Farben oder Tokens betrifft.

Wenn es fehlschlägt, sagt die Fehlermeldung, welcher Schritt fehlgeschlagen ist und wo sein Log liegt(.ui-diff/server-*.log, install-*.log, capture-*.log). Die üblichen Ursachen sind eine fehlende Umgebungsvariable, der falsche Dev-Befehl (übergeben Sie --dev) oder nicht installierte Abhängigkeiten im Workspace. Beheben Sie die Ursache und führen Sie erneut aus. Überspringen Sie keine Seite.

4. Ergebnisse lesen und Zusammenfassung schreiben

Lesen Sie zuerst .ui-diff/report/measured.md. Wenn es mit Mögliche Probleme beginnt, prüfen Sie diese zuerst: abgeschnittener Text, seitliches Scrollen, Überlappung, Steuerelemente außerhalb des Bildschirms, kleine mobile Touch-Ziele und Axe-Core-Barrierefreiheitsverletzungen, die im Head neu sind. Sie sind Heuristiken, also öffnen Sie jedes Zoombild (report/issues/) und bewerten Sie es. Führen Sie die echten mit „einen Blick wert“ an und lassen Sie absichtliche fallen oder formulieren Sie sie ab. Der Rest von measured.md enthält gemessene Fakten: Computed-Style-Änderungen gruppiert über Elemente hinweg, geänderte Elementgrößen, Layout-Verschiebungen, Textänderungen und neue WCAG-Kontrastfehler. Öffnen Sie dann die Zoombilder (report/zoom/*__after.png und __before.png) und Diff-Overlays mit dem Datei- oder Bildbetrachter Ihrer Wahl, um zu sehen, wie diese Fakten im Kontext aussehen. Wenn Sie keine Bilder anzeigen können, schreiben Sie die Zusammenfassung nur aus measured.md und sagen Sie, dass die Screenshots nicht überprüft wurden. Prüfen Sie results.json auf warnings: HTTP-Fehler, Framework-Fehler-Overlays, unbehandelte Ausnahmen.

Figma-Link angegeben (oder eine Route in .ui-diff.json hat figma)? Vergleichen Sie auch den Head mit dem Design-Frame. Folgen Sie references/figma.md.

Schreiben Sie .ui-diff/report/summary.md für einen Designer oder PM, der den Code nicht liest:

**Was geändert wurde**
- **Preiskarten** — CTA-Buttons sind jetzt Pillen (Radius 4 → 999px) mit mehr Padding (8×14 → 12×20px); die Pro-Karte ist hervorgehoben (2px `#2563EB`-Rand, `#EFF6FF`-Füllung) mit einem „Beliebteste“-Label.
- **Header (alle Seiten)** — Nav-Links wechselten von blau `#2563EB` zu grau `#9CA3AF`.

**Einen Blick wert**
- ⚠️ Nav-Links haben jetzt 2,5:1 Kontrast auf Weiß (vorher 5,2:1); Fließtext benötigt 4,5:1.
- ⚠️ `/einstellungen` hat sich geändert, aber keine seiner Dateien hat sich geändert — es übernimmt das neue `Button`-Padding, und „Speichern“/„Abbrechen“ umbrechen jetzt auf Mobilgeräten.

**Nicht geprüft:** `/admin/*` (benötigt Login), der „Konto löschen“-Modal.

Richtlinien:

  • Verwenden Sie gemessene Werte aus measured.md für Farben, Größen und Abstände. Schätzen Sie sie nicht aus Pixeln. Wenn etwas in den Bildern sichtbar ist, aber nicht in measured.md (Bilder, Canvas, SVG-Inhalte), beschreiben Sie es wie gesehen.
  • Ein großer Pixeländerungsprozentsatz mit „verschobener … Layout-Shift“-Zeilen bedeutet normalerweise, dass Inhalt nach unten gedrückt wurde, nicht dass alles geändert wurde. Erklären Sie es so.
  • Führen Sie unter „Einen Blick wert“ wahrscheinlich unbeabsichtigte Änderungen auf: Seiten, die sich geändert haben, ohne dass ihre Dateien geändert wurden, Brüche nur bei einem Viewport, Überlauf, verschwundene Elemente, Seitenfehler. Dann Kontrastfehler und kleine Touch-Ziele (unter etwa 44px auf Mobilgeräten).
  • Sagen Sie „geändert“, nicht „absichtlich geändert“. Sie können sehen, was sich geändert hat, nicht warum.
  • Halten Sie es proportional. Eine Ein-Farben-Anpassung bekommt einen Bullet-Punkt.

Führen Sie dann node $SKILL/scripts/viewer.cjs --report .ui-diff/report aus, um die lokale Review-Seite zu aktualisieren (report/index.html: Slider, nebeneinander, Diff-Overlay, Zusammenfassung oben) und bieten Sie an, sie für den Benutzer zu öffnen (open auf macOS, xdg-open auf Linux).

5. Veröffentlichen

Das Posten schreibt in einen gemeinsamen PR und pusht einen Branch. Zeigen Sie dem Benutzer die Zusammenfassung und holen Sie Bestätigung ein, es sei denn, die Anfrage hat bereits gesagt, dass gepostet werden soll. Dann:

PREFIX=$(bash $SKILL/scripts/publish.sh .ui-diff/report <pr> <head-short-sha>)
node $SKILL/scripts/comment.cjs --report .ui-diff/report --base-url "$PREFIX" \
  --summary .ui-diff/report/summary.md --out .ui-diff/comment.md
node $SKILL/scripts/post.cjs --pr <pr> --body .ui-diff/comment.md --mode comment   # oder --mode description
  • publish.sh pusht die Bilder in einen ui-diff-assets-Branch (ein Commit, bei jeder Veröffentlichung ersetzt) aus einem Wegwerf-Klon. Bilder werden dann inline auf GitHub gerendert, auch in privaten Repos für jeden mit Lesezugriff.
    • Exit 3 bedeutet keinen Push-Zugriff (typischerweise ein PR von einem Fork). Wechseln Sie in den manuellen Modus.
    • Wenn das Repo als öffentlich erkannt wird, teilen Sie dem Benutzer mit, dass die Screenshots öffentlich sind. Das ist am wichtigsten, wenn storageState als echter Account eingeloggt ist. Holen Sie ein Ja ein, bevor Sie posten.
  • post.cjs ersetzt den vorherigen ui-diff-Kommentar oder -Abschnitt, anstatt neue zu stapeln. Alles andere in der Beschreibung bleibt erhalten.
  • Fügen Sie --approval zu comment.cjs nur hinzu, wenn .ui-diff.json "requireApproval": true hat (das Repo hat den Design-Review-Workflow): Es fügt ein „Design genehmigt“-Feld hinzu.
  • Manueller Modus (kein Assets-Branch oder kein Push-Zugriff): Führen Sie comment.cjs ohne --base-url aus, dann open .ui-diff/report. Der Benutzer zieht die Bilder in das PR-Kommentarfeld (GitHub hat keine API für diesen Upload). Sagen Sie ihnen, welches Bild wohin gehört.
  • Noch kein PR: Behalten Sie .ui-diff/comment.md und bieten Sie an, es beim Öffnen des PRs in die Beschreibung einzufügen.

6. Abschluss

Melden Sie den Link, die Zählungen und die „Einen Blick wert“-Punkte. Wenn Sie den Dev-Befehl, Routen, Masken oder dynamische IDs selbst ermittelt haben, bieten Sie an, sie in .ui-diff.json zu speichern, damit der nächste Durchlauf ein einzelner Schritt ist. Sobald ein PR gemerged oder geschlossen ist, entfernt bash $SKILL/scripts/prune.sh <pr> seine Bilder aus dem Assets-Branch (fragen Sie zuerst, ob jemand den Kommentar noch benötigt).

Verwandte Skills