EugineKosenko/majordom

analyze-fig

Análisis de exportación de Figma (.fig) sin recurrir a la API de Figma: el árbol de nodos, los textos y los rásteres se leen directamente del archivo, mientras que los comentarios del autor, que no están en el .fig, se obtienen por separado a través de MCP mediante un enlace. El resultado son archivos md en spcfctn/ui/, que se utilizan en adelante en lugar de volver a leer Figma.

Cuándo no ejecutar

Las preguntas sobre un diseño ya analizado («¿qué dice el comentario del filtro…?», «¿qué columnas tiene la pantalla…?») deben resolverse leyendo spcfctn/ui/*.md, no con esta skill. El análisis es necesario para un .fig nuevo o actualizado, o cuando no hay respuesta en el md (ver spcfctn-code.md).

Directorios (único directorio de borradores draft, fuera de git)

• spcfctn/ui/draft/ — .fig de entrada (y cualquier otro borrador). El usuario coloca el archivo aquí.
• spcfctn/ui/draft/<nombre>/ — resultado del desempaquetado: message.json (todos los nodos), meta.json, images/, screens.json y screens.txt, además de los comentarios recopilados (comments.json). Se regenera a partir del .fig, no va a git. No hay directorios raw/ ni data/ separados (modeling.md).
• spcfctn/ui/*.md — resultado del análisis; solo esto permanece en git.

<nombre> es el nombre del archivo sin extensión en minúsculas y con guiones (internal-interfaces).

Paso 0 — preparación

• Encuentra spcfctn/ del proyecto. Si no existe, pide al usuario que lo cree (spcfctn-code.md). El artefacto ui/ y su subdirectorio draft/ debes crearlos tú.
• Verifica spcfctn/ui/.gitignore (repositorio del artefacto): debe contener draft (ver modeling.md); lo que falte, agrégalo mediante gitignore.org.
• Archivo fig: el usuario indica su nombre; si no lo indica, muestra spcfctn/ui/draft/*.fig y pregunta.
• Lee el CLAUDE.md del proyecto (idioma de prosa, convenciones) y los spcfctn/ui/*.md existentes: el análisis debe continuar su estructura y términos, no comenzar desde cero.
• Se necesitan python3 y zstd en el PATH.

Paso 1 — desempaquetar y decodificar

python3 ~/.claude/skills/analyze-fig/scripts/fig.py spcfctn/ui/draft/X.fig spcfctn/ui/draft/<nombre>

Muestra la versión del formato, cantidad de nodos, blobs e imágenes. El script está verificado en la versión 106; en otra versión o con error, no adivines el formato ni leas decodificadores ajenos, indícalo al usuario. meta.json contiene exported_at: la hora de exportación se necesitará en el paso 5. message.json es grande, no lo imprimas directamente.

Paso 2 — desglosar en secciones y pantallas

python3 ~/.claude/skills/analyze-fig/scripts/screens.py spcfctn/ui/draft/<nombre>

Muestra el listado de páginas, secciones (marcos de nivel superior) y pantallas (sus hijos) con cantidad de textos y rásteres. Toda la esencia está en screens.txt: para cada pantalla, las capas de texto agrupadas en filas de arriba abajo y de izquierda a derecha (así se leen filtros, encabezados de columna y botones), más referencias a los rásteres.

• Compara las cantidades con las esperadas (por ejemplo, con el md anterior); una discrepancia es motivo para detenerse.
• Las capas de texto no ven elementos sin texto (iconos simples) ni contenido de los rásteres. Para cada ráster en images/, abre el archivo (Read) y describe lo que no aparece en las capas de texto; indica que esto se ha leído de la imagen. El árbol y los textos son la evidencia principal; las imágenes, un complemento.
• Las instancias de componentes (INSTANCE) pueden tener textos sobrescritos que el script no ve; screens.txt advierte sobre esto.

Paso 3 — escribir spcfctn/ui/*.md

• Un md por sección (o por archivo cuando hay una sola sección). Si el archivo ya existe, léelo completo y actualízalo, no lo sobrescribas: los archivos md los gestiona solo el agente, pero no se pueden perder las aclaraciones anteriores.
• Idioma de prosa: según el CLAUDE.md del proyecto.
• Estructura (ejemplo: spcfctn/ui/internal-dashboard.md en job/vale/kylada): introducción con fuente y verificación (qué se leyó, fecha de exportación, cantidad de pantallas y textos), reglas de lectura de diseños, correspondencia de etiquetas UI con términos internos, pantallas en orden (filtros en orden del diseño, botón de lista, columnas, acciones en filas), preguntas abiertas.
• Todo lo que sea tu interpretación, no texto del diseño ni comentario, márcalo como inferred.
• Las reglas del proyecto para leer diseños (por ejemplo, que Select bajo el encabezado de columna es control de ordenación) tómalas del CLAUDE.md del proyecto y aplícalas, no las inventes.

Paso 4 — comentarios mediante MCP por enlace

Los comentarios no están en el .fig (verificado): permanecen en el servidor de Figma.

• Se necesita un enlace al archivo en Figma (con o sin node-id). Si no lo hay, pídelo al usuario.
• Utiliza únicamente la herramienta MCP comments del servidor MCP de Figma que esté conectado en el proyecto (toma el nombre de la lista de servidores conectados); el parámetro file es el enlace. Si no existe tal herramienta, indícaselo al usuario. El oficial figma-cs no devuelve comentarios; no invoques REST directamente con token ni toques .env.
• La invocación sin node_id devuelve todos los comentarios del archivo por hilos (número, fecha, estado, nodo @id, texto, respuestas). No llames refresh innecesariamente. El endpoint de comentarios se cuenta por separado de la lectura del archivo y funciona incluso cuando la lectura devolvió 429.
• Vinculación a la pantalla:
  • Si @id coincide con el id de la pantalla en screens.json, la pantalla está determinada.
  • Si @id es de sección o página, la pantalla se determina por geometría; para ello se necesitan node_id y node_offset del comentario. Compón líneas CLAVE NODO X Y (por ejemplo, #144 979:3 500 5471) y pásalas como entrada: python3 ~/.claude/skills/analyze-fig/scripts/place.py spcfctn/ui/draft/<nombre> < líneas. Salida: clave, sección, pantalla; o la razón y la pantalla más cercana si el punto no está en una pantalla.
  • Verifica la salida: la herramienta comments puede no imprimir node_offset (así era en el momento de creación de la skill). En ese caso, los comentarios de sección o página no se pueden ubicar con exactitud: no adivines la pantalla por el texto; asígnalos a la sección, marca pantalla no determinada e indica al usuario que se necesita el desplazamiento del comentario para ubicarlos.
• Las respuestas (↳) pertenecen al hilo del padre.

Paso 5 — verificar que los comentarios coincidan con el archivo

Para cada comentario con pantalla determinada (y para el grupo de comentarios de sección), verifica:

• Si los campos, columnas, botones, valores nombrados en el comentario están entre las capas de texto de esa pantalla (Amount of integrated services ↔ columna Services; citas entre comillas; listas de valores).
• Si el comentario no contradice el diseño (cantidad de columnas, orden, tipo de elemento, «hay filtro» / «no hay»).
• Fecha: si el comentario es más reciente que exported_at de meta.json, la exportación está desactualizada. En ese caso, pide una exportación nueva en spcfctn/ui/draft/.
• Si el nodo del comentario no está en el archivo (eliminado o renombrado), es un comentario huérfano.
• Comentario sin pantalla y sin contenido reconocible.

Resume las discrepancias en una tabla pequeña (número #N, pantalla, en qué consiste la discrepancia) y pregunta al usuario qué es lo correcto: no corrijas en silencio ni elijas tú entre el diseño y el comentario. Hasta recibir respuesta, márcalos en el md como conflict.

Paso 6 — escribir el resumen

• En el md, añade una sección con los comentarios del autor: resumen (qué aclaran) y todos los comentarios por pantalla con números #N. Cuando un comentario precise algo que era inferred, corrige el registro e indica el comentario.
• Actualiza «Verification» en la introducción: qué se leyó (.fig, versión, fecha de exportación, textos, rásteres, comentarios, fecha de obtención) y qué no está cubierto.
• Preguntas abiertas: como lista separada; las respuestas del usuario pásalas a «Resolved».
• No hagas commit sin que te lo pidan. Verbalmente (en español) resume: cuántas secciones, pantallas, comentarios, cuántas discrepancias y qué es necesario aclarar.

Qué no hacer

• No invoques la REST de Figma con token, no leas ni edites .env.
• No leas código ajeno (decodificadores kiwi, etc.): el formato ya está implementado en scripts/.
• No pongas el .fig ni el análisis (todo bajo draft/) en git.
• No adivines la pantalla de un comentario por las palabras, ni el contenido del diseño por la imagen cuando hay capas de texto.