Relier Figma et React avec Dev Mode et Code Connect

En Dev Mode, Figma affiche déjà du code pour le composant sélectionné — mais c’est un code générique, déduit des calques, qui ne ressemble pas à votre vrai composant React. Vos développeurs le regardent, puis vont chercher le « vrai » bouton dans la base de code. Code Connect supprime cet écart : il fait apparaître, directement dans Dev Mode, l’extrait d’usage de votre composant, avec ses props et ses imports. Le designer et le développeur regardent enfin la même source de vérité.

🎯 Ce que vous allez apprendre

• Comprendre ce que montre Dev Mode et où se situe son angle mort.
• Installer la CLI Code Connect et préparer un jeton d’accès adapté.
• Créer un fichier .figma.tsx qui relie un composant Figma à son équivalent React.
• Mapper les variants Figma vers les props React avec figma.boolean, figma.enum et figma.string.
• Publier ces liaisons pour qu’elles s’affichent dans Dev Mode, et les maintenir en intégration continue.

🛠️ Ce que vous allez construire

La liaison du composant Button de votre bibliothèque Figma vers le composant Button de votre design system React. À la fin, un développeur qui sélectionne ce bouton dans Dev Mode verra l’extrait exact à copier — import { Button } compris — avec les bonnes props selon le variant choisi.

Prérequis

• Un accès à Dev Mode (siège développeur ou complet sur un espace payant).
• Node.js 20+ et un projet React contenant au moins un composant de design system (un Button avec des props variant et disabled fera l’affaire).
• Le composant correspondant publié dans une bibliothèque Figma.
• Un jeton d’accès personnel Figma disposant des droits Code Connect (lecture du fichier et écriture des liaisons).
• ⏱️ Temps estimé : ~45 minutes.

Étape 1 — Comprendre Dev Mode et son angle mort

Dev Mode est la vue de Figma destinée aux développeurs : elle expose les mesures, les couleurs, les espacements et un panneau de code. Par défaut, ce panneau génère un balisage déduit de la structure des calques — utile pour les valeurs, mais déconnecté de votre code réel. Si votre bouton s’utilise via <Button variant="primary">, Dev Mode ne le sait pas : il propose une <div> stylée. Le développeur doit donc traduire mentalement entre ce qu’il voit et ce qu’il doit écrire.

C’est cet angle mort que comble Code Connect. Vous écrivez, une fois, comment s’utilise votre composant ; Figma affiche alors cet extrait à la place du code générique. Le gain n’est pas cosmétique : il supprime une source récurrente d’erreurs d’intégration et garde la documentation au plus près du code, là où elle ne se périme pas.

Étape 2 — Installer la CLI et préparer le jeton

Code Connect se pilote par une CLI distribuée dans le paquet @figma/code-connect. On l’ajoute au projet en dépendance de développement, aux côtés du design system :

npm install --save-dev @figma/code-connect

La publication nécessite un jeton. Générez-le comme à l’accoutumée dans les réglages Figma, en lui accordant les droits Code Connect. Exposez-le en variable d’environnement plutôt que de le coller dans une commande, surtout en intégration continue :

export FIGMA_ACCESS_TOKEN="figd_votre_jeton_ici"

La CLI lira automatiquement cette variable, ce qui évite d’écrire le jeton en clair dans l’historique du terminal ou dans un script versionné.

Étape 3 — Déclarer la configuration du projet

Code Connect a besoin de savoir où trouver vos fichiers de liaison. On crée figma.config.json à la racine du projet. La configuration indique le périmètre des fichiers à inclure et, si besoin, des règles d’import propres à votre base :

{
  "codeConnect": {
    "include": ["src/components/**/*.figma.tsx"]
  }
}

Le motif include dit à la CLI : « tous mes fichiers de liaison vivent à côté des composants, avec l’extension .figma.tsx ». Cette convention de nommage est importante — elle sépare clairement la liaison du composant lui-même tout en les gardant voisins dans l’arborescence.

