ui-preview-gate

UI Preview Gate (Tor für UI-Vorschauen)

Jede Änderung, die einen Bildschirm verändert, durchläuft vier Phasen. Überspringe keine Phase, nur weil die Änderung klein aussieht; die Bilder sind das, was Prüfer genehmigen.

1. Aktuellen Zustand inspizieren
2. Vorschau und Genehmigung einholen (bevor die Arbeit beginnt)
3. Implementieren
4. Überprüfen, ob das Ergebnis mit der genehmigten Vorschau übereinstimmt (nach Abschluss der Arbeit)

Ausnahme: Ein Bugfix, der den beabsichtigten Bildschirm nicht verändert, kann Phase 2 überspringen. Wenn Benutzer dennoch einen Unterschied sehen, lege Vorher/Nachher-Bilder mit dem Fix bei. Das Anzeigen eines anderen Bildschirms, Dialogs, Sheets oder einer anderen Nachricht als zuvor ist eine Bildschirmänderung – nicht diese Ausnahme – selbst wenn eine vorhandene Komponente wiederverwendet wird. Hole zuerst die Phase-2-Genehmigung ein.

Wann dies gilt

• Wende es an, ohne dass darum gebeten wird. Benutzer sollten dieses Skill nie selbst nennen müssen.
• Prüfe jeden Gesprächsschritt, nicht nur den ersten. Ein Gespräch, das als Support, Recherche, Review oder Bugmeldung begann, wird oft zur Hälfte zu „Was wäre, wenn der Bildschirm X täte?“; ab diesem Schritt gilt dieses Skill.
• „Was denkst du?“, „irgendwelche Ideen?“ und „wie würde es aussehen?“ über einen Bildschirm gelten als Vorschläge.
• Wende es in späteren Schritten weiter an, bis die genehmigte Änderung verifiziert ist (Phase 4) oder der Benutzer die Änderung fallen lässt.
• Ein Vorschlag, der nur in Prosa oder einer Falltabelle beantwortet wird, ist unvollständig. Füge das Vorher/Nachher-Bild in derselben Antwort bei oder sage, warum es noch nicht erstellt werden kann und wann es erstellt wird.
• Während eine UI-Änderung auf Genehmigung wartet oder in Bearbeitung ist, müssen Fortschrittsberichte, Optionenlisten und Fragen dazu das Vorher/Nachher-Bild erneut anhängen oder den Bildpfad angeben. Beschreibe den geänderten Bildschirm niemals nur in Prosa.

Skills werden normalerweise pro Schritt anhand ihrer Beschreibung ausgewählt, sodass Schritte mitten im Gespräch übersehen werden können. agent-instructions.md neben dieser Datei ist eine kurze Regel, die zu AGENTS.md / CLAUDE.md hinzugefügt werden sollte, damit der Agent in jedem Schritt erneut prüft.

1. Aktuellen Zustand inspizieren

Schlage niemals aus dem Gedächtnis oder mit Vermutungen vor.

• Erfasse den echten Bildschirm von einem laufenden Dev-Server oder Build. Standard-Viewport ist mobil 375px breit; füge Desktop hinzu, wenn die Änderung auch Desktop-Layouts betrifft.
• Lies den Code, der ihn rendert: Tab-/Router-Struktur, Komponenten, aktueller Text.
• Dokumentiere Belege als pfad/zu/datei:zeile plus die Erfassung. Jede Behauptung über die aktuelle UI sollte auf einen dieser Belege verweisen.
• Bevorzuge vorhandene Komponenten, Muster und Texte. Wenn ein neues Muster erforderlich ist, begründe, warum die vorhandenen nicht passen.

Erfasse mit scripts/capture.mjs (siehe Skripte), damit der Vorher-Schnappschuss, die Vorschau und der Verifizierungsschnappschuss denselben Viewport, dieselbe Skalierung und denselben Datenzustand teilen.

Fallinventar (führe dies unaufgefordert durch, vor der ersten Vorschau)

Der Prüfer sollte nie fragen müssen: „Was ist nach dem Antippen?“ oder „Was, wenn Daten vorhanden sind?“. Bevor du eine Vorschau sendest, liste jeden Fall auf, den die Änderung berührt, basierend auf dem Code und der echten App:

