gslvly/sketch-inspector

Sketch 检查器

Konvertiert Sketch-Designs in strukturierte Daten, Bildressourcen und implementierbare Seitenabschnitte.

Verwendungsszenarien

• Überprüfung eines geöffneten Sketch-Dokuments oder spezifischer Ebenen
• Extrahieren von Struktur, Stilen, Text, Farben, Layouts und Ressourceninformationen
• Implementierung von HTML/CSS, React, Vue oder anderen Seiten basierend auf einem Sketch-Bereich

Voraussetzungen

• Sketch ist geöffnet und das Zieldokument ist aktiv
• Sketch MCP ist aktiviert: Allgemein -> KI-Tools die Interaktion mit geöffneten Dokumenten erlauben
• MCP-Dienstadresse: http://localhost:31126/mcp
• Sketch Run Code läuft in einer JavaScriptCore/CocoaScript-Umgebung, nicht in normalem Node.js

Zwingender Ablauf für die Seitenimplementierung

Bei der Generierung einer Seite aus Sketch muss der folgende Ablauf strikt eingehalten werden. Dies ist der einzige schnellste Weg, die Aufgabe zu erledigen. Das Fehlen eines Schrittes gilt als Fehlschlag:

1. Scannen

Extrahiere die flache Umrissstruktur der Seite oder des Zielcontainers, bestätige die layerId des Wurzelknotens.

2. Pfad festlegen

• imageOutputDir: Projekt-Bilderverzeichnis, bevorzuge vorhandene images/, assets/images/, public/images/ usw.
• workTmpDir: Temporäres Verzeichnis, mindestens für result.json; bei großen Dateien auch für manifest.json, Abschnitts-JSONs, Abschnitts-HTMLs

3. Exportieren

Führe das Exportskript in sketch_run_code aus.

const sketch = require('sketch');

// Parameter vorbereiten
const layerId = '<layerId der Zielebene>'; // Aus Schritt 1 erhaltene Ziel-Wurzelknoten-ID
const outputDir = '<absoluter Pfad von imageOutputDir>';  // z.B.: '/Users/edy/project/images'
const outputJsonPath = '<absoluter Pfad von workTmpDir/result.json>';  // z.B.: '/Users/edy/project/tmp/result.json'

// Exportskript ausführen
const exportScript = require('@scripts/export-text-split-assets.js');
const result = exportScript.runExportTextSplitAssets({
  layerId: layerId,
  outputDir: outputDir,
  outputJsonPath: outputJsonPath
});

// Ergebnis zur Fehlersuche ausgeben
console.log(JSON.stringify(result, null, 2));

Ergebnis:

• Erfolg: Gibt Export-Statistiken zurück
• Fehlschlag: Gibt Fehlermeldung zurück, prüfe ob layerId gültig ist und ob Schreibrechte für den Pfad bestehen

Hinweise:

• Das Skript läuft in der Sketch JavaScriptCore-Umgebung, nicht in normalem Node.js
• Pfade müssen absolute Pfade sein
• Das Ausgabeverzeichnis muss existieren, das Skript erstellt es nicht automatisch

4. Layout-Inferenz und Überschreiben von result.json

Shell-Ausführung:

npx tsx @scripts/sketch_layout_ir_inference.ts \
  <workTmpDir>/result.json \
  <workTmpDir>/result.json

Dieser Schritt wandelt die exportierte Rohstruktur in ein direkt implementierbares, einheitliches Layout-JSON um und überschreibt das ursprüngliche result.json.

Struktur des einheitlichen result.json:

• kind: flex | grid | absolute | leaf
• direction: row | column (nur flex)
• gap: Abstand zwischen Kindelementen
• padding: Innenabstand { top, right, bottom, left }
• justifyContent: Flex-Ausrichtung
• alignItems: Ausrichtung auf der Querachse
• hasAbsoluteChildren: true wenn ein flex/grid-Container direkte absolute-Kindknoten hat
• css.position: "relative": Wird explizit ausgegeben, wenn ein flex/grid-Container direkte absolute-Kindknoten hat
• columns / rows: Anzahl der Spalten/Zeilen im Raster (nur grid)
• source: Ergänzende Implementierungsdaten für den aktuellen Layoutknoten, behält nur Nicht-Layout-Felder wie sourceClass / asset / background / style / decision / backgroundLayers / derivedFrom

5. Nach der Layout-Erkennung muss aufgeteilt werden

