html2figma — HTML Prototyp ⇄ Figma bearbeitbarer, klickbarer Prototyp
Wann verwenden
- Vorhandener HTML-Prototyp für Smartphones: 1:1 nach Figma übertragen: bearbeitbare Ebenen + klickbare Bildschirmwechsel + scrollbar + fixierte persistente Ebenen.
- Noch kein HTML-Prototyp: Zuerst nach der HTML-Prototyp-Spezifikation erstellen, vom Benutzer bestätigen lassen, dann nach Figma importieren.
- Fehlerbehebung im Figma-Prototyp: Textüberlappungen/falsche Zeilenumbrüche, fehlende Reaktionen, persistente Layer, die am unteren Ende eines langen Frames landen, fehlendes Scrollen.
Nicht geeignet: Nur-Figma-Dateien ohne HTML-Quelle; statische Desktop-Designs; reine How-to-Fragen zu Figma.
Drei Eingangsfragen (nicht überspringen)
- Gibt es einen HTML-Prototyp?
- Ja → Beginn mit Phase 1.
- Nein → Phase 0: Erstelle HTML-Prototyp gemäß Spezifikation → Rendere alle Bildschirm-Screenshots → Halte an und lass den Benutzer bestätigen → Erst nach Bestätigung nach Figma. HTML ist die Basis für alle Geometrie und Interaktionen; Import ohne Bestätigung verursacht hohen Nacharbeitsaufwand.
- Welche Elemente sind „persistente Ebenen“?
Gehe nicht standardmäßig von einem Dock aus. Scanne DOM/Screenshots gemäß §Persistente-Ebenen-Erkennung:
position:fixed, oder absolut positioniert und am oberen/unteren Viewport-Rand verankert,z-indexhöher als Inhalt, tritt in ≥2 Bildschirmen an derselben Viewport-Koordinate auf. Kann unteres Dock, obere Navigation, schwebender FAB, schwebender Hinweis, Zurück-nach-oben, modaler Griff usw. sein. Bei Unsicherheit: Überprüfe das HTML-Verhalten; wenn auch dort nicht, frage den Benutzer, rate nicht. - Lieferumfang? Drei Dinge: ① Pixelgenauigkeit (keine Textüberlappungen/falsche Zeilenumbrüche/Fehlpositionierungen) ② Bearbeitbar (Frame/Text/Vector/Bildfüllung) ③ Klickbar (Anzahl der Hotspots korrekt, nicht „ungefähr“).
Mentales Modell (4 Regeln, die Stunden sparen)
- HTML ist die einzige Basis. Jede Änderung in Figma muss eine semantische Entsprechung im HTML haben: fester Viewport,
overflow:hidden,position:fixed/absolute,closest('[data-goto]'). - Import ≠ Wiederherstellung. Das Plugin erzeugt ein „hohes langes Bild + statische Ebenen“; Viewport, Scrollen, fixierte Ebenen und Reaktionen werden nachträglich verarbeitet.
- Quantifizieren statt raten: Textüberlappungen mit Bounding Boxes, Wiedergabetreue mit MAE, Reaktionen mit Anzahl-Prüfung, Scrollen/Fixierung mit Present-Screenshot-Serien.
- Figma Plugin API kann Scrollen und Fixierung setzen (getestet):
frame.overflowDirection = 'VERTICAL'(gültige Werte nurNONE | VERTICAL | HORIZONTAL | BOTH;VERTICAL_SCROLLINGetc. verursacht Validation Error, nicht als „nicht unterstützt“ fehlinterpretieren). Fixierte Unterebenen mitnumberOfFixedChildren = N; fixierte Ebenen müssen die ersten N Unterebenen des Frames sein (zuerstinsertChild(0, layer)). Das Prototype-Panel dient als Fallback und für UI-only-Einstellungen wie Gerätemodelle.
Pipeline (jede Phase unabhängig prüfbar)
Phase 0 — HTML-Prototyp erstellen (nur wenn kein vorhandener HTML-Prototyp)
Gemäß references/html-prototype-spec.md: 393×852 Viewport, .phone/.screen/.scroll-Struktur, data-goto-Hotspots, Design-Tokens, Inline-SVG-Icons, eingebettete Schriftarten, clamp-Disziplin.
Abschlusskriterien: Alle Bildschirme renderbar, keine Überläufe/überlappender Text, alle Hotspots vorhanden; Ausgabe: Vollbild-Screenshots + Interaktionsbeschreibung, Benutzer zur Bestätigung vorlegen, erst dann fortfahren.
Phase 1 — Prototyp-Untersuchung
Erfasse: Anzahl und Größe der Bildschirme, Inhaltshöhe pro Bildschirm, -webkit-line-clamp-Knoten, Schriftfamilien/-stärken, data-goto-Hotspots (dedupliziert, effektiv), persistente Ebenen (siehe §Persistente-Ebenen-Erkennung).
Ergebnisse: boards.json, hotspots.json, clamp.json, persistent.json.
Phase 2 — Feed-Erstellung (Canvas → importierbarer Einzelbildschirm-Feed)
Nach Injektion von CSS/JS Serialisierung in feed/index.html:
- Canvas-Hülle ausblenden (obere Leiste, Seitenleiste, Bildschirm-Labels, Raster);
- UNCLIP: Entferne feste Höhe und
overflow:hidden, um Inhalt natürlich auszudehnen (Ebenen werden in voller Höhe erfasst, dann auf Viewport zurechtgeschnitten); - Abschneide-Strategie (erst nativ versuchen, dann Backen): Nach Import kann für Textebenen
textTruncation='ENDING'+maxLines=Ngesetzt werden (vorherloadFontAsyncaufrufen). Nur wenn buchstabengetreue Zeilenumbrüche wie im Browser benötigt werden, im Feed clamp backen (Algorithmus in pipeline). Gänzliches Weglassen des Abschneidens führt zu über den Rahmen ragendem Text; data-h2f-namezur Benennung von Boards und persistenten Ebenen; Schriftarten@font-faceinline/eingebettet.
Phase 3 — Exakter Schrifttreffer (Schlüssel zur korrekten Zeilenumbruch-Wiederherstellung)
Führe Subsetting der tatsächlich verwendeten Schriftarten durch, benenne sie mit einheitlichem Präfix um und installiere sie (HKCU/Systemschriften). Figma muss die gleiche Schriftart treffen, sonst verursacht der Ersatz scheinbare „Zeilenumbruchfehler“. Befehle und Umbenennungs-Skript in pipeline.
Phase 4 — Import und Board-Aufteilung
Upstream-Installation: git clone https://github.com/kevicebryan/open-htmltofigma.git, Figma Desktop → Plugins → Development → Import plugin from manifest… (Repository-internes manifest.json auswählen); festen Commit/Tag verwenden, bei manifest-ID-Konflikten ändern. Das Plugin rendert den Feed in einem iframe → erzeugt direkt Frame/Text/Vector; lokales Injektions-Skript füllt automatisch aus und konvertiert (vor Import Plugin-Viewport auf 393×852 setzen, sonst werden vh/Media Queries mit Standard 1440×1024 aufgelöst). Nach Import jeden Bildschirm-Frame als oberste Ebene anordnen, horizontal anordnen, benennen NN id · Titel, Root-Container löschen. Der Importer erstellt keine Reaktionen, diese müssen in Phase 5 neu geschrieben werden; Plugin-Version fixieren (siehe pipeline).
Phase 5 — Interaktionen (Reaktionen)
Durchlaufe Hotspots aufsteigend nach Fläche; Bounding Box ±2 trifft kleinsten Nicht-TEXT-Knoten, Mittelpunkt als Fallback; wenn Knoten keine Reaktion unterstützt, steige in der Elternkette auf; Vorhandene Reaktion ist ein Grund, weiter aufzusteigen (Eltern-Hotspot hat eigenen Knoten), kein Abbruchkriterium; Selbst-Sprünge überspringen. Lese node.reactions, schreibe mit await setReactionsAsync().
Nach Abschluss mit derselben Treffer+Aufstiegs-Logik zurückspielen; exp == ok && wrong == 0; Mengenprüfung erfordert dangling == 0.
Phase 6 — Viewport-Erstellung + Positionierung persistenter Ebenen
Zunächst mit persistent.json die Ankerpunkt-Bestimmung (bottom/top/fab/none) und Begründung für jede persistente Ebene auflisten, dann erst handeln; Unklarheiten markieren und Benutzer fragen, nicht standardmäßig alles fixieren.
Wandle jedes Board in die Prototyp-Viewport-Größe um (z. B. 393×852; von .phone auslesen, nicht hartcodieren, Android häufig 360×800/412×915), resize + clipsContent; hebe persistente Ebenen aus der Inhaltsebene in die Board-Wurzel, positioniere nach Viewport-Anker:
- Untere Leiste:
y = Viewport-Höhe - Höhe; - Obere Leiste:
y = 0; - FAB unten rechts: umrechnen nach HTML
right/bottom; - Ausblendbare/automatisch einklappbare Elemente (obere Leiste, die beim Scrollen ausblendet): nicht fixieren, im Inhaltsfluss belassen.
Fixierung und Scrollen können direkt über die API erfolgen (in diesem Projekt getestet, Figma Desktop):
board.insertChild(0, layer); // Fixierte Ebene muss ganz vorne in den Kinder-Ebenen stehen
board.numberOfFixedChildren = 1; // Die ersten N Kinder-Ebenen = fixierte Ebenen
board.overflowDirection = 'VERTICAL';
UI: Position = Fixed und Overflow = Vertical haben dieselbe Semantik und dienen als Fallback. Um Reaktionen zu erhalten, das Board nicht auf eine andere Seite klonen: setReactionsAsync schlägt seitenübergreifend fehl (getestet). Zuerst das volle Board auf einer ARCHIVE-Seite archivieren, dann vor Ort neu aufbauen.
Phase 7 — Scrollen + Fixierung + Gerätemodell
- Scrollen:
board.overflowDirection = 'VERTICAL'(Enum nurNONE | VERTICAL | HORIZONTAL | BOTH); - Fixierung:
board.numberOfFixedChildren = N(fixierte Ebenen = ersten N Kinder-Ebenen, siehe Phase 6); - UI-Fallback: Mehrere Boards auswählen → Prototype →
Overflow = Vertical; mehrere persistente Ebenen auswählen →Position = Fixed (stay in place); - Gerätemodell (UI-only): Abwahl → Dateiweite Prototype-Einstellungen → Device mit gleicher Größe wie Prototyp auswählen (z. B. iPhone 15 Pro = 393×852); Startseite mit Flow starting point markieren. Begründung und Koordinaten-Details in figma-ui-and-automation.
Phase 8 — Drei-Ebenen-Abnahme
- Pixel: 2x Export vs. Referenz, nach
@dx,dySchattenüberläufe beschneiden + ±2px Suche, MAE 3–10 normal; - Interaktion: Reaktions-Prüfung + Wiedergabe-Validierung;
- Präsentation: Present-Dreifach-Screenshots (initial / nach Scrollen / nach Bildschirmwechsel), bestätigen, dass persistente Ebenen stets im Viewport bleiben, sich nicht mit Inhalt verschieben. Details und Schwellwerte in verification.
Persistente-Ebenen-Erkennung (wichtig, nicht nur Docks erkennen)
Erkennungssignale (mindestens zwei Kriterien erfüllt = Kandidat):
| Signal | Wie prüfen |
|---|---|
| CSS-Positionierung | position:fixed, oder absolute + bottom/top am Viewport-Rand |
| Ebenen-Reihenfolge | z-index höher als Inhaltsebene; über scrollbarem Inhalt |
| Bildschirmübergreifende Wiederholung | Gleicher Selektor/gleiche Viewport-Koordinate in ≥2 Bildschirmen (untere Navigation, obere Leiste am häufigsten) |
| Visuell | Abgerundete schwebende Leiste, Glas-Effekt, Schatten-Float, FAB, Toast |
| Verhalten | HTML/JS überwacht Scrollen für Show/Hide oder Farbwechsel |
Entscheidungsmatrix:
- Immer überlagernd, bildschirmübergreifend persistent (untere Tab-Leiste, obere Leiste) → Im Figma-Viewport fixieren (
Fixed). - Nur überlagernd, nicht am Rand (FAB) → Ebenfalls in Viewport-Ebene anheben und fixieren.
- Mit Inhalt scrollend (normale Karten, Inline-Buttons) → In Inhaltsebene belassen, nicht fixieren.
- Beim Scrollen ausblendend/erscheinend (Auto-Hide-Header) → Figma kann die vollständige Logik nicht mit nativen Interaktionen reproduzieren: Bevorzugt die statische Semantik „scrollt mit/blendet aus“ beibehalten, oder in Zustandsbildschirme aufteilen; nicht fälschlicherweise auf Fixed setzen. Bei Unsicherheit Benutzer fragen, welchen Präsentationseffekt er wünscht.
- Overlay/modaler Griff → Gehört normalerweise zum Overlay-Bildschirm selbst, nach Inhalt dieses Bildschirms behandeln, nicht bildschirmübergreifend fixieren.
Projektbeispiel: Unteres Dock auf 14 Bildschirmen mit je 6 Hotspots, auf
y = 852-72 = 780gesetzt und auf Fixed; dieselbe Formel gilt für obere Leiste/FAB – zuerst Semantik bestimmen, dann Koordinaten anwenden.
Häufige Fallstricke (Top 14)
| # | Phänomen | Ursache / Maßnahme |
|---|---|---|
| 1 | Persistente Ebene am unteren Ende eines langen Bildes | Import UNCLIP hat den festen Viewport entfaltet, bottom:0 landet am Ende des Inhalts → Phase 6 Viewport-Erstellung |
| 2 | Validation Error beim Setzen von Scrollen | Falscher Enum-Wert (z. B. VERTICAL_SCROLLING) → VERTICAL verwenden; normales FRAME ist beschreibbar, nicht fälschlich als „nicht unterstützt“ einstufen |
| 3 | Fixierte Unterebene gesetzt, aber nicht wirksam | Fixierte Ebene muss erste N Kinder-Ebenen des Frames sein: zuerst insertChild(0, layer) dann numberOfFixedChildren = N setzen |
| 4 | Reaktionen nach Klonen auf neue Seite alle fehlgeschlagen | Seitenübergreifendes setReactionsAsync abgelehnt → Vor Ort neu aufbauen, Archiv getrennt speichern |
| 5 | Text überlappt darunter liegende Labels | Zuerst nativ textTruncation='ENDING' + maxLines versuchen; bei Abweichung im Feed buchstabengetreues Abschneiden backen |
| 6 | Figma-Zeilenumbruch anders als Browser | Schriftart ersetzt → Subsetting+Umbenennung+Installation |
| 7 | Exportiertes Bild größer als Zeichenfläche, Vergleich falsch | Export enthält Schattenüberläufe → nach @dx,dy beschneiden |
| 8 | Synthetischer Mausklick/Scrollen unwirksam | Webview filtert; Menü klickbar. Panel mit UIA/Tastatur; Player-Scrollen mit PostMessage-Rad |
| 9 | Zweiter Skript-Klick auf Overlay trifft nicht | Jeder Lauf bringt Fenster in den Vordergrund → Öffnen+Auswahl in denselben Lauf legen |
| 10 | Screenshot-Koordinaten verschoben | DPI-bewusst; Screenshot-Koordinaten == Fenster-relativ; UIA absolut in physikalischen Pixeln |
| 11 | Plugin läuft in andere Datei | Figma stellt alten Tab wieder her / öffnet fälschlich Unbenannt → zuerst aktiven Tab bestätigen |
| 12 | Zugeschnittenes Bild lässt sich nicht öffnen | Nicht-ganzzahlige Skalierung erzeugt nicht-ganzzahlige Größen → Ausgabe auf ganze Pixel runden |
| 13 | Canvas enthält seltsamen Text | Versehentliches Einfügen erzeugt TEXT-Knoten → nach Inhalt mit Regex bereinigen |
| 14 | Ergebnis nicht lesbar | Mit page.name oder lokalem HTTP-Collector Status zurücklesen |
Plattform & Kompatibilität
- Dieser Skill folgt dem Agent Skills-Standard (SKILL.md + references/ + scripts/), ladbar von ZCode, Claude Code und jedem Agent, der diesen Standard implementiert.
- Die Ablaufbeschreibung ist möglichst allgemein gehalten, aber der Import erfordert das open-htmltofigma-Entwicklungs-Plugin und Figma Desktop; Automatisierungsskripte sind für Windows ausgelegt; macOS/Linux mit AppleScript/
screencapture/xdotoolo. Ä. umschreiben oder gemäß Dokumentation manuell ausführen. - Figma Web kann keine lokalen Entwicklungs-Plugins importieren; pluginbezogene Schritte benötigen die Desktop-Version (Web kann bereits veröffentlichte Plugins öffnen).
Referenzen & Skripte
- references/html-prototype-spec.md — Spezifikation zur Erstellung eines HTML-Prototyps inklusive Abnahmeliste (mit „zuerst dem Benutzer vorlegen“-Gate), falls kein HTML-Prototyp vorhanden.
- references/pipeline.md — Feed/UNCLIP, Clamp-Algorithmus, Schriftarten, Import/Board-Aufteilung, Reaktionen, Viewport-Erstellungs-Code-Grundgerüst.
- references/figma-ui-and-automation.md — API/UI-Fähigkeitsmatrix, Batch-Einstellungen, Gerätemodell, Windows-Automatisierung und Koordinatenregeln.
- references/verification.md — MAE, Reaktions-Prüfung/Wiedergabe, Present-Dreifach-Screenshots, Fehlerdiagnose.
scripts/rename_font.py,scripts/install_font.ps1— Schriftart-Subsetting/Umbenennung und Installation für aktuellen Benutzer (inkl. Deinstallation).scripts/figma_win.ps1,scripts/uia.ps1— Windows-Hilfsfunktionen (Klick/Hover/Tastatur/Scrollen/Screenshot, UIA-Enumeration/Klick/Fokus).scripts/crop.mjs— Plattformunabhängiges PNG-Zuschneiden (ganzzahlige Skalierung, für Screenshot-Überprüfung).
Arbeitsweise
- Vor Code-Änderung erklären: „Welche Zeile, warum“, eine Ursache pro Schritt; Zwischenprodukte mit Versionsnummer und neuem Dateinamen versehen.
- Jedes „sieht richtig aus“ muss durch Zahlen oder Screenshots belegt werden; jedes „sollte funktionieren“ muss im Present getestet sein.
- Ausschließlich auf die drei Ziele „Wiederherstellung / Bearbeitbarkeit / Klickbarkeit“ konzentrieren; keine Refaktorisierung der Pipeline nebenbei, keine Abhängigkeits-Upgrades.