Composants Code Connect

Aperçu

Cette compétence vous aide à connecter les composants de conception Figma à leurs implémentations de code correspondantes en utilisant la fonctionnalité Code Connect de Figma. Elle analyse la structure de conception Figma, recherche les composants correspondants dans votre base de code et établit des mappings qui maintiennent la cohérence conception-code.

Limites de la compétence

• Utilisez cette compétence pour les workflows get_code_connect_suggestions + send_code_connect_mappings.
• Si la tâche nécessite d'écrire sur le canevas Figma avec des scripts de Plugin API, basculez vers figma-use.
• Si la tâche consiste à construire ou mettre à jour un écran complet dans Figma à partir du code ou d'une description, basculez vers figma-generate-design.
• Si la tâche consiste à implémenter du code produit à partir de Figma, basculez vers figma-implement-design.

Prérequis

• Le serveur Figma MCP doit être connecté et accessible
• L'utilisateur doit fournir une URL Figma avec l'ID de nœud : https://figma.com/design/:fileKey/:fileName?node-id=1-2
  • IMPORTANT : L'URL Figma doit inclure le paramètre node-id. Le mapping Code Connect échouera sans lui.
• OU lors de l'utilisation de figma-desktop MCP : L'utilisateur peut sélectionner un nœud directement dans l'application Figma de bureau (aucune URL requise)
• IMPORTANT : Le composant Figma doit être publié dans une bibliothèque d'équipe. Code Connect fonctionne uniquement avec les composants publiés ou les ensembles de composants.
• IMPORTANT : Code Connect n'est disponible que sur les plans Organisation et Entreprise.
• Accès à la base de code du projet pour la numérisation des composants

Workflow requis

Suivez ces étapes dans l'ordre. Ne sautez pas d'étapes.

Étape 1 : Obtenir les suggestions Code Connect

Appelez get_code_connect_suggestions pour identifier tous les composants non mappés en une seule opération. Cet outil :

• Récupère les informations de composant à partir du scenegraph Figma
• Identifie les composants publiés dans la sélection
• Vérifie les mappings Code Connect existants et filtre les composants déjà connectés
• Retourne les noms de composants, les propriétés et les images miniatures pour chaque composant non mappé

Option A : Utilisation de figma-desktop MCP (aucune URL fournie)

Si le serveur MCP figma-desktop est connecté et que l'utilisateur n'a PAS fourni d'URL Figma, appelez immédiatement get_code_connect_suggestions. Aucune analyse d'URL n'est nécessaire — le serveur MCP de bureau utilise automatiquement le nœud actuellement sélectionné à partir du fichier Figma ouvert.

Remarque : L'utilisateur doit avoir l'application Figma de bureau ouverte avec un nœud sélectionné. fileKey n'est pas transmis en tant que paramètre — le serveur utilise le fichier actuellement ouvert.

Option B : Lorsqu'une URL Figma est fournie

Analysez l'URL pour extraire fileKey et nodeId, puis appelez get_code_connect_suggestions.

IMPORTANT : Lors de l'extraction de l'ID de nœud d'une URL Figma, convertissez le format :

• Le format URL utilise des tirets : node-id=1-2
• L'outil s'attend à des deux-points : nodeId=1:2

Analysez l'URL Figma :

• Format URL : https://figma.com/design/:fileKey/:fileName?node-id=1-2
• Clé de fichier d'extraction : :fileKey (segment après /design/)
• Extraire l'ID de nœud : 1-2 de l'URL, puis convertir en 1:2 pour l'outil

get_code_connect_suggestions(fileKey=":fileKey", nodeId="1:2")

Gérez la réponse :

• Si l'outil retourne "No published components found in this selection" → informez l'utilisateur et arrêtez-vous. Les composants devront peut-être être publiés dans une bibliothèque d'équipe en premier lieu.
• Si l'outil retourne "All component instances in this selection are already connected to code via Code Connect" → informez l'utilisateur que tout est déjà mappé.
• Sinon, la réponse contient une liste de composants non mappés, chacun avec :
  • Nom du composant
  • ID de nœud
  • Propriétés du composant (JSON avec noms et valeurs de propriétés)
  • Une image miniature du composant (pour inspection visuelle)

Étape 2 : Numériser la base de code pour les composants correspondants

Pour chaque composant non mappé retourné par get_code_connect_suggestions, recherchez un composant de code correspondant dans la base de code.

Qu'il faut rechercher :

• Noms de composants qui correspondent ou sont similaires au nom du composant Figma
• Structure de composant qui s'aligne avec la hiérarchie Figma
• Props qui correspondent aux propriétés Figma (variantes, texte, styles)
• Fichiers dans des répertoires de composants typiques (src/components/, components/, ui/, etc.)

