heygen-com/hyperframes

Instalación del plugin: Antes de los comandos de configuración o actualización, sigue las reglas de ejecución del plugin cuando esta skill esté dentro de un plugin de HyperFrames. Las instalaciones independientes mantienen las instrucciones de actualización a continuación.

Primero, mantén esta skill actualizada — confirma con el usuario antes de ejecutar: npx hyperframes skills update figma. Una operación rápida sin cambios cuando todo está actualizado; de lo contrario, refresca esta skill junto con las skills del dominio principal de las que depende antes de confiar en ellas.

Figma → HyperFrames

Lleva el trabajo de Figma del usuario a una composición. Dividido por capacidad (especificación de diseño §2):

Fase	Qué	Transporte	Superficie
1	Assets estáticos	REST	hyperframes figma asset
2	Tokens/estilos de marca	REST	hyperframes figma tokens
3	Componentes → HTML	REST	hyperframes figma component
4	Movimiento → GSAP	conector cuando esté disponible	usa su contexto de movimiento
5	Shaders	conector / exportación manual	úsalo o una exportación nativa

Se usa REST siempre que sea posible (utilizable a gran escala, sin cabeza gráfica). Un conector compatible de Figma es opcional para datos de movimiento y shaders; sin uno, solicita una exportación nativa. Cada ruta congela los assets localmente para que los renders sean deterministas. Las reconstrucciones de storyboard componen exportaciones de assets de Fase 1 (REST) con ensamblaje de línea de tiempo impulsado por el agente — no se necesita conector. Los assets congelados existentes, registros de manifiesto y enlaces no se ven afectados por cambios de ruta — la división solo cambia qué credencial usa la siguiente importación.

Autenticación — dos credenciales, con alcance

Verificación previa — antes de la primera llamada CLI, comprueba que existe un token: variable de entorno del shell ([ -n "$FIGMA_TOKEN" ]) o el .env del proyecto (la CLI lo carga automáticamente — una entrada en .env cuenta como configurado). Si no hay ninguno, NO ejecutes el comando para obtener el error — guía al usuario a través de la configuración única primero, luego detente y espera:

1. figma.com/settings → Seguridad → Tokens de acceso personal → Generar nuevo token.
2. Alcances — solo lectura es todo lo que esta integración necesita (nunca escribe en Figma): Contenido del archivo: Solo lectura + Metadatos del archivo: Solo lectura. Añade Contenido de la biblioteca: Solo lectura si ejecutarás tokens en un plan que no sea Enterprise — la alternativa de estilos publicados accede a /v1/files/:key/styles, que da 403 sin ese alcance (un alcance que omitía el texto de configuración anterior). Opcionalmente Variables: Solo lectura para variables de marca — solo Enterprise; sin él tokens se degrada automáticamente a estilos publicados (esperado, no es un error — dilo). Un 403 ahora nombra el alcance exacto que falta; los 429 se reintentan automáticamente (límite por minuto, respeta Retry-After).
3. Haz que el usuario configure FIGMA_TOKEN en su perfil de shell o .env del proyecto; nunca le pidas que pegue el token en la conversación.

Mientras preparas, también establece expectativas en una sola frase: cada importación aterriza como un archivo local congelado con procedencia registrada — los renders nunca llaman a Figma, volver a ejecutar un comando reimporta solo lo que cambió en Figma, y un solo token funciona para assets, tokens de marca y componentes en todos los archivos que la cuenta de Figma del usuario pueda ver.

