Code Connect Components

Overview

Cette compétence vous aide à connecter les composants de design Figma à leurs implémentations de code correspondantes en utilisant la fonctionnalité Code Connect de Figma. Elle analyse la structure du design Figma, recherche les composants correspondants dans votre codebase et établit des mappings qui maintiennent la cohérence design-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 canvas Figma avec des scripts Plugin API, passez à figma-use.
• Si la tâche consiste à construire ou mettre à jour un écran complet dans Figma à partir du code ou d'une description, passez à figma-generate-design.
• Si la tâche consiste à implémenter du code produit à partir de Figma, passez à figma-implement-design.

Prérequis

• Le serveur MCP Figma doit être connecté et accessible
• L'utilisateur doit fournir une URL Figma avec l'ID du 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 de bureau Figma (aucune URL requise)
• IMPORTANT : Le composant Figma doit être publié dans une bibliothèque d'équipe. Code Connect ne fonctionne qu'avec les composants publiés ou les ensembles de composants.
• IMPORTANT : Code Connect n'est disponible que sur les plans Organization et Enterprise.
• Accès à la codebase du projet pour l'analyse des composants

Workflow obligatoire

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 effectue automatiquement :

• Récupère les informations des composants depuis le 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 des composants, propriétés et images miniatures pour chaque composant non mappé

Option A : Utiliser 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. Aucun parsing d'URL n'est nécessaire — le serveur MCP de bureau utilise automatiquement le nœud actuellement sélectionné du fichier Figma ouvert.

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

Option B : Quand 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 attend des deux-points : nodeId=1:2

Analysez l'URL Figma :

• Format URL : https://figma.com/design/:fileKey/:fileName?node-id=1-2
• Extrayez la clé du fichier : :fileKey (segment après /design/)
• Extrayez l'ID du nœud : 1-2 de l'URL, puis convertissez 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 pourraient avoir besoin d'être publiés dans une bibliothèque d'équipe d'abord.
• 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 du nœud
  • Propriétés du composant (JSON avec noms et valeurs des propriétés)
  • Une image miniature du composant (pour inspection visuelle)

Étape 2 : Analyser la codebase pour les composants correspondants

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

Recherchez :

• 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 correspondant 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 des fichiers de composants avec 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 des propriétés et leur correspondance aux propriétés Figma
   • Valeurs par défaut qui correspondent aux valeurs par défaut 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 prop la plus proche et documentez votre raisonnement dans un commentaire d'une ou deux phrases avant votre appel d'outil

Exemples de motifs 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ésenter les correspondances à l'utilisateur

Présentez vos conclusions et laissez l'utilisateur choisir quels 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 :

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

Si l'utilisateur rejette tous les mappings, informez-le et arrêtez-vous. Aucun appel d'outil supplémentaire 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 batch 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 du nœud Figma (avec format deux-points : 1:2)
• componentName : Nom du composant à connecter (par exemple, "Button", "Card")
• source : Chemin vers le fichier du composant de code (relatif à la racine du projet)
• label : L'étiquette framework ou 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 la création des mappings
• En cas d'erreur : l'outil signale quels mappings spécifiques ont échoué et pourquoi (par exemple, "Component is already mapped to code", "Published component not found", "Insufficient permissions")

Fournissez un résumé après 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 : Connecter 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 → convertissez 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 les composants Button dans la codebase : 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 : Plusieurs composants 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 → convertissez 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 codebase :

   • ProductCard : Trouvé src/components/ProductCard.tsx (les props correspondent)
   • Badge : Trouvé src/components/Badge.tsx (les 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 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 → convertissez 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 codebase : 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 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 au design Figma.

Bonnes pratiques

Découverte proactive des composants

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

Correspondance structurelle précise

Lors de la comparaison de composants Figma avec des composants de code, regardez au-delà des seuls 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 remplit la même fonction

Communication claire

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

• Ce que vous avez trouvé
• Pourquoi c'est une bonne correspondance
• Ce que le mapping fera
• 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 des étapes utiles :

• Affichage des candidats proches
• Suggerez 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 ne fonctionne qu'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. Clic droit et choisissez "Publish to library" ou utilisez le modal de publication de la Bibliothèque d'équipe
3. Publiez le composant
4. Une fois publié, relancez 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 Organization ou Enterprise, ou contacter son administrateur.

Problème : Aucun composant correspondant trouvé dans la codebase

Cause : La recherche dans la codebase n'a pas trouvé de composant avec un nom ou une structure correspondante. Solution : Demandez à l'utilisateur si le composant existe sous un nom différent ou dans un endroit différent. Il peut avoir besoin de créer le composant d'abord, 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 endroit, ou le 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 peut avoir besoin de supprimer le mapping existant d'abord 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 a besoin d'accès d'édition au fichier contenant le composant. Contactez le propriétaire du fichier ou l'administrateur de l'équipe.

Problème : Le mapping Code Connect échoue avec des 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 de convertir 1-2 en 1:2 lors de l'appel des outils.

Problème : Plusieurs composants similaires trouvés

Cause : La codebase 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 (par exemple, Button.tsx contre LinkButton.tsx).

Comprendre Code Connect

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

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

Le mapping que vous créez aide à garder le design et le code synchronisés en rendant ces connexions explicites et découvrables.

Ressources supplémentaires

Pour plus d'informations sur Code Connect :

• Code Connect Documentation
• Figma MCP Server Tools and Prompts