• Zustände des geänderten Bildschirms: leer / mit Daten / viele Einträge (Abschneidung, „alle anzeigen“) / Laden / Fehler / durch Plan, Rolle oder Berechtigung gesperrt / andere Konfigurationen (Einzel- vs. Mehrfach-Shop, Feature-Flags).
• Jeder von einem neuen oder geänderten Steuerelement aus erreichbare Bildschirm: Formulare, Picker, Dialoge, Validierungsfehler, Abbrechen/Zurück, Bestätigung, Erfolg, Fehlschlag.
• Nach der Aktion: wie der Ausgangsbildschirm aussieht, wenn die Aktion abgeschlossen ist (neues Element erscheint, Zähler ändern sich) und wie man rückgängig machen oder bearbeiten kann.
• Andere Stellen, die dieselben Daten anzeigen: Listen, Detailbildschirme, Verlauf, Berichte, Exporte, andere Plattformen (Desktop, Web, LINE, Kundenseite). Markiere jeweils als geändert / unverändert, zeigt aber neue Daten an / nicht betroffen.

Sende das Inventar als Tabelle mit der ersten Vorschau: Fall, was der Benutzer sieht, wiederverwendete vorhandene Komponente und Bildstatus (angehängt / benötigt Testdaten – wie vorbereitet / außerhalb des Geltungsbereichs – warum). Vorschauen können in Chargen kommen, aber die erste Nachricht zeigt immer das gesamte Inventar, und die Genehmigung eines Bildes impliziert nie die Genehmigung von noch nicht gezeigten Fällen. Schlage sinnvolle Standardwerte für offene Entscheidungen vor, anstatt nur Fragen aufzulisten.

2. Vorschau und Genehmigung einholen

Bevor du Implementierungscode schreibst, zeige dem Prüfer ein nebeneinander angeordnetes Bild und eine kurze Zusammenfassung und warte dann auf ein explizites OK.

Bildregeln:

• Vorher links, Nachher rechts, in einem Bild.
• Rahme jeden geänderten Bereich ein: rot auf Vorher, grün auf Nachher.
• Paare die Rahmen: Jede Änderung erhält einen Rahmen auf beiden Seiten an der passenden Stelle. Bei einer Hinzufügung markiere den Einfügepunkt auf Vorher mit einem dünnen Marker in der Lücke ("pad": 0, kleines h); bei einer Entfernung markiere die Lücke auf Nachher. Rahme niemals einen nicht zusammenhängenden Nachbarn (z. B. die Zeile darunter) ein, um ein fehlendes Element zu ersetzen.
• Entnimm die Rahmenkoordinaten aus der Ausgabe von capture.mjs --selector (oder Element-Rechtecken, die mit Playwright in einem e2e-Test gemessen wurden, wenn der Zustand Interaktion erfordert, z. B. ein Dialog, der nach Eingabe geöffnet wird), nicht nach Augenmaß. Sieh dir das zusammengesetzte Bild an, bevor du es sendest, um sicherzustellen, dass jeder Rahmen auf seinem Ziel sitzt.
• Gleicher Viewport, gleiche Scroll-Position und gleiche Beispieldaten auf beiden Seiten.
• Wenn der Bildschirm je nach Zustand verzweigt (Daten vorhanden/nicht vorhanden, Fehler, leer, pro Rolle oder pro Konfiguration), zeige ein Vorher/Nachher-Paar für jeden Zustand, den die Änderung berührt. Ein nicht gezeigter Zustand ist nicht genehmigt. Erstelle ein Bild pro Zustand; platziere niemals mehrere Paare in einem Bild.
• Ein echter Bildschirm, der nur durch Staging (vorübergehend geänderter Code, um ihn zu öffnen) erreicht wird, muss "staged" in der Spezifikation tragen, damit das Bild dies angibt.
• Vor dem Senden prüfen: compose.mjs lehnt Spezifikationen ab, die gegen diese Regeln verstoßen, und gibt eine Checkliste aus. Öffne das Bild, beantworte jeden Punkt und füge die Antworten in die Nachricht ein (siehe Vorlagen). Wenn ein Punkt fehlschlägt, korrigiere und setze neu zusammen; erkläre niemals einen fehlgeschlagenen Punkt stattdessen im Text.
• Befolge die Bildrichtlinie unten.

Bildrichtlinie

Der Benutzer oder das Projekt entscheidet, ob Mockups erlaubt sind. Suche nach der Wahl in der Anfrage oder den Projektanweisungen (AGENTS.md, CLAUDE.md, Mitwirkungsdokumente). Wenn nichts angegeben ist, verwende real-only. Wechsle niemals eigenständig zu mockup-allowed, weil das Erfassen schwierig ist; frage stattdessen nach.