• Fases 4–5 (movimiento/shaders): un conector de Figma compatible, con autorización separada del token. Si no está disponible o no está autenticado, pide al usuario que lo conecte o proporcione una exportación nativa, luego detente.
• Di exactamente qué credencial necesita una fase que falla — nunca presentes la división como rota.
• BAD_TOKEN (401) en medio del flujo → el token ha expirado o sido revocado; regenera. FORBIDDEN (403) → el mensaje nombra el alcance exacto que falta (ej. library_content:read para la alternativa de estilos) — agrégalo, o el archivo no es visible para la cuenta. REQUIRES_ENTERPRISE (403 en variables) → no es un fallo: la alternativa de estilos ya se ejecutó. RATE_LIMITED (429) → el cliente ya reintentó con retroceso (esto se aplica a TODA lectura — assets, tokens, estilos, árboles de nodos, versiones — el reintento vive en la ruta de solicitud compartida; Retry-After se respeta, con un límite de 60s); si aún aparece, espera un minuto o importa menos nodos por llamada.

Conciencia de límite de tasa (especificación §2.1): las cuotas del conector varían según el plan de Figma — agrupa solicitudes de fotogramas padre, omite capturas de pantalla de verificación a menos que se soliciten, y almacena en caché las respuestas sin procesar para que la re-derivación nunca gaste una segunda llamada. REST es por minuto (10+/min, cubos por punto final) — funciona bien a gran escala, retrocede en 429.

Enrutamiento

Analiza el enlace de Figma del usuario con parseFigmaRef (URL, fileKey:nodeId, fileKey simple). Luego según la intención:

• "usa esta capa / logo / imagen" → Asset (CLI)
• "obtén mi marca / colores / tokens" → Tokens (CLI)
• "construye una escena desde este fotograma" → Componente (CLI)
• "importa esta animación / movimiento" → Movimiento (conector cuando esté disponible, abajo)
• una sección de storyboard / tira de fotogramas de escena → Storyboard (abajo)
• relleno/efecto de shader → Shaders (abajo)

Narra cada paso para el usuario — antes de cada comando, di lo que estás a punto de obtener de Figma; después, di dónde aterrizó el artefacto (la ruta congelada / archivo sidecar / directorio de componentes), qué cambió en la composición y la siguiente acción inmediata (vista previa, añadir variables impresas, reimportar para enlazar enlaces). El usuario nunca debería tener que preguntar "¿funcionó?" o "¿y ahora qué?".

Assets (Fase 1 — CLI)

hyperframes figma asset '<url-o-fileKey:nodeId>' [más referencias…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]

Renderiza a través de REST, sanitiza SVG, congela bajo .media/images/, añade el manifiesto con procedencia, regenera .media/index.md (el inventario de uso de medios compartido), imprime un fragmento <img>. Idempotente por fileKey:nodeId:format:scale:version. Prefiere SVG para vectores/logos (escalable, animable), PNG --scale 2 para fidelidad rasterizada. Siempre pasa --description "<qué es>" (se convierte en la fila del índice + <img alt>); añade --entity "<nombre>" para marcas de marca con nombre para que la resolución de media-use los encuentre después (las coincidencias de entidad abarcan imagen/icono).

Procesa varios nodos en UNA sola solicitud — pasa varias referencias (separadas por espacios o comas) del MISMO archivo: hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'. Todas se renderizan en una sola llamada /v1/images, que es la propia respuesta de Figma al límite de tasa por minuto — prefierela sobre N comandos separados al obtener todos los assets de un fotograma completo. --description/--entity se aplican a cada nodo en el lote, así que agrupa nodos que compartan un propósito. Los 429 también se reintentan automáticamente con retroceso.

Tokens (Fase 2 — CLI)

hyperframes figma tokens <fileKey>

Importa variables como entradas de variable de marca de composición + archivo sidecar figma-tokens.json + registros de índice de enlace (.media/figma-bindings.jsonl). Las variables están restringidas a Enterprise aguas arriba: en otros planes, el comando se degrada a metadatos de estilo publicado (los valores se resuelven en el momento de la importación del componente). Añade las entradas impresas al data-composition-variables de la composición.

Importa tokens antes que componentes cuando se quieran ambos — eso permite que los colores de los componentes se vinculen a variables de marca en lugar de duplicar valores.