Stratégie de recherche :

1. Recherchez les fichiers de composants portant des noms correspondants
2. Lisez les fichiers candidats pour vérifier la structure et les props
3. Comparez les props du composant de code avec les propriétés du composant Figma retournées à l'étape 1
4. Détectez le langage de programmation (TypeScript, JavaScript) et le framework (React, Vue, etc.)
5. Identifiez la meilleure correspondance en fonction de la similarité structurelle, en pesant :
   • Noms de props et leur correspondance avec les propriétés Figma
   • Valeurs par défaut qui correspondent aux valeurs par défaut de Figma
   • Classes CSS ou objets de style
   • Commentaires descriptifs qui clarifient l'intention
6. Si plusieurs candidats sont également bons, choisissez celui avec la correspondance d'interface de props la plus proche et documentez votre raisonnement dans un commentaire d'une ou deux phrases avant votre appel d'outil

Exemples de modèles de recherche :

• Si le composant Figma est "PrimaryButton", recherchez Button.tsx, PrimaryButton.tsx, Button.jsx
• Vérifiez les chemins de composants courants : src/components/, app/components/, lib/ui/
• Recherchez des props de variante comme variant, size, color qui correspondent aux variantes Figma

Étape 3 : Présentez les correspondances à l'utilisateur

Présentez vos résultats et laissez l'utilisateur choisir les mappings à créer. L'utilisateur peut accepter tous, certains ou aucun des mappings suggérés.

Présentez les correspondances dans ce format :

The following components match the design:
- [ComponentName](path/to/component): DesignComponentName at nodeId [nodeId](figmaUrl?node-id=X-Y)
- [AnotherComponent](path/to/another): AnotherDesign at nodeId [nodeId2](figmaUrl?node-id=X-Y)

Would you like to connect these components? You can accept all, select specific ones, or skip.

Si aucune correspondance exacte n'est trouvée pour un composant :

• Montrez les 2 candidats les plus proches
• Expliquez les différences
• Demandez à l'utilisateur de confirmer quel composant utiliser ou de fournir le chemin correct

Si l'utilisateur refuse tous les mappings, informez-le et arrêtez-vous. Aucun autre appel d'outil n'est nécessaire.

Étape 4 : Créer les mappings Code Connect

Une fois que l'utilisateur confirme ses sélections, appelez send_code_connect_mappings avec uniquement les mappings acceptés. Cet outil gère la création en lot de tous les mappings en un seul appel.

Exemple :

send_code_connect_mappings(
  fileKey=":fileKey",
  nodeId="1:2",
  mappings=[
    { nodeId: "1:2", componentName: "Button", source: "src/components/Button.tsx", label: "React" },
    { nodeId: "1:5", componentName: "Card", source: "src/components/Card.tsx", label: "React" }
  ]
)

Paramètres clés pour chaque mapping :

• nodeId : L'ID de nœud Figma (format avec deux-points : 1:2)
• componentName : Nom du composant à connecter (p. ex. "Button", "Card")
• source : Chemin d'accès au fichier du composant de code (relatif à la racine du projet)
• label : L'étiquette de framework ou de langage pour ce mapping Code Connect. Les valeurs valides incluent :
  • Web : 'React', 'Web Components', 'Vue', 'Svelte', 'Storybook', 'Javascript'
  • iOS : 'Swift UIKit', 'Objective-C UIKit', 'SwiftUI'
  • Android : 'Compose', 'Java', 'Kotlin', 'Android XML Layout'
  • Cross-platform : 'Flutter'
  • Docs : 'Markdown'

Après l'appel :

• En cas de succès : l'outil confirme que les mappings ont été créés
• En cas d'erreur : l'outil rapporte quels mappings spécifiques ont échoué et pourquoi (p. ex. "Component is already mapped to code", "Published component not found", "Insufficient permissions")

Fournissez un résumé après le traitement :

Code Connect Summary:
- Successfully connected: 3
  - Button (1:2) → src/components/Button.tsx
  - Card (1:5) → src/components/Card.tsx
  - Input (1:8) → src/components/Input.tsx
- Could not connect: 1
  - CustomWidget (1:10) - No matching component found in codebase

Exemples

Exemple 1 : Connexion d'un composant Button

L'utilisateur dit : "Connect this Figma button to my code: https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15"

Actions :

1. Analysez l'URL : fileKey=kL9xQn2VwM8pYrTb4ZcHjF, nodeId=42-15 → convertir en 42:15

