use_figma. Skill de la API de Plugin de Figma
Usa la herramienta use_figma para ejecutar JavaScript en archivos de Figma a través de la API de Plugin. Todos los documentos de referencia detallados se encuentran en references/.
Pasa siempre skillNames: "figma-use" al llamar a use_figma. Este es un parámetro de registro para rastrear el uso de la skill. No afecta la ejecución.
Si las herramientas MCP de Figma aparecen como herramientas diferidas, carga todos sus esquemas en una sola llamada de ToolSearch usando la sintaxis select:, p. ej., ToolSearch query="select:use_figma,get_screenshot,get_metadata,create_new_file". Un solo viaje de ida y vuelta es mejor que seis.
Si la tarea implica construir o actualizar una página completa, pantalla o diseño de varias secciones en Figma desde código, carga también figma-generate-design. Proporciona el flujo de trabajo para descubrir componentes del sistema de diseño a través de search_design_system, importarlos y ensamblar pantallas de forma incremental. Ambas skills trabajan juntas: esta para las reglas de la API, esa para el flujo de trabajo de construcción de pantallas.
Si la tarea implica crear o construir un componente en Figma (incluso un solo componente), carga también figma-generate-library. Proporciona el flujo de trabajo de creación de componentes, fundamentos de variables, conjuntos de variantes, enlaces de tokens de diseño. Eso que figma-use por sí solo no cubre.
Antes de nada, carga plugin-api-standalone.index.md para entender lo que es posible. Cuando se te pida escribir código de la API de Plugin, usa este contexto para buscar en plugin-api-standalone.d.ts tipos, métodos y propiedades relevantes. Esta es la fuente de verdad definitiva para la superficie de la API. Es un archivo de tipos grande, así que no lo cargues todo de una vez, busca secciones relevantes según sea necesario.
IMPORTANTE: Siempre que trabajes con sistemas de diseño, comienza con working-with-design-systems/wwds.md para entender los conceptos clave, procesos y directrices para trabajar con sistemas de diseño en Figma. Luego carga las referencias más específicas para componentes, variables, estilos de texto y estilos de efecto según sea necesario.
1. Reglas Críticas
- Usa
returnpara enviar datos de vuelta. El valor de retorno se serializa automáticamente en JSON (objetos, arrays, cadenas, números). NO llames afigma.closePlugin()ni envuelvas el código en una IIFE asíncrona. Esto se maneja por ti. - Escribe JavaScript plano con
awaityreturnde nivel superior. El código se envuelve automáticamente en un contexto asíncrono. NO lo envuelvas en(async () => { ... })(). figma.notify()lanza "not implemented": nunca lo uses 3a.getPluginData()/setPluginData()no son compatibles conuse_figma: no los uses. UsagetSharedPluginData()/setSharedPluginData()en su lugar (estos SÍ son compatibles), o rastrea los IDs de nodos devolviéndolos y pasándolos a llamadas posteriores.console.log()NO se devuelve. Usareturnpara la salida- Trabaja de forma incremental en pasos pequeños. Divide las operaciones grandes en múltiples llamadas a
use_figma. Valida después de cada paso. Esta es la práctica más importante para evitar errores. - Los colores están en el rango 0-1 (no 0-255):
{r: 1, g: 0, b: 0}= rojo - Los rellenos/trazos son arrays de solo lectura: clona, modifica, reasigna
- Cada edición de texto sigue la receta canónica: cargar fuente →
await→ mutar → devolver IDs de nodos afectados. Omitir la carga lanzaCannot write to node with unloaded font "<familia> <estilo>". La regla cubre más quecharacters: se aplica a cualquier operación en nodos con fuentes no cargadas (appendChild,insertChild,setBoundVariable,setExplicitVariableModeForCollection,setValueForMode, callbacks defindAllque toquen texto). Al mutar texto existente, carga las fuentes actuales del nodo a través degetStyledTextSegments(['fontName']), no un valor predeterminado fijo. Inter está precargado en la mayoría de los entornos, por lo que otras familias muestran este error con más frecuencia. La receta es la misma para cada fuente. Usaawait figma.listAvailableFontsAsync()primero si la cadena de estilo no está verificada. Consulta Receta canónica de edición de texto. - Las páginas se cargan de forma incremental: usa
await figma.setCurrentPageAsync(page)para cambiar de página y cargar su contenido. El setter síncronofigma.currentPage = pageNO funciona y lanzará un error (consulta las Reglas de Página a continuación) setBoundVariableForPaintdevuelve un NUEVO paint, debes capturarlo y reasignarlocreateVariableacepta el objeto o cadena de ID de la colección (se prefiere el objeto)layoutSizingHorizontal/Verticaltiene restricciones de valor según el contexto estructural,FIXEDsiempre funciona,HUGyFILLno.'HUG'solo es válido en un marco de auto-layout en sí mismo O en un hijo TEXT de uno.'FILL'solo es válido en un hijo de un marco de auto-layout que tampoco esté en posición absoluta, no dentro de un marco inmutable y no sea hijo de una cuadrícula de lienzo. Consecuencia práctica: agrega primero a un padre de auto-layout, luego estableceHUG/FILL: un nodo recién creado o sin padre aún no puede cumplir la regla. La propiedad en sí existe en cadaSceneNode; el error es un rechazo de valor, no "no existe tal propiedad". Consulta Errores comunes. 12a. Usa auto-layout para contenedores que tienen hijos relacionados. Cuando los hijos tienen una relación estructural, apilados, uno al lado del otro, alineados, espaciados, ajustados, envuélvelos enfigma.createAutoLayout(), no enfigma.createFrame()conx/yabsolutos. Las coordenadas absolutas determinan dónde se sitúa un contenedor en el lienzo; el auto-layout determina cómo se relacionan sus hijos dentro de él. Omitir el contenedor no deja protección contra el reflujo de texto, cambios de contenido o superposiciones.- Posiciona los nuevos nodos de nivel superior lejos de (0,0). Los nodos agregados directamente a la página tienen como valor predeterminado (0,0). Escanea
figma.currentPage.childrenpara encontrar una posición clara (p. ej., a la derecha del nodo más a la derecha). Esto solo se aplica a nodos de nivel de página; los nodos anidados dentro de otros marcos o contenedores de auto-layout son posicionados por su padre. Consulta Errores comunes. - Ante un error de
use_figma, DETENTE. NO reintentes inmediatamente. Los scripts fallidos son atómicos: si un script da error, no se ejecuta en absoluto y no se realizan cambios en el archivo. Lee el mensaje de error cuidadosamente, corrige el script y luego reintenta. Consulta Recuperación de errores. - DEBES
returnTODOS los IDs de nodos creados/mutados. Cada vez que un script cree nodos nuevos o mute los existentes en el lienzo, recopila cada ID de nodo afectado y devuélvelos en un objeto estructurado (p. ej.,return { createdNodeIds: [...], mutatedNodeIds: [...] }). Esto es esencial para que las llamadas posteriores puedan hacer referencia, validar o limpiar esos nodos. - Siempre establece
variable.scopesexplícitamente al crear variables. El valor predeterminadoALL_SCOPEScontamina todos los selectores de propiedades, casi nunca es lo que deseas. Usa ámbitos específicos como["FRAME_FILL", "SHAPE_FILL"]para fondos,["TEXT_FILL"]para colores de texto,["GAP"]para espaciado, etc. Consulta variable-patterns.md para la lista completa. - Haz
awaita cada Promise. Nunca dejes una Promise sin esperar, las llamadas asíncronas no esperadas (p. ej.,figma.loadFontAsync(...)sinawait, ofigma.setCurrentPageAsync(page)sinawait) se ejecutarán y olvidarán, causando fallos silenciosos o condiciones de carrera. El script puede devolverse antes de que la operación asíncrona se complete, lo que lleva a datos faltantes o cambios aplicados a medias.
Para ejemplos DETALLADOS de INCORRECTO/CORRECTO de cada regla, consulta Errores comunes y trampas.
2. Reglas de Página (Críticas)
El contexto de la página se restablece entre llamadas a use_figma: figma.currentPage comienza en la primera página cada vez.
Cambio de páginas
Usa await figma.setCurrentPageAsync(page) para cambiar de página y cargar su contenido. El setter síncrono figma.currentPage = page NO funciona: lanza "Setting figma.currentPage is not supported" en use_figma. Siempre usa el método asíncrono.
// Cambiar a una página específica (carga su contenido)
const targetPage = figma.root.children.find((p) => p.name === "Mi Página");
await figma.setCurrentPageAsync(targetPage);
// targetPage.children ahora está poblado
Llama a setCurrentPageAsync como máximo una vez por invocación de use_figma, distribuye el trabajo de varias páginas en paralelo
Un script debe cambiar de página como máximo una vez. Nunca iteres sobre figma.root.children y cambies de página dentro del bucle.
Si el trabajo abarca varias páginas, divídelo en N llamadas a use_figma (una por página de destino) y emítelas en paralelo: un solo mensaje de asistente que contenga N bloques de uso de la herramienta use_figma. El entorno de ejecución las ejecuta simultáneamente; cada script establece currentPage exactamente una vez.
Instrucción explícita: al distribuir, DEBES emitir las N llamadas a la herramienta en un mensaje. No las envíes en múltiples turnos. No esperes una antes de emitir la siguiente. Las llamadas secuenciales por página son más lentas que el patrón dentro del bucle que esta regla reemplaza y desperdician todo el beneficio de la división.
// EVITAR, cambia de página N veces en un script, recarga el archivo cada vez
for (const page of figma.root.children) {
await figma.setCurrentPageAsync(page);
// ... tocar esta página ...
}
// PREFERIR, llamada de solo lectura para obtener IDs de páginas, luego en el SIGUIENTE mensaje
// emitir N llamadas paralelas a la herramienta use_figma (una por página), cada una estableciendo currentPage una vez.
Predetermina la distribución en paralelo para cualquier trabajo de varias páginas, tanto lecturas como escrituras. Consulta gotchas.md → Establecer página actual una vez por llamada a use_figma para ver la justificación completa.
Entre ejecuciones de scripts
figma.currentPage se restablece a la primera página al inicio de cada llamada a use_figma. Si tu flujo de trabajo abarca múltiples llamadas y apunta a una página que no es la predeterminada, llama a await figma.setCurrentPageAsync(page) al inicio de cada invocación.
Puedes llamar a use_figma varias veces para construir incrementalmente sobre el estado del archivo, o para recuperar información antes de escribir otro script. Por ejemplo, escribe un script para obtener metadatos sobre nodos existentes, return esos datos, luego úsalos en un script posterior para modificar esos nodos.
3. return es tu Canal de Salida
El agente ve SOLAMENTE el valor que returnas. Todo lo demás es invisible.
- Devolver IDs (CRÍTICO): Cada script que cree o mute nodos en el lienzo DEBE devolver todos los IDs de nodos afectados, p. ej.,
return { createdNodeIds: [...], mutatedNodeIds: [...] }. Este es un requisito estricto, no opcional. - Informe de progreso:
return { createdNodeIds: [...], count: 5, errors: [] } - Información de error: Los errores lanzados se capturan y devuelven automáticamente, solo déjalos propagar o lanza
throwexplícitamente. - La salida de
console.log()nunca se devuelve al agente - Siempre devuelve datos procesables (IDs, recuentos, estado) para que las llamadas posteriores puedan hacer referencia a los objetos creados
4. Modo Editor
use_figma funciona en modo diseño (editorType "figma", el predeterminado). FigJam ("figjam") y Presentaciones ("slides") tienen diferentes conjuntos de tipos de nodos disponibles. La mayoría de los nodos de diseño están bloqueados en FigJam, y los nodos solo de FigJam están bloqueados en Presentaciones.
Identifica el editor por la URL: Diseño = figma.com/design/..., FigJam = figma.com/board/..., Presentaciones = figma.com/slides/.... Confirma antes de asumir que una API está disponible.
Disponible en modo diseño: Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Page, Section, TextPath.
Bloqueados en modo diseño: Sticky, Connector, ShapeWithText, CodeBlock, Slide, SlideRow, SlideGrid, InteractiveSlideElement, Webpage.
Disponible en modo Presentaciones (Slides): Rectangle, Frame, Component, Text, Ellipse, Star, Line, Vector, Polygon, BooleanOperation, Slice, Section, TextPath, Slide, SlideRow, SlideGrid, InteractiveSlideElement.
Bloqueados en modo Presentaciones (Slides): Sticky, Connector, ShapeWithText, CodeBlock, Webpage, Page.
APIs solo de diseño (no solo tipos de nodos): figma.createPage() está disponible solo en archivos de Diseño (figma.com/design/...). Tanto en FigJam (figma.com/board/...) como en Presentaciones (figma.com/slides/...) lanza TypeError: figma.createPage no such property 'createPage' on the figma global object. No emitas figma.createPage() en flujos de trabajo de FigJam o Presentaciones.
Nota sobre Presentaciones: Todavía no hay una herramienta de lectura dedicada para archivos de Presentaciones. Usa
use_figmacon scripts de solo lectura para inspección (consulta la Sección 6 "Patrón Inspeccionar primero"), yget_screenshot/await node.screenshot()para contexto visual. Para obtener orientación específica de la API de Presentaciones, carga la skill figma-use-slides.
5. APIs Eficientes. Prefiere Estas Sobre Alternativas Verbosas
Estas APIs reducen el código repetitivo, eliminan errores de orden y comprimen la salida de tokens. Prefiérelas siempre sobre las alternativas verbosas.
node.query(selector): Búsqueda de nodos tipo CSS
Encuentra nodos dentro de un subárbol usando selectores tipo CSS. Reemplaza los bucles verbosos de findAll + filtro.
// ANTES, recorrido verboso
const texts = frame.findAll(n => n.type === 'TEXT' && n.name === 'Título')
// DESPUÉS, una línea con query
const texts = frame.query('TEXT[name=Título]')
Sintaxis de selector:
- Tipo:
FRAME,TEXT,RECTANGLE,ELLIPSE,COMPONENT,INSTANCE,SECTION(sin distinción de mayúsculas/minúsculas) - Atributo exacto:
[name=Card],[visible=true],[opacity=0.5] - Subcadena de atributo:
[name*=art](contiene),[name^=Header](empieza con),[name$=Nav](termina con) - Recorrido de ruta de puntos:
[fills.0.type=SOLID],[fills.*.type=SOLID](índice comodín) - Coincidencia de instancia:
[mainComponent=nodeId],[mainComponent.name=Button] - Combinadores:
FRAME > TEXT(hijo directo),FRAME TEXT(cualquier descendiente),A + B(hermano adyacente),A ~ B(hermano general) - Pseudoclases:
:first-child,:last-child,:nth-child(2),:not(TYPE),:is(FRAME, RECTANGLE),:where(TEXT, ELLIPSE) - ID de nodo:
#nodeIdo GUID simple - Coma:
TEXT, RECTANGLE
figma.create*(): Creación directa de nodos
Usa estos en lugar de figma.importComponentByKeyAsync() cuando los nodos no necesiten ser referenciados a componentes de la biblioteca:
// Crea un rectángulo
const rect = figma.createRectangle()
rect.resize(100, 100)
rect.fills = [{ type: 'SOLID', color: { r: 0.2, g: 0.4, b: 0.6 } }]
// Crea un marco con auto-layout
const frame = figma.createAutoLayout()
frame.itemSpacing = 8
frame.paddingLeft = frame.paddingRight = 16
frame.paddingTop = frame.paddingBottom = 12
figma.mixed: Comprobación de valores mixtos
Usa figma.mixed para comprobar si una propiedad tiene múltiples valores (p. ej., rellenos, pesos de trazo):
if (node.fillStyleId !== figma.mixed) {
// El estilo de relleno es uniforme en todos los rellenos
}
await node.screenshot(): Captura de pantalla directa
En lugar de get_screenshot para un nodo individual, puedes llamar a await node.screenshot() dentro de un script use_figma. Devuelve los bytes de la imagen. Esto ahorra un viaje de ida y vuelta a la herramienta externa.
6. Recuperación de Errores y Autocorrección
Regla de oro: ante un error, DETENTE. NO reintentes.
Los scripts fallidos con use_figma son atómicos: si un script produce un error, no se ejecuta en absoluto y no se realizan cambios en el archivo. No hay "cambios parciales" que deshacer.
Cuando obtengas un error de use_figma:
- Lee el mensaje de error cuidadosamente. La API de Plugin de Figma proporciona mensajes de error descriptivos (p. ej., fuente no cargada, tipo no válido, propiedad faltante).
- Identifica la regla violada. La mayoría de los errores corresponden a una de las reglas en la Sección 1 (verificar fuente, problema de ámbito, restricción de
layoutSizing, etc.). - Corrige el script. Aplica la corrección; si no estás seguro, consulta
references/gotchas.mdpara ejemplos INCORRECTO/CORRECTO. - Vuelve a emitir la llamada
use_figmacorregida.
Excepción: Si un error indica un problema transitorio (error de red, tiempo de espera), puedes reintentar una vez después de una breve pausa. Si el segundo intento falla, detente e informa al usuario.
Patrón: Inspeccionar primero
Para conjuntos de cambios grandes, primero emite un script use_figma de solo lectura para recopilar metadatos del nodo (IDs, nombres, tipos), devolver esos datos, luego construir el script de escritura basado en la estructura real.
// Script de inspección
const pageInfo = figma.root.children.map(p => ({
id: p.id,
name: p.name,
childCount: p.children.length,
types: [...new Set(p.children.map(c => c.type))]
}))
return { pages: pageInfo }
Esto evita suposiciones sobre la estructura del archivo que podrían provocar errores.
7. Referencias
Toda la documentación detallada de la API, incluyendo ejemplos, gotchas y patrones, está en el directorio references/:
- plugin-api-standalone.index.md - Resumen de capacidades de la API
- plugin-api-standalone.d.ts - Archivo de tipos de la API (busca secciones relevantes, no lo cargues todo)
- gotchas.md - Errores comunes, ejemplos INCORRECTO/CORRECTO para cada regla
- working-with-design-systems/wwds.md - Conceptos y procesos de sistemas de diseño
- variable-patterns.md - Patrones para crear y usar variables
Skills complementarias:
- figma-generate-design - Flujo de trabajo para construir layouts completos de pantallas desde código
- figma-generate-library - Creación de componentes, conjuntos de variantes y tokens de diseño
- figma-use-slides - Orientación específica de la API para archivos de Presentaciones