Avant tout, gardez cette compétence à jour — confirmez avec l'utilisateur avant de lancer :
npx hyperframes skills update figma. Un no-op rapide quand tout est à jour ; sinon, cela rafraîchit cette compétence ainsi que les compétences du domaine central dont elle 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 dispo. | utiliser son contexte de mvt |
| 5 | Shaders | connecteur / export man. | l'utiliser ou un export natif |
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 shaders ; sans lui, demandez une exportation native. Chaque chemin fige les assets localement pour que les rendus restent déterministes. Les reconstructions de storyboard composent les exports d'assets de Phase 1 (REST) avec un assemblage de timeline piloté par l'agent — aucun connecteur nécessaire. Les assets figés existants, les enregistrements de manifeste et les liaisons ne sont pas affectés par les changements de routage — la répartition ne change que les identifiants que la prochaine importation utilise.
Authentification — deux identifiants, avec portée
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 ni l'un ni l'autre, n'exécutez PAS la commande pour récolter l'erreur — guidez d'abord l'utilisateur dans la configuration unique, puis arrêtez et attendez :
- figma.com/settings → Sécurité → Jetons d'accès personnels → Générer un nouveau jeton.
- Portées — la 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-Entreprise — le repli des styles publiés touche/v1/files/:key/styles, qui retourne 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é aux plans Entreprise ; sans cela,tokensse dégrade automatiquement aux styles publiés (attendu, pas une erreur — dites-le). Un 403 nomme désormais la portée manquante exacte ; 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 comme un fichier local figé 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 seul jeton fonctionne pour les assets, les tokens de marque et les composants sur tous les fichiers que le compte Figma de l'utilisateur peut voir.
- Phases 4–5 (mouvement/shaders) : un connecteur Figma compatible, avec une autorisation distincte du jeton. S'il est indisponible ou non authentifié, demandez à l'utilisateur de le connecter ou de fournir une exportation native, puis arrêtez.
- Dites exactement quel identifiant une phase défaillante nécessite — ne présentez jamais la répartition comme cassée.
BAD_TOKEN(401) en cours de route → le jeton est expiré/révoqué ; à renouveler.FORBIDDEN(403) → le message nomme la portée manquante exacte (par ex.library_content:readpour le repli des styles) — ajoutez-la, ou le fichier n'est pas visible pour le compte.REQUIRES_ENTERPRISE(403 sur les variables) → pas un échec : le repli des styles a déjà eu lieu.RATE_LIMITED(429) → le client a déjà essayé avec backoff (cela s'applique à CHAQUE lecture — assets, tokens, styles, arbres 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.
Sensibilisation aux limites de débit (spéc. §2.1) : les quotas du connecteur varient selon le plan Figma — regroupez les requêtes de trames parentes, évitez les captures d'écran de vérification sauf demande explicite, et mettez en cache les réponses brutes pour qu'une re-dérivation ne passe jamais un second appel. REST est par minute (10+/min, buckets par point de terminaison) — 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 / tokens" → Tokens (CLI)
- "construire une scène à partir de cette trame" → Composant (CLI)
- "importer cette animation / ce mouvement" → Mouvement (connecteur dispo., 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 pour l'utilisateur — avant chaque commande, dites ce que vous allez extraire de Figma ; après, dites où l'artefact a atterri (le chemin figé / sidecar / dossier du composant), ce qui a changé dans la composition et la prochaine action immédiate (aperçu, ajout de variables imprimées, réimportation 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>' [plus de refs…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
Rend via REST, nettoie SVG, fige sous .media/images/, ajoute le manifeste avec provenance, régénère .media/index.md (l'inventaire partagé d'utilisation des médias), imprime un extrait <img>. Idempotent par fileKey:nodeId:format:scale:version. Préférez SVG pour les vecteurs/logos (évolutif, animatable), PNG --scale 2 pour la fidélité raster. Passez toujours --description "<ce que c'est>" (il devient la ligne d'index + <img alt>) ; ajoutez --entity "<nom>" pour les marques nommées afin que media-use resolve --entity les trouve ultérieurement (les correspondances d'entité s'appliquent à l'image/icône).
Regroupez plusieurs nœuds dans 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 rendent dans 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'importation de tous les assets d'une trame. --description/--entity s'appliquent à chaque nœud du lot, donc regroupez les nœuds qui partagent un même objectif. Les 429 sont également réessayés automatiquement avec backoff.
Tokens (Phase 2 — CLI)
hyperframes figma tokens <fileKey>
Importe les variables comme entrées de variables de marque de composition + sidecar figma-tokens.json + enregistrements d'index de liaison (.media/figma-bindings.jsonl). Les variables sont limitées aux Entreprises en amont : sur d'autres plans, la commande se dégrade aux métadonnées de style publié (les valeurs sont résolues au moment de l'importation du composant). Ajoutez les entrées imprimées à 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 au lieu de dupliquer des valeurs.
Chemin des variables non-Entreprise (testé sur le terrain) : les variables REST sont limitées aux Entreprises, 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. L'arbre de nœuds REST boundVariables fournit des VariableID par propriété ; joignez-les par nœud et propriété, puis écrivez les lignes .media/figma-bindings.jsonl ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<nom>", version}) plus les entrées de variables de composition. Tout ce qui suit (résolution var() du composant, rafraîchissement, variables CSS d'exécution) est la machinerie livrée. Étiquetez-le pour l'utilisateur : "tokens via le connecteur Figma — les plans Entreprise obtiennent cela directement depuis 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-composants), donc var(--slug, littérale) remplit la recoloration lorsque la valeur par défaut de la variable change — mettre à jour une valeur dans data-composition-variables re-marque chaque composant importé sans réimporter quoi que ce soit. hyperframes render --variables '<json>' les remplace au moment du rendu.
Composants (Phase 3 — CLI)
hyperframes figma component '<url-or-fileKey:nodeId>'
Arbre de nœuds → HTML modifiable à la géométrie figma exacte, emballé comme un élément de registre sous compositions/components/<nom>/. Les vecteurs/opérations booléennes sont auto-rasterisés via l'export Phase 1. Passe de liaison (spéc. §7.1, ID exact uniquement — jamais de correspondance de valeur) :
- Auto-vérification de fidélité statique (obligatoire pour le contenu héro): 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 boîte de texte figma plus courte que sa hauteur de ligne a des limites verticalement rognées (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 à la main en silence. - Remplissage lié à un token importé →
var(--slug, #littérale)— la mise à jour de la marque se propage. - Lié à un token inconnu → littérale + indicateur
data-figma-unresolved. La commande vous le dit ; 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 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, alors déclenchez la balise de compétence au début et à la fin (anonyme, consentement requis, 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 aides pures dans @hyperframes/core/figma ; sinon, demandez une exportation native :
- Récupérez le contexte de mouvement pour la trame 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(réponseBrute, { selectorFor, repeat })de@hyperframes/core/figma— ne transcrivez jamais les numéros d'image clé à la main. L'aide encode les règles de décodage testées sur le terrain mécaniquement : elle 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 sous-millisecondes à des temps ≈0,9999→1 sont la réinitialisation instantanée de la boucle, pas un mouvement créé — le wrap est réalisé par le redémarragerepeat), et préserve les courbes de Bézier textuellement.selectorFordoit retourner les ids de l'importation Phase 3 du composant — 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 trame racine de la cohorte via le connecteur disponible et exécuteznode skills/figma/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é d'importation statique s'annule) et échoue en dessous de 15 dB de PSNR min (calibré : fidèle ≈ 20+, divergent ≈ 5). Mesurez--cropà partir des bords de carte réels du 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, figez la MP4, puis intégrez-la comme
<video class="clip">. Exception : les pistes pilotées par shader — le chemin d'export de Figma aplatit les shaders sur la couleur de base (voir Shaders ci-dessous), donc un calcul là-bas perd silencieusement le shader ; demandez plutôt à l'utilisateur une exportation Figma native. Dites toujours quel chemin vous avez utilisé et pourquoi. Les easing nommés en dehors de l'ensemble mappé reviennent à linéaire — la table de mappage se trouve dansmotionEase.ts; signalez le repli à l'utilisateur lorsqu'il se produit. - 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 sur la couleur de base), et le source du shader n'est accessible que pour les styles publiés dans la bibliothèque (accès complet payant). Chemin par défaut : demandez à l'utilisateur d'exporter la trame du shader nativement dans Figma (PNG ou Motion MP4), puis importez-la comme un asset / clip de Phase 1. 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 de 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 de diapositives fixes. Un logo dessiné dans quatre images consécutives à un y décroissant est UN élément s'élevant à travers quatre images clés. Jouer les images de storyboard bout à bout est le mode de défaillance ; reconstruire les timelines 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 à l'œil, 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és et les RECTANGLEs lâches en pleine image (les designers collent des images fixes directement dans la section). Filtrez par taille (≈ aspect de la composition, par ex. >1400×900), pas par type de nœud ou nom.
- Ordre = position x (par ligne si la bande s'enroule). Triez les scènes par
absoluteBoundingBox.x. - Différenciez les images adjacentes en chaînes d'éléments — c'est là que vit l'animation. Faites correspondre les enfants entre images consécutives : d'abord par nom (même nom = même élément → tween son x/y/w/h relatif entre les états), puis par similarité géométrique (position/encombrement similaire = nouvel enfant, pas élément déplacé), puis par similarité visuelle (contenu bitmap, pas de hachage perceptuel — vérifiez si le nom de l'élément figure est le même et si le type de calque est le même). Terminez la chaîne lorsqu'une image ne peut pas être appariée de manière fiable — ne fabriquez pas de faux positifs. Pour chaque chaîne, émettez des keyframes GSAP (position, échelle, rotation, opacité, probablement clip) aux temps correspondant au numéro d'image de la scène. Ancrez l'ordre des images scéniques à un temps de trame absolu ; définissez la plage de temps du storyboard à
[0, nombre_d_images * intervalle_s], intervalle par défaut = 2,5 s. Utilisezgsap.to(el, { ... keyframes: [...] }). Le défilement du storyboard est laissé à GSAP ScrollTrigger ; la configuration minimale :scrollTrigger: { trigger: "#storyboard-track", start: "top bottom", end: "bottom top" }.
Validez la chronologie contre la vérité terrain obligatoire : comme pour le mouvement (Phase 4), utilisez verify-motion.mjs contre un PNG composite exporté par le connecteur, s'il est disponible. La fidélité du storyboard est jugée par la cohérence temporelle des éléments — les scènes statiques sont faciles ; les scènes avec des calques qui se chevauchent et des transitions subtiles sont le signal. Validez le storyboard complet, pas seulement les scènes individuelles. L'onglet Timeline de GSAP est votre ami — encouragez l'utilisateur à le consulter s'il demande des ajustements.
Journalisation et journal de route de la composition
Le formulaire le plus concis pour le journal de route : une entrée d'horodatage, la phase, le fichier clé résolu, le compte de nœuds, l'identifiant de la composition et les actions suivantes. Exemple :
[2025-04-01 10:42] asset 'ABC123:1-2' (2 nœuds, SVG) → .media/images/ + manifeste ; composant >1400px vide ; prochaine étape : `component` pour les trames principales.
Les views de la composition, l'index des médias et les manifestes sont réels — ce journal de route est une narration, pas un fichier.
Actions suivantes après l'importation
- Aperçu :
npx hyperframes servepuis ouvrez la view de la composition. N'ouvrez pas les fichiers figés individuellement sauf si vous vérifiez la fidélité. - Augmenter la résolution des assets bitmap : réimportez avec
--scale 2(ou 3) — les SVG sont indépendants de l'échelle. - Reconnecter les tokens aux composants : n'oubliez pas,
tokensd'abord, puiscomponent— les variables de marque se propagent. - Enrichir avec des données en direct : les variables de composition remplacent les valeurs Tokens au moment du rendu ;
variables.jsonles remplace toutes. Utilisezhyperframes render --variables '.media/live-data.json'. - Publier une view de composition :
hyperframes deploy. Les assets figés et les fichiers de registre sont inclus.