byceebee/layout-witness

Layout Witness

Machen Sie die Seite leichter überblickbar und nutzbar. Geben Sie verwandten Elementen eine klare Gruppierung, halten Sie wiederholte Komponenten konsistent und bewahren Sie diese Beziehungen, wenn sich der Inhalt und die Viewport-Größe ändern. Verwenden Sie die Hilfslinien, um zu entscheiden, was Sie während der Bearbeitung korrigieren müssen.

Verwenden Sie die Chrome-Erweiterung im vorhandenen Entwicklungstab. Verbinden Sie dessen lokale Agent-Verbindung, um die Hilfslinien zu steuern und Seiten- und Elementmessungen als JSON im Terminal zu lesen. Verwenden Sie die optionale Playwright-CLI für unbeaufsichtigte Aufnahmen in frischen Browser-Kontexten.

Verbindung zum vorhandenen Tab herstellen

Laden Sie das gesamte layout-witness-Skillverzeichnis als entpackte Erweiterung unter chrome://extensions. Verwenden Sie Chrome 116 oder neuer.

1. Setzen Sie WITNESS_DIR auf das installierte Skillverzeichnis. Führen Sie einmal (cd "$WITNESS_DIR" && npm ci --omit=dev) aus, und starten Sie dann node "$WITNESS_DIR/scripts/agent.mjs" serve in einem persistenten Terminal.
2. Öffnen Sie Layout Witness über die Symbolleiste im Entwicklungstab. Fügen Sie unter Agentenzugriff die vom Terminal ausgegebene Pairing-URL ein und wählen Sie Agent verbinden. Dies autorisiert den einen Tab. Wenn der Zugriff fehlt, bitten Sie den Benutzer, diesen Tab einmal zu paaren.
3. Verwenden Sie die CLI von einem beliebigen Terminal auf demselben Rechner. Lassen Sie den lokalen Server während der Bearbeitung laufen.

node "$WITNESS_DIR/scripts/agent.mjs" start
node "$WITNESS_DIR/scripts/agent.mjs" select 'header [aria-label="Search"]'
node "$WITNESS_DIR/scripts/agent.mjs" measure
# Bearbeiten Sie das CSS des Projekts und warten Sie, bis der Dev-Server es anwendet.
node "$WITNESS_DIR/scripts/agent.mjs" measure

measure gibt Seitenregionen, Prüfergebnisse und das aktuell ausgewählte Element aus, sofern vorhanden. Dieses Element kann seinen dargestellten Rahmen, Rand (margin), Rahmenlinie (border), Innenabstand (padding), Raster- und Abstandswerte, Typografie (einschließlich des Viewport-Basislinien-Y, wenn messbar) sowie SVG-Geometrie umfassen. Verwenden Sie einen Selektor, der genau ein sichtbares Element findet. Behalten Sie die Auswahl während der Bearbeitung bei und lesen Sie das JSON erneut, nachdem der Browser die Änderung angewendet hat.

Verwenden Sie status, um die Verbindung zu prüfen, clear, um nur die Elementhilfslinie zu entfernen, pick für die manuelle Auswahl per Klick, import <rules.json>, um Projektregeln zu laden, und defaults, um die Standardregeln wiederherzustellen. Verwenden Sie stop, um beide Hilfslinien zu entfernen und die Auswahl für eine saubere Überprüfung zu löschen. Verwenden Sie start und select, um fortzufahren. Verwenden Sie disconnect, wenn der Tab keine Befehle mehr annehmen soll. Gleichherkunfts-Neuladungen können die Hilfslinien und eine Auswahl auf derselben Route wiederherstellen. Eine andere Herkunft oder das Schließen des Tabs beendet die Paarung.

Für die manuelle Überprüfung verwenden Sie Hilfslinien starten, Element inspizieren und Hilfslinien stoppen im Popup der Symbolleiste. Bericht herunterladen ist verfügbar, wenn Sie eine Kopie speichern möchten.

Mit den Hilfslinien arbeiten

1. Legen Sie das erwartete Layout fest. Lesen Sie die Layout- und Komponentenregeln des Projekts, überprüfen Sie dann die vorhandenen Tokens und akzeptierten Geschwisterkomponenten. Notieren Sie die für die Aufgabe relevanten Beziehungen, z. B. eine gemeinsame Lesekante, einen Abstand zwischen Navigationsgruppen oder den Innenabstand einer Schaltfläche. Wählen Sie auf einer neuen Seite diese Beziehungen aus dem Brief und notieren Sie Ihre Annahmen. Behandeln Sie das Standardraster der Erweiterung als explorativen Leitfaden.
2. Inspizieren Sie von der Seite bis zum Element. Starten Sie die Hilfslinien vor der Bearbeitung. Erfassen Sie den dargestellten Startpunkt und wählen Sie das Element aus, das das Problem verursacht. Verwenden Sie den Bericht für genaue Messungen, wenn die Beschriftungen gedrängt sind. Starten Sie bei einer neuen Seite die Hilfslinien, sobald das Shell gerendert ist, und behalten Sie die Hilfslinien bei, während Sie Abschnitte und Steuerelemente hinzufügen.
3. Bearbeiten Sie die Quelle bei aktiver Auswahl. Vergleichen Sie den gemessenen Wert mit dem erwarteten. Korrigieren Sie das CSS oder die gemeinsam genutzte Komponente, die für die Beziehung verantwortlich ist. Wenn der Dev-Server die Bearbeitung anwendet, überprüfen Sie die Hilfslinien und Messungen desselben Elements, bevor Sie ein anderes Element auswählen. Wenn ein Neuladen das Element ersetzt, bestätigen Sie, dass die wiederhergestellte Auswahl immer noch auf das beabsichtigte Steuerelement verweist. Notieren Sie den tatsächlichen Wert, den erwarteten Wert und das gemessene Ergebnis.
4. Überprüfen Sie die saubere Darstellung. Erfassen Sie zuerst die korrigierte Hilfslinie, schalten Sie dann die Hilfslinien aus und inspizieren Sie die tatsächliche Seite. Überprüfen Sie Gruppierung, Hierarchie, Ausrichtung, Umbruch und sichtbaren Fokus bei den Breiten, bei denen sich das Layout ändert. Berücksichtigen Sie lange Beschriftungen oder übersetzte Inhalte sowie relevante geöffnete, geschlossene oder dichte Zustände. Melden Sie verbleibende Probleme sowie die Breiten und Zustände, die Sie überprüft haben.

