EugineKosenko/majordom

analyze-fig

Analyse de l'export Figma (.fig) sans appel à l'API Figma : l'arborescence des nœuds, les textes et les rasters sont lus à partir du fichier lui-même, tandis que les commentaires de l'auteur, absents du .fig, sont récupérés séparément via MCP par lien. Le résultat est constitué de fichiers Markdown dans spcfctn/ui/, que l'on utilise ensuite au lieu de relire Figma.

Quand ne pas exécuter

Les questions sur une maquette déjà analysée (« qu'indique le commentaire du filtre… », « quelles colonnes dans l'écran… ») se résolvent en lisant spcfctn/ui/*.md, pas avec cette compétence. L'analyse est nécessaire pour un nouveau .fig ou un .fig mis à jour, ou lorsque la réponse manque dans le md (voir spcfctn-code.md).

Répertoires (répertoire unique de brouillons draft, hors git)

• spcfctn/ui/draft/ — le .fig d'entrée (et tout autre brouillon). Le fichier est placé par l'utilisateur.
• spcfctn/ui/draft/<nom>/ — résultat de la décompression : message.json (tous les nœuds), meta.json, images/, screens.json et screens.txt, ainsi que les commentaires collectés (comments.json). Régénéré à partir du .fig, non versionné dans git. Pas de raw/ ni de data/ séparés (modeling.md).
• spcfctn/ui/*.md — résultat de l'analyse ; seul cela reste dans git.

<nom> est le nom du fichier sans extension, en minuscules avec des tirets (internal-interfaces).

Étape 0 — préparation

• Trouve le répertoire spcfctn/ du projet. S'il n'existe pas, demande à l'utilisateur de le créer (spcfctn-code.md). Crée toi-même l'artefact ui/ et son sous-répertoire draft/.
• Vérifie spcfctn/ui/.gitignore (dépôt de l'artefact) : il doit contenir draft (voir modeling.md) ; ajoute ce qui manque via gitignore.org.
• Fichier Fig : son nom est fourni par l'utilisateur ; s'il n'est pas précisé, affiche spcfctn/ui/draft/*.fig et demande.
• Lis le CLAUDE.md du projet (langue de la prose, conventions) ainsi que les spcfctn/ui/*.md existants : l'analyse doit poursuivre leur structure et leur terminologie, ne pas repartir de zéro.
• python3 et zstd doivent être dans le PATH.

Étape 1 — décompresser et décoder

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

Affiche la version du format, le nombre de nœuds, blobs et images. Le script a été testé sur la version 106 ; sur une autre version ou en cas d'erreur, ne devine pas le format et ne lis pas d'autres décodeurs, informe l'utilisateur. meta.json contient exported_at : l'heure d'export sera utile à l'étape 5. message.json est volumineux, ne l'imprime pas directement.

Étape 2 — découper en sections et écrans

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

Affiche la liste des pages, sections (cadres de premier niveau) et écrans (leurs enfants) avec le nombre de textes et de rasters. L'essentiel est dans screens.txt : pour chaque écran, les calques de texte regroupés en lignes de haut en bas et de gauche à droite (ainsi sont lus les filtres, les en-têtes de colonnes et les boutons), ainsi que les références aux rasters.

• Compare les quantités avec les valeurs attendues (par exemple, l'ancien md) ; un écart est une raison de s'arrêter.
• Les calques de texte ne voient pas les éléments sans texte (icônes nues) ni le contenu des rasters. Pour chaque raster dans images/, ouvre le fichier (Read) et décris ce qui manque dans les calques de texte ; précise qu'il s'agit d'une lecture depuis l'image. L'arborescence et les textes sont la preuve principale, les images un complément.
• Les instances de composants (INSTANCE) peuvent avoir des textes redéfinis que le script ne voit pas ; screens.txt en avertit.

Étape 3 — écrire spcfctn/ui/*.md

• Un md par section (ou par fichier lorsqu'il n'y a qu'une seule section). Si le fichier existe déjà, lis-le entièrement et mets-le à jour, ne le réécris pas : les fichiers md sont gérés uniquement par l'agent, mais les précisions précédentes ne doivent pas être perdues.
• La langue de la prose suit le CLAUDE.md du projet.
• Structure (exemple : spcfctn/ui/internal-dashboard.md dans job/vale/kylada) : introduction avec la source et la vérification (ce qui a été lu, date d'export, nombre d'écrans et de textes), règles de lecture des maquettes, correspondance des libellés UI avec les termes internes, écrans dans l'ordre (filtres dans l'ordre de la maquette, bouton de liste, colonnes, actions dans les lignes), questions ouvertes.
• Tout ce qui relève de ton interprétation, et non du texte de la maquette ou d'un commentaire, est marqué inferred.
• Les règles de lecture des maquettes du projet (par exemple, que Select sous un en-tête de colonne est le contrôle de tri) proviennent du CLAUDE.md du projet et sont appliquées, non inventées.

Étape 4 — commentaires via MCP par lien

Les commentaires ne sont pas dans le fichier .fig (vérifié) : ils restent sur le serveur Figma.

• Un lien vers le fichier Figma (avec ou sans node-id) est nécessaire. S'il n'est pas fourni, demande-le à l'utilisateur.
• Utilise uniquement l'outil MCP comments du serveur MCP Figma connecté au projet (le nom est à prendre dans la liste des serveurs connectés) ; le paramètre file est le lien. Si cet outil n'existe pas, informe l'utilisateur. Le serveur officiel figma-cs ne fournit pas les commentaires ; n'appelle pas directement l'API REST avec un token et ne modifie pas .env.
• Un appel sans node_id renvoie tous les commentaires du fichier par branche (numéro, date, état, nœud @id, texte, réponses). Ne lance pas refresh inutilement. Le point de terminaison des commentaires est compté séparément de la lecture du fichier et fonctionne même si la lecture a retourné 429.
• Liaison à l'écran :
  • Si @id correspond à l'ID d'un écran dans screens.json, l'écran est identifié.
  • Si @id est celui d'une section ou d'une page, l'écran est déterminé par géométrie ; pour cela, node_id et node_offset du commentaire sont nécessaires. Construis des lignes CLÉ NŒUD X Y (par exemple, #144 979:3 500 5471) et passe-les en entrée : python3 ~/.claude/skills/analyze-fig/scripts/place.py spcfctn/ui/draft/<nom> < lignes. La sortie donne la clé, la section, l'écran ; ou la raison et l'écran le plus proche si le point n'est pas sur un écran.
  • Vérifie la sortie : l'outil comments peut ne pas afficher node_offset (c'était le cas au moment de la création de la compétence). Dans ce cas, les commentaires liés à une section ou une page ne peuvent pas être attribués précisément : ne devine pas l'écran d'après le texte, rattache-les à la section, marque écran non déterminé et informe l'utilisateur que le décalage du commentaire est nécessaire pour l'attribution.
• Les réponses (↳) appartiennent à la branche du parent.

Étape 5 — vérifier que les commentaires correspondent au fichier

Pour chaque commentaire dont l'écran est déterminé (et pour le groupe de commentaires d'une section) :

• Vérifie que les champs, colonnes, boutons, valeurs nommés dans le commentaire se trouvent parmi les calques de texte de cet écran (Amount of integrated services ↔ colonne Services ; citations entre guillemets ; listes de valeurs).
• Vérifie que le commentaire ne contredit pas la maquette (nombre de colonnes, ordre, type d'élément, « il y a un filtre » / « non »).
• Date : si le commentaire est plus récent que exported_at dans meta.json, l'export est obsolète. Demande alors un nouvel export dans spcfctn/ui/draft/.
• Si le nœud du commentaire est absent du fichier (supprimé ou renommé), il s'agit d'un commentaire orphelin.
• Commentaire sans écran ni contenu reconnaissable.

Regroupe les divergences dans un petit tableau (numéro #N, écran, nature de la divergence) et demande à l'utilisateur ce qui est correct : ne corrige pas silencieusement et ne choisis pas toi-même entre la maquette et le commentaire. En attendant la réponse, marque-les dans le md comme conflict.

Étape 6 — écrire le résumé

• Ajoute dans le md une section avec les commentaires de l'auteur : un résumé (ce qu'ils clarifient) et tous les commentaires par écran avec les numéros #N. Lorsqu'un commentaire précise ce qui était inferred, corrige l'entrée et référence le commentaire.
• Mets à jour la section « Verification » de l'introduction : ce qui a été lu (.fig, version, date d'export, textes, rasters, commentaires, date de leur récupération) et ce qui n'est pas couvert.
• Questions ouvertes — sous forme de liste séparée ; les réponses de l'utilisateur sont déplacées dans « Resolved ».
• Ne commit rien sans demande. Résume oralement (en français) : combien de sections, d'écrans, de commentaires, combien de divergences et ce qui doit être clarifié.

Ce qu'il ne faut pas faire

• N'appelle pas l'API REST Figma avec un token, ne lis ni ne modifie .env.
• Ne lis pas de code externe (décodeurs kiwi, etc.) : le format est déjà implémenté dans scripts/.
• Ne place pas le .fig ni l'analyse (tout ce qui se trouve sous draft/) dans git.
• Ne devine pas l'écran d'un commentaire d'après le texte, ni le contenu de la maquette d'après une image quand des calques de texte existent.