bdsanxz/figma-access

Figma access

Vous travaillez avec Figma via un seul outil en ligne de commande. Il affiche les données au format KDL et enregistre ses fichiers de données en .kdl : un nœud par ligne, avec les champs simples d'un nœud comme key=value sur cette ligne, de sorte que grep, awk et sed fonctionnent directement dessus. Les exceptions sont spec, qui affiche son propre plan textuel (une ligne par nœud), daemon log, qui affiche les lignes de journal du démon telles qu'elles apparaissent, et render, screenshot, image-fills et compare, qui enregistrent des fichiers image (leur résumé sur stdout est toujours en KDL). Il fonctionne selon deux modes :

• REST (file, node, spec, render, image-fills, api) : lit tout fichier à partir de son URL avec le jeton de l'utilisateur. Rien ne doit être ouvert. Les lectures sont mises en cache localement et réessayées en cas de limite de débit.
• Plugin (exec, screenshot, selection, logs, changes, call) : un démon en arrière-plan communique avec le plugin Desktop Bridge exécuté dans Figma Desktop. C'est le seul moyen de modifier un fichier. Votre outil principal ici est exec, qui exécute du code JavaScript de l'API Plugin Figma dans le fichier.

references/tips.md contient des leçons tirées d'exécutions réelles, organisées par situation. Ce sont des conseils, pas des règles : lisez la section correspondant à votre situation et adaptez-la à votre cas.

Règles

• Ne montrez jamais le jeton. N'affichez pas, n'écho pas et ne journalisez pas le jeton ; testez-le avec figma-access api /v1/me.
• Regardez avant et après chaque modification. Jugez tout résultat visible sur une image, pas sur le code qui l'a produite.
• Lisez les valeurs, ne les devinez pas ; le rendu décide. Prenez les couleurs, tailles, espacements, polices et textes depuis le fichier, jamais à l'œil depuis une image. Lorsque les données du fichier et le rendu divergent, le rendu est ce que l'utilisateur voit.
• Modifiez uniquement ce que l'utilisateur a demandé. La lecture est toujours acceptable. Ne supprimez ni n'écrasez le travail existant de l'utilisateur, sauf si la demande le spécifie.
• Un délai d'attente n'est pas un échec. Figma ne peut pas arrêter un script en cours d'exécution ; vérifiez les logs et le fichier avant de le relancer.

Flux de travail

1. Configuration

1. <skill> est le répertoire de ce SKILL.md. Exécutez l'outil ainsi : bun <skill>/scripts/figma-access.js COMMANDE ... ; ce fichier écrit figma-access COMMANDE .... Il fonctionne avec Bun, pas Node : lancez-le toujours avec bun, jamais node, et exécutez tout script d'assistance JavaScript ou TypeScript que vous écrivez également avec bun. Pour raccourcir la commande, définissez une fonction shell au début de chaque appel shell (fa(){ bun <skill>/scripts/figma-access.js "$@"; }; fa ...), pas une variable : zsh ne divise pas une variable en mots. Mettez chaque URL et identifiant de nœud entre guillemets : ?, & et ; sont spéciaux pour le shell. Si bun est manquant, dites à l'utilisateur de l'installer depuis https://bun.sh et arrêtez-vous.
2. Exécutez figma-access --help une fois, et figma-access <commande> --help avant la première utilisation de chaque commande. Codes de sortie : 0 ok, 1 Figma a signalé un échec, 2 mauvais arguments, 3 démon, plugin ou jeton non disponible. « Lire la sortie » dans references/tips.md explique le format et comment la rechercher.
3. Choisissez le chemin selon la demande, comme décrit dans « Choisir un chemin » dans references/tips.md : une URL et un travail en lecture seule → REST ; toute modification du fichier → plugin ; les deux peuvent être utilisés ensemble.

2a. Connexion via REST

