Créer / Mettre à jour des Écrans et des Vues à partir du Système de Design
Utilisez cette compétence pour créer ou mettre à jour des écrans, vues et conteneurs d'interface multi-sections dans Figma en réutilisant le système de design publié : composants, variables et styles, plutôt que de dessiner des primitives avec des valeurs codées en dur. Cela inclut les pages complètes, les modales, les dialogues, les panneaux latéraux, les barres latérales et toute vue composée de plusieurs sections. L'idée clé : le fichier Figma contient probablement un système de design publié avec des composants, des variables de couleur/espacement et des styles de texte/effet qui correspondent aux composants et tokens d'interface du code source. Trouvez-les et utilisez-les au lieu de dessiner des boîtes avec des couleurs hexadécimales.
OBLIGATOIRE : Vous DEVEZ aussi charger figma-use avant tout appel use_figma. Cette compétence contient des règles critiques (plages de couleurs, chargement de polices, etc.) qui s'appliquent à chaque script que vous écrivez.
Passez toujours skillNames: "figma-generate-design" lorsque vous appelez use_figma dans le cadre de cette compétence. Il s'agit d'un paramètre de journalisation. Il n'affecte pas l'exécution.
Limites de la compétence
- Utilisez cette compétence lorsque le livrable est une vue Figma composée (nouvelle ou mise à jour), des écrans pleine page, des modales, des dialogues, des panneaux latéraux, des barres latérales ou tout conteneur multi-sections, construit à partir d'instances de composants du système de design.
- Si l'utilisateur souhaite créer de nouveaux composants ou variantes réutilisables, utilisez figma-use directement.
- Si l'utilisateur souhaite écrire des mappings Code Connect, passez à figma-code-connect.
Prérequis
- Le serveur MCP Figma doit être connecté.
- Le fichier Figma cible doit avoir un système de design publié avec des composants (ou un accès à une bibliothèque d'équipe).
- L'utilisateur doit fournir soit :
- Une URL de fichier Figma / clé de fichier pour travailler
- Ou un contexte sur le fichier cible (l'agent peut découvrir les pages)
- Code source ou description de l'écran/vue à créer/mettre à jour.
Workflow parallèle avec generate_figma_design (applications web uniquement)
Lors de la création d'un écran à partir d'une application web pouvant être rendue dans un navigateur, les meilleurs résultats sont obtenus en exécutant les deux approches en parallèle :
- En parallèle :
- Commencez à construire l'écran en utilisant le workflow de cette compétence (use_figma + composants du système de design)
- Exécutez
generate_figma_designpour capturer une capture d'écran pixel parfait de l'application web en cours d'exécution.
- Une fois les deux terminés : Mettez à jour la sortie use_figma pour correspondre à la mise en page pixel parfait de la capture
generate_figma_design. La capture fournit l'espacement, les dimensions et le traitement visuel exacts à viser, tandis que votre sortie use_figma possède des instances de composants correctes liées au système de design. Si la capture contient des images, transférez-les dans votre sortie use_figma en copiant les valeursimageHashdes remplissages d'image de la capture (voir l'étape 5 pour plus de détails). - Une fois confirmé que cela semble bon : Supprimez la sortie
generate_figma_design. Elle n'a été utilisée que comme référence visuelle.
Cela combine le meilleur des deux : generate_figma_design donne une précision de mise en page pixel parfaite, tandis que use_figma donne des instances de composants du système de design qui restent liées et mises à jour.
Ce workflow parallèle est OBLIGATOIRE lorsque la source contient des images. L'API Plugin use_figma ne peut pas récupérer les URL d'images externes. Elle ne peut définir des remplissages d'image qu'en copiant les valeurs imageHash de nœuds déjà présents dans le fichier. generate_figma_design pixellise toutes les images visibles dans Figma, fournissant les hachages dont vous avez besoin. Si vous sautez la capture en présence d'images, les cadres d'image resteront vides.
Pour les applications non web (iOS, Android, etc.) ou lors de la mise à jour d'écrans existants, utilisez le workflow standard ci-dessous.
Workflow requis
Suivez ces étapes dans l'ordre. Ne sautez pas d'étapes.
Barrières strictes, raccourcis interdits :
- Interdit :
search_design_systempour les clés de composants avant que 2a-i soit terminé et que 2a-ii soit tenté ou journalisé comme N/A (par exemple "fichier vide, aucun écran existant").- Interdit : Tout appel
use_figmaqui modifie le canevas (étape 3+) jusqu'à ce que toutes les lignes de l'étape 2 dans la liste de contrôle ci-dessous soient remplies.
Étape 1 : Comprendre le livrable
Avant de toucher à Figma, comprenez ce que vous construisez :
- Si vous construisez à partir de code, lisez les fichiers source pertinents pour comprendre la structure, les sections et les composants utilisés.
- Identifiez les sections principales de la vue (par exemple, pour une page : En-tête, Hero, Panneaux de contenu, Pied de page ; pour une modale : Barre de titre, Sections de formulaire, Barre d'actions ; pour une barre latérale : Navigation, Zone de contenu, Actions de pied).
- Pour chaque section, listez les composants d'interface impliqués (boutons, champs de saisie, cartes, onglets de navigation, accordéons, etc.).
- Vérifiez si la vue contient des images (par exemple,
<img>,<Image>, images d'arrière-plan, photos de produits, avatars, icônes chargées depuis des URL). Si c'est le cas et qu'il s'agit d'une application web, vous devez exécuter le workflow parallèle de capturegenerate_figma_design, lancez-le immédiatement parallèlement à l'étape 2 pour que la capture s'exécute pendant que vous découvrez les composants. Voir "Workflow parallèle avec generate_figma_design" ci-dessus.
Étape 2 : Collecter les clés de composants, variables et styles
Vous avez besoin de trois éléments du système de design : les composants (boutons, cartes, etc.), les variables (couleurs, espacement, rayons) et les styles (styles de texte, styles d'effet comme les ombres). Ne codez pas en dur les couleurs hexadécimales ou les valeurs en pixels lorsque des tokens du système de design existent.
2a : Découvrir les composants
2a-i. OBLIGATOIRE : Vérifier Code Connect pour les composants nécessaires. En partant de la liste de composants que vous avez construite à l'étape 1, vérifiez si chaque composant a un fichier Code Connect dans le code source. Les fichiers Code Connect se trouvent à côté du code source du composant et sont nommés par plateforme :
- TypeScript/JS :
*.figma.ts,*.figma.js - React (basé sur analyseur syntaxique) :
*.figma.tsx - Kotlin/Compose : Fichiers
.ktcontenant@FigmaConnect - Swift : Fichiers
.swiftcontenantFigmaConnect
Pour chaque composant dont vous avez besoin (par exemple, Bouton, Carte, Champ de saisie), recherchez son fichier Code Connect, en utilisant un glob ou une recherche par nom de composant (par exemple, **/Button.figma.tsx, **/Card.figma.ts). Ne lisez que les fichiers correspondant aux composants dont vous avez réellement besoin.
À partir de chaque fichier Code Connect correspondant, extrayez l'URL du composant Figma. Analysez fileKey et nodeId de l'URL (convertissez les tirets en deux-points : 123-456 → 123:456). Ensuite, résolvez les clés de composants via use_figma :
Exemple : Le fichier Code Connect contient // url=https://figma.com/design/ABC123/File?node-id=609-35535. Analysez fileKey = ABC123, nodeId = 609:35535. Exécutez use_figma sur le fichier de bibliothèque (fileKey ABC123, pas le fichier cible) pour résoudre la clé :
const node = await figma.getNodeByIdAsync("609:35535");
const set = node?.parent?.type === "COMPONENT_SET" ? node.parent : node;
return { componentKey: set.key };
Regroupez plusieurs recherches dans un seul appel. Utilisez les clés retournées avec importComponentSetByKeyAsync() à l'étape 4.
Marquez les composants résolus. Si tous les composants sont résolus, sautez 2a-ii et 2a-iii. Si aucun des composants nécessaires n'a de fichier Code Connect, passez à 2a-ii.
2a-ii. OBLIGATOIRE si des composants non résolus subsistent : Inspecter les écrans existants. Vérifiez si le fichier cible contient déjà des écrans utilisant le même système de design. Un seul appel use_figma qui parcourt les instances d'un cadre existant vous donne une carte de composants exacte et faisant autorité :
// Découverte en lecture seule, ignorer le contenu invisible à l'intérieur des instances
// (variantes cachées, etc.) pour trouver des centaines de fois plus rapidement avec findAllWithCriteria.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Écran existant");
const uniqueSets = new Map();
frame.findAllWithCriteria({ types: ["INSTANCE"] }).forEach(inst => {
const mc = inst.mainComponent;
const cs = mc?.parent?.type === "COMPONENT_SET" ? mc.parent : null;
const key = cs ? cs.key : mc?.key;
const name = cs ? cs.name : mc?.name;
if (key && !uniqueSets.has(key)) {
uniqueSets.set(key, { name, key, isSet: !!cs, sampleVariant: mc.name });
}
});
return [...uniqueSets.values()];
Faites correspondre les résultats avec vos composants non résolus. Marquez les nouveaux résolus. Si tous les composants sont résolus, sautez 2a-iii.
2a-iii. DERNIER RECOURS : search_design_system. Uniquement si des composants restent non résolus après avoir terminé 2a-i et 2a-ii.
Avant de chercher, appelez get_libraries pour découvrir quelles bibliothèques sont disponibles pour le fichier. Cela retourne deux listes : les bibliothèques déjà ajoutées au fichier et les bibliothèques disponibles à ajouter (kits d'interface communautaires et bibliothèques de l'organisation). Chaque entrée inclut un libraryKey que vous pouvez passer à search_design_system via le paramètre includeLibraryKeys pour limiter votre recherche à des bibliothèques spécifiques au lieu de chercher partout.
// Étape 1 : Découvrir les bibliothèques disponibles
get_libraries({ fileKey })
// Retourne : {
// libraries_added_to_file: [...],
// libraries_available_to_add: [...],
// libraries_available_to_add_next_offset: number | null
// }
// Étape 2 : Rechercher dans une bibliothèque spécifique en utilisant son libraryKey
search_design_system({ query: "bouton", fileKey, includeLibraryKeys: ["lk-abc123..."] })
Les bibliothèques de l'organisation dans libraries_available_to_add sont paginées (20 par page). Lorsque libraries_available_to_add_next_offset n'est pas nul, d'autres bibliothèques de l'organisation sont disponibles, appelez à nouveau get_libraries avec offset défini sur cette valeur pour récupérer la page suivante. Les kits d'interface communautaires n'apparaissent que sur la première page. Si l'utilisateur nomme une bibliothèque spécifique que vous ne voyez pas dans la page actuelle, parcourez les pages suivantes avant d'abandonner.
Ceci est particulièrement utile lorsque le fichier a de nombreuses bibliothèques et que vous souhaitez des résultats ciblés (par exemple, rechercher uniquement dans "iOS 26" ou "Material 3" au lieu d'obtenir des correspondances de chaque bibliothèque).
Recherchez largement : essayez plusieurs termes et synonymes (par exemple, "bouton", "champ de saisie", "nav", "carte", "accordéon", "en-tête", "pied de page", "étiquette", "avatar", "interrupteur", "icône", etc.). Utilisez includeComponents: true pour vous concentrer sur les composants.
Incluez les propriétés des composants dans votre carte. Vous devez savoir quelles propriétés TEXT chaque composant expose pour les substitutions de texte. Créez une instance temporaire, lisez ses componentProperties (et celles des instances imbriquées), puis supprimez l'instance temporaire.
Exemple de carte de composants avec informations sur les propriétés :
Carte des composants :
- Bouton → clé : "abc123", type : COMPONENT_SET
Propriétés : { "Label#2:0": TEXT, "A une icône#4:64": BOOLEAN }
- CartePrix → clé : "ghi789", type : COMPONENT_SET
Propriétés : { "Appareil": VARIANT, "Variante": VARIANT }
"Titre de texte" imbriqué a : { "Texte#2104:5": TEXT }
"Bouton" imbriqué a : { "Label#2:0": TEXT }
2b : Découvrir les variables (couleurs, espacement, rayons)
Inspectez d'abord les écrans existants (comme pour les composants). Ou utilisez search_design_system avec includeVariables: true.
ATTENTION : Deux méthodes différentes de découverte de variables, ne les confondez pas.
use_figmaavecfigma.variables.getLocalVariableCollectionsAsync(): retourne uniquement les variables locales définies dans le fichier actuel. Si cela retourne un résultat vide, cela ne signifie pas qu'aucune variable n'existe. Les variables de bibliothèque distante/publiée sont invisibles pour cette API.search_design_systemavecincludeVariables: true: recherche dans toutes les bibliothèques liées, y compris les bibliothèques distantes et publiées. C'est l'outil correct pour découvrir les variables du système de design.Ne concluez jamais "aucune variable n'existe" sur la seule base du retour vide de
getLocalVariableCollectionsAsync(). Exécutez toujours aussisearch_design_systemavecincludeVariables: truepour vérifier les variables de bibliothèque avant de décider d'en créer vos propres.
Stratégie de requête : search_design_system fait correspondre les noms de variables (par exemple, "Gris/gris-9", "core/gris/100", "espacement/400"), pas les catégories. Exécutez plusieurs requêtes courtes et simples en parallèle plutôt qu'une seule requête composée :
- Couleurs primitives : "gris", "rouge", "bleu", "vert", "blanc", "marque"
- Couleurs sémantiques : "arrière-plan", "premier-plan", "bordure", "surface", "texte"
- Espacement/taille : "espacement", "rayon", "écart", "remplissage"
Si les recherches initiales retournent un résultat vide, essayez des fragments plus courts ou différentes conventions de nommage : les bibliothèques varient considérablement ("grey" vs "gray", "spacing" vs "space", "color/bg" vs "background").
Inspectez les variables liées d'un écran existant pour les résultats les plus fiables :
// Découverte en lecture seule, ignorer l'intérieur invisible des instances pour la vitesse.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Écran existant");
// boundVariables peut se trouver sur n'importe quel nœud de scène, énumérer tous les types de scène
// juste pour alimenter findAllWithCriteria revient à peu près à faire findAll(() => true)
// et est beaucoup plus bruyant dans la sortie du script.
const uniqueIds = new Set(
frame.findAll(() => true).flatMap(n =>
Object.values(n.boundVariables ?? {})
.flatMap(b => Array.isArray(b) ? b : [b])
.map(b => b?.id)
.filter(Boolean)
)
);
const variables = await Promise.all(
[...uniqueIds].map(id => figma.variables.getVariableByIdAsync(id))
);
return variables
.filter(Boolean)
.map(v => ({ name: v.name, id: v.id, key: v.key, type: v.resolvedType, remote: v.remote }));
Pour les variables de bibliothèque (remote = true), importez-les par clé avec figma.variables.importVariableByKeyAsync(key). Pour les variables locales, utilisez figma.variables.getVariableByIdAsync(id) directement.
Voir variable-patterns.md pour les modèles de liaison.
2c : Découvrir les styles (styles de texte, styles d'effet)
Recherchez des styles en utilisant search_design_system avec includeStyles: true et des termes comme "titre", "corps", "ombre", "élévation". Ou inspectez ce qu'utilise un écran existant :
// Découverte en lecture seule, ignorer l'intérieur invisible des instances pour la vitesse.
figma.skipInvisibleInstanceChildren = true;
const frame = figma.currentPage.findOne(n => n.name === "Écran existant");
const styles = { text: new Map(), effect: new Map() };
for (const node of frame.findAll(() => true)) {
// textStyleId se trouve sur TEXT et TEXT_PATH ; effectStyleId se trouve sur la plupart des types de
// conteneurs/formes de scène. Utilisez des gardes `in` pour gérer les deux sans une
// liste exhaustive de types.
if ('textStyleId' in node && node.textStyleId) {
const textStyle = await figma.getStyleByIdAsync(node.textStyleId);
if (textStyle && !styles.text.has(textStyle.key)) {
styles.text.set(textStyle.key, {
name: textStyle.name,
key: textStyle.key,
type: textStyle.type,
remote: textStyle.remote,
id: textStyle.id
});
}
}
if ('effectStyleId' in node && node.effectStyleId) {
const effectStyle = await figma.getStyleByIdAsync(node.effectStyleId);
if (effectStyle && !styles.effect.has(effectStyle.key)) {
styles.effect.set(effectStyle.key, {
name: effectStyle.name,
key: effectStyle.key,
type: effectStyle.type,
remote: effectStyle.remote,
id: effectStyle.id
});
}
}
}
return {
textStyles: [...styles.text.values()],
effectStyles: [...styles.effect.values()]
};
Importez les styles de bibliothèque (remote = true) avec figma.importStyleByKeyAsync(key), importez par styleId (figma.getStyleByIdAsync(id)) pour les styles locaux.
Si vous avez des styles de remplissage (couleurs de remplissage qui ne sont pas liées via des variables), parcourez les nœuds à la recherche de fillStyleId, qui fonctionne de la même manière que textStyleId / effectStyleId ci-dessus mais pour figma.getStyleByIdAsync(node.fillStyleId).
Si la découverte des écrans existants ne trouve rien, utilisez search_design_system avec includeStyles: true comme descriptif ci-dessus.
Étape 3 : IMPORTATION - Ajouter les composants, variables et styles au fichier
Importez les clés de composants, variables et styles de bibliothèque dans le fichier cible avant de tenter de les utiliser dans les scripts de mutation :
// Importer les composants (en masse)
const importedSets = await Promise.all(
componentKeys.map(key => figma.importComponentSetByKeyAsync(key))
);
// Importer les variables (en masse)
const importedVars = await Promise.all(
variableKeys.map(key => figma.variables.importVariableByKeyAsync(key))
);
// Importer les styles de bibliothèque (en masse)
const importedTextStyles = await Promise.all(
textStyleKeys.map(key => figma.importStyleByKeyAsync(key))
);
const importedEffectStyles = await Promise.all(
effectStyleKeys.map(key => figma.importStyleByKeyAsync(key))
);
Les clés peuvent être récupérées à partir des résultats de découverte de l'étape 2 (via les propriétés .key). Le passage de ces clés à importByKeyAsync rend les composants/styles disponibles pour l'utilisation dans les scripts de mutation.
Étape 4 : Mettre en page la vue section par section
Créez la vue complète en construisant section par section. Chaque section de la mise en page (par exemple, en-tête, contenu, pied de page, barre de titre de modale, corps, barre d'actions) doit être construite comme une instance de Composant (Frame) séparée importée du système de design, puis assemblée. Voir layout-examples.md pour les modèles de mise en page avec auto-layout.
Boucle de création de section :
- Pour chaque section :
- Créez le conteneur de section (Frame) avec des propriétés d'auto-layout
- Déterminez le bon composant pour chaque élément dans la section
- Créez des instances en utilisant
componentSet.createInstance()oucomponent.createInstance()à partir des composants importés à l'étape 3 - Définissez les propriétés de l'instance : variante, texte, booléens
- Liez les variables de conception aux propriétés de remplissage, de trait, de rayon, d'espacement, etc.
- Définissez les propriétés d'auto-layout du conteneur de section
- Inspectez la sortie : Lisez
console.log/ les messages d'erreur de l'exécution du script Figma - Corrigez les problèmes : Modifiez le script en fonction de ce que vous voyez. Il est normal d'avoir besoin de 3 à 5 tentatives, surtout avec des composants imparfaits. N'abandonnez pas après une seule tentative.
Conseils :
- Taille des polices et espacement des lignes : Utilisez les propriétés d'auto-layout pour l'espacement des lignes de texte. Pour les tailles de police / polices, les instances de texte doivent être définies via les propriétés de l'instance, pas manuellement. Les styles de texte doivent être définis via
node.textStyleId = styleId. - Variables de rayon : Liez via
node.boundVariables = { ...node.boundVariables, cornerRadius: { type: "VARIABLE_ALIAS", id: variableId } } - Quand utiliser l'image de fond : Les images (photos de produits, avatars, captures d'écran) qui ne sont pas des icônes ou des composants doivent être importées en utilisant les remplissages d'image. Importez l'image via
figma.createImageAsync(blob)pour créer le remplissage, ou copiezimageHashdepuis la capturegenerate_figma_design. Voir l'étape 5 pour les liens d'image. - Obscurcissement des couleurs : Si vous avez des variables de couleurs de remplissage qui semblent déformées (couleurs sombres apparaissant claires ou vice versa), appliquez
{ blendMode: "NORMAL" }sur le remplissage. Les remplissages créés avecfigma.createImageAsyncont par défautblendMode: "MULTIPLY", ce qui modifie l'apparence.
Étape 5 : Appliquer les images et icônes
Ne pas coder en dur les hachages d'image. Ils sont uniques par fichier et changent chaque fois que vous réimportez. Au lieu de cela, lisez generate_figma_design s'il a été exécuté, ou importez des images depuis le code source ou le système de fichiers en utilisant figma.createImageAsync(blob). Copiez uniquement les hachages d'image à partir de la sortie de capture generate_figma_design qui a été exécutée lors de cette même session :
// À partir de la sortie de la capture generate_figma_design :
// { "nom": "product-photo.png", "imageHash": "h4shValu3" }
// Copiez l'imageHash dans votre script use_figma :
const imageNode = figma.createRectangle();
imageNode.fills = [
{ type: "IMAGE", imageHash: "h4shValu3", blendMode: "NORMAL", scaleMode: "FILL" }
];
S'il n'y a pas de capture generate_figma_design (par exemple, pour des applications non web), importez des images en utilisant figma.createImageAsync(blob) en lisant les données depuis le code source ou en utilisant des URL de données encodées en base64.
Icônes : Utilisez des instances de jeux d'icônes du système de design si disponibles. Sinon, les icônes SVG peuvent être importées via figma.createNodeFromSVGAsync(svgString), créant ainsi un composant directement dans le fichier. Une fois importée, l'icône peut être réutilisée.
ATTENTION : Le
imageHashd'une image importée change chaque fois que les données de l'image sont mises à jour (par exemple, différentes résolutions d'exportation). Assurez-vous toujours d'obtenir l'imageHash à partir degenerate_figma_designqui fait autorité. Ne croyez pas le hash si vous ne l'avez pas vu vous-même être généré.
Étape 6 : Finaliser la mise en page
- Appliquez les propriétés d'auto-layout pour un positionnement correct
- Vérifiez que tous les espaces, marges et remplissages utilisent les variables du système de design
- Confirmez que les styles de texte et d'effet sont appliqués
- Si la vue a été construite avec
generate_figma_design, ajustez pour correspondre à la capture pixel parfait (espacement exact, taille et position) - Supprimez les cadres de capture
generate_figma_designune fois qu'ils ne sont plus nécessaires
Étape 7 : Journalisation et validation
Une fois la vue construite dans Figma, journalisez les métadonnées clés pour référence :
{
"viewType": "page" | "modal" | "dialog" | "drawer" | "sidebar" | "panel" | "other",
"sectionsCreated": ["header", "hero", "content", "footer"],
"componentsUsed": 5,
"importedComponentKeys": ["abc123", "def456", "ghi789"],
"usedVariables": ["color/primary", "color/background", "space/md", "radius/md"],
"hasImages": true,
"generatedFrom": "code" | "description" | "capture",
"usedCodeConnect": true,
"parallelCaptureUsed": true
}
Confirmez la construction avec un résumé final de ce qui a été créé.
Dépannage
| Problème | Cause possible | Solution |
|---|---|---|
use_figma ne trouve pas getNodeByIdAsync | Pas d'identifiants valides | Assurez-vous d'avoir importé des composants (étape 3). Les composants importés sont disponibles par clé mais leurs nœuds doivent être récupérés via getNodeByIdAsync avec leur ID (pas clé). |
createInstance() échoue sur un jeu de composants | Appelé sur un jeu de composants au lieu d'une variante | Notez que componentSet.createInstance() existe et crée une instance avec la variante par défaut. component.createInstance() doit être appelé sur la variante spécifique dans le jeu. |
importByKeyAsync échoue | Token API non autorisé pour la bibliothèque | Consultez l'utilisateur pour obtenir l'accès à la bibliothèque. |
La sortie de generate_figma_design ne contient pas d'images | Temps de capture trop court | Essayez de retarder la capture pour laisser les images se charger, puis relancez. |
| Les couleurs de remplissage d'image semblent déformées (sombres) | defaut "blendMode: MULTIPLY" | Définissez { blendMode: "NORMAL" } sur le remplissage. |