• real-only (Standard): Beide Seiten sind Vollbild-Erfassungen der echten laufenden App. Erstelle die Nachher-Seite auf einem Prototyp-Branch oder hinter einem Feature-Flag und erfasse sie. Verwende niemals zugeschnittene oder eingefügte Fragmente, aus Code oder von Hand neu gezeichnete Mockups (einschließlich generierter Bilder), Erfassungen, die eine Zeile halbieren, oder Dummy-Daten, die sich von dem unterscheiden, was die echte App zeigt.
• mockup-allowed: Die Nachher-Seite darf nur dann ein Mockup sein, wenn der Benutzer oder das Projekt dies ausdrücklich erlaubt. Die Vorher-Seite ist dennoch eine echte Erfassung. Markiere jedes Mockup-Panel mit "mockup": true in der Compose-Spezifikation, damit das Bild es zeigt, und gib es in der Genehmigungsanfrage an. Ein Mockup zählt niemals als Phase-4-Nachweis: Die Verifizierung verwendet immer eine echte Erfassung des implementierten Bildschirms.

Eine strengere Projektregel gewinnt immer über eine lockerere Benutzerpräferenz; wenn sie in Konflikt geraten, weise darauf hin und befolge die Projektregel.

Zusammenfassung (verwende references/templates.md):

• Wo: welcher Bildschirm/Tab und wo darauf die Änderung erscheint
• Was wird möglich, pro Benutzertyp (z. B. Admin, Kunde)
• Was ändert sich nicht, und die betroffenen Plattformen/Oberflächen

Die Genehmigung deckt genau das ab, was gezeigt wurde. Alles außerhalb erfordert eine neue Vorschau.

3. Implementieren

Baue nach der genehmigten Vorschau. Wenn die Implementierung eine sichtbare Abweichung erzwingt (Layout, Text, Verhalten, neue Plattformauswirkung), stoppe und kehre mit einer aktualisierten Vorschau zu Phase 2 zurück, anstatt den Unterschied auszuliefern.

Dies schließt kleine Textbearbeitungen und Korrekturen ein, die als Reaktion auf Code-Reviews vorgenommen wurden: Wenn eine Korrektur das ändert, was Benutzer über die genehmigten Bilder hinaus sehen, stoppe und hole zuerst eine neue Vorschau-Genehmigung ein. Das nachträgliche Melden im Text zählt nicht.

4. Gegen die genehmigte Vorschau verifizieren

Melde den Abschluss nicht allein aus dem Code-Diff.

1. Erfasse den implementierten Bildschirm erneut mit denselben Erfassungseinstellungen und demselben Zustand, die für die Vorschau verwendet wurden.
2. Erstelle ein Verifizierungsbild: genehmigte Vorschau | tatsächliches Ergebnis. Rahme jede versprochene Änderung ein; rahme jeden Unterschied zur genehmigten Vorschau in Bernstein ein, selbst eine kleine Verschiebung. Ein Unterschied, der nur im Text beschrieben wird, ist nicht verifiziert.
3. Prüfe Punkt für Punkt:
   • Jede versprochene Änderung ist vorhanden und stimmt mit der Vorschau überein;
   • Alles, was als „ändert sich nicht“ aufgeführt ist, ist unverändert;
   • Nichts außerhalb der eingerahmten Bereiche hat sich bewegt, umgebrochen oder läuft über;
   • Die geänderte Interaktion funktioniert tatsächlich, wenn sie ausgeführt wird, und rendert nicht nur. Bestandene e2e-Tests bestätigen das Verhalten; sie ersetzen nicht die Bildprüfung für jeden Zustand, der unverändert aussehen sollte.
4. Entscheide:
   • Übereinstimmung: Melde mit dem Verifizierungsbild und dem Checklistenergebnis.
   • Geringfügige Abweichung innerhalb der genehmigten Absicht: Korrigiere, erfasse erneut, prüfe erneut.
   • Abweichung, die das Genehmigte ändert: Melde und hole erneut Genehmigung ein.

Liste alles, was du nicht verifizieren konntest (eine Plattform, ein Gerät, echte Daten), separat auf, anstatt es als erledigt zu bezeichnen.

Skripte

Beide Skripte benötigen Node 18+ und Playwright (npm i -D playwright && npx playwright install chromium). Setze PLAYWRIGHT_MODULE auf einen Modulpfad, um eine vorhandene Installation wiederzuverwenden.

Erfasse einen Bildschirm und erhalte Rahmenkoordinaten für Elemente:

node scripts/capture.mjs --url http://localhost:3000/menu --out before.png \
  --width 375 --selector ".category-tabs" --selector ".menu-list"

Es gibt die Rechtecke der Selektoren in CSS-Pixeln aus, bereit zum Einfügen als boxes.

Setze Panels aus einer JSON-Spezifikation zusammen:

node scripts/compose.mjs spec.json

Spezifikationsformat, Bildtöne und das Verifizierungslayout befinden sich in references/compose-spec.md.