UX-Qualitätsprüfung

Was macht UX-Qualitätsprüfung?

Überprüfen Sie die von einer Änderung betroffenen UI-Oberflächen anhand der Regeln in references/rules.md. Jede Regel enthält einen Grund, eine Überprüfung im Code, eine Überprüfung im Browser und eine Reparatur. Die Tabelle am Anfang dieser Datei gibt an, auf welche Arten von Änderungen jede Regel zutrifft.

1. Änderung finden

1. Ermitteln Sie den Diff, den die Anfrage benennt: einen PR, einen Branch, einen Commit oder die unbestätigten Änderungen. Ohne Namen verwenden Sie die unbestätigten Änderungen. Falls keine vorhanden sind, verwenden Sie den Branch gegen seine Merge-Basis mit dem Standard-Branch (git diff $(git merge-base HEAD origin/HEAD)...HEAD). Falls der Branch der Standard-Branch ist, verwenden Sie den letzten Commit. Geben Sie im Bericht an, welchen Diff Sie überprüft haben.
2. Listen Sie die geänderten UI-Dateien auf: Komponenten, Templates, Styles und die Strings und Props, die sie rendern. Eine Änderung an einer gemeinsam genutzten Komponente oder einem Token ist ebenfalls eine UI-Änderung.
3. Wenn keine Datei im Diff UI rendert (nur Servercode, Tests, Konfiguration oder Dokumentation), sagen Sie dies in ein oder zwei Sätzen und brechen Sie ab. Melden Sie keine Befunde.

2. Repository-eigene UI-Regeln lesen und die Oberflächen abbilden

Die Regeln eines Repositorys haben Vorrang vor den Standardwerten des Katalogs.

• Lesen Sie die Agenten-Dokumentation des Repositorys (AGENTS.md, CLAUDE.md, ein Design-System-README) nach einem Abschnitt „UI-Regeln“ oder ähnlich. Notieren Sie jedes Steuerelement, Token oder jede Komponente, die sie für eine Regel nennen, wie z. B. einen Dialog-Helfer, einen asynchronen Button, Typ-Token oder eine KI-Markierung. Eine Reparatur benennt diese Komponente.
• Suchen Sie nach den eigenen UX-Prüfungen des Repositorys: einem make ux-check oder ux:check-Target, einem Layout- oder Barrierefreiheitsskript, Lint-Regeln oder Tests, die Quellen auf UI-Regeln scannen. Führen Sie jede aus, die die Änderung abdeckt, und verwenden Sie deren Ausgabe als Nachweis.

Ordnen Sie dann jede geänderte Datei den Oberflächen zu, die ein Benutzer sieht: der Route, der Ansicht und dem Steuerelement. Eine gemeinsam genutzte Komponente wird jeder Oberfläche zugeordnet, die sie verwendet. Benennen Sie eine Oberfläche so, wie ein Benutzer sie findet („Review-Seite, Kommentar hinzufügen-Formular“). Notieren Sie für jede Oberfläche:

• Arten. Markieren Sie die Oberfläche mit jeder Art aus der Legende von references/rules.md, die der Diff hinzufügt oder bearbeitet: write, data, form, list, control, overlay, layout, route, copy, chart, style. Ein neuer Hover-Stil ist control und list. Ein Speichern-Button ist write.
• Zustände. Leer, Laden, Ausstehend, Fehler, Hover, Fokus, Ausgewählt und Deaktiviert. Die meisten Befunde befinden sich in einem Zustand, den der Autor nicht geöffnet hat.

3. Prüfungen ausführen

Führen Sie für jede Oberfläche jede Regel aus, deren „Anwendbar auf“ eine Art mit der Oberfläche gemeinsam hat. Lesen Sie den Abschnitt der Regel, bevor Sie sie überprüfen. Notieren Sie jede Regel, die Sie überspringen, und den Grund.

Lesen Sie zuerst den Code. Jede Regel „Überprüfung im Code“ gibt an, wonach gesucht werden muss. Dies erfasst die meisten Defekte und benötigt keinen Browser. Bevor Sie einen fehlenden Zustand melden, lesen Sie die Komponenten, die der Code aufruft: Ein Wrapper (ein asynchroner Button, ein Formular-Hook, ein übergeordnetes Element, das pending übergibt) behandelt ihn oft.

Dann messen Sie im Browser, wenn möglich. Eine statische HTML-Seite wird von der Festplatte mit einer file://-URL geöffnet. Suchen Sie für eine App nach einem laufenden Entwicklungsserver oder starten Sie einen mit dem im Repository dokumentierten Befehl. Verwenden Sie das Browser-Tool, das der Host bereitstellt: einen integrierten Browser-Bereich, ein Playwright-Skript oder Headless Chrome. Wenn die Seite eine Anmeldung erfordert, bitten Sie den Benutzer, sich in diesem Browser anzumelden. Geben Sie selbst keine Anmeldedaten ein.

Laden Sie scripts/measure.js in die Seite. Es definiert die Hilfsfunktionen, die jede Regel „Überprüfung im Browser“ benennt, und references/rules.md listet auf, was jede zurückgibt. Fügen Sie es nach jedem Seitenaufruf erneut ein. Überprüfen Sie jedes Theme und jedes Schema, das die App bietet, und mindestens eine Telefonbreite und eine Desktop-Breite.

