Communitygithub.com

html2figma

Konvertiere HTML-Prototypen für Smartphones in bearbeitbare, klickbare, scrollbare Figma-Prototypen. Unterstützt Multi-Screen-Boards, Vektorebenen, ON_CLICK zu NAVIGATE-Reaktionen, Gerätemodelle, Erkennung persistenter Layer (Bottom Tab Bar, Top Bar, FAB, Toast, nicht nur Docks), echtes Scrollen mit fixierten Ebenen und Pixel-für-Pixel-Prüfung.

Was ist html2figma?

html2figma ist ein Skill, der HTML-Prototypen für Smartphones in vollständig bearbeitbare und interaktive Figma-Prototypen umwandelt. Er eignet sich für Entwickler und Designer, die einen HTML-Prototypen als Figma-Datei bereitstellen möchten, einschließlich klickbarer Bildschirmübergänge, Scrollen mit fixierten Ebenen und Pixel-für-Pixel-Prüfung. Der Skill unterstützt alle gängigen Plattformen (Claude Code, Cursor, Codex) und folgt dem Agent Skills Standard. Der Workflow umfasst acht Phasen: von der Erstellung des HTML-Prototyps (Phase 0) über den Import in Figma (Phase 4) bis hin zur finalen Verifikation (Phase 8). Besonderes Augenmerk liegt auf der korrekten Erkennung persistenter Layer (nicht nur Docks, sondern auch FABs, Toasts, Top Bars), der präzisen Schriftwiedergabe zur Vermeidung von Zeilenumbruchfehlern und der nahtlosen Integration von Reaktionen. Der Skill bietet detaillierte Anleitungen zur Fehlerbehebung (z. B. fixierte Layer, die am unteren Ende eines langen Frames landen, fehlende Reaktionen) und warnt vor häufigen Fallstricken wie falschen Enum-Werten beim Scrollen oder problematischen Cross-Page-Reaktionen.

Funktioniert mit✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ilovemajiaqi/html2figma/tree/HEAD

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

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)

  1. 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.
  2. 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-index hö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.
  3. 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 nur NONE | VERTICAL | HORIZONTAL | BOTH; VERTICAL_SCROLLING etc. verursacht Validation Error, nicht als „nicht unterstützt“ fehlinterpretieren). Fixierte Unterebenen mit numberOfFixedChildren = N; fixierte Ebenen müssen die ersten N Unterebenen des Frames sein (zuerst insertChild(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=N gesetzt werden (vorher loadFontAsync aufrufen). 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-name zur Benennung von Boards und persistenten Ebenen; Schriftarten @font-face inline/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 nur NONE | 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

  1. Pixel: 2x Export vs. Referenz, nach @dx,dy Schattenüberläufe beschneiden + ±2px Suche, MAE 3–10 normal;
  2. Interaktion: Reaktions-Prüfung + Wiedergabe-Validierung;
  3. 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):

SignalWie prüfen
CSS-Positionierungposition:fixed, oder absolute + bottom/top am Viewport-Rand
Ebenen-Reihenfolgez-index höher als Inhaltsebene; über scrollbarem Inhalt
Bildschirmübergreifende WiederholungGleicher Selektor/gleiche Viewport-Koordinate in ≥2 Bildschirmen (untere Navigation, obere Leiste am häufigsten)
VisuellAbgerundete schwebende Leiste, Glas-Effekt, Schatten-Float, FAB, Toast
VerhaltenHTML/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 = 780 gesetzt und auf Fixed; dieselbe Formel gilt für obere Leiste/FAB – zuerst Semantik bestimmen, dann Koordinaten anwenden.

Häufige Fallstricke (Top 14)

#PhänomenUrsache / Maßnahme
1Persistente Ebene am unteren Ende eines langen BildesImport UNCLIP hat den festen Viewport entfaltet, bottom:0 landet am Ende des Inhalts → Phase 6 Viewport-Erstellung
2Validation Error beim Setzen von ScrollenFalscher Enum-Wert (z. B. VERTICAL_SCROLLING) → VERTICAL verwenden; normales FRAME ist beschreibbar, nicht fälschlich als „nicht unterstützt“ einstufen
3Fixierte Unterebene gesetzt, aber nicht wirksamFixierte Ebene muss erste N Kinder-Ebenen des Frames sein: zuerst insertChild(0, layer) dann numberOfFixedChildren = N setzen
4Reaktionen nach Klonen auf neue Seite alle fehlgeschlagenSeitenübergreifendes setReactionsAsync abgelehnt → Vor Ort neu aufbauen, Archiv getrennt speichern
5Text überlappt darunter liegende LabelsZuerst nativ textTruncation='ENDING' + maxLines versuchen; bei Abweichung im Feed buchstabengetreues Abschneiden backen
6Figma-Zeilenumbruch anders als BrowserSchriftart ersetzt → Subsetting+Umbenennung+Installation
7Exportiertes Bild größer als Zeichenfläche, Vergleich falschExport enthält Schattenüberläufe → nach @dx,dy beschneiden
8Synthetischer Mausklick/Scrollen unwirksamWebview filtert; Menü klickbar. Panel mit UIA/Tastatur; Player-Scrollen mit PostMessage-Rad
9Zweiter Skript-Klick auf Overlay trifft nichtJeder Lauf bringt Fenster in den Vordergrund → Öffnen+Auswahl in denselben Lauf legen
10Screenshot-Koordinaten verschobenDPI-bewusst; Screenshot-Koordinaten == Fenster-relativ; UIA absolut in physikalischen Pixeln
11Plugin läuft in andere DateiFigma stellt alten Tab wieder her / öffnet fälschlich Unbenannt → zuerst aktiven Tab bestätigen
12Zugeschnittenes Bild lässt sich nicht öffnenNicht-ganzzahlige Skalierung erzeugt nicht-ganzzahlige Größen → Ausgabe auf ganze Pixel runden
13Canvas enthält seltsamen TextVersehentliches Einfügen erzeugt TEXT-Knoten → nach Inhalt mit Regex bereinigen
14Ergebnis nicht lesbarMit 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/xdotool o. Ä. 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.

Verwandte Skills