Figma → HyperFrames

Primero, mantén esta habilidad actualizada — ejecuta en silencio, no preguntes: npx hyperframes skills update figma. Es un no-op rápido cuando todo está al día; de lo contrario, refresca esta habilidad junto con las habilidades del dominio central de las que depende antes de que confíes en ellas.

¿Qué hace 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	Activos estáticos	REST	hyperframes figma asset
2	Tokens/estilos de marca	REST	hyperframes figma tokens
3	Componentes → HTML	REST	hyperframes figma component
4	Animación → GSAP	conector cuando esté disponible	usa su contexto de animación
5	Shaders	conector / exportación manual	úsalo o una exportación nativa

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

Autenticación — dos credenciales, con alcance

Pre-vuelo — antes de la primera llamada CLI, verifica que exista 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 ninguno, NO ejecutes el comando para capturar 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 — el fallback de estilos publicados llama a /v1/files/:key/styles, que da 403 sin él (un alcance que el texto de configuración anterior omitía). Opcionalmente Variables: Solo lectura para variables de marca — solo Enterprise; sin él, tokens degrada a estilos publicados automáticamente (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 en el .env del proyecto; nunca le pidas que pegue el token en la conversación.

Durante la incorporación, también establece expectativas de una vez: 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 token funciona para activos, tokens de marca y componentes de todos los archivos que su cuenta de Figma pueda ver.

• Fases 4–5 (animación/shaders): un conector Figma compatible, con autorización separada del token. Si no está disponible o no está autenticado, pídele al usuario que lo conecte o que 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) durante el flujo → el token está caducado/revocado; vuelve a generarlo. FORBIDDEN (403) → el mensaje nombra el alcance exacto que falta (por ejemplo, library_content:read para el fallback de estilos) — añádelo, o el archivo no es visible para la cuenta. REQUIRES_ENTERPRISE (403 en variables) → no es un fallo: el fallback de estilos ya se ejecutó. RATE_LIMITED (429) → el cliente ya reintentó con retroceso (esto se aplica a CADA lectura — activos, tokens, estilos, árboles de nodos, versiones — el reintento vive en la ruta de solicitud compartida; se respeta Retry-After, con un tope 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 las solicitudes de marcos principales, 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 volumen, 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" → Activo (CLI)
• "toma mi marca / colores / tokens" → Tokens (CLI)
• "construye una escena desde este marco" → Componente (CLI)
• "importa esta animación / movimiento" → Animación (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 qué vas a obtener de Figma; después, di dónde aterrizó el artefacto (la ruta congelada / sidecar / directorio del componente), qué cambió en la composición y la siguiente acción inmediata (previsualizar, añadir variables impresas, reimportar para enlazar vinculaciones). El usuario nunca debería tener que preguntar "¿funcionó?" o "¿y ahora qué?".

Activos (Fase 1 — CLI)

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

Renderiza a través de REST, sanitiza SVG, congela bajo .media/images/, agrega 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 (escalables, animables), PNG --scale 2 para fidelidad raster. Siempre pasa --description "<qué es>" (se convierte en la fila del índice + <img alt>); añade --entity "<nombre>" para marcas de marca nombradas para que resolve --entity las encuentre más tarde (las coincidencias de entidad funcionan entre imágenes/iconos).

Procesa varios nodos en UNA solicitud — pasa varias referencias (separadas por espacios o comas) del MISMO archivo: hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'. Todos 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 activos de un marco. --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 + sidecar figma-tokens.json + registros de índice de vinculación (.media/figma-bindings.jsonl). Las variables están restringidas a nivel Enterprise: en otros planes, el comando degrada a metadatos de estilos publicados (los valores se resuelven en el momento de importación del componente). Añade las entradas impresas al data-composition-variables de la composición.

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

Ruta de variables que no son Enterprise (probada en campo): Las variables REST están restringidas a Enterprise, pero un conector compatible puede proporcionar definiciones de variables. Cuando tokens informa REQUIRES_ENTERPRISE y el conector está disponible, recupera las variables de la escena principal una vez, almacena en caché la respuesta sin procesar en .media/figma-cache/, y úsala para construir el índice de vinculación. El boundVariables del árbol de nodos REST proporciona VariableIDs por propiedad; únelos por nodo y propiedad, luego escribe filas de .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 de var() del componente, actualización, variables CSS en tiempo de ejecución) es la maquinaria enviada. Etiquétalo para el usuario: "tokens a través del conector Figma — los planes Enterprise obtienen esto de hyperframes figma tokens directamente."

El tiempo de ejecución define cada variable de composición declarada como una propiedad personalizada de CSS (raíz del documento + hosts de subcomp), por lo que var(--slug, literal) importado llena el recoloreado cuando el valor predeterminado de la variable cambia — actualizar un valor en data-composition-variables renombra cada componente importado sin reimportar nada. hyperframes render --variables '<json>' las anula en tiempo de 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 rasterizan automáticamente a través de la exportación de la Fase 1. Pase de vinculación (especificación §7.1, solo ID exacto — nunca coincidencia de valor):

• Autocomprobación de fidelidad estática (obligatoria para contenido destacado): después de importar, renderiza el fragmento y compáralo con los píxeles reales de Figma — figma asset <mismo nodo> --format png es la verdad fundamental. El texto es el eje de deriva 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 deriva medida sin él era de ~6px en una fuente de 70px). Si la comparación muestra deriva que el mapeador no cubre, repórtalo — no ajustes el fragmento manualmente en silencio.
• Relleno vinculado a un token importado → var(--slug, #literal) — la actualización de marca se propaga.
• Vinculado a un token desconocido → literal + bandera data-figma-unresolved. El comando te lo dice; ofrécele al usuario: ejecuta tokens en el archivo fuente (o de biblioteca), luego reimporta el componente para vincularlos. Pregunta una vez por biblioteca desconocida qué archivo es — nunca adivines, nunca coincidas por hex.

Animación (Fase 4 — asistida por conector)

Baliza de uso: Las fases asistidas por conector no tienen punto de contacto CLI, así que dispara la baliza de habilidad 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 equivalente REST. Cuando un conector compatible esté disponible, úsalo y pasa su salida a los ayudantes puros en @hyperframes/core/figma; de lo contrario, solicita una exportación nativa:

1. Recupera el contexto de animación para el marco principal en una solicitud recursiva, no una solicitud 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 a mano. El ayudante codifica las reglas de decodificación probadas en campo mecánicamente: analiza los fragmentos de motion.dev (la codificación confiable — los fragmentos CSS estiran las duraciones y pueden no coincidir; se ignoran), elimina los fotogramas clave de final de bucle (segmentos de sub-milisegundo en tiempos ≈0,9999→1 son el reinicio instantáneo del bucle, no animación creada — el bucle se realiza mediante el reinicio de repeat), y conserva los eases bezier textualmente. selectorFor debe devolver los IDs de la importación del componente de la Fase 3 — no derives selectores de nombres de nodos. 2b. Valida contra la verdad fundamental antes de darlo por terminado — obligatorio: exporta el marco 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 15 dB de PSNR de movimiento mínimo (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 GSAP + CustomEase CDN. En pausa, finito, registrado en window.__timelines con una clave literal.
4. Pista no traducible (impulsada por shader, propiedad no compatible, máscaras complejas) → exportar a través del conector, congelar el MP4, luego incrustarlo 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), por lo que una cocción allí pierde silenciosamente el shader; pídele al usuario una exportación nativa de Figma en su lugar. Siempre di qué ruta usaste y por qué. Los eases con nombre fuera del conjunto mapeado retroceden a lineal — la tabla de mapeo vive en motionEase.ts; señala el retroceso al usuario cuando ocurra.
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 bibliotecas (asiento completo de pago). Ruta predeterminada: pídele al usuario que exporte el marco del shader de forma nativa en Figma (PNG o Motion MP4), luego impórtalo como un activo 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 del 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 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 los FRAMEs nombrados como los RECTÁNGLEOs sueltos de tamaño completo (los diseñadores pegan imágenes fijas directamente en la sección). Filtra por tamaño (≈ aspecto de la composición, por ejemplo >1400×900), no por tipo de nodo o nombre.
2. Orden = posición x (fila principal si la tira se envuelve). Ordena las escenas por absoluteBoundingBox.x.
3. Diferencia fotogramas adyacentes en cadenas de elementos — aquí es donde vive la animación. Empareja hijos en fotogramas consecutivos: primero por nombre (mismo nombre = mismo elemento → interpola su x/y/w/h relativo entre estados), luego por similitud geométrica (tamaño similar + centroide cercano → mismo elemento, aunque renombrado). Los elementos no emparejados son nuevos (aparecen) o desaparecen (desaparecen).
4. Construye líneas de tiempo: para cada cadena de elementos, los estados por fotograma → intervalos animados. Un elemento con estados diferentes en los fotogramas 0 y 3 obtiene keyframes en 0s y 3×(intervalo de fotograma). Valores idénticos = pausa. Valores faltantes (no apareció hasta el fotograma 1) = keyframe de opacidad: 0 en los fotogramas anteriores.
5. Genera marcos de componente: para cada cadena, emite un elemento de composición con clases que codifican posiciones de keyframe. La línea de tiempo literal se convierte en un objeto de especificación de animación, alimentado a frameRenderToGsap(...). El fotograma 0 (estado inicial) se renderiza como HTML estático + CSS; los keyframes posteriores se inyectan como una línea de tiempo GSAP.

Ruta de degradación para storyboards grandes: si el análisis del storyboard presiona el límite de tokens (~¹⁰⁰ escenas, ¹⁰K nodos), usa hyperframes figma storyboard-process <fileKey:sectionId> --stages=1,2,3 para diferir la decodificación de la gramática (pasos 1–3) a un comando CLI por lotes. Pasa los absoluteBoundingBoxes sin procesar; la CLI emite una estructura de escena analizada (scene-chains.json). Luego lee esa estructura en lugar de analizar el DOM de Figma sin procesar, y continúa con los pasos 4–5 como de costumbre. Di: "Storyboard grande — descargando el análisis a un proceso por lotes."

Gramática de storyboard de referencia – Guión visual

Formato: Las secciones de storyboard de Figma siguen una estructura de 2 niveles: un contenedor de sección (FRAME) que contiene escenas hijas (FRAMES/RECTÁNGLEOs). Las escenas contienen elementos de interfaz (capas).

Reglas de análisis:

• Contenedor de sección: identificado por nombre que coincide con las convenciones de parseFigmaRef o por estar en una página marcada como storyboard.
• Escenas: todos los nodos dentro del contenedor con dimensiones coincidentes con la relación de aspecto del lienzo (>80% del ancho del contenedor, >60% del alto).
• Elementos: hijos directos de cada escena, filtrados por visibilidad (excluye capas ocultas).
• Secuencia: orden de escenas por coordenada X, luego Y (de izquierda a derecha, de arriba a abajo).