1. Exécutez figma-access api /v1/me. Si « pas de jeton » : trouvez où l'utilisateur l'a défini et chargez-le dans la même commande, comme décrit dans « Jeton » dans references/tips.md. Demandez un jeton à l'utilisateur (Figma : Paramètres > Sécurité > Jetons d'accès personnels, lecture du contenu du fichier) uniquement lorsqu'aucun n'est défini nulle part.
2. Exécutez figma-access file <url> pour voir les pages et les cadres de premier niveau. Choisissez le nœud sur lequel travailler, en suivant « Trouver le bon nœud » dans references/tips.md.

2b. Connexion via le plugin

1. Exécutez figma-access status. Il démarre le démon si nécessaire.
   • Fichiers listés : continuez.
   • Aucun fichier : exécutez figma-access files, qui attend le plugin. S'il se termine avec le code 3, exécutez figma-access setup et donnez à l'utilisateur ses étapes en mots simples : importez le plugin une fois depuis le chemin du manifeste affiché, puis exécutez Plugins > Développement > Figma Desktop Bridge dans le fichier et gardez sa fenêtre ouverte. Demandez à l'utilisateur de vous dire quand il est en cours d'exécution, puis exécutez à nouveau figma-access files.
2. Plus d'un fichier connecté : passez --file <fileKey> sur chaque commande après celle-ci.

3. Comprendre la conception

1. Lisez la vue la plus petite qui répond à la question, d'abord le plan général et les détails uniquement là où vous travaillez :
   • structure : figma-access node <url|key> <id> --outline 2 (REST), ou la recette de plan de page dans references/plugin-api.md (plugin) ;
   • tout ce dont le code a besoin, une ligne par nœud visible : figma-access spec <url|key> <id> -o <fichier> ; pour un grand cadre, enregistrez-le une fois avec node ... -o <fichier> et passez --from <fichier> à chaque spec ultérieur, comme décrit dans « Limites de débit et cache » dans references/tips.md ;
   • ce que l'utilisateur entend par « ceci » ou « la sélection » : figma-access selection ;
   • à quoi cela ressemble : figma-access render <key> <id> (REST, taille exacte) ou figma-access screenshot <id> (plugin), puis ouvrez l'image.
2. Lisez les rapports de node : polices, remplissages d'image et combien de couches masquées ont été élaguées. Lisez « Couches masquées » et « Lire une image de conception » dans references/tips.md.
3. Pour les composants, variantes, variables et styles, lisez leur structure réelle avant de les modifier ou copier, et réutilisez ce qui existe plutôt que de créer des doublons.

4. Effectuer le travail

