bdsanxz/figma-access

Acceso a Figma

Trabajas con Figma a través de una herramienta de línea de comandos. Imprime KDL y guarda sus archivos de datos como .kdl: un nodo por línea, con los campos simples de un nodo como clave=valor en esa línea, por lo que grep, awk y sed funcionan directamente sobre ellos. Las excepciones son spec, que imprime su propio esquema de texto de una línea por nodo, daemon log, que imprime las líneas de registro del demonio tal como aparecen, y render, screenshot, image-fills y compare, que guardan archivos de imagen (su resumen en stdout sigue siendo KDL). Tiene dos formas de acceso:

• REST (file, node, spec, render, image-fills, api): lee cualquier archivo desde su URL con el token del usuario. No es necesario tener nada abierto. Las lecturas se almacenan en caché local y se reintentan en caso de límites de velocidad.
• Plugin (exec, screenshot, selection, logs, changes, call): un demonio en segundo plano se comunica con el plugin Desktop Bridge que se ejecuta en Figma Desktop. Esta es la única forma de modificar un archivo. Tu herramienta principal aquí es exec, que ejecuta JavaScript de la API de plugins de Figma en el archivo.

references/tips.md contiene lecciones de ejecuciones reales, organizadas por situación. Son orientación, no reglas: lee la sección correspondiente a la situación en la que te encuentres y adáptala a tu caso.

Reglas

• Nunca muestres el token. No lo imprimas, registres ni muestres; pruébalo con figma-access api /v1/me.
• Inspecciona antes y después de cualquier cambio. Juzga cada resultado visible en una imagen, no en el código que lo generó.
• Lee los valores, no los adivines; el render decide. Toma colores, tamaños, espaciados, fuentes y texto del archivo, nunca a ojo desde una imagen. Cuando los datos del archivo y el render no coinciden, el render es lo que el usuario ve.
• Cambia solo lo que el usuario pidió. Leer siempre está bien. Nunca elimines ni sobrescribas el trabajo existente del usuario a menos que la solicitud lo indique.
• Un tiempo de espera no es un fallo. Figma no puede detener un script en ejecución; verifica logs y el archivo antes de ejecutarlo de nuevo.

Flujo de trabajo

1. Configuración

1. <skill> es el directorio de este SKILL.md. Ejecuta la herramienta como bun <skill>/scripts/figma-access.js COMANDO ...; este archivo lo escribe como figma-access COMANDO .... Se ejecuta en Bun, no en Node: inícialo siempre con bun, nunca con node, y ejecuta cualquier script auxiliar de JavaScript o TypeScript que escribas también con bun. Para acortar el comando, define una función de shell al inicio de cada llamada de shell (fa(){ bun <skill>/scripts/figma-access.js "$@"; }; fa ...), no una variable: zsh no divide una variable en palabras. Pon entre comillas cada URL e ID de nodo que pases: ?, & y ; son especiales para el shell. Si bun no está disponible, dile al usuario que lo instale desde https://bun.sh y detente.
2. Ejecuta figma-access --help una vez, y figma-access <comando> --help antes del primer uso de cada comando. Códigos de salida: 0 correcto, 1 Figma reportó un fallo, 2 argumentos incorrectos, 3 demonio, plugin o token no disponible. "Lectura de la salida" en references/tips.md explica el formato y cómo buscarlo.
3. Elige la ruta según la solicitud, como describe "Elección de una ruta" en references/tips.md: una URL y un trabajo de solo lectura → REST; cualquier cambio en el archivo → plugin; ambos pueden usarse juntos.

2a. Conexión a través de REST

1. Ejecuta figma-access api /v1/me. Si aparece "no token": busca dónde lo configuró el usuario y cárgalo en el mismo comando, como describe "Token" en references/tips.md. Pídele al usuario un token (Figma: Configuración > Seguridad > Tokens de acceso personal, lectura de contenido de archivo) solo cuando no esté configurado en ningún lugar.
2. Ejecuta figma-access file <url> para ver las páginas y los frames de nivel superior. Elige el nodo en el que trabajar, siguiendo "Encontrar el nodo correcto" en references/tips.md.

2b. Conexión a través del plugin

1. Ejecuta figma-access status. Inicia el demonio cuando sea necesario.
   • Archivos listados: continúa.
   • Sin archivos: ejecuta figma-access files, que espera al plugin. Si sale con 3, ejecuta figma-access setup y dale al usuario sus steps en palabras simples: importa el plugin una vez desde la ruta del manifiesto impresa, luego ejecuta Plugins > Development > Figma Desktop Bridge en el archivo y mantén su ventana abierta. Pídele al usuario que te avise cuando esté en ejecución, luego vuelve a ejecutar figma-access files.
2. Si hay más de un archivo conectado, pasa --file <fileKey> en cada comando de aquí en adelante.

3. Comprender el diseño

1. Lee la vista más pequeña que responda la pregunta, primero el esquema y solo los detalles donde trabajes:
   • estructura: figma-access node <url|key> <id> --outline 2 (REST), o la receta de esquema de página en references/plugin-api.md (plugin);
   • todo lo que el código necesita, una línea por nodo visible: figma-access spec <url|key> <id> -o <archivo>; para un frame grande, guárdalo una vez con node ... -o <archivo> y pasa --from <archivo> a cada spec posterior, como describe "Límites de velocidad y caché" en references/tips.md;
   • qué quiere decir el usuario con "esto" o "lo seleccionado": figma-access selection;
   • cómo se ve: figma-access render <key> <id> (REST, tamaño exacto) o figma-access screenshot <id> (plugin), luego abre la imagen.