Umfang	Worauf zu achten ist
Seiten-Shell	Verwenden Sie die Seitenhilfslinien, um gemeinsame Lesekanten, äußere Rinnen und die Anpassung von Kopfzeile, Seitenleiste, Hauptbereich und Fußzeile an Breakpoints zu überprüfen. Überprüfen Sie in der sauberen Darstellung, dass wiederkehrende Aktionen leicht zu finden bleiben und die Hauptaufgabe die meiste visuelle Betonung erhält.
Gruppen und wiederholte Komponenten	Verwenden Sie lokale Rasterspuren, um Ausrichtung und Spannweiten innerhalb einer Region zu überprüfen. Vergleichen Sie den Abstand zwischen Gruppen getrennt von den Innenabständen innerhalb jeder Komponente. Halten Sie verwandte Elemente sichtbar gruppiert und überprüfen Sie die Lesereihenfolge, wenn Gruppen gestapelt werden.
Einzelne Elemente	Wählen Sie das Steuerelement aus, um seinen Rahmen, Innenabstand und den Abstand zwischen Symbol und Beschriftung zu inspizieren. Vergleichen Sie Zeilenhöhe und Grundlinie von Beschriftungen, die ausgerichtet sein sollen. Überprüfen Sie die Symbolgröße und Strichstärke innerhalb derselben Familie und beurteilen Sie dann den optischen Ausgleich in der dargestellten Größe. Messen Sie das interaktive Ziel getrennt von seiner Glyphe.

Überprüfen Sie bei einer überfüllten Seitenleiste zuerst, ob verwandte Links als Gruppe lesbar sind und benachbarte Abschnitte einen klaren Abstand aufweisen. Wählen Sie dann eine Zeile aus und vergleichen Sie ihren Innenabstand und den Symbol-Beschriftungs-Abstand mit gleichwertigen Zeilen. Wenn die gemeinsam genutzte Komponente 16 px auf jeder Seite vorsieht und die Hilfslinie 8 px auf einer Seite anzeigt, stellen Sie das Token wieder her und messen Sie dieselbe Auswahl erneut. Schalten Sie die Hilfslinie aus, um die erweiterte und reduzierte Seitenleiste im Kontext zu überprüfen.

Verwenden Sie strenge Prüfungen für explizite Erwartungen wie Token-Werte, Ausrichtung zwischen benannten Kanten und Überlauf. Beurteilen Sie Hierarchie und optischen Ausgleich auf der gerenderten Seite. Verwenden Sie die Schriftskala des Projekts, um zu entscheiden, ob eine Grundlinie ausgerichtet werden soll.

Design-Referenzen

• Adobe Spectrum 2 erklärt, wie Nähe Beziehungen signalisiert, wie sich Abstände je nach Umfang unterscheiden und wie Symbole und Strichstärken innerhalb einer Familie überprüft werden. Abstände · Grundlagen der Symbolografie
• Figma zeigt, wie man Hilfslinien für die Seite, verschachtelte Regionen, Komponentenabstände und Textgrundlinien auswählt. Layoutraster
• Das Design-Update von Linear ist eine Fallstudie zu vorhersagbaren Kopfzeilenaktionen und visueller Hierarchie in einem dichten Arbeitsbereich. Design-Update

Wenn Barrierefreiheit im Umfang ist, verwenden Sie die WCAG, um Reflow, Textabstandsüberschreibungen durch den Benutzer und tatsächliche Zeigergeräte-Zielgrößen sowie geltende Ausnahmen zu überprüfen. Reflow · Textabstand · Zielgröße

Optionale unbeaufsichtigte Aufnahmen

Verwenden Sie die CLI, wenn die Automatisierung frische Browser-Kontexte über verschiedene Viewport-Breiten oder Themen hinweg benötigt. Voraussetzung sind Node.js 22+ und Playwright Chromium. Setzen Sie WITNESS_DIR auf das installierte Skillverzeichnis und installieren Sie dort seine Abhängigkeiten:

(cd "$WITNESS_DIR" && npm ci && npx --no-install playwright install chromium)

Führen Sie die CLI aus dem Projektverzeichnis aus, damit dessen Konfigurations- und Ausgabepfade dort aufgelöst werden:

node "$WITNESS_DIR/scripts/witness.mjs" capture http://localhost:3000 \
  --config ./layout-witness.json --width 1440 --width 390 --strict \
  --out .layout-witness/review

Lesen Sie den generierten Overlay- und JSON-Bericht. Der Erfassungsmodus öffnet für jede Breite und jedes Thema eine frische Seite. Siehe die Regelreferenz für Regions- und Prüfdefinitionen. Verwenden Sie watch für den interaktiven CLI-Workflow.