2. Exécutez get_code_connect_suggestions(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15")

3. La réponse affiche : composant Button (non mappé) avec propriétés variant (primary/secondary) et size (sm/md/lg), plus une image miniature

4. Recherchez des composants Button dans la base de code : Trouvez src/components/Button.tsx

5. Lisez Button.tsx et confirmez qu'il a les props variant et size

6. Présentez à l'utilisateur :

   I found a match:
   - [Button](src/components/Button.tsx): Button at nodeId [42:15](https://figma.com/design/kL9xQn2VwM8pYrTb4ZcHjF/DesignSystem?node-id=42-15)
   
   Would you like to connect this component?

7. L'utilisateur confirme : "Yes"

8. Détectez qu'il s'agit d'un composant TypeScript React

9. Exécutez send_code_connect_mappings(fileKey="kL9xQn2VwM8pYrTb4ZcHjF", nodeId="42:15", mappings=[{ nodeId: "42:15", componentName: "Button", source: "src/components/Button.tsx", label: "React" }])

Résultat : Le composant button Figma est maintenant connecté au composant Button du code.

Exemple 2 : Composants multiples avec sélection partielle

L'utilisateur dit : "Connect components in this frame: https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-50"

Actions :

1. Analysez l'URL : fileKey=pR8mNv5KqXzGwY2JtCfL4D, nodeId=10-50 → convertir en 10:50

2. Exécutez get_code_connect_suggestions(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50")

3. La réponse affiche 3 composants non mappés : ProductCard, Badge et CustomWidget

4. Recherchez dans la base de code :

   • ProductCard : Trouvé src/components/ProductCard.tsx (props correspondent)
   • Badge : Trouvé src/components/Badge.tsx (props correspondent)
   • CustomWidget : Aucun composant correspondant trouvé

5. Présentez à l'utilisateur :

   The following components match the design:
   - [ProductCard](src/components/ProductCard.tsx): ProductCard at nodeId [10:51](https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-51)
   - [Badge](src/components/Badge.tsx): Badge at nodeId [10:52](https://figma.com/design/pR8mNv5KqXzGwY2JtCfL4D/Components?node-id=10-52)
   
   I couldn't find a match for CustomWidget (10:53).
   
   Would you like to connect these components? You can accept all, select specific ones, or skip.

6. L'utilisateur : "Just connect ProductCard, skip Badge for now"

7. Exécutez send_code_connect_mappings(fileKey="pR8mNv5KqXzGwY2JtCfL4D", nodeId="10:50", mappings=[{ nodeId: "10:51", componentName: "ProductCard", source: "src/components/ProductCard.tsx", label: "React" }])

Résultat : Seul ProductCard est connecté, selon la sélection de l'utilisateur.

Exemple 3 : Composant nécessitant une création

L'utilisateur dit : "Connect this icon: https://figma.com/design/8yJDMeWDyBz71EnMOSuUiw/Icons?node-id=5-20"

Actions :

1. Analysez l'URL : fileKey=8yJDMeWDyBz71EnMOSuUiw, nodeId=5-20 → convertir en 5:20
2. Exécutez get_code_connect_suggestions(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20")
3. La réponse affiche : composant CheckIcon (non mappé) avec propriétés color et size
4. Recherchez CheckIcon dans la base de code : Aucune correspondance trouvée
5. Recherchez des composants Icon génériques : Trouvez le répertoire src/icons/ avec d'autres icônes
6. Rapportez à l'utilisateur : "I couldn't find a CheckIcon component, but I found an icons directory at src/icons/. Would you like to:
   • Create a new CheckIcon.tsx component first, then connect it
   • Connect to a different existing icon
   • Provide the path to the CheckIcon if it exists elsewhere"
7. L'utilisateur fournit le chemin : "src/icons/CheckIcon.tsx"
8. Détectez le langage et le framework à partir du fichier
9. Exécutez send_code_connect_mappings(fileKey="8yJDMeWDyBz71EnMOSuUiw", nodeId="5:20", mappings=[{ nodeId: "5:20", componentName: "CheckIcon", source: "src/icons/CheckIcon.tsx", label: "React" }])

Résultat : Le composant CheckIcon est connecté avec succès à la conception Figma.

Meilleures pratiques

Découverte proactive des composants

Ne vous contentez pas de demander le chemin du fichier à l'utilisateur — recherchez activement votre base de code pour trouver les composants correspondants. Cela offre une meilleure expérience et détecte les opportunités de mapping potentielles.

Correspondance de structure précise

Lors de la comparaison des composants Figma avec les composants de code, allez au-delà des simples noms. Vérifiez que :

• Les props s'alignent (types de variantes, options de taille, etc.)
• La hiérarchie des composants correspond (éléments imbriqués)
• Le composant a le même objectif

Communication claire

Lorsque vous proposez de créer un mapping, expliquez clairement :

• Ce que vous avez trouvé
• Pourquoi c'est une bonne correspondance
• Ce que fera le mapping
• Comment les props seront connectées

Gérer l'ambiguïté

Si plusieurs composants pourraient correspondre, présentez des options plutôt que de deviner. Laissez l'utilisateur prendre la décision finale sur quel composant connecter.

Dégradation gracieuse

Si vous ne trouvez pas de correspondance exacte, fournissez les étapes suivantes utiles :

• Montrez les candidats proches
• Suggérez la création de composants
• Demandez des conseils à l'utilisateur

Problèmes courants et solutions

Problème : "No published components found in this selection"

Cause : Le composant Figma n'est pas publié dans une bibliothèque d'équipe. Code Connect fonctionne uniquement avec les composants publiés. Solution : L'utilisateur doit publier le composant dans une bibliothèque d'équipe dans Figma :

1. Dans Figma, sélectionnez le composant ou l'ensemble de composants
2. Cliquez avec le bouton droit et choisissez "Publish to library" ou utilisez la fenêtre modale de publication de la Team Library
3. Publiez le composant
4. Une fois publié, réessayez le mapping Code Connect avec le même ID de nœud

Problème : "Code Connect is only available on Organization and Enterprise plans"

Cause : Le plan Figma de l'utilisateur n'inclut pas l'accès à Code Connect. Solution : L'utilisateur doit passer à un plan Organisation ou Entreprise, ou contacter son administrateur.

Problème : Aucun composant correspondant trouvé dans la base de code

Cause : La recherche de base de code n'a pas trouvé de composant avec un nom ou une structure correspondant. Solution : Demandez à l'utilisateur si le composant existe sous un nom différent ou dans un emplacement différent. Ils devront peut-être créer le composant en premier, ou il peut être situé dans un répertoire inattendu.

Problème : "Published component not found" (CODE_CONNECT_ASSET_NOT_FOUND)

Cause : Le chemin du fichier source est incorrect, le composant n'existe pas à cet emplacement, ou componentName ne correspond pas à l'export réel. Solution : Vérifiez que le chemin source est correct et relatif à la racine du projet. Vérifiez que le composant est correctement exporté du fichier avec le componentName exact spécifié.

Problème : "Component is already mapped to code" (CODE_CONNECT_MAPPING_ALREADY_EXISTS)

Cause : Un mapping Code Connect existe déjà pour ce composant. Solution : Le composant est déjà connecté. Si l'utilisateur souhaite mettre à jour le mapping, il devra peut-être supprimer le mapping existant en premier dans Figma.

Problème : "Insufficient permissions to create mapping" (CODE_CONNECT_INSUFFICIENT_PERMISSIONS)

Cause : L'utilisateur n'a pas les permissions d'édition sur le fichier ou la bibliothèque Figma. Solution : L'utilisateur doit avoir accès à l'édition du fichier contenant le composant. Contactez le propriétaire du fichier ou l'administrateur d'équipe.

Problème : Le mapping Code Connect échoue avec les erreurs d'URL

Cause : Le format de l'URL Figma est incorrect ou le paramètre node-id est manquant. Solution : Vérifiez que l'URL suit le format requis : https://figma.com/design/:fileKey/:fileName?node-id=1-2. Le paramètre node-id est obligatoire. Assurez-vous également que vous convertissez 1-2 en 1:2 lors de l'appel des outils.

Problème : Plusieurs composants similaires trouvés

Cause : La base de code contient plusieurs composants qui pourraient correspondre au composant Figma. Solution : Présentez tous les candidats à l'utilisateur avec leurs chemins de fichiers et laissez-le choisir lequel connecter. Différents composants peuvent être utilisés dans différents contextes (p. ex. Button.tsx vs LinkButton.tsx).

Comprendre Code Connect

Code Connect établit un lien bidirectionnel entre la conception et le code :

Pour les designers : Voir quel composant de code implémente un composant Figma Pour les développeurs : Naviguer directement de conceptions Figma vers le code qui les implémente Pour les équipes : Maintenir une source unique de vérité pour les mappings des composants

Le mapping que vous créez aide à maintenir la conception et le code en synchronisation en rendant ces connexions explicites et détectables.

Ressources supplémentaires

Pour plus d'informations sur Code Connect :

• Code Connect Documentation
• Figma MCP Server Tools and Prompts