Installation du plugin : Avant les commandes de configuration ou de fraîcheur, suivez les règles d'exécution du plugin lorsque ce skill se trouve dans un plugin HyperFrames. Pour les installations autonomes, gardez les instructions de mise à jour ci-dessous.
Tout d'abord, maintenez ce skill à jour — confirmez avec l'utilisateur avant d'exécuter :
npx hyperframes skills update figma. Une opération rapide sans effet si tout est à jour ; sinon, cela rafraîchit ce skill ainsi que les skills de domaine principaux dont il dépend avant de vous y fier.
Figma → HyperFrames
Importez le travail Figma de l'utilisateur dans une composition. Réparti par capacité (spécification de conception §2) :
| Phase | Quoi | Transport | Surface |
|---|---|---|---|
| 1 | Assets statiques | REST | hyperframes figma asset |
| 2 | Tokens/styles de marque | REST | hyperframes figma tokens |
| 3 | Composants → HTML | REST | hyperframes figma component |
| 4 | Mouvement → GSAP | connecteur si disponible | utiliser son contexte de mouvement |
| 5 | Shaders | connecteur / export manuel | l'utiliser ou une exportation native |
REST est utilisé partout où c'est possible (utilisable en volume, sans tête). Un connecteur Figma compatible est optionnel pour les données de mouvement et de shader ; sans lui, demandez une exportation native. Chaque chemin gèle les assets localement pour que les rendus restent déterministes. Les reconstitutions de storyboard composent les exports d'assets de Phase 1 (REST) avec un assemblage de chronologie piloté par l'agent — aucun connecteur nécessaire. Les assets gelés existants, les enregistrements de manifeste et les liaisons ne sont pas affectés par les changements de routage — la répartition change uniquement les identifiants que la prochaine importation utilise.
Auth — deux identifiants, limités
Pré-vol — avant le premier appel CLI, vérifiez qu'un token existe : variable d'environnement shell ([ -n "$FIGMA_TOKEN" ]) ou le fichier .env du projet (le CLI le charge automatiquement — une entrée .env compte comme configurée). Si aucun des deux, n'exécutez PAS la commande pour récolter l'erreur — guidez d'abord l'utilisateur dans la configuration unique, puis arrêtez-vous et attendez :
- figma.com/settings → Security → Personal access tokens → Générer un nouveau token.
- Périmètres — la lecture seule est tout ce dont cette intégration a jamais besoin (elle n'écrit jamais dans Figma) : File content: Read-only + File metadata: Read-only. Ajoutez Library content: Read-only si vous exécutez
tokenssur un plan non-Enterprise — le repli sur les styles publiés frappe/v1/files/:key/styles, qui retourne 403 sans cela (un périmètre que le texte d'installation plus ancien omettait). Optionnellement Variables: Read-only pour les variables de marque — réservé à Enterprise ; sans cela,tokensse dégrade automatiquement vers les styles publiés (attendu, pas une erreur — dites-le). Un 403 nomme désormais le périmètre manquant exact ; les 429 sont réessayés automatiquement (limite par minute, respecteRetry-After). - Demandez à l'utilisateur de définir
FIGMA_TOKENdans son profil shell ou le fichier.envdu projet ; ne lui demandez jamais de coller le token dans la conversation.
Lors de l'intégration, fixez également les attentes d'un seul souffle : chaque importation atterrit comme un fichier gelé local avec provenance enregistrée — les rendus n'appellent jamais Figma, ré-exécuter une commande réimporte uniquement ce qui a changé dans Figma, et un token fonctionne pour les assets, les tokens de marque et les composants sur tous les fichiers que leur compte Figma peut voir.
- Phases 4–5 (mouvement/shaders) : un connecteur Figma compatible, avec une autorisation séparée du token. S'il est indisponible ou non authentifié, demandez à l'utilisateur de le connecter ou de fournir une exportation native, puis arrêtez-vous.
- Dites exactement quel identifiant une phase défaillante nécessite — ne présentez jamais la répartition comme cassée.
BAD_TOKEN(401) en milieu de flux → le token est expiré/révoqué ; régénérez-le.FORBIDDEN(403) → le message nomme le périmètre manquant exact (p. ex.library_content:readpour le repli des styles) — ajoutez-le, ou le fichier n'est pas visible par le compte.REQUIRES_ENTERPRISE(403 sur les variables) → pas un échec : le repli des styles a déjà été exécuté.RATE_LIMITED(429) → le client a déjà réessayé avec backoff (cela s'applique à CHAQUE lecture — assets, tokens, styles, arbres de nœuds, versions — la tentative vit dans le chemin de requête partagé ;Retry-Afterest respecté, plafonné à 60s) ; s'il remonte toujours, attendez une minute ou importez moins de nœuds par appel.
Conscience des limites de débit (spécification §2.1) : les quotas du connecteur varient selon le plan Figma — regroupez les requêtes de frames parentes, sautez les captures d'écran de vérification sauf demande explicite, et mettez en cache les réponses brutes pour que la re-dérivation n'utilise jamais un second appel. REST est par minute (10+/min, compartiments par endpoint) — bien en volume, ralentissez sur 429.
Routage
Analysez le lien figma de l'utilisateur avec parseFigmaRef (URL, fileKey:nodeId, fileKey nu). Ensuite, selon l'intention :
- "utiliser ce calque / logo / image" → Asset (CLI)
- "récupérer ma marque / mes couleurs / mes tokens" → Tokens (CLI)
- "construire une scène à partir de cette frame" → Component (CLI)
- "importer cette animation / ce mouvement" → Motion (connecteur si disponible, ci-dessous)
- une section de storyboard / filmstrip de frames de scène → Storyboard (ci-dessous)
- remplissage/effet shader → Shaders (ci-dessous)
Racontez chaque étape à l'utilisateur — avant chaque commande, dites ce que vous allez extraire de Figma ; après, dites où l'artefact a atterri (le chemin gelé / sidecar / dossier du composant), ce qui a changé dans la composition, et l'action immédiate suivante (aperçu, ajouter des variables imprimées, réimporter pour lier les liaisons). L'utilisateur ne devrait jamais avoir à demander "ça a marché ?" ou "et maintenant ?".
Assets (Phase 1 — CLI)
hyperframes figma asset '<url-or-fileKey:nodeId>' [autre refs…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
Rend via REST, assainit le SVG, gèle sous .media/images/, ajoute le manifeste avec provenance, régénère .media/index.md (l'inventaire partagé des utilisations de médias), imprime un extrait <img>. Idempotent par fileKey:nodeId:format:scale:version. Préférez SVG pour les vecteurs/logos (évolutif, animable), PNG --scale 2 pour la fidélité raster. Passez toujours --description "<ce que c'est>" (cela devient la ligne d'index + l'attribut <img alt>) ; ajoutez --entity "<nom>" pour les marques nommées afin que la résolution resolve --entity du système de gestion des médias les retrouve plus tard (les correspondances d'entités fonctionnent sur toute image/icône).
Traitez plusieurs nœuds en UNE SEULE requête — passez plusieurs références (séparées par des espaces ou des virgules) du MÊME fichier : hyperframes figma asset 'KEY:1-2' 'KEY:3-4' 'KEY:5-6'. Tous sont rendus en un seul appel /v1/images, ce qui est la réponse de Figma à la limite de débit par minute — préférez-le à N commandes séparées lors de l'extraction d'un ensemble complet d'assets d'une frame. --description/--entity s'appliquent à chaque nœud du lot, donc regroupez les nœuds partageant un objectif. Les 429 sont également réessayés automatiquement avec backoff, indépendamment du format.
Tokens (Phase 2 — CLI)
hyperframes figma tokens <fileKey>
Importe les variables comme entrées de variable de marque de composition + sidecar figma-tokens.json + enregistrements d'index de liaison (.media/figma-bindings.jsonl). Les variables sont limitées à Enterprise côté amont : sur d'autres plans, la commande se dégrade vers les métadonnées de style publié (les valeurs sont résolues au moment de l'importation du composant). Ajoutez les entrées imprimées aux data-composition-variables de la composition.
Importez les tokens avant les composants lorsque les deux sont souhaités — cela permet aux couleurs des composants de se lier aux variables de marque plutôt que de créer des doublons.
Chemin des variables non-Enterprise (testé sur le terrain) : les variables REST sont limitées à Enterprise, mais un connecteur compatible peut fournir des définitions de variables. Lorsque tokens signale REQUIRES_ENTERPRISE et que le connecteur est disponible, récupérez les variables de la scène parente une fois, mettez en cache la réponse brute dans .media/figma-cache/, et utilisez-la pour construire l'index de liaison. Le boundVariables de l'arbre de nœuds REST fournit des VariableID par propriété ; joignez-les par nœud et propriété, puis écrivez des lignes .media/figma-bindings.jsonl ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<nom>", version}) plus les entrées de variable de composition. Tout ce qui suit (résolution var() du composant, rafraîchissement, variables CSS d'exécution) est le mécanisme expédié. Étiquetez-le pour l'utilisateur : "tokens via le connecteur Figma — les plans Enterprise obtiennent cela directement depuis hyperframes figma tokens."
Le runtime définit chaque variable de composition déclarée comme une propriété personnalisée CSS (racine du document + hôtes des sous-composants), donc l'importation de var(--slug, littéral) remplit la recoloration lorsque la valeur par défaut de la variable change — mettre à jour une valeur dans data-composition-variables rebrandit chaque composant importé sans réimporter quoi que ce soit. hyperframes render --variables '<json>' les écrase au moment du rendu.
Composants (Phase 3 — CLI)
hyperframes figma component '<url-or-fileKey:nodeId>'
Arbre de nœuds → HTML modifiable aux dimensions exactes de Figma, empaqueté comme élément de registre sous compositions/components/<nom>/. Les vecteurs/opérations booléennes sont automatiquement pixellisés via l'exportation Phase 1. Passe de liaison (spécification §7.1, ID exact uniquement — jamais de correspondance de valeur) :
- Auto-vérification de la fidélité statique (obligatoire pour le contenu héros) : après l'importation, rendez le fragment et comparez-le aux propres pixels de Figma —
figma asset <même node> --format pngest la vérité terrain. Le texte est l'axe de dérive connu : une zone de texte Figma plus courte que sa hauteur de ligne a des limites verticalement rognées (le mapper émettext-box-trimpour celles-ci ; la dérive mesurée sans cela était d'environ 6px sur une police de 70px). Si la comparaison montre une dérive que le mapper ne couvre pas, signalez-la — ne modifiez pas le fragment manuellement en silence. - Remplissage lié à un token importé →
var(--slug, #littéral)— la mise à jour de la marque se propage. - Lié à un token inconnu → littéral + indicateur
data-figma-unresolved. La commande vous le dit ; proposez à l'utilisateur : exécuteztokenssur le fichier source (ou bibliothèque), puis réimportez le composant pour les lier. Demandez une fois par bibliothèque inconnue quel fichier c'est — ne devinez jamais, ne correspondez jamais par hexadécimal.
Mouvement (Phase 4 — assisté par connecteur)
Balise d'utilisation : Les phases assistées par connecteur n'ont pas de point de contact CLI, donc déclenchez la balise de skill au début et à la fin (anonyme, consentement requis, jamais d'échec) : npx hyperframes events --skill=figma-motion lorsque vous commencez, npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error lorsque vous terminez. Idem pour les shaders (figma-shaders) et les storyboards (figma-storyboard).
Aucun équivalent REST n'existe. Lorsqu'un connecteur compatible est disponible, utilisez-le et transmettez sa sortie aux assistants purs de @hyperframes/core/figma ; sinon, demandez une exportation native :
- Récupérez le contexte de mouvement pour la frame parente en une seule requête récursive, pas une requête par élément. Sauvegardez le JSON brut à côté du projet (
.media/figma-cache/) afin que la retraduction soit gratuite. - Normalisez en
MotionDocavecmotionContextToDocs(rawResponse, { selectorFor, repeat })de@hyperframes/core/figma— ne transcrivez jamais les numéros d'image clé à la main. L'assistant encode les règles de décodage testées sur le terrain mécaniquement : il analyse les extraits motion.dev (l'encodage fiable — les extraits CSS étirent les durées et peuvent être en désaccord ; ils sont ignorés), supprime les images clés de fin de boucle (les segments sub-millisecondes à des temps ≈0.9999→1 sont la réinitialisation instantanée de la boucle, pas un mouvement créé — la boucle est réalisée par le redémarragerepeat), et préserve les courbes bezier verbatim.selectorFordoit retourner les IDs de l'importation du composant Phase 3 — ne dérivez pas les sélecteurs des noms de nœuds. 2b. Validez par rapport à la vérité terrain avant de déclarer terminé — obligatoire : exportez la frame racine de la cohorte via le connecteur disponible et exécuteznode <SKILL_DIR>/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop LxH+X+Y— il compare les deltas d'énergie du mouvement (la fidélité d'importation statique s'annule) et échoue en dessous de 15 dB de PSNR minimal de mouvement (calibré : fidèle ≈ 20+, divergent ≈ 5). Mesurez--cropà partir des bords réels de la carte dans le rendu, ne devinez pas. ÉCHEC signifie revérifier la traduction, pas le seuil. motionToGsap(doc)→emitTimelineScript(spec)→ injectez comme<script>après les balises CDN GSAP + CustomEase. En pause, fini, enregistré surwindow.__timelinesavec une clé littérale.- Piste intraduisible (pilotée par shader, propriété non prise en charge, masques complexes) → exportez via le connecteur, gelez le MP4, puis intégrez-le comme
<video class="clip">. Exception : les pistes pilotées par shader — le chemin d'exportation de Figma aplatit les shaders en couleur de base (voir Shaders ci-dessous), donc une cuisson là-bas perd silencieusement le shader ; demandez à l'utilisateur une exportation Figma native à la place. Dites toujours quel chemin vous avez utilisé et pourquoi. Les easings nommés en dehors de l'ensemble mappé tombent en linéaire — la table de mappage vit dansmotionEase.ts; signalez le repli à l'utilisateur lorsqu'il se déclenche. - Exécutez
npx hyperframes checkavant de déclarer terminé.
Shaders (Phase 5 — principalement manuelle)
Le chemin de rendu du connecteur Figma n'exécute pas les shaders (ils sont aplatis en couleur de base), et la source du shader n'est accessible que pour les styles publiés en bibliothèque (siège complet payant). Chemin par défaut : demandez à l'utilisateur d'exporter la frame du shader nativement dans Figma (PNG ou Motion MP4), puis importez-la comme asset de Phase 1 / clip. N'essayez pas la capture pixel du connecteur d'un shader — elle produira silencieusement la mauvaise chose.
Storyboards (une SECTION de frames de scène → animation)
La règle cardinale : les frames de storyboard sont des IMAGES CLÉS, pas des diapositives. Deux frames contenant le même élément décrivent l'état de cet élément dans le temps — animez l'ÉLÉMENT entre les états ; ne jouez jamais les frames comme une séquence d'images fixes. Un logo dessiné dans quatre frames consécutives à un y décroissant est UN élément montant à travers quatre images clés. Jouer les frames de storyboard dos à dos est le mode d'échec ; reconstruire les chronologies des éléments qu'elles impliquent est le travail.
Les fichiers de storyboard suivent une grammaire que vous pouvez analyser mécaniquement — ne regardez pas à l'œil, décodez :
- Unités de scène : à l'intérieur de la SECTION, chaque nœud de la taille d'une frame est une scène — à la fois les FRAMEs nommées et les RECTANGLEs pleine frame lâches (les designers collent des images fixes directement dans la section). Filtrez par taille (≈ aspect de la composition, p. ex. >1400×900), pas par type de nœud ou nom.
- Ordre = position x (principalement par ligne si la bande s'enroule). Triez les scènes par
absoluteBoundingBox.x. - Différence entre adjacentes : pour chaque paire de scènes, exécutez la comparaison visuelle via le connecteur ou un pixel diff côté client (numérique : différences de bords de boîtes Englober, changements de position, apparitions/disparitions). À partir de là, déduisez quels éléments sont les mêmes entre les scènes (par nom de nœud, par chemin dans l'arbre, par forme — jamais seulement par position), puis émettez une chronologie qui anime ces éléments entre leurs états.
- Aucune durcissement des valeurs : ne générez pas de chronologie qui anime chaque élément séparément. Au lieu de cela, créez une chronologie maître avec des plages par scène, et au sein de chaque plage, animez uniquement les propriétés qui changent par rapport à l'état précédent. Les propriétés inchangées sont laissées comme elles sont (héritées de l'importation du composant Phase 3). Si un élément n'apparaît pas dans une scène, fondez-le/hors dans la transition.
- Durée : par défaut, chaque plage de scène dure 2 secondes, avec un chevauchement de 0,3 s pour la transition. Si l'utilisateur spécifie un timing différent, utilisez-le, mais ne demandez pas.
Après la construction, exportez le rendu MP4 et montrez-le à l'utilisateur ; s'il n'est pas satisfait, itérez sur les chronologies plutôt que de réimporter les données brutes.
Respondre aux échecs (tout chemin)
- L'importation renvoie zéro résultat → cadres ou calques non visibles dans le fichier. Demandez la permission d'ajuster les limites d'exportation ou de déverrouiller les calques.
FETCH_ERROR/ timeout → le service Figma est temporairement indisponible. Proposez de réessayer après avoir exécuténpx hyperframes check.- Le composant s'affiche vide → soit un calque racine transparent sans fond de remplissage, soit un cadre sans largeur/hauteur visible. Demandez à l'utilisateur de vérifier dans l'éditeur Figma.
- Le chemin du connecteur est introuvable ou ne répond pas → dites que le mouvement/les shaders ne peuvent pas être importés électroniquement pour l'instant, demandez une exportation native Figma, et dites à l'utilisateur que les phases 1 à 3 restent entièrement disponibles via l'API REST immédiatement.