Nach Abschluss der Layout-Inferenz darf nicht nach Gefühl entschieden werden, wie implementiert wird. Die Entscheidung muss auf der tatsächlichen Zeilenanzahl des vereinheitlichten result.json basieren:

• result.json hat weniger als oder gleich 3000 Zeilen: Lese das gesamte result.json und implementiere direkt, keine Aufteilung mehr
• result.json hat mehr als 3000 Zeilen: Der "Großdateien-Aufteilungsprozess" muss verwendet werden, es ist verboten, das gesamte JSON direkt in die nächsten Implementierungsschritte zu geben

Beispiel für die Zeilenanzahl-Prüfung:

wc -l <workTmpDir>/result.json

6. Hauptprozess für kleine Dateien: Direkte Implementierung

Anwendungsbedingung: result.json Zeilenanzahl <= 3000

Kernregeln (MÜSSEN BEFOLGT WERDEN):

1. Keine absolute Positionierung in normalen Layouts: Nur Knoten mit kind: "absolute" dürfen absolut positioniert werden
2. Bei direkten absoluten Kindknoten muss den Positionierungssignalen aus result.json vertraut werden: Wenn ein Knoten hasAbsoluteChildren: true oder css.position: "relative" ausgibt, muss der übergeordnete Container bei der Implementierung in einen positionierten Zustand versetzt werden, darf nicht ignoriert werden

Generierungsprozess:

1. Vollständiges result.json lesen
2. Layoutbaum rekursiv durchlaufen
3. Entsprechend kind das entsprechende CSS generieren:
   • flex: display: flex; flex-direction: {direction}; gap: {gap}px; ...
   • grid: display: grid; grid-template-columns: repeat({columns}, 1fr); ...
   • absolute: position: relative; beim übergeordneten Element, Kindelemente position: absolute;
   • leaf: Kein Layout, Inhalt rendern
4. Das source des aktuellen Knotens direkt verwenden, um Text, Bilder, Hintergründe, Stile, Entscheidungen zu implementieren, nicht mehr auf die alte Struktur-JSON zurückgreifen

7. Hauptprozess für große Dateien: Aufteilung -> Einzelabschnitt-Implementierung -> Zusammenführung

Anwendungsbedingung: result.json Zeilenanzahl > 3000

7.1 JSON aufteilen

Shell-Ausführung:

node @scripts/split-result-json.js \
  --inputJsonPath=<workTmpDir>/result.json \
  --outputDir=<workTmpDir> \
  --assetBasePath=images/ \
  --splitStrategy=auto

Ausgabe:

• <workTmpDir>/manifest.json
• Mehrere Abschnitts-JSONs
• Vereinbarte implementationPath, htmlMarker, cssMarker
• manifest.json.root.layoutIR: Semantische Zusammenfassung des Hauptseitenlayouts
• manifest.json.sections[].layoutIR: Semantische Zusammenfassung des Layouts des Abschnittsknotens selbst

7.2 Einzelabschnitt-Implementierung

Jeder Abschnitt muss nur seinen eigenen jsonPath lesen und gemäß manifest.json in seinen eigenen implementationPath schreiben.

Zwingende Regeln:

• Der Ablauf für Einzelabschnitt-Implementierung siehe @references/single-section-workflow.md
• Abschnittsdateien müssen Fragmente sein: ein <section> + ein <style>
• Innerhalb eines Abschnitts nur interne Struktur und interne Stile schreiben, nicht den äußeren Rand des Hauptlayoutcontainers definieren
• Nicht-Wurzel-Selektoren müssen mittels className isoliert werden
• Bei Bedarf einer tiefergehenden Prüfung mit @scripts/inspect-single-section.js verwenden

7.3 Zusammenführung

Nachdem alle Abschnitte implementiert sind, müssen die Fragmente jedes Abschnitts in die Hauptlayoutdatei eingefügt werden. Marker-Inhalte dürfen nicht manuell kopiert und eingefügt werden.

Die Hauptlayoutdatei muss vorbereitend erfüllen:

• htmlMarker muss an der Stelle in der Seitenstruktur platziert werden, an der der Abschnitt eingefügt werden soll
• cssMarker muss innerhalb des <style>-Blocks der Hauptlayoutdatei platziert werden, nicht außerhalb anderer Tags, Kommentarblöcke oder im Textkörper
• Wenn HTML und CSS in separaten Dateien sind, muss cssMarker in der durch cssLayoutPath angegebenen CSS-Datei platziert werden

