heygen-com/hyperframes

Installations 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, gardez 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, elle rafraîchit cette compétence ainsi que les compétences de base dont elle dépend avant que vous ne les utilisiez.

Figma → HyperFrames

Importez le travail Figma de l'utilisateur dans une composition. Divisé par capacité (spécification de design §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 quand 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 interface graphique). 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 assets localement pour que les rendus restent déterministes. Les reconstructions de storyboard composent les exportations 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 division ne change 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 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 :

1. figma.com/settings → Sécurité → Jetons d'accès personnel → Générer un nouveau jeton.
2. Périmètres — 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 tokens sur un plan non Enterprise — la solution de repli des styles publiés accède à /v1/files/:key/styles, qui renvoie 403 sans ce périmètre (un périmètre que l'ancien texte de configuration omettait). Optionnellement Variables : Lecture seule pour les variables de marque — réservé aux plans Enterprise ; sans cela, tokens se replie automatiquement sur les styles publiés (attendu, pas une erreur — dites-le). Un code 403 indique désormais le périmètre manquant exact ; les 429 sont réessayés automatiquement (limite par minute, respecte Retry-After).
3. Demandez à l'utilisateur de définir FIGMA_TOKEN dans son profil shell ou le fichier .env du projet ; ne lui demandez jamais de coller le token dans la conversation.

Pendant l'intégration, définissez également les attentes en une phrase : chaque importation aboutit à 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 token fonctionne pour les assets, les tokens de marque et les composants dans tous les fichiers que le compte Figma de l'utilisateur peut voir.

• Phases 4–5 (mouvement/shadeurs) : un connecteur Figma compatible, avec une autorisation distincte 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 division comme cassée.
• BAD_TOKEN (401) en cours de route → le token a expiré ou a été révoqué ; recréez-en un. FORBIDDEN (403) → le message nomme le périmètre manquant exact (par ex. library_content:read pour le repli des styles) — ajoutez-le, ou le fichier n'est pas visible par le compte. REQUIRES_ENTERPRISE (403 sur les variables) → pas une erreur : le repli des styles a déjà été exécuté. RATE_LIMITED (429) → le client a déjà réessayé avec un backoff (cela s'applique à CHAQUE lecture — assets, tokens, styles, arborescences de nœuds, versions — la tentative de réessai réside dans le chemin de requête partagé ; Retry-After est respecté, plafonné à 60 s) ; si cela persiste, attendez une minute ou importez moins de nœuds par appel.

Conscience de la limite de débit (spécification §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, 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 point de terminaison) — acceptable 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 trame" → Composant (CLI)
• "importer cette animation / ce mouvement" → Mouvement (connecteur quand disponible, ci-dessous)
• une section de storyboard / un filmstrip d'images de scène → Storyboard (ci-dessous)
• remplissage/effet shader → Shaders (ci-dessous)

Narrez 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 / répertoire 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 "est-ce que ça a marché ?" ou "et maintenant ?".

Assets (Phase 1 — CLI)

hyperframes figma asset '<url-ou-fileKey:nodeId>' [autres réf…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]

Rend via REST, nettoie le 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), affiche 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>" (il devient la ligne d'index + <img alt>) ; ajoutez --entity "<nom>" pour les marques nommées afin que resolve --entity de media-use les trouve plus tard (les correspondances d'entité s'étendent entre 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 sont rendus 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'extraction d'une trame entière d'assets. --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 un backoff.

Tokens (Phase 2 — CLI)

hyperframes figma tokens <fileKey>

Importe les variables en tant qu'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 aux plans Enterprise 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 — cela permet aux couleurs des composants de se lier aux variables de marque plutôt que de dupliquer les valeurs.

Chemin des variables non Enterprise (testé sur le terrain) : les variables REST sont limitées aux plans 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. L'arborescence des nœuds REST boundVariables fournit des VariableIDs 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 variable de composition. Tout ce qui suit (résolution var() du composant, rafraîchissement, variables CSS d'exécution) relève du mécanisme livré. Étiquetez-le pour l'utilisateur : "tokens via le connecteur Figma — les plans Enterprise les obtiennent directement via 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 des sous-composants), de sorte que var(--slug, littéral) importé 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 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 des nœuds → HTML éditable à la géométrie exacte de Figma, emballé comme un élément de registre sous compositions/components/<nom>/. Les vecteurs/opérations booléennes sont automatiquement pixellisés via l'exportation de phase 1. Passage 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 principal) : après l'importation, rendez le fragment et comparez-le aux propres pixels de Figma — figma asset <même nœud> --format png est 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 verticales rognées (le mappeur émet text-box-trim pour 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 non couverte par le mappeur, 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 en informe ; proposez à l'utilisateur : exécutez tokens sur 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.

Mouvement (Phase 4 — assisté par connecteur)

Balisage d'utilisation : Les phases assistées par connecteur n'ont pas de point de contact CLI, donc déclenchez le balisage 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é. De même 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 :

