Installation du plugin : Avant les commandes de configuration ou de mise à jour, suivez les règles d'exécution du plugin lorsque cette compétence se trouve dans un plugin HyperFrames. Les installations autonomes conservent les instructions de mise à jour ci-dessous.
D'abord, maintenez cette compétence à 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 cette compétence ainsi que les compétences du domaine principal dont elle dépend avant de les utiliser.
Figma → HyperFrames
Importez le travail Figma de l'utilisateur dans une composition. Divisé par capacité (spécification de conception §2) :
| Phase | Quoi | Transport | Surface |
|---|---|---|---|
| 1 | Ressources statiques | REST | hyperframes figma asset |
| 2 | Jetons/styles de marque | REST | hyperframes figma tokens |
| 3 | Composants → HTML | REST | hyperframes figma component |
| 4 | Animation → GSAP | connecteur lorsqu'il est disponible | utiliser son contexte d'animation |
| 5 | Shaders | connecteur / exportation manuelle | l'utiliser ou une exportation native |
REST est utilisé partout où c'est possible (utilisable à volume, sans interface graphique). Un connecteur Figma compatible est facultatif pour les données d'animation et de shader ; sans celui-ci, demandez une exportation native. Chaque chemin fige les ressources localement afin que les rendus restent déterministes. Les reconstructions de storyboard composent les exportations de ressources de la Phase 1 (REST) avec un assemblage de chronologie piloté par l'agent — aucun connecteur nécessaire. Les ressources déjà figées, les enregistrements de manifeste et les liaisons ne sont pas affectés par les changements de routage — la division ne modifie que les identifiants que la prochaine importation utilisera.
Authentification — deux identifiants, limités
Vérification préalable — avant le premier appel CLI, vérifiez qu'un jeton existe : variable d'environnement shell ([ -n "$FIGMA_TOKEN" ]) ou le fichier .env du projet (la CLI le charge automatiquement — une entrée dans .env compte comme configuré). Si aucun des deux n'est présent, 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 → Sécurité → Jetons d'accès personnels → Générer un nouveau jeton.
- Portées — lecture seule est tout ce dont cette intégration a besoin (elle n'écrit jamais dans Figma) : Contenu du fichier : Lecture seule + Métadonnées du fichier : Lecture seule. Ajoutez Contenu de la bibliothèque : Lecture seule si vous exécutez
tokenssur un plan non Enterprise — la solution de secours des styles publiés atteint/v1/files/:key/styles, qui renvoie une erreur 403 sans cette portée (une portée que l'ancien texte de configuration omettait). Optionnellement Variables : Lecture seule pour les variables de marque — réservé à Enterprise ; sans cela,tokensdégrade automatiquement vers les styles publiés (attendu, pas une erreur — dites-le). Une erreur 403 indique désormais la portée exacte manquante ; 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 jeton dans la conversation.
Pendant l'intégration, définissez également les attentes en une phrase : chaque importation atterrit sous la forme d'un fichier local figé avec une 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 seul jeton fonctionne pour les ressources, les jetons de marque et les composants dans tous les fichiers que le compte Figma de l'utilisateur peut voir.
- Phases 4–5 (animation/shader) : un connecteur Figma compatible, avec une autorisation séparée du jeton. 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 division comme cassée.
BAD_TOKEN(401) en cours de route → le jeton a expiré/révoqué ; regénérez-le.FORBIDDEN(403) → le message nomme la portée exacte manquante (par exemplelibrary_content:readpour la solution de secours des styles) — ajoutez-la, ou le fichier n'est pas visible pour le compte.REQUIRES_ENTERPRISE(403 sur les variables) → pas une erreur : la solution de secours des styles a déjà été exécutée.RATE_LIMITED(429) → le client a déjà réessayé avec un backoff (cela s'applique à CHAQUE lecture — ressources, jetons, styles, arborescences de nœuds, versions — la nouvelle tentative réside dans le chemin de requête partagé ;Retry-Afterest respecté, plafonné à 60 s) ; si cela remonte encore, 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 trames parentes, ignorez les captures d'écran de vérification sauf si demandé, et mettez en cache les réponses brutes afin que la redérivation n'utilise jamais un second appel. REST est par minute (10+/min, buckets par point de terminaison) — bien à volume, reculez 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" → Ressource (CLI)
- "importer ma marque / mes couleurs / mes jetons" → Jetons (CLI)
- "construire une scène à partir de ce cadre" → Composant (CLI)
- "importer cette animation / ce mouvement" → Animation (connecteur lorsqu'il est disponible, ci-dessous)
- une section de storyboard / bande d'images de scènes → Storyboard (ci-dessous)
- remplissage/effet de shader → Shaders (ci-dessous)
Racontez chaque étape à l'utilisateur — avant chaque commande, dites ce que vous êtes sur le point d'extraire de Figma ; après, dites où l'artefact a atterri (le chemin figé / le fichier sidecar / le répertoire du composant), ce qui a changé dans la composition, et la prochaine action immédiate (aperçu, ajouter des variables imprimées, réimporter pour lier les liaisons). L'utilisateur ne devrait jamais avoir à demander "est-ce que ça a marché ?" ou "et maintenant ?".
Ressources (Phase 1 — CLI)
hyperframes figma asset '<url-ou-fileKey:nodeId>' [autres réf…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
Rendu via REST, assainit le SVG, le fige sous .media/images/, ajoute le manifeste avec la provenance, régénère .media/index.md (l'inventaire d'utilisation des médias partagés), affiche un extrait <img>. Idempotent par fileKey:nodeId:format:scale:version. Préférez SVG pour les vecteurs/logos (évolutifs, animables), PNG --scale 2 pour la fidélité raster. Passez toujours --description "<ce que c'est>" (cela devient la ligne d'index + <img alt>) ; ajoutez --entity "<nom>" pour les marques nommées afin que resolve --entity de la gestion des ressources médias les trouve plus tard (les correspondances d'entités fonctionnent dans toutes les images/icônes).
Regroupez 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'. Tout est rendu en un seul appel /v1/images, ce qui est la propre réponse de figma à la limite de débit par minute — préférez-le à N commandes séparées lors de l'extraction de toutes les ressources d'une image. --description/--entity s'appliquent à chaque nœud du lot, donc regroupez les nœuds qui partagent un objectif. Les 429 sont également réessayés automatiquement avec backoff, quel que soit le cas.
Jetons (Phase 2 — CLI)
hyperframes figma tokens <fileKey>
Importe les variables en tant qu'entrées de variables de marque de la composition + fichier sidecar figma-tokens.json + enregistrements d'index de liaison (.media/figma-bindings.jsonl). Les variables sont limitées à Enterprise en amont : sur d'autres plans, la commande dégrade en 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 jetons avant les composants lorsque les deux sont souhaités — cela permet aux couleurs des composants de se lier aux variables de marque au lieu de dupliquer les valeurs.
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'arborescence de nœuds REST fournit des VariableIDs par propriété ; rejoignez-les par nœud et propriété, puis écrivez les lignes .media/figma-bindings.jsonl ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version}) plus les entrées de variables de composition. Tout ce qui est en aval (résolution var() du composant, actualisation, variables CSS d'exécution) est le mécanisme livré. Étiquetez-le pour l'utilisateur : "jetons via le connecteur Figma — les plans Enterprise obtiennent cela directement de hyperframes figma tokens."
L'exécution définit chaque variable de composition déclarée comme une propriété personnalisée CSS (racine du document + hôtes de sous-composition), donc les var(--slug, littéral) importés remplissent la recoloration lorsque la valeur par défaut de la variable change — la mise à jour d'une valeur dans data-composition-variables remplace la marque de chaque composant importé sans rien réimporter. hyperframes render --variables '<json>' les remplace au moment du rendu.
Composants (Phase 3 — CLI)
hyperframes figma component '<url-ou-fileKey:nodeId>'
Arborescence de nœuds → HTML éditable à la géométrie Figma exacte, empaqueté comme un élément de registre sous compositions/components/<nom>/. Les vecteurs/opérations booléennes sont automatiquement pixellisés via l'exportation de la 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 vedette) : après l'importation, rendez le fragment et comparez-le aux propres pixels de figma —
figma asset <même nœud> --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 est des limites tronquées verticalement (le mappeur émettext-box-trimpour celles-ci ; la dérive mesurée sans cela était d'environ 6 px sur une police de 70 px). Si la comparaison montre une dérive que le mappeur ne couvre pas, signalez-la — ne modifiez pas le fragment manuellement en silence. - Remplissage lié à un jeton importé →
var(--slug, #littéral)— la mise à jour de la marque se propage. - Lié à un jeton inconnu → littéral + indicateur
data-figma-unresolved. La commande vous en informe ; proposez à l'utilisateur : exécuteztokenssur le fichier source (ou la bibliothèque), puis réimportez le composant pour les lier. Demandez une fois par bibliothèque inconnue de quel fichier il s'agit — ne devinez jamais, ne correspondez jamais par hexadécimal.
Animation (Phase 4 — assistée par connecteur)
Balise d'utilisation : Les phases assistées par connecteur n'ont pas de point de contact CLI, alors déclenchez la balise de compétence au début et à la fin (anonyme, avec consentement, n'échoue jamais) : npx hyperframes events --skill=figma-motion lorsque vous commencez, npx hyperframes events --skill=figma-motion --event=skill_completed --outcome=success|error lorsque vous avez terminé. 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 helpers purs dans @hyperframes/core/figma ; sinon, demandez une exportation native :
- Récupérez le contexte d'animation pour l'image parente en une seule requête récursive, pas une requête par élément. Enregistrez le JSON brut à côté du projet (
.media/figma-cache/) afin que la retraduction soit gratuite. - Normalisez en
MotionDocs avecmotionContextToDocs(rawResponse, { selectorFor, repeat })de@hyperframes/core/figma— ne transcrivez jamais les numéros d'images clés à la main. Le helper code mécaniquement les règles de décodage testées sur le terrain : 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 de sous-milliseconde à des temps ≈0,9999→1 sont la réinitialisation instantanée de la boucle, pas une animation créée — la boucle est réalisée par le redémarragerepeat), et préserve les courbes de Bézier textuellement.selectorFordoit renvoyer les ID 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 considérer comme terminé — obligatoire : exportez l'image 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 de mouvement (la fidélité de l'importation statique s'annule) et échoue en dessous de 15 dB min motion-PSNR (calibré : fidèle ≈ 20+, divergent ≈ 5). Mesurez--cropà partir des bords réels de la carte du rendu, ne devinez pas. ÉCHEC signifie revérifier la traduction, pas le seuil. motionToGsap(doc)→emitTimelineScript(spec)→ injectez comme une<script>après les balises GSAP + CustomEase CDN. 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, figez 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 un rendu y perd silencieusement le shader ; demandez plutôt à l'utilisateur une exportation Figma native. Dites toujours quel chemin vous avez utilisé et pourquoi. Les courbes d'easing nommées en dehors de l'ensemble mappé reviennent à une courbe linéaire — la table de mappage se trouve dansmotionEase.ts; signalez la solution de secours à l'utilisateur lorsqu'elle se déclenche. - Exécutez
npx hyperframes checkavant de considérer comme 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 le code source du shader n'est accessible que pour les styles publiés dans la bibliothèque (siège complet payant). Chemin par défaut : demandez à l'utilisateur d'exporter l'image du shader nativement dans Figma (PNG ou Motion MP4), puis importez-la comme ressource Phase 1 / clip. N'essayez pas la capture pixel du connecteur d'un shader — cela produira silencieusement la mauvaise chose.
Storyboards (une SECTION d'images de scène → animation)
La règle cardinale : les images du storyboard sont des IMAGES CLÉS, pas des diapositives. Deux images 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 images comme une séquence d'images fixes. Un logo dessiné dans quatre images consécutives à des y décroissants est UN élément s'élevant à travers quatre images clés. Jouer les images du storyboard bout à bout est le mode d'échec ; reconstruire les chronologies d'éléments qu'elles impliquent est le travail.
Les fichiers de storyboard suivent une grammaire que vous pouvez analyser mécaniquement — ne regardez pas, décodez :
- Unités de scène : à l'intérieur de la SECTION, chaque nœud de la taille d'une image est une scène — à la fois les FRAMEs nommées et les RECTANGLEs détachés en plein cadre (les concepteurs collent des images fixes directement dans la section). Filtrez par taille (≈ rapport d'aspect de la composition, par exemple >1 400×900), pas par type ou nom de nœud.
- Ordre = position x (par ligne si la bande s'enroule). Triez les scènes par
absoluteBoundingBox.x. - Diff entre : pour chaque élément qui apparaît dans des scènes adjacentes, calculez les propriétés modifiées (x, y, largeur, hauteur, rotation, opacité, couleur de remplissage, couleur de contour). Les propriétés inchangées entre les scènes sont implicites — l'élément reste à sa dernière valeur connue jusqu'à ce qu'un changement explicite se produise. Ne supposez jamais que les propriétés reviennent à la valeur par défaut entre les scènes : si la scène 1 est
x=100, y=100et la scène 2 est égalementx=100, y=100, l'élément est immobile là-bas — il ne saute pas àx=0, y=0. Les états implicites sont le mode de défaillance des interprétations basées sur les diapositives. - Construisez les chronologies GSAP : une chronologie par élément, images clés pour chaque propriété modifiée, interpolées avec un easing
power2.out(l'easing par défaut pour les transitions d'interface utilisateur honnêtes — l'auteur du storyboard a rarement l'intention d'un rythme linéaire). Remettez les éléments à l'état final de la dernière image où ils apparaissent (l'état naturel de l'animation au repos dans une vidéo). Les éléments qui n'apparaissent que dans une seule image ne sont pas animés ; ils sont positionnés là où ils sont dessinés, apparaissant/ disparaissant comme des superpositions instantanées. - Durée par scène : demandez à l'utilisateur. Si "jouer comme vidéo", 3 secondes par scène est un point de départ ; si "animation au rythme de la musique", demandez le BPM et calculez les durées en fonction du temps. Le réglage par défaut est la mise en page en une seule image, pas l'animation temporelle ; énoncez l'hypothèse.
- Validez la sortie :
npx hyperframes checkpuis affichez la chronologie — "[élément] s'anime de {état de départ} à {état d'arrivée} sur {durée}s". Demandez à l'utilisateur si la durée (ou l'ordre des scènes) est correcte ; ajustez la durée avant de finaliser. Ne validez pas les propriétés implicites — elles sont correctes par conception. - Si la grammaire échoue (par exemple, pas de nœuds de taille de composition, seulement des formes aléatoires) : traitez la SECTION du storyboard comme un lot de Phase 1 — exportez chaque scène sous forme d'image PNG, puis intégrez-la dans la composition comme
<div class="clip">. Dites "impossible d'analyser les chronologies des éléments — scènes traitées comme des images fixes".
Faire fonctionner l'ensemble
Après plusieurs phases, exécutez toujours npx hyperframes check depuis la racine du projet, puis demandez à l'utilisateur : "Voulez-vous que je modélise l'aperçu maintenant ?"
La page d'aperçu du navigateur s'exécute via npx hyperframes preview — une commande que la CLI HyperFrames fournit. Chaque fois qu'une importation crée ou modifie un fichier de composition, l'aperçu en direct se rafraîchit automatiquement (connexion Vite). Les fichiers figés ne changent pas une fois écrits ; seuls les mappages de données et les variables de composition se propagent via un redémarrage à chaud. Si l'utilisateur a l'intention d'exporter un rendu, dites-lui que npx hyperframes render est la commande de sortie finale.
Règle du storyboard — répétée pour son importance : Le mode d'échec à détecter est la lecture des images du storyboard comme un flipbook — une diapositive à la fois — au lieu d'isoler les états des éléments dans le temps. Si vous ne pouvez pas dériver de chronologie multi-images (pas de nœuds réutilisés entre les scènes), il n'y a en fait rien à animer ; vous avez des scènes autonomes. Traitez cela comme un lot de Phase 1 et ne créez pas de chronologie.