Communitygithub.com

html2figma

Convierte prototipos HTML de teléfono en prototipos Figma editables, clicables y desplazables, o permite crear primero el prototipo HTML para que sea aprobado antes de importarlo.

¿Qué es html2figma?

Esta habilidad (skill) convierte prototipos HTML de teléfono en prototipos Figma totalmente editables, interactivos y con desplazamiento. Es ideal para desarrolladores y diseñadores que ya tienen un prototipo HTML y quieren llevarlo a Figma con capas editables, reacciones de clic para navegar, capas persistentes (como barras inferiores, barras superiores, FABs, toasts) y desplazamiento real con capas fijas. El proceso sigue un pipeline de 8 fases: desde la creación del prototipo HTML (fase 0), inspección y extracción de datos (fase 1), construcción del feed (fase 2), coincidencia exacta de fuentes (fase 3), importación y descomposición en pantallas (fase 4), creación de reacciones interactivas (fase 5), viewportización y posicionamiento de capas persistentes (fase 6), configuración de desplazamiento y fijación (fase 7), y verificación triple (fase 8) que cubre píxeles, interacciones y presentación. Funciona con el plug-in de desarrollo 'open-htmltofigma' en Figma Desktop y sigue las especificaciones de Agent Skills (SKILL.md + references/ + scripts/). No es adecuado para prototipos nativos de Figma sin fuente HTML, importaciones de diseño estático de escritorio o preguntas aisladas sobre Figma.

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

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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)

  1. ¿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.
  2. ¿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-index superior 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.
  3. ¿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 solo NONE | VERTICAL | HORIZONTAL | BOTH; pasar VERTICAL_SCROLLING etc. dará error de validación, no lo malinterpretes como "no soportado"). Las capas fijas secundarias usan numberOfFixedChildren = N; las capas fijas deben ser las primeras N capas secundarias del marco (primero insertChild(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=N en las capas de texto (debes llamar a loadFontAsync antes de escribir). Solo se hornea el clamp en 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-face en 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/bottom del 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 solo NONE | 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

  1. Píxeles: exportación 2x vs referencia, recortar desbordamiento de sombra según @dx,dy + búsqueda ±2px, MAE 3–10 es normal;
  2. Interacción: auditoría de reacciones + verificación de reproducción;
  3. 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ñalCómo verlo
Posicionamiento CSSposition:fixed, o absolute + bottom/top pegado al borde de la ventana gráfica
Nivelz-index superior a la capa de contenido; superpuesto sobre el contenido desplazable
Repetición entre pantallasEl mismo selector/mismas coordenadas de ventana gráfica aparecen en ≥2 pantallas (barra de navegación inferior, barra superior son las más comunes)
VisualBarra flotante con bordes redondeados, vidrio esmerilado, capa de sombra, FAB, toast
ComportamientoEn 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 = 780 y 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ómenoCausa raíz / Contramedida
1La capa persistente está al final de la imagen largaLa importación UNCLIP expande la ventana gráfica de altura fija, bottom:0 cae al final del contenido → Fase 6 viewportización
2Configurar desplazamiento da error de validaciónEl valor de enumeración está mal escrito (p. ej., VERTICAL_SCROLLING) → usar VERTICAL; FRAME normal se puede escribir, no lo malinterpretes como "no soportado"
3Las capas fijas secundarias no funcionanLas capas fijas deben ser las primeras N capas secundarias del marco: primero insertChild(0, layer) y luego establecer numberOfFixedChildren = N
4Las reacciones fallan después de clonar a una nueva páginasetReactionsAsync entre páginas es rechazado → reestructurar in-situ, archivar por separado
5El texto presiona la etiqueta inferiorPrimero probar textTruncation='ENDING' + maxLines nativo; si sigue sin coincidir, hornear el truncamiento carácter por carácter en el feed
6Los saltos de línea en Figma difieren del navegadorLa fuente se ha reemplazado → subconjunto+renombrar+instalar
7La imagen exportada es más grande que el panel y la comparación fallaLa exportación incluye el desbordamiento de sombra → recortar según @dx,dy
8El clic sintético/rueda de desplazamiento no funcionaEl webview filtra; los menús se pueden hacer clic. El panel usa UIA / teclado; el reproductor usa PostMessage para la rueda
9El segundo clic de script en la capa superpuesta fallaCada ejecución re-enfoca la ventana → abrir+seleccionar en la misma ejecución
10Desviación de coordenadas de capturaConocimiento de DPI; las coordenadas de captura son relativas a la ventana; UIA son píxeles físicos absolutos
11El plugin se ejecuta en otro archivoFigma restaura pestañas antiguas/abre Sin título por error → primero confirmar la pestaña activa
12La imagen recortada no se abreEscalado no entero produce tamaño decimal → redondear la salida
13Aparece texto extraño en el lienzoPegado accidental genera nodos TEXT → limpiar según el contenido con expresión regular
14No se puede leer el resultadoUsar 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/xdotool etc. 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.

Skills relacionados