Ruta de variables no Enterprise (probada en campo): Las variables REST están restringidas a Enterprise, pero un conector compatible puede proporcionar definiciones de variables. Cuando tokens reporte REQUIRES_ENTERPRISE y el conector esté disponible, recupera las variables de la escena padre una vez, almacena en caché la respuesta sin procesar en .media/figma-cache/, y úsala para construir el índice de enlace. El árbol de nodos REST proporciona VariableIDs por propiedad a través de boundVariables; únelos por nodo y propiedad, luego escribe filas .media/figma-bindings.jsonl ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<nombre>", version}) más las entradas de variable de composición. Todo lo que sigue (resolución var() del componente, actualización, variables CSS en tiempo de ejecución) es la maquinaria ya integrada. Etiquétalo para el usuario: "tokens a través del conector de Figma — los planes Enterprise obtienen esto directamente de hyperframes figma tokens."

El tiempo de ejecución define cada variable de composición declarada como una propiedad personalizada CSS (raíz del documento + hosts de subcomponentes), así que el var(--slug, literal) importado llena el recoloreo cuando el valor predeterminado de la variable cambia — actualizar un valor en data-composition-variables re-marca cada componente importado sin reimportar nada. hyperframes render --variables '<json>' los sobrescribe en el momento del renderizado.

Componentes (Fase 3 — CLI)

hyperframes figma component '<url-o-fileKey:nodeId>'

Árbol de nodos → HTML editable en la geometría exacta de Figma, empaquetado como un elemento de registro bajo compositions/components/<nombre>/. Los vectores/operaciones booleanas se auto-rasterizan mediante la exportación de Fase 1. Paso de enlace (especificación §7.1, solo ID exacta — nunca coincidencia de valores):

