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
--headangegeben, 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.mdfür Farben, Größen und Abstände. Schätzen Sie sie nicht aus Pixeln. Wenn etwas in den Bildern sichtbar ist, aber nicht inmeasured.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.shpusht die Bilder in einenui-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
storageStateals echter Account eingeloggt ist. Holen Sie ein Ja ein, bevor Sie posten.
post.cjsersetzt den vorherigen ui-diff-Kommentar oder -Abschnitt, anstatt neue zu stapeln. Alles andere in der Beschreibung bleibt erhalten.- Fügen Sie
--approvalzucomment.cjsnur hinzu, wenn.ui-diff.json"requireApproval": truehat (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.cjsohne--base-urlaus, dannopen .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.mdund 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).