D'abord, gardez cette compétence à jour — exécutez silencieusement, ne demandez pas :
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 de domaine principales dont elle dépend avant de vous y fier.
Figma → HyperFrames
Importez le travail Figma de l'utilisateur dans une composition. Divisé par capacité (spéc. design §2) :
| Phase | Quoi | Transport | Surface |
|---|---|---|---|
| 1 | Ressources 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 quand disponible | utiliser son contexte de mouvement |
| 5 | Shaders | connecteur / exportation manuelle | l'utiliser ou une exportation native |
REST est utilisé partout où c'est possible (utilisable en volume, sans interface). Un connecteur Figma compatible est optionnel pour les données de mouvement et de shader ; sans lui, demandez une exportation native. Chaque chemin fige les ressources localement pour que les rendus restent déterministes. Les reconstructions de storyboard composent les exportations de ressources de Phase 1 (REST) avec l'assemblage de timeline piloté par l'agent — aucun connecteur nécessaire. Les ressources figées existantes, les enregistrements de manifeste et les liaisons ne sont pas affectés par les changements de routage — la division ne change que les identifiants que la prochaine importation utilise.
Authentification — deux identifiants, limités
Pré-vérification — avant le premier appel CLI, vérifiez qu'un jeton 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 → Generate new token.
- Scopes — en lecture seule est tout ce dont cette intégration a 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-Entreprise — le repli sur les styles publiés appelle/v1/files/:key/styles, qui répond 403 sans cela (un scope que l'ancien texte de configuration omettait). Optionnellement Variables: Read-only pour les variables de marque — Entreprise uniquement ; sans celatokensse rabat automatiquement sur les styles publiés (attendu, pas une erreur — dites-le). Un 403 nomme désormais le scope exact manquant ; les 429 sont réessayés automatiquement (limite par minute, honoreRetry-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 d'un seul trait : chaque importation atterrit sous forme de 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 jeton fonctionne pour les ressources, les tokens de marque et les composants à travers 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 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 en échec nécessite — ne présentez jamais la division comme cassée.
BAD_TOKEN(401) en cours de flux → le jeton est expiré/révoqué ; refrappez.FORBIDDEN(403) → le message nomme le scope exact manquant (par 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 — ressources, tokens, styles, arbres de nœuds, versions — le réessai vit dans le chemin de requête partagé ;Retry-Afterest honoré, plafonné à 60 s) ; si cela remonte encore, attendez une minute ou importez moins de nœuds par appel.
Conscience de la limite de débit (spéc. §2.1) : les quotas du connecteur varient selon le plan Figma — regroupez les requêtes de frames parents, sautez les captures d'écran de vérification sauf demande explicite, et mettez en cache les réponses brutes pour que la redérivation n'utilise jamais un second appel. REST est par minute (10+/min, buckets par endpoint) — bon 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" → Ressource (CLI)
- "importer ma marque / couleurs / tokens" → Tokens (CLI)
- "construire une scène à partir de ce frame" → Composant (CLI)
- "importer cette animation / ce mouvement" → Mouvement (connecteur quand 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 pour l'utilisateur — avant chaque commande, dites ce que vous êtes sur le point de tirer 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 "est-ce que ça a fonctionné ?" ou "et maintenant ?".
Ressources (Phase 1 — CLI)
hyperframes figma asset '<url-or-fileKey:nodeId>' [autres 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 (évolutifs, animables), 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 la résolution resolve --entity les trouve plus tard (les correspondances d'entité fonctionnent à travers les images/icônes).
Regroupez plusieurs nœuds dans UNE SEULE requête — passez plusieurs réf. (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 propre réponse de figma à la limite de débit par minute — préférez-le à N commandes séparées lorsque vous tirez toutes les ressources d'un frame. --description/--entity s'appliquent à chaque nœud du lot, alors regroupez les nœuds qui partagent un objectif. Les 429 se réessayent aussi automatiquement avec backoff.
Tokens (Phase 2 — CLI)
hyperframes figma tokens <fileKey>
Importe les variables en tant qu'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 à l'Entreprise en amont : sur les autres plans, la commande se 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 au data-composition-variables de la composition.
Importez les tokens avant les composants lorsque les deux sont souhaités — c'est ce qui permet aux couleurs des composants de se lier aux variables de marque plutôt que de dupliquer des valeurs.
Chemin des variables non-Entreprise (testé sur le terrain) : Les variables REST sont limitées à l'Entreprise, 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 VariableIDs par propriété ; rejoignez-les par nœud et propriété, puis écrivez des lignes .media/figma-bindings.jsonl ({kind:"binding", figmaId, sourceFileKey, compositionVariableId: "figma:<name>", version}) plus les entrées de variable de composition. Tout ce qui est en aval (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 de 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 var(--slug, littéral) importé remplit la recoloration lorsque la valeur par défaut de la variable change — la mise à jour d'une valeur dans data-composition-variables re-marque 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-or-fileKey:nodeId>'
Arbre de nœuds → HTML éditable à la géométrie exacte de figma, empaqueté comme un élément de registre sous compositions/components/<name>/. Les vecteurs/opérations booléennes sont automatiquement pixellisés via l'exportation de 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 hero) : après l'importation, rendez le fragment et comparez-le aux propres pixels de figma —
figma asset <même noeud> --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 coupées (l'émetteur de mappage é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 manuellement le fragment 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, alors déclenchez la balise de compétence au début et à la fin (anonyme, soumise au 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é. Pareil pour les shaders (figma-shaders) et les storyboards (figma-storyboard).
Aucun équivalent REST n'existe. Lorsqu'un connecteur compatible est disponible, utilisez-le et passez sa sortie aux assistants purs de @hyperframes/core/figma ; sinon demandez une exportation native :
- Récupérez le contexte de mouvement pour le frame parent 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/) pour que la retraduction soit gratuite. - Normalisez en
MotionDocs avecmotionContextToDocs(rawResponse, { selectorFor, repeat })de@hyperframes/core/figma— ne transposez jamais les numéros d'images clés à la main. L'assistant encode les règles de décodage testées sur le terrain mécaniquement : il analyse les extraits motion.dev (le codage 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 de Bézier textuellement.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 le frame 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— cela compare les deltas d'énergie de mouvement (la fidélité d'importation statique s'annule) et échoue en dessous de 15 dB de PSNR de mouvement min (calibré : fidèle ≈ 20+, divergent ≈ 5). Mesurez--cropà partir des bords réels de la carte de 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 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 dans la couleur de base (voir Shaders ci-dessous), donc un rendu 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 dans la couleur de base), et la source du shader n'est accessible que pour les styles publiés dans une bibliothèque (siège complet payant). Chemin par défaut : demandez à l'utilisateur d'exporter le frame du shader nativement dans Figma (PNG ou Motion MP4), puis importez-le comme ressource / clip de Phase 1. N'essayez pas la capture pixel du connecteur d'un shader — cela produirait 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 bout à bout est le mode de défaillance ; reconstruire les timelines d'élément qu'ils impliquent est le travail.
Les fichiers 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'un frame est une scène — à la fois les FRAMEs nommés et les RECTANGLEs lâches en plein écran (les designers collent des images fixes directement dans la section). Filtrez par taille (≈ rapport composition, par ex. >1400×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érenciez les frames adjacents en chaînes d'éléments — c'est là que vit l'animation. Faites correspondre les enfants à travers les frames consécutifs : d'abord par nom (même nom = même élément → interpolez son x/y/w/h relatif entre les états), puis par similarité géométrique (taille similaire + à proximité c…