html2figma — Prototype HTML ⇄ Prototype Figma éditable et cliquable
Quand l’utiliser
- Vous avez un prototype HTML existant pour mobile et souhaitez l’importer à l’identique dans Figma : calques éditables + clic de navigation + défilement + éléments persistants fixes.
- Vous n’avez pas encore de prototype HTML : créez-le d’abord selon la spécification des prototypes HTML, faites-le valider par l’utilisateur, puis importez.
- Vous devez corriger des problèmes dans un prototype Figma : texte qui se chevauche/sauts de ligne incorrects, réactions perdues, éléments persistants qui tombent en bas d’un grand cadre, impossibilité de défiler.
Ne convient pas : câblage natif Figma sans source HTML, import de maquettes statiques desktop, questions ponctuelles sur les opérations Figma.
Trois questions d’entrée (à ne pas sauter)
- Avez-vous un prototype HTML ?
- Oui → commencez par la Phase 1.
- Non → passez par la Phase 0 : produisez le prototype HTML selon la spécification → rendez tous les écrans en captures → arrêtez-vous pour faire valider par l’utilisateur → continuez seulement après approbation. Le HTML est la base de toute la géométrie et des interactions ; importer sans validation entraîne des reprises très coûteuses.
- Quels sont les « calques persistants » ?
N’assumez pas qu’il s’agit uniquement du dock. Parcourez le DOM/les captures selon la §Détection des calques persistants :
position:fixed, ouabsoluteancré en haut/bas du viewport,z-indexsupérieur au contenu, répété sur ≥2 écrans aux mêmes coordonnées viewport. Il peut s’agir du dock en bas, de la barre de navigation en haut, d’un FAB, d’un toast flottant, d’un bouton retour en haut, d’une poignée modale, etc. En cas de doute, référez-vous au comportement HTML ; si le HTML ne tranche pas, demandez à l’utilisateur, ne devinez pas. - Quel est le périmètre de livraison ? Les trois éléments sont requis : ① fidélité pixel (pas de chevauchement/sauts de ligne/décalage), ② éditabilité (Frame/Text/Vector/remplissage par image), ③ cliquabilité (le nombre de zones réactives est exact, pas « approximatif »).
Modèle mental (4 règles qui font gagner des heures)
- Le HTML est la seule référence. Chaque transformation dans Figma doit avoir un équivalent sémantique dans le HTML : viewport de hauteur fixe,
overflow:hidden,position:fixed/absolute,closest('[data-goto]'). - Importer ≠ restituer. Le plugin produit une « grande image pleine hauteur + calques statiques » ; le viewport, le défilement, les calques fixes et les réactions sont des post-traitements.
- Quand on peut quantifier, on ne devine pas à l’œil : chevauchement de texte par boîtes englobantes, fidélité par MAE, réactions par audit de nombre, défilement/fixation par séquence de captures en mode Présentation.
- L’API du plugin Figma permet de définir défilement et fixation (testé) :
frame.overflowDirection = 'VERTICAL'(seules valeurs valides :NONE | VERTICAL | HORIZONTAL | BOTH; passerVERTICAL_SCROLLINGprovoque une erreur de validation, ne l’interprétez pas comme « non supporté »). Pour les enfants fixes :numberOfFixedChildren = N; les calques fixes doivent être les N premiers enfants du cadre (d’abordinsertChild(0, layer)). Le panneau Prototype est une solution de dernier recours et pour les réglages purement UI (modèle de téléphone).
Pipeline (chaque phase peut être validée indépendamment)
Phase 0 — Création du prototype HTML (uniquement si pas de HTML existant)
Suivez references/html-prototype-spec.md : viewport 393×852, structure .phone/.screen/.scroll, zones data-goto, design tokens, icônes SVG inline, polices auto-contenues, discipline clamp.
Critères d’achèvement : tous les écrans sont rendus sans débordement ni chevauchement, zones réactives complètes ; produire des captures plein écran + notes d’interaction, faire valider par l’utilisateur, continuer seulement après accord.
Phase 1 — Examen du prototype
Quantifiez : nombre d’écrans et leurs dimensions, hauteur du contenu par écran, nœuds -webkit-line-clamp, familles de polices/graisses, nombre de zones data-goto uniques effectives, liste des calques persistants (voir §Détection des calques persistants).
Livrables : boards.json, hotspots.json, clamp.json, persistent.json.
Phase 2 — Construction du feed (canvas → flux d’écrans importables)
Après injection CSS/JS, sérialisez feed/index.html :
- Masquez le cadre du canvas (barre supérieure/latérale, étiquettes d’écran, grille) ;
- UNCLIP : supprimez la hauteur fixe et
overflow:hiddenpour laisser le contenu se déployer naturellement (les calques sont récupérés en pleine hauteur, puis recadrés au viewport) ; - Stratégie de troncature (essayer d’abord le natif, envisager la cuisson) : après import, vous pouvez définir
textTruncation='ENDING'+maxLines=Nsur les calques de texte (aprèsloadFontAsync). Ne cuisez leclampdans le feed que si un alignement caractère par caractère avec le navigateur est nécessaire (algorithme dans pipeline). Ne faire aucune troncature provoque des débordements hors cadre ; - Nommez les planches et calques persistants avec
data-h2f-name; polices@font-faceen inline/auto-contenues.
Phase 3 — Correspondance exacte des polices (clé pour les sauts de ligne)
Sous-ensemblez les polices réelles du prototype, renommez-les avec un préfixe commun, installez-les (HKCU / polices système). Figma doit trouver la même police, sinon le remplacement crée de faux « défauts de saut de ligne ». Les commandes et scripts de renommage sont dans le pipeline.
Phase 4 — Import et découpage des planches
Installation en amont : git clone https://github.com/kevicebryan/open-htmltofigma.git, Figma desktop → Plugins → Development → Import plugin from manifest… (sélectionnez manifest.json dans le dépôt) ; fixez un commit/tag, changez l’ID du manifest en cas de conflit. Le plugin rend le feed dans un iframe réel → crée directement des Frame/Text/Vector ; le script d’injection local remplit et Convertit automatiquement (avant l’import, réglez le viewport du plugin sur 393×852, sinon vh/les media queries seront résolues avec le viewport par défaut 1440×1024). Après import, remontez chaque Frame d’écran au niveau supérieur, alignez-les horizontalement, nommez-les NN id · Titre, supprimez le conteneur racine. L’importateur ne crée aucune réaction, elles doivent être réécrites en Phase 5 ; la version du plugin doit être figée (voir pipeline).
Phase 5 — Interactions (réactions)
Parcourez les zones réactives par ordre croissant de surface ; seuil de correspondance de bbox ±2 px sur le plus petit nœud non TEXT, par défaut le centre ; si le nœud ne supporte pas les réactions, remontez dans les ancêtres ; une réaction existante est une raison de continuer à remonter (la zone parente porte son propre nœud), pas une condition d’arrêt ; ignorez les auto-sauts. Lisez node.reactions, écrivez avec await setReactionsAsync().
Après écriture, rejouez avec la même logique de correspondance+remontée ; exp == ok && wrong == 0 ; l’audit de quantité exige dangling == 0.
Phase 6 — Viewportisation + positionnement des calques persistants
D’abord, listez chaque calque persistant dans persistent.json avec son point d’ancrage présumé (bottom/top/fab/none) et sa justification ; ne passez à l’action qu’ensuite ; marquez les incertitudes et demandez à l’utilisateur, ne fixez pas tout par défaut.
Transformez chaque planche sur place aux dimensions du viewport du prototype (ex. 393×852 ; lisez depuis .phone, ne les codez pas en dur ; Android courant : 360×800/412×915), resize + clipsContent, remontez les calques persistants du contenu vers la racine de la planche, positionnez selon le point d’ancrage viewport :
- Barre inférieure :
y = viewportHeight - height; - Barre supérieure :
y = 0; - FAB en bas à droite : convertissez
right/bottomdu HTML ; - Calques auto-masquants (barre qui s’estompe au défilement) : ne fixez pas, conservez le sens du flux de contenu.
Fixation et défilement peuvent être gérés directement par l’API (testé dans ce projet, Figma desktop) :
board.insertChild(0, layer); // Le calque fixe doit être parmi les premiers enfants
board.numberOfFixedChildren = 1; // Les N premiers enfants = calques fixes
board.overflowDirection = 'VERTICAL';
Les réglages UI Position = Fixed et Overflow = Vertical ont la même sémantique, en dernier recours. Pour conserver les réactions, ne clonez pas la planche sur une autre page : setReactionsAsync échoue systématiquement entre pages. Clonez d’abord la planche pleine hauteur dans une page ARCHIVE pour sauvegarde, puis reconstruisez sur place.
Phase 7 — Défilement + fixation + modèle de téléphone
- Défilement :
board.overflowDirection = 'VERTICAL'(énumération : seulementNONE | VERTICAL | HORIZONTAL | BOTH) ; - Fixation :
board.numberOfFixedChildren = N(les calques fixes = les N premiers enfants, voir Phase 6) ; - Solution UI de dernier recours : sélectionnez plusieurs planches → Prototype →
Overflow = Vertical; sélectionnez plusieurs calques persistants →Position = Fixed (stay in place); - Modèle de téléphone (UI uniquement) : désélectionnez tout → paramètres Prototype au niveau du fichier → Device choisissez un appareil aux dimensions du prototype (ex. iPhone 15 Pro = 393×852) ; définissez le point de départ du flow sur la première planche. Raison et coordonnées détaillées dans figma-ui-and-automation.
Phase 8 — Triple validation
- Pixels : export 2× vs référence, recadrez les ombres débordantes avec
@dx,dy+ recherche ±2 px, MAE 3–10 normal ; - Interactions : audit des réactions + rejeu de validation ;
- Présentation : trois captures d’écran en mode Présentation (initiale / après défilement / après navigation) : vérifiez que les calques persistants restent dans le viewport et ne bougent pas avec le contenu. Détails et seuils dans verification.
Détection des calques persistants (important, ne pas se limiter au dock)
Signaux (au moins deux critères remplis → candidat) :
| Signal | Comment l’observer |
|---|---|
| Position CSS | position:fixed, ou absolute + bottom/top collé au bord du viewport |
| Empilement | z-index supérieur au contenu ; superposé au contenu défilant |
| Répétition inter-écrans | Même sélecteur / mêmes coordonnées viewport sur ≥2 écrans (barre de navigation en bas, barre supérieure les plus courants) |
| Visuel | Barre flottante arrondie, verre dépoli, ombre portée, FAB, toast |
| Comportement | Le HTML/JS écoute le défilement pour afficher/masquer ou changer de couleur |
Décision de traitement :
- Toujours superposé et persistant entre écrans (barre d’onglets en bas, barre supérieure) → fixé dans le viewport Figma (
Fixed). - Superposé mais pas collé au bord (FAB) → remontez aussi dans le calque viewport et fixez.
- Qui défile avec le contenu (cartes normales, boutons inline) → laissez dans le contenu, ne fixez pas.
- Qui se masque/apparaît au défilement (auto-hide header) → Figma ne peut pas reproduire toute la logique avec des interactions natives : privilégiez la sémantique statique « suit le défilement / se masque », ou découpez en écrans d’état ; ne le fixez pas par erreur. En cas de doute, demandez à l’utilisateur quel effet de présentation il souhaite.
- Modal/poignée → appartient généralement à l’écran modal lui-même, traitez-le comme contenu de cet écran, pas de fixation inter-écrans.
Exemple du projet : un dock en bas sur 14 écrans avec 6 zones réactives chacun, remonté à
y = 852-72 = 780puis fixé ; la même formule s’applique à la barre supérieure et au FAB — déterminez d’abord la sémantique, puis appliquez les coordonnées.
Pièges fréquents (Top 14)
| # | Phénomène | Cause racine / Correctif |
|---|---|---|
| 1 | Calque persistant tout en bas du grand cadre | L’import UNCLIP déplie le viewport fixe, bottom:0 tombe à la fin du contenu → viewportisation Phase 6 |
| 2 | Erreur de validation au réglage du défilement | Mauvaise valeur d’énumération (ex. VERTICAL_SCROLLING) → utilisez VERTICAL ; les FRAME classiques l’acceptent, ne dites pas « non supporté » |
| 3 | Calque fixe positionné mais pas effectif | Les calques fixes doivent être les N premiers enfants du cadre : d’abord insertChild(0, layer), puis numberOfFixedChildren = N |
| 4 | Réactions perdues après clonage sur une nouvelle page | setReactionsAsync rejeté entre pages → reconstruisez sur place, archivez à part |
| 5 | Texte qui écrase les étiquettes en dessous | Essayez d’abord le natif textTruncation='ENDING' + maxLines ; si pas cohérent, cuisez la troncature caractère par caractère dans le feed |
| 6 | Sauts de ligne Figma différents du navigateur | Police remplacée → sous-ensemblez + renommez + installez |
| 7 | Export plus grand que la planche, comparaison fausse | L’export contient les ombres débordantes → recadrez selon @dx,dy |
| 8 | Clic/roulement synthétique inactif | Webview filtré ; le menu est cliquable. Panneaux : UIA/clavier ; lecteur : défilement via PostMessage |
| 9 | Deuxième clic de script sur un modal sans effet | Chaque exécution ramène la fenêtre au premier plan → ouvrez et sélectionnez dans la même exécution |
| 10 | Coordonnées de capture décalées | Sensible aux DPI ; coordonnées de capture = coordonnées relatives à la fenêtre ; UIA = pixels physiques absolus |
| 11 | Le plugin s’exécute dans un autre fichier | Figma restaure un ancien onglet ou ouvre “Sans titre” → vérifiez d’abord l’onglet actif |
| 12 | Image recadrée illisible | Zoom non entier produit des dimensions décimales → arrondissez la sortie |
| 13 | Texte étrange sur le canvas | Collé accidentellement, génère un nœud TEXT → nettoyez par expression régulière |
| 14 | Résultat illisible | Utilisez page.name ou un collecteur HTTP local pour lire l’état |
Plateformes et compatibilité
- Ce skill suit la spécification Agent Skills (SKILL.md + references/ + scripts/), chargeable par ZCode, Claude Code et tout agent implémentant la spécification.
- Le flux est décrit de manière générique, mais l’étape d’import dépend du plugin de développement open-htmltofigma et de Figma desktop ; les scripts d’automatisation ciblent Windows ; macOS/Linux : adaptez avec AppleScript/
screencapture/xdotool, ou suivez les instructions manuelles. - Figma web ne peut pas importer un plugin de développement local ; les étapes liées au plugin nécessitent la version desktop (la version web peut ouvrir un plugin déjà publié).
Références et scripts
- references/html-prototype-spec.md — Spécification de création du prototype HTML et checklist de validation (avec la porte « montrer d’abord à l’utilisateur »).
- references/pipeline.md — Squelette du code pour feed/UNCLIP, algorithme clamp, polices, import/découpage, réactions, viewportisation.
- references/figma-ui-and-automation.md — Matrice API/UI, paramétrage par lot, modèle de téléphone, automatisation Windows et règles de coordonnées.
- references/verification.md — MAE, audit/rejeu des réactions, triple capture Présentation, diagnostic d’échec.
scripts/rename_font.py,scripts/install_font.ps1— Sous-ensemble/renommage des polices et installation pour l’utilisateur courant (avec désinstallation).scripts/figma_win.ps1,scripts/uia.ps1— Aides Windows (clic/survol/touche/roulement/capture, énumération UIA/clic/focus).scripts/crop.mjs— Recadrage PNG multi-plateforme (zoom entier, pour la vérification des captures).
Mode de travail
- Avant de modifier le code, expliquez « quelle ligne, pourquoi », une cause racine à la fois ; les artefacts intermédiaires portent un numéro de version et un nouveau nom de fichier.
- Chaque « ça semble correct » doit être étayé par une donnée chiffrée ou une capture d’écran ; chaque « ça devrait marcher » doit être testé en mode Présentation.
- Concentrez-vous uniquement sur les trois piliers « restitution / éditabilité / cliquabilité » ; ne refactorez pas le pipeline ni ne mettez à jour les dépendances en passant.