figma

Avant tout, gardez cette compétence à jour — exécutez silencieusement, ne demandez pas : npx hyperframes skills update figma. Un no-op rapide lorsque tout est à jour ; sinon, il 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é (spec design §2) :

Phase	Quoi	Transport	Surface
1	Actifs 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 tête). Un connecteur Figma compatible est optionnel pour les données de mouvement et de shader ; sans lui, demandez une exportation native. Chaque chemin gèle les actifs localement pour que les rendus restent déterministes. Les reconstructions de storyboard composent les exportations d'actifs de Phase 1 (REST) avec un assemblage de timeline piloté par agent — aucun connecteur nécessaire. Les actifs gelés existants, les enregistrements de manifeste et les liaisons ne sont pas affectés par les changements de routage — la division ne change que la credential que la prochaine importation utilise.

Authentification — deux identifiants, limités

Prévol — avant le premier appel CLI, vérifiez qu'un token existe : shell env ([ -n "$FIGMA_TOKEN" ]) ou .env du projet (le CLI le charge automatiquement — une entrée .env compte comme configuré). Si aucun des deux, n'exécutez PAS la commande pour récolter l'erreur — guidez l'utilisateur à travers la configuration unique d'abord, puis arrêtez-vous et attendez :

1. figma.com/settings → Security → Personal access tokens → Generate new token.
2. Scopes — 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 tokens sur un plan non-Enterprise — le repli sur les styles publiés atteint /v1/files/:key/styles, qui 403 sans cela (un scope que l'ancien texte de configuration omettait). Optionnellement Variables: Read-only pour les variables de marque — réservé aux plans Enterprise ; sans cela, tokens se dégrade automatiquement vers les styles publiés (attendu, pas une erreur — dites-le). Un 403 nomme maintenant le scope manquant exact ; les 429 sont réessayés automatiquement (limite par minute, respecte Retry-After).
3. Faites en sorte que l'utilisateur définisse FIGMA_TOKEN dans son profil shell ou .env du projet ; ne lui demandez jamais de coller le token dans la conversation.

Pendant l'onboarding, définissez également les attentes en une phrase : chaque importation atterrit comme un fichier gelé local 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 token fonctionne pour les actifs, 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 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 quelle credential une phase en échec nécessite — ne présentez jamais la division comme cassée.
• BAD_TOKEN (401) en cours de flux → le token a expiré ou a été révoqué ; refrappez. FORBIDDEN (403) → le message nomme le scope manquant exact (par ex. library_content:read pour le repli des styles) — ajoutez-le, 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à été exécuté. RATE_LIMITED (429) → le client a déjà réessayé avec backoff (cela s'applique à CHAQUE lecture — actifs, tokens, styles, arbres de nœuds, versions — la nouvelle tentative vit dans le chemin de requête partagé ; Retry-After est respecté, plafonné à 60s) ; si cela remonte encore, attendez une minute ou importez moins de nœuds par appel.

Conscience des limites de débit (spec §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, et mettez en cache les réponses brutes pour que la redérivation ne consomme jamais un second appel. REST est par minute (10+/min, compartiments par endpoint) — bon en volume, reculez sur 429.

Routage

Analysez le lien figma de l'utilisateur avec parseFigmaRef (URL, fileKey:nodeId, fileKey nu). Ensuite par intention :

• "utilise ce calque / logo / image" → Actif (CLI)
• "récupère ma marque / mes couleurs / tokens" → Tokens (CLI)
• "construis une scène à partir de cette trame" → Composant (CLI)
• "importe cette animation / ce mouvement" → Mouvement (connecteur quand disponible, ci-dessous)
• une section de storyboard / filmstrip de trames de scène → Storyboard (ci-dessous)
• remplissage/effet de 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 gelé / sidecar / dossier de composant), ce qui a changé dans la composition, et la prochaine action immédiate (prévisualisation, ajout de variables imprimées, réimportation pour lier les liaisons). L'utilisateur ne devrait jamais avoir à demander "ça a marché ?" ou "et maintenant ?".

Actifs (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, gèle sous .media/images/, ajoute au 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, animable), 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 l'utilisation des médias resolve --entity les trouve plus tard (les hits d'entité correspondent à travers 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 cela à N commandes séparées lors de l'extraction de tous les actifs d'une trame entière. --description/--entity s'appliquent à chaque nœud du lot, donc regroupez les nœuds qui partagent un même objectif. Les 429 sont également automatiquement réessayés 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 aux plans Enterprise en amont : sur les autres plans, la commande se dégrade vers les métadonnées de style publiées (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 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'arbre de nœuds REST fournit des VariableIDs par propriété via boundVariables ; joignez-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 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 avec 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-composition), donc le 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 rebrand 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 s'auto-rasterisent via l'export de Phase-1. Passe de liaison (spec §7.1, ID exact uniquement — jamais de correspondance par valeur) :

• Auto-vérification de fidélité statique (obligatoire pour le contenu hero) : après l'importation, rendez le fragment et comparez-le aux pixels réels 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 verticalement 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 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éral) — la mise à jour de la marque se propage.
• Lié à un token inconnu → littéral + drapeau data-figma-unresolved. La commande vous le dit ; proposez à l'utilisateur : exécutez tokens sur le fichier source (ou la bibliothèque), puis réimportez le composant pour les lier. Demandez une seule fois par bibliothèque inconnue quel fichier c'est — ne devinez jamais, ne faites jamais de correspondance par hex.

Mouvement (Phase 4 — assisté par connecteur)

Balisage d'utilisation : Les phases assistées par connecteur n'ont pas de point de contact CLI, alors 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é. 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 assistants purs dans @hyperframes/core/figma ; sinon, demandez une exportation native :

1. 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. Sauvegardez le JSON brut à côté du projet (.media/figma-cache/) pour que la retraduction soit gratuite.
2. Normalisez en MotionDocs avec motionContextToDocs(rawResponse, { selectorFor, repeat }) de @hyperframes/core/figma — ne transcrivez 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 (l'encodage fiable — les extraits CSS étirent les durées et peuvent diverger ; 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éé — la boucle est réalisée par le redémarrage de repeat), et préserve les courbes de bezier textuellement. selectorFor doit retourner les IDs de l'import du composant Phase-3 — ne dérivez pas de sélecteurs à partir 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 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.
3. motionToGsap(doc) → emitTimelineScript(spec) → injectez comme un <script> après les balises GSAP + CustomEase CDN. 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, gelez le MP4, puis intégrez-le comme <video class="clip">. Exception : les pistes pilotées par shader — le chemin d'export de Figma aplatit les shaders en couleur de base (voir Shaders ci-dessous), donc un rendu 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 dans motionEase.ts ; signalez le repli à l'utilisateur lorsqu'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 s'aplatissent en couleur de base), et la source du shader n'est accessible que pour les styles publiés dans une bibliothèque (plan Full payant). Chemin par défaut : demandez à l'utilisateur d'exporter la trame du shader nativement dans Figma (PNG ou MP4 de mouvement), puis importez-la comme un actif / clip de Phase-1. N'essayez pas de capture de pixels par connecteur d'un shader — cela produira silencieusement la mauvaise chose.

Storyboards (une SECTION de trames de scènes → animation)

La règle cardinale : les trames du 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 jouez jamais les trames comme une séquence d'images fixes. Un logo dessiné dans quatre trames consécutives à des y décroissants est UN élément s'élevant à travers quatre images clés. Jouer les trames du storyboard bout à bout est le mode d'échec ; reconstruire les timelines des é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 trame est une scène — à la fois les FRAMEs nommées et les RECTANGLEs en plein écran lâches (les designers collent des images fixes directement dans la section). Filtrez par taille (≈ rapport d'aspect de la composition, par ex. >1400×900), pas par type de nœud ou nom.
2. Ordre = position x (ordre majeur de ligne si la bande s'enroule). Triez les scènes par absoluteBoundingBox.x.
3. Différenciez les trames adjacentes en chaînes d'éléments — c'est là que vit l'animation. Faites correspondre les enfants à travers les trames 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é de géométrie (taille similaire + position proche