Communitygithub.com

html2figma

Convertit des prototypes HTML pour mobile en prototypes Figma éditables, cliquables et défilables. Permet aussi de créer d’abord le prototype HTML pour validation avant import.

Qu'est-ce que html2figma ?

html2figma est un skill d’agent spécialisé dans la conversion de prototypes HTML pour téléphone en prototypes Figma entièrement éditables, interactifs et fidèles au pixel près. Il prend en charge les écrans multiples, les calques vectoriels, les réactions de navigation au clic, les modèles de téléphone, la détection des couches persistantes (barre d’onglets, barre supérieure, FAB, toasts, pas seulement les docks), le défilement réel avec éléments fixes, et une vérification de conformité écran par écran. Le skill fonctionne avec Claude Code, Cursor, Codex et tout agent compatible Agent Skills. Il repose sur un pipeline en neuf phases : de la création du prototype HTML (phase 0) jusqu’à une triple validation (pixels, interactions, présentation). Il utilise l’API Figma (overflowDirection, numberOfFixedChildren) et le plugin open‑htmltofigma pour l’import, avec des scripts d’automatisation pour Windows. Il détecte les couches persistantes via des signaux CSS (position:fixed, z-index, répétition inter-écrans) et les traite correctement dans Figma. Le skill évite les erreurs courantes comme les débordements de texte, les réactions perdues ou les éléments fixes mal positionnés, et exige une validation utilisateur avant tout import pour minimiser les reprises.

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

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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)

  1. 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.
  2. 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, ou absolute ancré en haut/bas du viewport, z-index supé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.
  3. 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 ; passer VERTICAL_SCROLLING provoque 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’abord insertChild(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:hidden pour 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=N sur les calques de texte (après loadFontAsync). Ne cuisez le clamp dans 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-face en 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/bottom du 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 : seulement NONE | 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

  1. Pixels : export 2× vs référence, recadrez les ombres débordantes avec @dx,dy + recherche ±2 px, MAE 3–10 normal ;
  2. Interactions : audit des réactions + rejeu de validation ;
  3. 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) :

SignalComment l’observer
Position CSSposition:fixed, ou absolute + bottom/top collé au bord du viewport
Empilementz-index supérieur au contenu ; superposé au contenu défilant
Répétition inter-écransMême sélecteur / mêmes coordonnées viewport sur ≥2 écrans (barre de navigation en bas, barre supérieure les plus courants)
VisuelBarre flottante arrondie, verre dépoli, ombre portée, FAB, toast
ComportementLe 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 = 780 puis 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èneCause racine / Correctif
1Calque persistant tout en bas du grand cadreL’import UNCLIP déplie le viewport fixe, bottom:0 tombe à la fin du contenu → viewportisation Phase 6
2Erreur de validation au réglage du défilementMauvaise valeur d’énumération (ex. VERTICAL_SCROLLING) → utilisez VERTICAL ; les FRAME classiques l’acceptent, ne dites pas « non supporté »
3Calque fixe positionné mais pas effectifLes calques fixes doivent être les N premiers enfants du cadre : d’abord insertChild(0, layer), puis numberOfFixedChildren = N
4Réactions perdues après clonage sur une nouvelle pagesetReactionsAsync rejeté entre pages → reconstruisez sur place, archivez à part
5Texte qui écrase les étiquettes en dessousEssayez d’abord le natif textTruncation='ENDING' + maxLines ; si pas cohérent, cuisez la troncature caractère par caractère dans le feed
6Sauts de ligne Figma différents du navigateurPolice remplacée → sous-ensemblez + renommez + installez
7Export plus grand que la planche, comparaison fausseL’export contient les ombres débordantes → recadrez selon @dx,dy
8Clic/roulement synthétique inactifWebview filtré ; le menu est cliquable. Panneaux : UIA/clavier ; lecteur : défilement via PostMessage
9Deuxième clic de script sur un modal sans effetChaque exécution ramène la fenêtre au premier plan → ouvrez et sélectionnez dans la même exécution
10Coordonnées de capture décaléesSensible aux DPI ; coordonnées de capture = coordonnées relatives à la fenêtre ; UIA = pixels physiques absolus
11Le plugin s’exécute dans un autre fichierFigma restaure un ancien onglet ou ouvre “Sans titre” → vérifiez d’abord l’onglet actif
12Image recadrée illisibleZoom non entier produit des dimensions décimales → arrondissez la sortie
13Texte étrange sur le canvasCollé accidentellement, génère un nœud TEXT → nettoyez par expression régulière
14Résultat illisibleUtilisez 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.

Skills associés