2. Lee los reports de node: fuentes, rellenos de imagen y cuántas capas ocultas se eliminaron. Lee "Capas ocultas" y "Lectura de una imagen de diseño" en references/tips.md.
3. Para componentes, variantes, variables y estilos, lee su estructura real antes de modificarlos o copiarlos, y reutiliza lo que existe en lugar de crear duplicados.

4. Realizar el trabajo

Implementar un diseño en código. Antes de escribir código, lee "Del diseño al código" en references/tips.md: la mayoría de las diferencias que persisten después de una primera construcción (recortes de imagen, fuentes, desplazamientos de texto, ancho de página) están cubiertas allí. Escribe el código donde el usuario o su proyecto indiquen que debe ir (la ruta que nombren, o la estructura del propio proyecto); _swe/figma-access/ solo contiene artefactos de trabajo como renders, archivos de nodo guardados, especificaciones, capturas de pantalla y scripts.

1. Renderiza el frame a escala 1 como referencia, y léelo en partes si es alto.
2. Escribe la spec del frame en un archivo, con --origin en la esquina donde comienza el contenido de la página, y toma cada valor de ella. Renderiza imágenes, y lo que marque como ICON o MASKED, en lugar de reconstruirlos. Construye los frames de diseño automático a partir de la dirección, el espacio, el relleno y el tamaño que spec imprime, en lugar de sus cuadros almacenados, y coloca los hijos de grupos y frames sin diseño automático en sus cuadros. No posiciones cada nodo de forma absoluta en su cuadro almacenado, manualmente o con un generador: esa página copia cada cuadro obsoleto, se rompe cuando un texto se alarga y no puede adaptarse a la ventana. Verifica cada parte marcada como LAYOUT DRIFT contra el render.
3. Enumera las fuentes con cada peso; busca en el proyecto los archivos de cualquier familia que no sea pública, y pídele al usuario, en un solo mensaje, las que aún falten, y cualquier otra cosa que no puedas obtener del archivo. Hasta que lleguen, o cuando no puedas preguntar, usa un sustituto y dilo.
4. Omite el marco del dispositivo o del navegador, y deja que la página se adapte a la ventana: el ancho del frame es la pantalla para la que fue dibujado, por lo que los fondos y divisores abarcan la ventana y la columna de contenido está centrada, a menos que el usuario solicite un ancho fijo.
5. Construye sección por sección, luego mide la página contra la referencia con figma-access compare <referencia.png> <pagina> --nodes <archivo de nodo> --wide <px>: captura la página, imprime los píxeles diferentes por sección del frame con el desplazamiento que explica cada uno, qué tan lejos están cada estilo de texto y nodo, y cuáles faltan, escribe una imagen de diferencias y verifica una ventana más ancha. Con --nodes toma las secciones de los hijos propios del frame y recorta una referencia que la sombra del frame ensanchó. Mira también la captura y la imagen de diferencias, y repite hasta que cada sección coincida. Cuando el usuario solicite un resultado perfecto o 1:1 y haya una habilidad para eso listada en tu sesión, úsala con estos renders como imágenes de diseño.

Modificar el archivo. A través del plugin:

1. Escribe el cambio como código de la API de plugins y ejecútalo con figma-access exec, siguiendo references/plugin-api.md para lo que la API exige y para la colocación. El código largo va en un archivo de trabajo (por ejemplo, en _swe/figma-access/) y se ejecuta con exec -f. Siempre return los ids que necesites a continuación; añade --timeout 30s o más para trabajos largos.
2. Para trabajos que cubre una rutina de plugin ya preparada (conjuntos de componentes, auditorías de lint y accesibilidad, rellenos de imagen, anotaciones, ayudantes de FigJam y Slides), usa figma-access call <METODO> '<json>'; figma-access methods <filtro> lista los parámetros.
3. Lee la salida cada vez: en ok #false, corrige la causa y elimina el trabajo parcial antes de reintentar; en un warning bajo resultAnalysis, verifica ids y nombres; para el rastro del propio script, figma-access logs --since 2m.
4. Toma una captura de pantalla de cada nodo que creaste o modificaste (--scale 2 para los pequeños) y compárala con la solicitud. Corrige y vuelve a capturar; después de tres rondas que aún fallen, dile al usuario qué queda y por qué.

"Trabajar a través del plugin" en references/tips.md cubre lo que suele salir mal aquí.

5. Informar

Dile al usuario qué leíste o modificaste, con nombres de nodo e ids, y las rutas de los renders, capturas de pantalla y archivos que escribiste. Menciona cualquier cosa que no hiciste, cada suposición que hiciste (una fuente sustituta, una capa oculta omitida, el marco del navegador omitido) y lo que no se verificó.

Solución de problemas

• "Límite de velocidad excedido" (429): la CLI ya esperó y reintentó. Sigue "Límites de velocidad y caché" en references/tips.md, y espera un minuto antes de la siguiente lectura grande.
• Salida 3, ningún archivo conectado: el plugin no se está ejecutando en ese archivo, o todavía está buscando (verifica cada pocos segundos). Pídele al usuario que lo ejecute de nuevo. figma-access daemon log muestra las conexiones a medida que ocurren.
• Otra herramienta usa el mismo plugin (como figma-console-mcp): ambas funcionan juntas; figma-access status muestra si este demonio tiene el archivo.
• Comportamiento obsoleto después de actualizar la habilidad: ejecuta figma-access setup de nuevo, pídele al usuario que reimporte el manifiesto en Figma, luego ejecuta figma-access daemon restart.
• "El plugin se desconectó antes de responder": el usuario cerró el plugin o el archivo, o el plugin se recargó. Verifica el archivo antes de repetir el cambio.