• Autocomprobación de fidelidad estática (obligatoria para contenido principal): después de importar, renderiza el fragmento y compáralo con los píxeles propios de Figma — figma asset <mismo nodo> --format png es la verdad fundamental. El texto es el eje de desviación conocido: un cuadro de texto de Figma más corto que su altura de línea tiene límites recortados verticalmente (el mapeador emite text-box-trim para estos; la desviación medida sin él era de ~6px en una fuente de 70px). Si la comparación muestra una desviación que el mapeador no cubre, repórtala — no ajustes el fragmento manualmente en silencio.
• Relleno enlazado a un token importado → var(--slug, #literal) — la actualización de marca se propaga.
• Enlazado a un token desconocido → literal + indicador data-figma-unresolved. El comando te lo dice; ofrece al usuario: ejecuta tokens en el archivo de origen (o biblioteca), luego reimporta el componente para enlazarlos. Pregunta una vez por biblioteca desconocida qué archivo es — nunca adivines, nunca coincidas por hex.

Movimiento (Fase 4 — asistido por conector)

Baliza de uso: Las fases asistidas por conector no tienen punto de contacto CLI, así que activa la baliza de la skill al inicio y al final (anónimo, con consentimiento, nunca falla): npx hyperframes events --skill=figma-motion cuando comiences, npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error cuando termines. Lo mismo para shaders (figma-shaders) y storyboards (figma-storyboard).

No existe un equivalente REST. Cuando haya un conector compatible disponible, úsalo y entrega su salida a los ayudantes puros en @hyperframes/core/figma; de lo contrario, solicita una exportación nativa:

1. Recupera el contexto de movimiento para el fotograma padre en una solicitud recursiva, no una por elemento. Guarda el JSON sin procesar junto al proyecto (.media/figma-cache/) para que la retraducción sea gratuita.
2. Normaliza en MotionDocs con motionContextToDocs(rawResponse, { selectorFor, repeat }) de @hyperframes/core/figma — nunca transcribas números de fotogramas clave manualmente. El ayudante codifica mecánicamente las reglas de decodificación probadas en campo: analiza los fragmentos de motion.dev (la codificación confiable — los fragmentos CSS estiran las duraciones y pueden discrepar; se ignoran), elimina los fotogramas clave finales de bucle (segmentos de submilisegundos en tiempos ≈0.9999→1 son el reinicio instantáneo del bucle, no movimiento creado — el envoltorio se realiza mediante el reinicio de repeat), y preserva las curvas bezier textualmente. selectorFor debe devolver los IDs de la importación del componente de Fase 3 — no derives selectores de nombres de nodo. 2b. Valida contra la verdad fundamental antes de darlo por terminado — obligatorio: exporta el fotograma raíz del cohorte a través del conector disponible y ejecuta node skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop WxH+X+Y — compara deltas de energía de movimiento (la fidelidad de importación estática se cancela) y falla por debajo de 15dB de PSNR mínimo de movimiento (calibrado: fiel ≈ 20+, divergente ≈ 5). Mide --crop desde los bordes reales de la tarjeta del render, no adivines. FALLO significa verificar la traducción, no el umbral.
3. motionToGsap(doc) → emitTimelineScript(spec) → inyecta como un <script> después de las etiquetas CDN de GSAP + CustomEase. En pausa, finito, registrado en window.__timelines con una clave literal.
4. Pista intraducible (impulsada por shader, propiedad no soportada, máscaras complejas) → exporta a través del conector, congela el MP4, luego insértalo como <video class="clip">. Excepción: pistas impulsadas por shader — la ruta de exportación de Figma aplana los shaders al color base (ver Shaders abajo), así que una cocción allí pierde silenciosamente el shader; pide al usuario una exportación nativa de Figma en su lugar. Siempre di qué ruta usaste y por qué. Las aceleraciones nombradas fuera del conjunto mapeado vuelven a lineal — la tabla de mapeo vive en motionEase.ts; marca la alternativa para el usuario cuando se active.
5. Ejecuta npx hyperframes check antes de darlo por terminado.

Shaders (Fase 5 — mayormente manual)

La ruta de renderizado del conector de Figma no ejecuta shaders (se aplanan al color base), y la fuente del shader solo es accesible para estilos publicados en biblioteca (Asiento completo de pago). Ruta predeterminada: pide al usuario que exporte el fotograma del shader de forma nativa en Figma (PNG o MP4 de movimiento), luego impórtalo como un asset de Fase 1 / clip. No intentes la captura de píxeles del conector de un shader — producirá silenciosamente el resultado incorrecto.

Storyboards (una SECCIÓN de fotogramas de escena → animación)

La regla cardinal: los fotogramas de storyboard son FOTOGRAMAS CLAVE, no diapositivas. Dos fotogramas que contienen el mismo elemento describen el estado de ese elemento a través del tiempo — anima el ELEMENTO entre los estados; nunca reproduzcas los fotogramas como una secuencia de imágenes fijas. Un logo dibujado en cuatro fotogramas consecutivos con una y descendente es UN elemento que se eleva a través de cuatro fotogramas clave. Reproducir los fotogramas del storyboard uno tras otro es el modo de fallo; reconstruir las líneas de tiempo de los elementos que implican es el trabajo.

Los archivos de storyboard siguen una gramática que puedes analizar mecánicamente — no mires a ojo, decodifica:

1. Unidades de escena: dentro de la SECCIÓN, cada nodo del tamaño de un fotograma es una escena — tanto FRAMEs con nombre como RECTÁNGULOS sueltos de tamaño completo (los diseñadores pegan imágenes fijas directamente en la sección). Filtra por tamaño (≈ aspecto de composición, ej. >1400×900), no por tipo de nodo o nombre.
2. Orden = posición x (en orden de filas si la tira se envuelve). Ordena las escenas por absoluteBoundingBox.x.
3. Diferencia entre adyacentes: compara cada escena con su predecesora en el orden. Los elementos que aparecen en ambas son los mismos — registra sus propiedades cambiantes (posición, rotación, opacidad, relleno) como un solo fotograma clave animado. Los elementos que desaparecen son un corte (opacity: 0 en la salida entre las escenas). Los elementos que aparecen son una aparición (opacity: 0 en la entrada). Todo lo demás: composición, no movimiento. 3b. Paso de coincidencia de elementos: siempre coincide por ID (el ID de Figma del nodo viaja a través de la importación del componente de Fase 3) o, cuando el elemento es un asset estático en lugar de un componente, por contenido hash (el contenido renderizado es el mismo asset de medios, por lo que el hash de origen es la identidad). Nunca coincidas por nombre de capa ("Rectángulo 4") o coincidencia visual (píxeles) — los diseñadores renombran las capas, y la coincidencia visual es frágil. Una tabla de coincidencia es { [id|hash]: elementRef }, donde elementRef es el componente congelado o la ruta del asset.
4. Señales de índice de línea de tiempo: donde las escenas adyacentes difieren solo en una propiedad (ej. rotación), esa es una interpolación de un solo atributo — emite un fotograma clave de GSAP. Donde difieren ampliamente, es una clave compleja — emite todos los atributos cambiantes en ese fotograma. No interpolues a través de cortes de opacidad; los límites de corte son cambi donde display: none o opacity: 0 cambian a opacity: 1 sin estados intermedios.
5. El movimiento, no las transiciones: en el storyboard, todas las escenas son absolutas — cada una es un estado completo del sistema de fotogramas clave. Sin retardo, sin duración, sin curvas de aceleración. Interpola linealmente entre fotogramas clave a menos que la escena contenga directamente anotaciones de aceleración (que el conector de Figma puede exponer). duration = tiempo de escena (diferencia de tiempo de cuadro del storyboard, o 1 segundo por defecto). ease = "power1.out" (el valor predeterminado de GSAP) o la animación de entrada/salida que el conector haya adherido.
6. Bucle invertido para fotogramas clave concurrentes: cuando reensamblas la línea de tiempo (después de recopilar todos los cambios de elementos a través de las escenas), verifica si una sola escena cambia varios elementos. Esos fotogramas clave están en el mismo momento temporal pero en diferentes pistas de elementos — "invertir el bucle" significa: para cada escena, itera los elementos que cambian, no para cada elemento, itera las escenas. Pseudocódigo:

timeline = {}
for each scene in scenes:
    for each (element, properties) in scene. Changes:
        timeline[element].push({time: scene.time, properties})

No:

// INCORRECTO — mezcla los tiempos de los elementos
for each element in allElements:
    for each scene in scenes:
        ...

7. Renderiza el resultado antes de darlo por terminado: hyperframes render scene-<name> [--duration <n>] — verifica visualmente que los elementos se muevan suavemente en lugar de parpadear entre posiciones. Si el render parece incorrecto, ejecuta el paso de coincidencia de elementos manualmente para confirmar que los elementos se están refiriendo correctamente. Usa node skills/figma/scripts/visual-diff.mjs entre escenas consecutivas renderizadas como PNG para validar estadísticamente los cambios de movimiento esperados.

Los storyboards no requieren conector de Figma cuando se usan assets de Fase 1 — solo REST. Cuando el conector esté disponible, úsalo para recuperar propiedades de trama de movimiento (aceleraciones, duraciones) si el storyboard las anota. De lo contrario, valores predeterminados de línea de tiempo lineales.

Secuencia de comandos para storyboards

Cuando te encuentres con una sección de storyboard/varios fotogramas de escena:

# 1 — Congela todos los assets de escena primero (REST, no se necesita conector)
hyperframes figma asset '<fileKey:scene1>' '<fileKey:scene2>' … --format png --description "fotograma de storyboard"

# 2 — Importa cada escena como un componente
hyperframes figma component '<fileKey:scene1>'
hyperframes figma component '<fileKey:scene2>'
…

# 3 — (opcional) Análisis de movimiento para detección de fotogramas clave
# La skill analiza mecánicamente las diferencias de escena entre los archivos de componentes
# para construir la línea de tiempo

# 4 — Renderiza el resultado
hyperframes render storyboard-scene --duration 3

Siempre explica el proceso de reconstrucción del storyboard: "Este storyboard contiene N fotogramas de escena. Los he importado como N componentes y estoy reconstruyendo sus elementos en una sola línea de tiempo. El resultado será una animación suave de los elementos, no una presentación de diapositivas."

Después de la reconstrucción, imprime el resumen de la línea de tiempo: "Línea de tiempo: elemento A se mueve de Y:100 a Y:300 a través de 3 fotogramas clave, elemento B aparece en el fotograma 2 — B está animado, no solo cortado."

Verificación de fidelidad post-importación

Después de cualquier importación de combos/heroe/storyboard, verifica la corrección antes de presentar los resultados:

# Verifica que los activos renderizados coincidan con Figma
node skills/figma/scripts/visual-diff.mjs --reference <figma-asset> --render <rendered-scene>

Requisitos mínimo de aprobación: PSNR > 25dB entre el asset congelado de Figma y el render de la composición (relajado del umbral de 30dB porque la rasterización de texto puede diferir). Si falla: verifica primero si la geometría coincide (el componente se renderiza en la posición/rotación/escala correcta), luego verifica el relleno. Reporta al usuario la métrica de fidelidad: "Coincidencia visual: PSNR = X dB (mínimo requerido: 25dB) — verificación de fidelidad superada/fallada."

Recuperación de errores y orientación para el usuario

Todos los escenarios de error deben ser manejados con un mensaje claro que describa la acción del usuario:

• Token faltante (401): "El token de Figma ha expirado o fue revocado. Ve a figma.com/settings → Security → Personal access tokens, genera un nuevo token con el alcance 'File content: Read-only', luego actualiza FIGMA_TOKEN en tu perfil de shell o .env del proyecto."
• Alcance faltante (403): "El token de Figma carece del alcance requerido: <alcance_faltante>. Para importar tokens de marca, se necesita 'Library content: Read-only'. Ve a figma.com/settings, edita el alcance del token y agrega el alcance faltante."
• Límite de tasa alcanzado (429): "Límite de tasa de Figma alcanzado. Los reintentos automáticos se completaron con retroceso. Espera un minuto o importa menos nodos por solicitud. Las solicitudes por lotes (varias referencias en un comando figma asset) ayudan a mitigar esto."
• Conector no disponible (Fases 4-5): "Esta fase requiere un complemento de Figma compatible. Si tienes acceso, instala el conector 'HyperFrames Figma Connector' desde la comunidad de Figma. De lo contrario, proporciona una exportación nativa de Figma (PNG/MP4) para continuar."
• Fallo de verificación de fidelidad: "La verificación de fidelidad visual falló (PSNR < 25dB). Los problemas comunes son la representación del texto (diferencia de altura de línea) o artefactos de rasterización. Revisa el render y considera usar la opción --scale 2 para los assets si la nitidez es un problema."
• No se puede reconstruir el storyboard: "El análisis del storyboard encontró discrepancias en la coincidencia de elementos entre escenas. Esto generalmente indica que se renombraron capas entre fotogramas del storyboard. Intenta importar cada escena como un componente separado y enlázalos manualmente."

Referencia de comandos

Comando	Propósito	Fase
hyperframes figma asset <ref>	Renderiza nodo(s) de Figma como archivos estáticos (SVG, PNG, etc.)	Fase 1
hyperframes figma tokens <fileKey>	Importa estilos/variables de marca	Fase 2
hyperframes figma component <ref>	Convierte nodo de Figma en componente HTML editable	Fase 3
hyperframes render <scene>	Renderiza la composición para verificar	Post-fase
npx hyperframes check	Verifica la integridad de la composición	Integrador
npx hyperframes skills update figma	Actualiza esta skill de Figma	Mantenimiento