✅ Point d’étape — Vous avez la CLI installée, un jeton en variable d’environnement et un figma.config.json. Vérifiez l’installation avec npx figma connect --help : la liste des sous-commandes (create, publish, unpublish) doit s’afficher.

Étape 4 — Générer un premier fichier de liaison

Plutôt que d’écrire le fichier à la main, on part du squelette généré par la CLI. Copiez l’URL du composant Button dans Figma (clic droit → Copy link to selection), puis lancez :

npx figma connect create "https://www.figma.com/design/ABC123/DS?node-id=10-20"

La CLI inspecte le composant — ses variants, ses propriétés — et écrit un fichier Button.figma.tsx pré-rempli. Ouvrez-le : il contient un appel à figma.connect avec un squelette de props correspondant aux variants détectés. C’est un point de départ, pas un résultat final : il faut maintenant le faire pointer vers votre vrai composant.

Étape 5 — Mapper les variants vers les props React

Le cœur de Code Connect est la fonction figma.connect. Elle reçoit votre composant React, l’URL Figma, puis un objet décrivant les props (comment lire les propriétés Figma) et un example (comment s’utilise le composant). Voici la liaison complète pour notre bouton :

import figma from '@figma/code-connect';
import { Button } from './Button';

figma.connect(Button, 'https://www.figma.com/design/ABC123/DS?node-id=10-20', {
  props: {
    label: figma.string('Label'),
    disabled: figma.boolean('Disabled'),
    variant: figma.enum('Variant', {
      Primary: 'primary',
      Secondary: 'secondary',
    }),
  },
  example: ({ label, disabled, variant }) => (
    <Button variant={variant} disabled={disabled}>
      {label}
    </Button>
  ),
});

Chaque helper traduit un type de propriété Figma. figma.string('Label') récupère le texte de la propriété « Label ». figma.boolean('Disabled') lit un variant booléen. figma.enum('Variant', {...}) est le plus important : il fait correspondre les options du variant Figma (« Primary », « Secondary ») aux valeurs attendues par votre prop React ('primary', 'secondary'). La fonction example assemble enfin l’usage réel : c’est exactement ce que Dev Mode affichera, valeurs substituées selon la sélection.

Étape 6 — Publier et vérifier dans Dev Mode

La liaison n’existe pour l’instant que sur votre disque. On la publie pour la rendre visible à toute l’équipe :

npx figma connect publish

La commande valide chaque fichier, puis téléverse les extraits. En cas d’erreur de syntaxe ou de prop introuvable, elle s’arrête avec un message pointant le fichier fautif — corrigez et relancez. Une fois la publication réussie, ouvrez le composant Button en Dev Mode dans Figma : le panneau de code affiche désormais votre extrait, avec l’import et les props, et il réagit au variant sélectionné. Sélectionnez la version « Secondary » : la prop variant passe à 'secondary' sous vos yeux.

✅ Point d’étape — En Dev Mode, le panneau de code montre votre composant React et non plus une <div> générique. Si vous voyez encore le code par défaut, la publication a échoué silencieusement : relancez publish et lisez attentivement sa sortie.

Étape 7 — Maintenir les liaisons en intégration continue

Une liaison publiée une fois se périme dès que le composant évolue. Pour éviter la dérive, on republie automatiquement à chaque fusion sur la branche principale. Le principe : un job qui exporte le jeton (stocké en secret) et lance la publication.

# extrait d'un job d'intégration continue
- run: npm ci
- run: npx figma connect publish
  env:
    FIGMA_ACCESS_TOKEN: ${{ secrets.FIGMA_ACCESS_TOKEN }}

Ainsi, toute évolution du design system se reflète dans Dev Mode sans geste manuel. On peut aussi ajouter, en validation de pull request, une vérification qui échoue si un fichier de liaison ne compile pas — la même garantie que pour le reste du code.

Quels composants relier en priorité

Relier l’intégralité d’une bibliothèque d’un coup est un piège classique : on y passe des jours, et la moitié des liaisons concernent des composants que personne n’intègre à la main. La bonne approche est d’ordonner l’effort par fréquence d’usage et par coût d’erreur.