Shell-Ausführung:

node @scripts/replace-section-placeholder.js \
  --layoutPath=/path/layout.html \
  --sectionPath=/path/01-section.html \
  --htmlMarker="<!-- 01-section HTML -->" \
  --cssMarker="/* 01-section CSS */"

Wenn HTML und CSS in verschiedenen Dateien sind, zusätzlich --cssLayoutPath übergeben.

8. Checkliste vor der Implementierung

Vor der Implementierung prüfen:

• Vollständiges result.json gelesen
• Das kind-Feld jedes Knotens überprüft
• Hintergrundebenen-Informationen in meta.background überprüft
• Text-, Bild- und Ebenenbeziehungen überprüft
• Marken-Assets und komplexe visuelle Gruppen identifiziert

9. Lieferung

Berichte über objektive Ergebnisse:

• Layoutumriss und Zielbereichs-ID
• result.json Pfad und tatsächliche Zeilenanzahl
• Ob "Kleine Datei direkte Implementierung" oder "Großdateien-Aufteilungsprozess" verwendet wurde
• Wenn Aufteilungsprozess: manifest.json Pfad, Anzahl der Abschnitte, Pfad der Zielzusammenführungsdatei
• Layouttyp-Statistik (Anzahl flex/grid/absolute/leaf)
• Exportierte Ressourcenliste
• Pfade der generierten HTML/CSS-Dateien

Keine Schlussfolgerungen ausgeben, die eine Maschine nicht beurteilen kann, wie z.B. "visuell verifiziert".

Feste Skripte

Skriptparameter und Rückgabestruktur siehe @references/script-api.md.

• @scripts/export-text-split-assets.js: Exportiert Bilder und JSON. Erforderlich: layerId, outputDir
• @scripts/sketch_layout_ir_inference.ts: Layout-Inferenz und Ausgabe des vereinheitlichten result.json
• @scripts/split-result-json.js: Skript für den Großdateien-Prozess, generiert manifest.json und mehrere Abschnitts-JSONs
• @scripts/replace-section-placeholder.js: Skript für den Großdateien-Prozess, fügt Abschnittsimplementierungen in die Hauptlayoutdatei ein
• @scripts/inspect-single-section.js: Lokale Tiefenprüfung bei unzureichenden Abschnittsinformationen

Verboten: Eigene Exportskripte generieren, Skriptquellen kopieren oder die Traversierungslogik neu implementieren.

LayoutIR-Typbeschreibung

type LayoutKind = 'leaf' | 'flex' | 'grid' | 'absolute'

interface FlexIR {
  kind: 'flex'
  direction: 'row' | 'column'
  gap: number
  padding: { top, right, bottom, left }
  justifyContent: 'flex-start' | 'center' | 'flex-end' | 'space-between'
  alignItems: 'flex-start' | 'center' | 'flex-end' | 'stretch'
  children: LayoutIR[]
}

interface GridIR {
  kind: 'grid'
  columns: number
  rows: number
  columnGap: number
  rowGap: number
  padding: { top, right, bottom, left }
  children: LayoutIR[]
}

interface AbsoluteIR {
  kind: 'absolute'
  children: LayoutIR[]  // Kindelemente benötigen absolute Positionierung
}

interface LeafIR {
  kind: 'leaf'
  text?: string
  css: { width?, height? }
}

Regeln für den Ressourcenexport

• Bilder werden nach imageOutputDir exportiert, temporäre JSONs nach workTmpDir
• Bilddateinamen verwenden die ersten 8 Zeichen des MD5-Hashs, gleiche Bilder werden wiederverwendet
• asset/exports behalten nur path, src, x, y, width, height. Im generierten Code wird src referenziert, nicht path
• JSON löscht leere Werte und Style-Felder mit Wert 0
• Standardmäßig werden ausgeblendete Ebenen gefiltert
• Knoten mit echtem Text müssen aufgeteilt werden, dürfen nicht als Ganzes als Bild exportiert werden
• Normale Hintergrund-Rechtecke werden durch Code rekonstruiert; Marken-Assets und komplexe visuelle Gruppen werden bevorzugt originalgetreu exportiert

Referenzindex

• @references/export-assets.md: Regeln für den Ressourcenexport
• @references/script-api.md: Skriptparameter und Rückgabestruktur
• @references/single-section-workflow.md: Ablauf für Einzelabschnitt-Implementierung