Messen Sie auch jede geänderte Zeile, Karte und jedes Steuerelement in seinen Interaktionszuständen. Ein Hover-, Fokus- oder Ausgewählt-Zustand fügt oft eine Füllung, einen Rahmen, einen Schatten oder ein Steuerelement hinzu. Zwei eingerahmte Elemente berühren sich dann, ein Element wächst und verschiebt seine Nachbarn, oder eine Nur-Hover-Aktion drückt einen Zähler aus der Zeile. Führen Sie für jede Liste, Kartengruppe oder Steuerelementgruppe auf der Oberfläche Folgendes aus:

1. Führen Sie snapshot(sel, "rest") und gaps(sel) aus, während die Elemente im Ruhezustand sind.
2. Fahren Sie mit der Maus über ein Element mit dem Browser-Tool, führen Sie dann erneut snapshot(sel, "hover") und gaps(sel) aus. Machen Sie dasselbe mit dem Tastaturfokus (drücken Sie Tab) und mit dem ausgewählten Element neben einem Element, über das mit der Maus gefahren wird.
3. Führen Sie moved("rest", "hover") aus. Ein Abstand von 0px zwischen zwei eingerahmten Elementen oder ein Element, das sich bewegt hat, wenn ein anderes mit der Maus überfahren wurde, ist ein Befund.

Machen Sie dasselbe um jede Aktion herum, die ein Menü, Popover oder Panel öffnet: Erstellen Sie einen Schnappschuss der Hauptblöcke, öffnen Sie es, erstellen Sie erneut einen Schnappschuss und vergleichen Sie. Lesen Sie im Code jede :hover-, :focus-visible- und Ausgewählt-Klasse-Regel auf Eigenschaften, die ein Element hinzufügen oder die Größe ändern: background, border, box-shadow, padding, margin, width und display.

Ohne Browser oder ohne eine zu öffnende Seite melden Sie die Code-Befunde und listen Sie die Browser-Prüfungen auf, die nicht ausgeführt wurden.

4. Jeden Befund überprüfen

Bevor Sie einen Befund melden, überprüfen Sie ihn noch einmal:

• Code-Befund. Bestätigen Sie, dass ein Benutzer den Zustand erreichen kann: Der Branch läuft, das Prop wird übergeben, und kein Wrapper oder übergeordnetes Element behandelt ihn.
• Browser-Befund. Messen Sie ein zweites Mal, nach einem Neuladen, in dem Zustand, den der Befund benennt. Verwerfen Sie einen Wert, der sich nicht wiederholt.
• In der Änderung oder davor. Ein Defekt in einer Zeile, die der Diff hinzugefügt oder geändert hat, gehört zur Änderung. Das gilt auch für einen Zustand, den der Diff ohne sein Gegenstück hinzufügt, selbst wenn die fehlende Zeile woanders hingehört: eine neue :hover-Regel ohne :focus-visible-Regel oder ein neuer Schreibvorgang ohne ausstehenden Zustand. Ein Defekt in einer Zeile, die der Diff nicht berührt hat, existierte davor. Melden Sie ihn unter „Bestehende Defekte“, getrennt von den Befunden der Änderung, und nur, wenn er sich auf einer geänderten Oberfläche befindet.

Verwerfen Sie einen Befund, der die Prüfung nicht besteht. Melden Sie einen Befund, den Sie nicht überprüfen konnten, als „Nicht bestätigt“ mit dem Grund.

5. Befunde melden

Beginnen Sie mit einer Zeile, die den von Ihnen überprüften Diff und die Oberflächen benennt. Geben Sie dann einen Befund pro Defekt an, zuerst den schwerwiegendsten. Schweregrad:

• Hoch: Der Benutzer verliert Daten oder Eingaben, sendet einen doppelten Schreibvorgang, kann ein Steuerelement nicht erreichen oder kann Text nicht lesen.
• Mittel: Das Steuerelement führt in die Irre (falsches Symbol, nur-Farben-Zustand, fehlende KI-Markierung) oder das Layout ist sichtbar defekt.
• Niedrig: Inkonsistenz mit dem System des Repositorys (rohe Typ-Werte, gemischte Auswahlsteuerelemente, Platzhalter).

Jeder Befund hat vier Teile:

Teil	Inhalt
Oberfläche	Die Ansicht und das Steuerelement sowie die Datei und Zeile (ReviewForm.tsx:42)
Regel	Die Regel-ID aus dem Katalog oder die Repository-Regel, die verletzt wird
Nachweis	Was Sie gelesen oder gemessen haben: die Codezeile, die gemessenen Werte, den Zustand, das Theme und die Breite
Reparatur	Die Änderung in ein oder zwei Sätzen, mit der Komponente oder dem Token des Repositorys, falls genannt

Beispiel:

Oberfläche: Stack-Seitenleiste, Autorenfilterliste (AuthorList.tsx:58) Regel: no-cramped-controls Nachweis: gaps(".author-row") bei 1440px, mit Zeile 2 hover: y: 0 zwischen Zeile 1 (ausgewählt) und Zeile 2. Im Ruhezustand beträgt der Abstand ebenfalls 0, aber nur die ausgewählte Zeile zeichnet einen Rahmen. Reparatur: Fügen Sie gap: 2px zur Liste hinzu oder setzen Sie die Hover-Füllung um 2px ein.

Fügen Sie dann diese Abschnitte hinzu:

1. Bestehende Defekte: die Defekte aus Schritt 4, die die Änderung nicht eingeführt hat, jeweils eine Zeile.
2. Nicht überprüft: die Regeln, die Sie übersprungen haben, und warum, sowie die Browser-Prüfungen, die nicht ausgeführt wurden.

Wenn der Benutzer Reparaturen anfordert, führen Sie diese durch und führen Sie dann dieselben Prüfungen erneut auf denselben Oberflächen durch.