html2figma — HTML prototipos ⇄ Figma prototipos editables y clicables
Cuándo usarlo
- Tienes un prototipo HTML de teléfono y quieres pasarlo 1:1 a Figma: capas editables + clic para navegar entre pantallas + desplazamiento + capas persistentes fijas.
- Aún no tienes un prototipo HTML: primero crea uno siguiendo la especificación de prototipo HTML, el usuario lo confirma y luego importas a Figma.
- Solucionar problemas en prototipos Figma: texto superpuesto/saltos de línea incorrectos, reacciones perdidas, capas persistentes que caen al final de un marco largo, desplazamiento que no funciona.
No aplica: Solo archivos Figma sin fuente HTML para cableado nativo; importación de diseños estáticos de escritorio; preguntas aisladas sobre cómo hacer algo en Figma.
Tres preguntas iniciales (no te las saltes)
- ¿Tienes un prototipo HTML?
- Sí → Comienza desde la Fase 1.
- No → Ve a la Fase 0: crea el prototipo HTML según la especificación → renderiza todas las capturas de pantalla → detente y pide confirmación al usuario → solo si aprueba, continúa a Figma. El HTML es la base de toda la geometría e interacción posterior; importar sin confirmación tiene un coste de retrabajo muy alto.
- ¿Cuáles son las "capas persistentes"?
No asumas que es solo un dock. Revisa el DOM/las capturas según la sección §Determinación de capas persistentes:
position:fixed, o ancladas al borde superior/inferior de la ventana gráfica con posicionamiento absoluto,z-indexsuperior al contenido, que aparecen repetidas en las mismas coordenadas de la ventana gráfica en ≥2 pantallas. Pueden ser dock inferior, barra de navegación superior, botón FAB flotante, notificación flotante, botón de volver arriba, manija de modal, etc. Si no estás seguro, mira el comportamiento en HTML; si el HTML tampoco lo especifica, pregunta al usuario, no adivines. - ¿Cuál es el alcance de la entrega? Deben cumplirse tres requisitos: ① Fidelidad de píxeles (sin texto superpuesto/saltos de línea/desalineaciones) ② Editable (Frame/Text/Vector/relleno de imagen) ③ Clicable (el número de zonas activas coincide exactamente, no "aproximadamente").
Modelo mental (4 reglas que ahorran horas)
- El HTML es la única referencia. Cada modificación en Figma debe poder encontrar su equivalente semántico en el HTML: ventana gráfica de altura fija,
overflow:hidden,position:fixed/absolute,closest('[data-goto]'). - Importar ≠ restaurar. El plugin genera una "imagen larga de altura completa + capas estáticas"; la ventana gráfica, el desplazamiento, las capas fijas y las reacciones son post-procesamiento.
- Si se puede cuantificar, no mires la imagen para adivinar: superposición de texto se mide con cajas de tinta, fidelidad con MAE, reacciones con auditoría de cantidad, desplazamiento/fijación con secuencias de capturas de Present.
- La API del plugin de Figma puede configurar desplazamiento y fijación (probado):
frame.overflowDirection = 'VERTICAL'(los valores válidos son soloNONE | VERTICAL | HORIZONTAL | BOTH; pasarVERTICAL_SCROLLINGetc. dará error de validación, no lo malinterpretes como "no soportado"). Las capas fijas secundarias usannumberOfFixedChildren = N; las capas fijas deben ser las primeras N capas secundarias del marco (primeroinsertChild(0, layer)). El panel Prototype es un respaldo, así como para configuraciones puramente UI como los modelos de dispositivo.
Pipeline (cada fase se puede verificar de forma independiente)
Fase 0 — Crear prototipo HTML (solo si no hay HTML existente)
Sigue references/html-prototype-spec.md: ventana gráfica 393×852, estructura .phone/.screen/.scroll, zonas activas data-goto, tokens de diseño, iconos SVG en línea, fuentes auto-contenidas, disciplina clamp.
Criterio de finalización: todas las pantallas se pueden renderizar, sin desbordamiento/texto superpuesto, zonas activas completas; salida de capturas de pantalla completas + instrucciones de interacción, deja que el usuario vea las imágenes y confirme, solo después de la confirmación se continúa.
Fase 1 — Inspección del prototipo
Cuantificar: número de pantallas y tamaños, altura de contenido por pantalla, nodos -webkit-line-clamp, familias/ grosores de fuente, número de zonas activas únicas data-goto después de deduplicar, lista de capas persistentes (ver §Determinación de capas persistentes).
Productos: boards.json, hotspots.json, clamp.json, persistent.json.
Fase 2 — Construcción del feed (lienzo → flujo de pantalla única importable)
Inyectar CSS/JS y serializar feed/index.html:
- Ocultar el caparazón del lienzo (barra superior/barra lateral/etiquetas de pantalla/cuadrícula);
- UNCLIP: eliminar altura fija y
overflow:hidden, dejar que el contenido se expanda de forma natural (más adelante se toman las capas con altura completa y luego se recortan a la ventana gráfica); - Estrategia de truncamiento (probar nativo primero, considerar horneado después): después de la importación, se puede establecer
textTruncation='ENDING'+maxLines=Nen las capas de texto (debes llamar aloadFontAsyncantes de escribir). Solo se hornea elclampen el feed cuando se necesita una concordancia carácter por carácter con el navegador (algoritmo en pipeline). No hacer ningún truncamiento provocará texto fuera del marco; - Nombres de paneles y capas persistentes con
data-h2f-name; fuentes@font-faceen línea/auto-contenidas.
Fase 3 — Coincidencia exacta de fuentes (clave para restaurar saltos de línea)
Subconjunto de la fuente real del prototipo + renombrar con un prefijo unificado + instalar (HKCU/fuentes del sistema). Figma debe encontrar la fuente con el mismo nombre, de lo contrario el reemplazo creará "errores de salto de línea" falsos. Comandos y script de renombrado en pipeline.
Fase 4 — Importar y dividir en paneles
Instalación previa: git clone https://github.com/kevicebryan/open-htmltofigma.git, Figma Desktop → Plugins → Development → Import plugin from manifest… (selecciona manifest.json dentro del repositorio); commit/tag fijo, si hay conflicto de id de manifiesto, cámbialo. El plugin renderiza el feed en un iframe real → crea directamente Frame/Text/Vector; el script de inyección local rellena automáticamente y convierte (antes de importar, establece la ventana gráfica del plugin a 393×852, de lo contrario vh/media queries se resolverán con el valor predeterminado de 1440×1024). Después de importar, eleva cada Frame de pantalla a la capa superior, alineación horizontal, nombra NN id · título, elimina el contenedor raíz. El importador no crea ninguna reacción, se deben reescribir según la Fase 5; la versión del plugin debe ser fija (ver pipeline).
Fase 5 — Interacciones (reacciones)
Recorrer las zonas activas en orden ascendente de área; bbox ±2 acierta el nodo más pequeño que NO sea TEXT, el punto central como respaldo; si el nodo no soporta reacciones, subir por los ancestros; tener una reacción existente es una razón para seguir subiendo (la zona activa padre cuelga de su propio nodo), no una condición de parada; omitir auto-salto. Leer node.reactions, escribir await setReactionsAsync().
Después de escribir, reproducir con la misma lógica de acierto+subida, exp == ok && wrong == 0; la auditoría de cantidad requiere dangling == 0.
Fase 6 — Viewportización + Posicionamiento de capas persistentes
Primero, usa persistent.json para listar el anclaje de cada capa persistente (bottom/top/fab/none) y la justificación, luego actúa; marca las inciertas y pregunta al usuario, no fijes todo por defecto.
In-situ, cambia cada panel al tamaño de la ventana gráfica del prototipo (p. ej., 393×852; lee de .phone realmente, no lo hardcodees, Android común 360×800/412×915), resize + clipsContent, eleva las capas persistentes de la capa de contenido a la raíz del panel, posiciona según el anclaje de la ventana gráfica:
- Barra inferior:
y = altura ventana gráfica - altura; - Barra superior:
y = 0; - FAB inferior derecha: convertir según
right/bottomdel HTML; - Clases ocultables/auto-cerrables (barra superior que se desvanece al hacer scroll): no fijar, mantener la semántica de flujo de contenido.
La fijación y el desplazamiento se pueden hacer directamente a través de la API (probado en este proyecto, Figma Desktop):
board.insertChild(0, layer); // Las capas fijas deben ir al principio de las capas secundarias
board.numberOfFixedChildren = 1; // Las primeras N capas secundarias = capas fijas
board.overflowDirection = 'VERTICAL';
La opción Position = Fixed en la interfaz de usuario es semánticamente equivalente a Overflow = Vertical y puede servir como respaldo. Para conservar las reacciones, no clones el panel a otra página: setReactionsAsync entre páginas falla en todas las pruebas. Primero clona el panel de altura completa a la página ARCHIVE para archivar, luego reestructura in-situ.
Fase 7 — Desplazamiento + fijación + modelo de dispositivo
- Desplazamiento:
board.overflowDirection = 'VERTICAL'(los valores de enumeración son soloNONE | VERTICAL | HORIZONTAL | BOTH); - Fijación:
board.numberOfFixedChildren = N(las capas fijas son las primeras N capas secundarias, ver Fase 6); - Respaldo de IU: seleccionar múltiples paneles → Prototype →
Overflow = Vertical; seleccionar múltiples capas persistentes →Position = Fixed (stay in place); - Modelo de dispositivo (solo IU): deseleccionar → configuración de Prototype a nivel de archivo → Device seleccionar un dispositivo del mismo tamaño que el prototipo (p. ej., iPhone 15 Pro = 393×852); establecer Flow starting point en la pantalla de inicio. Razones y detalles de coordenadas en figma-ui-and-automation.
Fase 8 — Verificación triple
- Píxeles: exportación 2x vs referencia, recortar desbordamiento de sombra según
@dx,dy+ búsqueda ±2px, MAE 3–10 es normal; - Interacción: auditoría de reacciones + verificación de reproducción;
- Presentación: captura triple de Present (inicial / después de desplazar / después de navegar), confirmar que las capas persistentes siempre están dentro de la ventana gráfica y no se mueven con el contenido. Detalles y umbrales en verification.
Determinación de capas persistentes (importante, no solo reconocer dock)
Señales de determinación (si cumple dos o más, es candidato):
| Señal | Cómo verlo |
|---|---|
| Posicionamiento CSS | position:fixed, o absolute + bottom/top pegado al borde de la ventana gráfica |
| Nivel | z-index superior a la capa de contenido; superpuesto sobre el contenido desplazable |
| Repetición entre pantallas | El mismo selector/mismas coordenadas de ventana gráfica aparecen en ≥2 pantallas (barra de navegación inferior, barra superior son las más comunes) |
| Visual | Barra flotante con bordes redondeados, vidrio esmerilado, capa de sombra, FAB, toast |
| Comportamiento | En HTML/JS, escucha el desplazamiento para mostrar/ocultar o cambiar de color |
Decisión de tratamiento:
- Siempre superpuesto, persistente entre pantallas (barra de pestañas inferior, barra superior) → Fijar dentro de la ventana gráfica en Figma (
Fixed). - Solo superpuesto, no fijo (FAB) → También elevar a la capa de ventana gráfica y fijar.
- Se desplaza con el contenido (tarjetas normales, botones en línea) → Dejar en la capa de contenido, no fijar.
- Se oculta/aparece al desplazarse (encabezado auto-ocultable) → Figma no puede reproducir la lógica completa con interacciones nativas: prioriza mantener la semántica estática de "sigue el desplazamiento/oculto" o divídelo en pantallas de estado; no lo fijes incorrectamente. Si no estás seguro, pregunta al usuario qué efecto de presentación quiere.
- Capas de superposición / manija de modal → Generalmente pertenecen a la pantalla del modal en sí, trátalas según el contenido de esa pantalla, no las fijes entre pantallas.
Ejemplo de este proyecto: dock inferior con 6 zonas activas en 14 pantallas, elevado a
y = 852-72 = 780y luego fijado; la misma fórmula se aplica a la barra superior/FAB: primero determinar la semántica, luego aplicar las coordenadas.
Errores frecuentes (Top 14)
| # | Fenómeno | Causa raíz / Contramedida |
|---|---|---|
| 1 | La capa persistente está al final de la imagen larga | La importación UNCLIP expande la ventana gráfica de altura fija, bottom:0 cae al final del contenido → Fase 6 viewportización |
| 2 | Configurar desplazamiento da error de validación | El valor de enumeración está mal escrito (p. ej., VERTICAL_SCROLLING) → usar VERTICAL; FRAME normal se puede escribir, no lo malinterpretes como "no soportado" |
| 3 | Las capas fijas secundarias no funcionan | Las capas fijas deben ser las primeras N capas secundarias del marco: primero insertChild(0, layer) y luego establecer numberOfFixedChildren = N |
| 4 | Las reacciones fallan después de clonar a una nueva página | setReactionsAsync entre páginas es rechazado → reestructurar in-situ, archivar por separado |
| 5 | El texto presiona la etiqueta inferior | Primero probar textTruncation='ENDING' + maxLines nativo; si sigue sin coincidir, hornear el truncamiento carácter por carácter en el feed |
| 6 | Los saltos de línea en Figma difieren del navegador | La fuente se ha reemplazado → subconjunto+renombrar+instalar |
| 7 | La imagen exportada es más grande que el panel y la comparación falla | La exportación incluye el desbordamiento de sombra → recortar según @dx,dy |
| 8 | El clic sintético/rueda de desplazamiento no funciona | El webview filtra; los menús se pueden hacer clic. El panel usa UIA / teclado; el reproductor usa PostMessage para la rueda |
| 9 | El segundo clic de script en la capa superpuesta falla | Cada ejecución re-enfoca la ventana → abrir+seleccionar en la misma ejecución |
| 10 | Desviación de coordenadas de captura | Conocimiento de DPI; las coordenadas de captura son relativas a la ventana; UIA son píxeles físicos absolutos |
| 11 | El plugin se ejecuta en otro archivo | Figma restaura pestañas antiguas/abre Sin título por error → primero confirmar la pestaña activa |
| 12 | La imagen recortada no se abre | Escalado no entero produce tamaño decimal → redondear la salida |
| 13 | Aparece texto extraño en el lienzo | Pegado accidental genera nodos TEXT → limpiar según el contenido con expresión regular |
| 14 | No se puede leer el resultado | Usar page.name o un recolector HTTP local para leer el estado de vuelta |
Plataforma y compatibilidad
- Esta habilidad sigue la especificación Agent Skills (SKILL.md + references/ + scripts/), puede ser cargada por ZCode, Claude Code y cualquier agente que implemente dicha especificación.
- La descripción del flujo es lo más general posible, pero el paso de importación depende del plugin de desarrollo open-htmltofigma y Figma Desktop; los scripts de automatización están orientados a Windows; macOS/Linux usarían AppleScript/
screencapture/xdotooletc. reescritos, o siguiendo los pasos manuales según la documentación. - La versión web de Figma no puede importar plugins de desarrollo local; los pasos relacionados con el plugin necesitan la versión de escritorio (la versión web puede abrir plugins publicados).
Referencias y scripts
- references/html-prototype-spec.md — Especificación de creación y lista de verificación de aceptación cuando no hay prototipo HTML (incluye la puerta de "mostrar primero al usuario").
- references/pipeline.md — Esqueleto de código para feed/UNCLIP, algoritmo clamp, fuentes, importación/división, reacciones, viewportización.
- references/figma-ui-and-automation.md — Matriz de capacidades API/IU, configuración por lotes, modelo de dispositivo, automatización de Windows y reglas de coordenadas.
- references/verification.md — MAE, auditoría/reproducción de reacciones, triple captura de Present, diagnóstico de fallos.
scripts/rename_font.py,scripts/install_font.ps1— Subconjunto/renombrado de fuentes e instalación para el usuario actual (incluye desinstalación).scripts/figma_win.ps1,scripts/uia.ps1— Asistentes de Windows (clic/hover/tecla/rueda/captura, enumeración UIA/clic/enfoque).scripts/crop.mjs— Recorte de PNG multiplataforma (escalado entero, usado para revisión de capturas).
Forma de trabajo
- Antes de modificar código, explica "qué línea se cambia y por qué", una causa raíz a la vez; los productos intermedios llevan número de versión y nuevo nombre de archivo.
- Cada "parece correcto" debe tener evidencia numérica o de captura; cada "debería funcionar" debe probarse en Present.
- Concéntrate solo en las tres cosas: «restauración / editable / clicable»; no reestructures el pipeline ni actualices dependencias de paso.