⚠ Statut du contrat : pas encore porté sur Remotion
Le framework de sortie de cette pile est Remotion + React (
/hyperframes-core). Cette compétence décrit encore le pipeline retiré HTML +data-*+ timeline GSAP en pause, et ses scripts groupés émettent toujoursindex.htmldans ce contrat.Jusqu'à ce qu'il soit porté :
- Ne pas exécuter
npx hyperframes <n'importe quoi>— cette CLI est retirée./hyperframes-climappe chaque ancienne commande vers son équivalent Remotion.- Ne pas copier son balisage
data-*ou le code de timeline GSAP dans un projet Remotion.- Faire s'inspirer de son savoir-faire : la forme de l'histoire, le rythme des coupes, le design visuel, les décisions sur ce qui apparaît à l'écran. Cette partie est indépendante du framework et c'est pourquoi cette compétence est toujours présente.
- Faire exprimer le résultat via le contrat de
/hyperframes-core:<Composition>,<Sequence>, et les valeurs dérivées deuseCurrentFrame().Dites dans votre résumé quand vous avez dû contourner ce problème, afin que le port puisse être terminé.
D'abord, gardez cette compétence à jour — exécutez silencieusement, ne demandez pas :
npx hyperframes skills update figma. Une opération rapide sans effet quand tout est à jour ; sinon elle rafraîchit cette compétence ainsi que les compétences du domaine central dont elle dépend avant que vous ne comptiez dessus.
Que fait Figma → HyperFrames ?
Intégrez 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 | Tokens/styles de marque | REST | hyperframes figma tokens |
| 3 | Composants → HTML | REST | hyperframes figma component |
| 4 | Motion → GSAP | connecteur quand disponible | utiliser son contexte de motion |
| 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 motion et de shader ; sans lui, demandez une exportation native. Chaque chemin gèle les ressources localement afin que les rendus restent déterministes. Les reconstructions de storyboard composent les exportations de ressources de Phase 1 (REST) avec un assemblage de timeline piloté par l'agent — aucun connecteur nécessaire. Les ressources gelées existantes, les enregistrements de manifeste et les liaisons ne sont pas affectés par les changements de routage — la division ne modifie que les informations d'identification que la prochaine importation utilise.
Authentification — deux identifiants, limités
Pré-vérification — avant le premier appel CLI, vérifiez qu'un token existe : dans l'environnement shell ([ -n "$FIGMA_TOKEN" ]) ou dans le .env du projet (la 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 à travers la configuration unique, puis arrêtez et attendez :
- figma.com/settings → Sécurité → Jetons d'accès personnels → Générer un nouveau jeton.
- Périmètres — la lecture seule est tout ce dont cette intégration a jamais 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écuterez
tokenssur un plan non-Entreprise — le recours aux styles publiés atteint/v1/files/:key/styles, qui renvoie 403 sans cela (un périmètre que l'ancien texte de configuration omettait). Optionnellement Variables : Lecture seule pour les variables de marque — uniquement Enterprise ; sans cela,tokensse dégrade automatiquement aux styles publiés (attendu, pas une erreur — dites-le). Un 403 nomme désormais le périmètre manquant exact ; les 429 sont relancés automatiquement (limite par minute, respecteRetry-After). - Demandez à l'utilisateur de définir
FIGMA_TOKENdans son profil shell ou.envdu projet ; ne lui demandez jamais de coller le jeton dans la conversation.
Pendant l'intégration, établissez également les attentes en une phrase : chaque importation aboutit à un fichier local gelé 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 de tous les fichiers que leur compte Figma peut voir.
- Phases 4–5 (motion/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-vous.
- Dites exactement quelle information d'identification une phase en échec nécessite — ne présentez jamais la division comme cassée.
BAD_TOKEN(401) en cours d'exécution → le jeton a expiré/révoqué ; régénérez-le.FORBIDDEN(403) → le message nomme le périmètre manquant exact (par ex.library_content:readpour le recours aux styles) — ajoutez-le, ou le fichier n'est pas visible par le compte.REQUIRES_ENTERPRISE(403 sur les variables) → pas un échec : le recours aux styles a déjà été exécuté.RATE_LIMITED(429) → le client a déjà relancé avec backoff (cela s'applique à CHAQUE lecture — ressources, tokens, styles, arbres de nœuds, versions — la relance vit dans le chemin de requête partagé ;Retry-Afterest respecté, plafonné à 60s) ; 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 de connecteur varient selon le plan Figma — regroupez les requêtes de trames parentes, sautez les captures d'écran de vérification sauf demande explicite, et mettez en cache les réponses brutes afin que la redérivation n'utilise jamais un deuxième appel. REST est par minute (10+/min, buckets par endpoint) — acceptable en volume, reculez sur 429.
Routage
Analysez le lien figma de l'utilisateur avec parseFigmaRef (URL, fileKey:nodeId, fileKey nu). Ensuite, selon l'intention :
- "utilise ce calque / logo / image" → Ressource (CLI)
- "récupère ma marque / mes couleurs / tokens" → Tokens (CLI)
- "construis une scène à partir de cette trame" → Composant (CLI)
- "importe cette animation / motion" → Motion (connecteur quand disponible, ci-dessous)
- une section de storyboard / bande de trames 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 êtes sur le point de récupérer depuis Figma ; après, dites où l'artefact a atterri (le chemin gelé / le sidecar / le dossier 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 refs…] [--format svg|png|jpg|pdf] [--scale 2] [--description "..."] [--entity "..."]
Génère via REST, nettoie SVG, gèle sous .media/images/, ajoute le manifeste avec provenance, régénère .media/index.md (l'inventaire d'utilisation des médias partagé), 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 de l'index + <img alt>) ; ajoutez --entity "<nom>" pour les marques nommées afin que resolve --entity de l'utilisation des médias les trouve plus tard (les correspondances d'entité fonctionnent 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 par 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-la à N commandes séparées lors de l'extraction des ressources d'une trame entière. --description/--entity s'appliquent à chaque nœud du lot, alors regroupez les nœuds qui partagent un objectif. Les 429 sont également relancés automatiquement avec backoff, quel que soit le cas.
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 par Enterprise en amont : sur d'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 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 au lieu de dupliquer les valeurs.
Chemin des variables non-Enterprise (testé sur le terrain) : les variables REST sont limitées par Enterprise, mais un connecteur compatible peut fournir les 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é ; 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 est en aval (résolution var() des composants, rafraîchissement, variables CSS d'exécution) est la machinerie livrée. Étiquetez-le pour l'utilisateur : "tokens via le connecteur Figma — les plans Enterprise 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 de sous-composants), donc le var(--slug, littéral) importé remplit le recolor 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>'
Arbre de nœuds → HTML modifiable à 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 auto-rasterisé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 héro) : après l'importation, rendez le fragment et comparez-le aux 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 correspond à des limites verticalement rognées (le mappeur é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 mappeur ne couvre pas, signalez-la — ne modifiez pas le fragment manuellement en silence. - Remplissage lié à un token importé →
var(--slug, #littéral)— la propagation du rafraîchissement de la marque. - Lié à un token inconnu → littéral + indicateur
data-figma-unresolved. La commande vous le dit ; proposez à l'utilisateur : exécuteztokenssur le fichier source (ou de 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.
Motion (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, ne plante 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 passez sa sortie aux helpers purs dans @hyperframes/core/figma ; sinon, demandez une exportation native :
- Récupérez le contexte de motion 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(rawResponse, { selectorFor, repeat })de@hyperframes/core/figma— ne transcrivez jamais les numéros d'image clé à la main. L'helper encode les règles de décodage testées sur le terrain de manière mécanique : 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 (segments inférieurs à la milliseconde à des temps ≈0,9999→1 sont la réinitialisation instantanée de la boucle, pas une motion créée — l'enveloppe est réalisée par le redémarragerepeat), et préserve les courbes bezier textuellement.selectorFordoit 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écuteznode skills/figma/scripts/verify-motion.mjs --reference <export.mp4> --render <render.mp4> --crop LxH+X+Y— il compare les deltas d'énergie de motion (la fidélité d'importation statique s'annule) et échoue en dessous de 15 dB de PSNR de motion minimum (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 en tant que<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 en tant que
<video class="clip">. Exception : les pistes pilotées par shader — le chemin d'exportation de Figma aplatit les shaders à la couleur de base (voir Shaders ci-dessous), donc une cuisson y perd silencieusement le shader ; demandez à l'utilisateur une exportation Figma native à la place. 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 dansmotionEase.ts; signalez le recul à 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 s'aplatissent à la couleur de base), et la source du shader n'est accessible que pour les styles publiés dans la bibliothèque (siège payant). Chemin par défaut : demandez à l'utilisateur d'exporter la trame du shader nativement dans Figma (PNG ou Motion MP4), puis importez-la en tant que ressource de Phase 1 / clip. N'essayez pas la capture de pixels du connecteur pour un shader — cela produirait silencieusement la mauvaise chose.
Storyboards (une SECTION d'images de scène → animation)
La règle cardinale : les trames de storyboard sont des IMAGES CLÉS, pas des diapositives. Deux trames 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
…
[tronqué pour la traduction]