Implémenter une conception en code. Avant d'écrire du code, lisez « De la conception au code » dans references/tips.md : la plupart des différences qui subsistent après une première construction (recadrages d'image, polices, décalages de texte, largeur de page) y sont couvertes. Écrivez le code là où l'utilisateur ou son projet indique qu'il doit se trouver (le chemin qu'il nomme, ou la structure du projet lui-même) ; _swe/figma-access/ ne contient que des artefacts de travail tels que des rendus, des fichiers de nœuds enregistrés, des specs, des captures d'écran et des scripts.

1. Rendre le cadre à l'échelle 1 comme référence, et lisez-le par parties s'il est grand.
2. Écrivez la spec du cadre dans un fichier, avec --origin au coin où le contenu de la page commence, et prenez chaque valeur de celui-ci. Rendez les images, et ce qui est marqué ICON ou MASKED, au lieu de les reconstruire. Construisez les cadres à mise en page automatique à partir de la direction, de l'espacement, du remplissage et du dimensionnement que spec imprime plutôt qu'à partir de leurs boîtes stockées, et placez les enfants des groupes et des cadres sans mise en page automatique à leurs boîtes. Ne positionnez pas chaque nœud de manière absolue à sa boîte stockée, à la main ou avec un générateur : cette page copie chaque boîte obsolète, se casse lorsqu'un texte est plus long et ne peut pas s'adapter à la fenêtre. Vérifiez chaque partie marquée LAYOUT DRIFT par rapport au rendu.
3. Listez les polices avec chaque poids ; cherchez dans le projet les fichiers de toute famille qui n'est pas publique, et demandez à l'utilisateur, en un seul message, celles qui manquent encore, et tout ce que vous ne pouvez pas obtenir du fichier. En attendant, ou lorsque vous ne pouvez pas demander, utilisez un substitut et dites-le.
4. Laissez de côté le chrome de l'appareil ou du navigateur, et laissez la page s'adapter à la fenêtre : la largeur du cadre est l'écran pour lequel il a été dessiné, donc les arrière-plans et les séparateurs couvrent la fenêtre et la colonne de contenu est centrée, sauf si l'utilisateur demande une largeur fixe.
5. Construisez section par section, puis mesurez la page par rapport à la référence avec figma-access compare <reference.png> <page> --nodes <fichier nœud> --wide <px> : il capture la page, affiche les pixels différents par section du cadre avec le décalage qui explique chacun, la distance de chaque style de texte et nœud par rapport à leur position, et ceux qui manquent, écrit une image de différence et vérifie une fenêtre plus large. Avec --nodes, il prend les sections des propres enfants du cadre et recadre une référence que l'ombre du cadre a élargie. Regardez aussi la capture et l'image de différence, et répétez jusqu'à ce que chaque section corresponde. Lorsque l'utilisateur demande un résultat pixel-perfect ou 1:1 et qu'une compétence pour cela est listée dans votre session, utilisez-la avec ces rendus comme images de conception.

Modifier le fichier. Via le plugin :

1. Écrivez la modification sous forme de code API Plugin et exécutez-la avec figma-access exec, en suivant references/plugin-api.md pour ce que l'API impose et pour le placement. Le code long va dans un fichier de travail (par exemple sous _swe/figma-access/) et s'exécute avec exec -f. Renvoyez toujours les ids dont vous avez besoin ensuite ; ajoutez --timeout 30s ou plus pour un travail long.
2. Pour les tâches couvertes par une routine de plugin prête à l'emploi (ensembles de composants, audits de lint et d'accessibilité, remplissages d'image, annotations, aides FigJam et Slides), utilisez figma-access call <METHODE> '<json>' ; figma-access methods <filtre> liste les paramètres.
3. Lisez la sortie à chaque fois : sur ok #false, corrigez la cause et supprimez le travail partiel avant de réessayer ; sur un warning sous resultAnalysis, vérifiez les ids et les noms ; pour la trace du script lui-même, figma-access logs --since 2m.
4. Prenez une capture d'écran de chaque nœud que vous avez créé ou modifié (--scale 2 pour les petits) et vérifiez-la par rapport à la demande. Corrigez et recapturez ; après trois tentatives qui manquent encore, dites à l'utilisateur ce qui reste et pourquoi.

« Travailler avec le plugin » dans references/tips.md couvre ce qui va généralement mal ici.

5. Rapport

Dites à l'utilisateur ce que vous avez lu ou modifié, avec les noms et ids des nœuds, ainsi que les chemins des rendus, captures d'écran et fichiers que vous avez écrits. Nommez tout ce que vous n'avez pas fait, chaque hypothèse que vous avez faite (une police de remplacement, une couche masquée ignorée, un chrome laissé de côté), et ce qui n'a pas été vérifié.

Dépannage

• « Limite de débit dépassée » (429) : la CLI a déjà attendu et réessayé. Suivez « Limites de débit et cache » dans references/tips.md, et attendez une minute avant la prochaine lecture importante.
• Code de sortie 3, aucun fichier connecté : le plugin ne s'exécute pas dans ce fichier, ou il cherche encore (il vérifie toutes les quelques secondes). Demandez à l'utilisateur de l'exécuter à nouveau. figma-access daemon log montre les connexions au fur et à mesure.
• Un autre outil utilise le même plugin (par exemple figma-console-mcp) : les deux fonctionnent côte à côte ; figma-access status montre si ce démon a le fichier.
• Comportement obsolète après une mise à jour de la compétence : exécutez à nouveau figma-access setup, demandez à l'utilisateur de réimporter le manifeste dans Figma, puis exécutez figma-access daemon restart.
• « Plugin déconnecté avant d'avoir répondu » : l'utilisateur a fermé le plugin ou le fichier, ou le plugin a été rechargé. Vérifiez le fichier avant de répéter la modification.