figma

Primero, mantén esta habilidad actualizada — ejecútala silenciosamente, no preguntes: npx hyperframes skills update figma. Una operación rápida que no hace nada cuando todo está al día; de lo contrario, actualiza esta habilidad más las habilidades centrales del dominio de las que depende, antes de que confíes en ellas.

Figma → HyperFrames

Trae el trabajo de Figma del usuario a una composición. Dividido por capacidad (sección de 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	Movimiento → GSAP	conector cuando esté disponible	usa su contexto de movimiento
5	Shaders	conector / exportación manual	úsalo o una exportación nativa

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

Autenticación — dos credenciales, con alcance

Verificación previa — antes de la primera llamada CLI, verifica que exista un token: entorno shell ([ -n "$FIGMA_TOKEN" ]) o el .env del proyecto (el CLI lo carga automáticamente — una entrada en .env cuenta como configurado). Si 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. Ámbitos — solo lectura es todo lo que esta integración necesita (nunca escribe en Figma): Contenido del archivo: Solo lectura + Metadatos del archivo: Solo lectura. Agrega Contenido de la biblioteca: Solo lectura si vas a ejecutar tokens en un plan que no sea Enterprise — la alternativa de estilos publicados llama a /v1/files/:key/styles, que da 403 sin él (un ámbito que el texto de configuración anterior omitía). Opcionalmente Variables: Solo lectura para variables de marca — solo Enterprise; sin él, tokens degrada automáticamente a estilos publicados (esperado, no es un error — dilo). Un 403 ahora menciona el ámbito 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 en todos los archivos que la cuenta de Figma del usuario puede 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 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) en medio del flujo → el token ha caducado/ha sido revocado; vuelve a generarlo. FORBIDDEN (403) → el mensaje menciona el ámbito exacto que falta (por ejemplo, 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 ha reintentado con retroceso (esto se aplica a CADA lectura — activos, tokens, estilos, árboles de nodos, versiones — el reintento reside en la ruta de solicitud compartida; Retry-After se respeta, limitado a 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 fotogramas principales, omite las 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, buckets por extremo) — funciona bien a gran escala, retrocede en caso de 429.

Enrutamiento

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

• "usa esta capa / logo / imagen" → Activo (CLI)
• "trae 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 qué vas a extraer 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 (vista previa, agregar variables impresas, reimportar para enlazar bindings). 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 referencias…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]

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

Agrupa muchos 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'. Todos se renderizan en una sola llamada /v1/images, que es la propia respuesta de Figma al límite de tasa por minuto — prefiero esto sobre N comandos separados al extraer todos los activos de un fotograma completo. --description/--entity se aplican a cada nodo del 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 la composición + sidecar figma-tokens.json + registros del índice de enlaces (.media/figma-bindings.jsonl). Las variables están restringidas a Enterprise upstream: en otros planes, el comando degrada a metadatos de estilo publicado (los valores se resuelven en el momento de la importación del componente). Agrega las entradas impresas a la data-composition-variables de la composición.

Importa los tokens antes que los componentes cuando se deseen ambos — eso permite que los colores de los componentes se vinculen a las 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 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 enlaces. El árbol de nodos REST boundVariables 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 downstream (resolución 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 de Figma — los planes Enterprise obtienen esto directamente de hyperframes figma tokens."

El tiempo de ejecución declara cada variable de composición como una propiedad personalizada de CSS (raíz del documento + hosts de subcomposición), por lo que var(--slug, literal) importado rellena el recoloreado cuando cambia el valor predeterminado de la variable — actualizar un valor en data-composition-variables renombra cada componente importado sin reimportar nada. hyperframes render --variables '<json>' las anula 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 rasterizan automáticamente a través de la exportación de la Fase 1. Pase de enlace (especificación §7.1, solo ID exacto — 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 propios píxeles 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 son 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órtalo — no ajustes a mano el fragmento 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; ofrece al usuario: ejecuta tokens en el archivo de origen (o biblioteca), luego reimporta el componente para vincularlos. Pregunta una vez por biblioteca desconocida qué archivo es — nunca adivines, nunca coincidas por código hexadecimal.

Movimiento (Fase 4 — asistido 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 un equivalente REST. Cuando haya un conector compatible disponible, úsalo y pasa su salida a los helpers puros en @hyperframes/core/figma; de lo contrario, solicita una exportación nativa:

1. Recupera el contexto de movimiento para el fotograma principal en una sola 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(respuestaSinProcesar, { selectorFor, repeat }) de @hyperframes/core/figma — nunca transcribas números de fotogramas clave manualmente. El helper 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 diferir; se ignoran), elimina los fotogramas clave de cola de bucle (segmentos de menos de un milisegundo en tiempos ≈0.9999→1 son el reinicio instantáneo del bucle, no movimiento creado — el envoltorio se realiza mediante repeat restart), y preserva 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 nodo. 2b. Valida contra la verdad fundamental antes de darlo por terminado — obligatorio: exporta el fotograma raíz de la 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 los deltas de energía de movimiento (la fidelidad de importación estática se cancela) y falla por debajo de 15dB 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 volver a verificar la traducción, no el umbral.
3. motionToGsap(doc) → emitTimelineScript(especificación) → 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 no traducible (impulsada por shader, propiedad no soportada, máscaras complejas) → exporta a través del conector, congela el MP4, luego incrústalo como <video class="clip">. Excepción: pistas impulsadas por shader — la ruta de exportación de Figma aplana los shaders al color base (consulta Shaders más abajo), por lo que un horneado 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é. Los eases con nombre fuera del conjunto mapeado retroceden a lineal — la tabla de mapeo vive en motionEase.ts; señala la alternativa al usuario cuando ocurre.
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 el código 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 Motion MP4), luego impórtalo como un activo/clip de la Fase 1. 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 lo largo 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 los 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ÁNGULO suelto a tamaño completo (los diseñadores pegan imágenes fijas directamente en la sección). Filtra por tamaño (≈ relación de aspecto de la composición, por ejemplo >1400×900), no por tipo de nodo o nombre.
2. Orden = posición x (en orden de fila si la tira se envuelve). Ordena las escenas por absoluteBoundingBox.x.
3. Diferencia los fotogramas adyacentes en cadenas de elementos — aquí es donde vive la animación. Compara los hijos entre 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 + posición xy cercana dentro de la posición x/y

… (truncado para traducción)