Commencez par les composants atomiques les plus repris : bouton, champ de saisie, case à cocher, badge, lien. Ce sont eux qu’un développeur pose dix fois par jour, et donc eux dont l’extrait correct fait gagner le plus de temps cumulé. Un bouton bien relié, avec ses variants mappés, élimine la question récurrente « quelle valeur passer à variant déjà ? ». L’investissement est faible et le retour immédiat.

Viennent ensuite les composants composés à forte ambiguïté : une carte, une barre de navigation, une fenêtre modale. Leur structure laisse plusieurs interprétations possibles côté code, et c’est exactement là que le code générique de Dev Mode induit en erreur. Une liaison qui montre la composition réelle — quels sous-composants, dans quel ordre, avec quelles props — supprime les divergences d’intégration entre développeurs. Le helper figma.children sert précisément à refléter cette imbrication.

Laissez pour la fin, voire ignorez, les composants rares ou jetables : illustrations ponctuelles, mises en page uniques, éléments d’une seule page. Les relier coûte autant qu’un bouton mais ne sera presque jamais consulté. Code Connect n’a de valeur que sur ce qui se réutilise ; l’appliquer à l’unique dilue l’effort sans bénéfice.

Cette hiérarchisation rejoint une idée plus large : une liaison Code Connect est une forme de documentation, et la meilleure documentation est celle qui vit là où on en a besoin, au moment où on en a besoin. En la rattachant au composant plutôt qu’à un wiki séparé, elle ne se périme pas en silence — le pipeline de publication la maintient à jour. Mais comme toute documentation, elle a un coût de maintenance : mieux vaut dix liaisons impeccables sur les composants vitaux que cent liaisons approximatives que personne ne fait évoluer. Traitez votre couverture Code Connect comme votre couverture de tests : ciblée, entretenue, et mesurée à l’usage réel plutôt qu’au pourcentage brut.

🐞 Pièges fréquents

✅ Récapitulatif

Vous avez relié un composant Figma à son équivalent React : Dev Mode affiche maintenant l’usage réel de votre code, props comprises, au lieu d’un balisage déduit. Vous savez installer la CLI, déclarer la configuration, générer puis affiner un fichier .figma.tsx, mapper variants et propriétés, publier et maintenir l’ensemble en intégration continue. Designers et développeurs partagent désormais une seule définition de chaque composant.

🧾 Aide-mémoire

💪 À vous de jouer

Reliez un composant Input qui possède une icône optionnelle (un variant booléen « Has icon ») et un état (« Default », « Error »). Mappez l’icône avec figma.boolean et l’état avec figma.enum, et faites en sorte que l’example n’affiche le message d’erreur que dans l’état « Error ».

Tutoriels de la série

• Construire des composants React accessibles avec ARIA — pour que le composant relié soit aussi utilisable au clavier.
• Générer ses design tokens avec Style Dictionary — l’autre passerelle design-code.

Pour aller plus loin

• 🔝 Retour au guide principal : Du design au code : Figma, tokens et WCAG 2.2.
• Documentation officielle : developers.figma.com — Code Connect React.

FAQ

Code Connect remplace-t-il Storybook ?
Non, il s’y intègre. Code Connect peut s’appuyer sur des fichiers Storybook existants ; les deux outils se complètent, l’un documentant l’usage dans Figma, l’autre dans le navigateur.

Faut-il un fichier de liaison par composant ?
Oui, généralement un .figma.tsx par composant relié. Un même composant peut avoir plusieurs exemples d’usage si nécessaire.

Et pour Vue, Angular ou les Web Components ?
Code Connect propose des intégrations pour plusieurs technologies, dont une voie HTML qui couvre les Web Components, Angular et Vue, ainsi que SwiftUI et Jetpack Compose côté mobile.

Que se passe-t-il si je supprime un composant ?
On retire la liaison correspondante avec npx figma connect unpublish pour éviter qu’un extrait pointe vers un composant disparu.