1. Récupérez le contexte de mouvement de la trame 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/) pour que la re-traduction soit gratuite.
2. Normalisez en MotionDocs avec motionContextToDocs(rawResponse, { selectorFor, repeat }) de @hyperframes/core/figma — ne retranscrivez jamais les numéros de keyframe à la main. Le helper encode les règles de décodage testées sur le terrain de manière mécanique : il analyse les extraits motion.dev (l'encodage fiable — les extraits CSS étirent les durées et peuvent diverger ; ils sont ignorés), supprime les keyframes de fin de boucle (les segments sous-milliseconde à des temps ≈0,9999→1 sont la réinitialisation instantanée de la boucle, pas un mouvement intentionnel — l'enveloppe est réalisée par le redémarrage repeat), et préserve les courbes bezier textuellement. selectorFor doit retourner les identifiants de l'importation du composant de 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 trame racine de la cohorte via le connecteur disponible et exécutez node 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 15dB 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.
3. motionToGsap(doc) → emitTimelineScript(spec) → injectez comme <script> après les balises CDN GSAP + CustomEase. En pause, fini, enregistré sur window.__timelines avec une clé littérale.
4. 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 fixe y perd silencieusement le shader ; demandez plutôt une exportation Figma native à l'utilisateur. Dites toujours quel chemin vous avez utilisé et pourquoi. Les courbes nommées en dehors de l'ensemble mappé tombent en linéaire — la table de mappage se trouve dans motionEase.ts ; signalez le repli à l'utilisateur quand il se déclenche.
5. Exécutez npx hyperframes check avant 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 trame 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 — elle produira silencieusement un résultat erroné.

Storyboards (une SECTION d'images de scène → animation)

La règle cardinale : les images de storyboard sont des KEYFRAMES, 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 à un y décroissant est UN élément s'élevant à travers quatre keyframes. Jouer les images du storyboard les unes après les autres est le mode d'échec ; 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 :

1. 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 pleine image lâches (les designers collent des images fixes directement dans la section). Filtrez par taille (≈ format de la composition, par ex. >1400×900), pas par type de nœud ou nom.
2. Ordre = position x (ligne principale si la bande s'enroule). Triez les scènes par absoluteBoundingBox.x.
3. Différence entre scènes adjacentes : pour chaque propriété d'un nœud qui a changé d'une scène N à N+1 (position, opacité, rotation, visibilité, remplissage, trait), la propriété est une CLÉ d'animation de N à N+1. Métadonnées : transitionDuration: number (ms, défaut 400), transitionEasing: string ('linear'|'ease-in'|'ease-out'|'ease-in-out'|'cubic-bezier(p1x,p1y,p2x,p2y)').
4. Supprimez les scènes en double : si N+1 est identique à N en position/propriétés visuelles, c'est intentionnel (la scène N a une durée de maintien) ; gardez la scène N+1 mais avec transitionDuration = la durée de maintien de N + la durée de transition de N. (C'est ainsi que les designers encodent « ceci reste ici pendant 2 secondes puis l'image suivante commence à arriver ».)
5. Pour les compositions où l'image N dure jusqu'à ce que l'image N+1 la recouvre, la TIMELINE est une superposition de toutes les images de la section étalonnées pour commencer ensemble avec des durées individuelles — chaque image superposée a une <div> parente avec animation-delay: <temps cumulé des images précédentes>s. Il n'y a pas de coupure entre les images.
6. 'this scene stops, next scene starts' = un fondu au noir explicite (une image noire RECTANGLE entre les scènes) suivi d'un fondu depuis le noir — c'est la seule façon dont un storyboard encode une coupure. Détectez-la uniquement par la présence d'une image noire intercalée entre des scènes non noires.

Ne déduisez jamais d'une image de storyboard plus que ce qui y est explicitement tracé — l'image est la vérité ; ce qui n'est pas tracé n'existe pas. Si l'utilisateur veut ajouter des keyframes intermédiaires, il doit éditer le fichier Figma original — le storyboard est la source d'autorité.

De plus, l'étape de reconstruction multi-image émet un MotionDoc en sortie qui est consommé par motionToGsap de la Phase 4 — la validation de la Phase 4 s'applique également (vérification de la PSNR de mouvement en sortie). Après l'importation du storyboard, exécutez toujours npx hyperframes check.

Alignement de l'importation

Les tokens utilisent des noms de variables et des slugs de propriété qui doivent correspondre aux attentes des composants et des appels de rendu.

Table de mappage des propriétés (fiable, non exhaustive)

Variable Figma (expectation)	Slug CSS	Attendu par
color-background-default	--bg	composition-variables
color-text-primary	--text	composition-variables
color-brand-primary	--brand-primary	media-use (résolution d'entité)
radius-default	--radius	composition-variables
spacing-default	--space	composition-variables

Toutes les valeurs sont exprimées avec des unités de correspondance de Pixel. Les variables de composition sont définies sur la racine du document (le hôte du composant, pas à l'intérieur).