Design-to-Code · 21 octobre 2026

Pourquoi vos développeurs n'utilisent pas votre design system

Les tokens empêchent les mauvaises valeurs, pas les mauvaises combinaisons. Les six causes d'un design system mal suivi, et pourquoi son adoption se mesure.

Le scénario est toujours le même. Une équipe design passe des mois à construire un design system dans Figma. Composants propres, variantes exhaustives, documentation soignée. Six mois plus tard, l'interface en production ne lui ressemble qu'à moitié, et les développeurs continuent de coder leurs propres boutons.

La réaction réflexe est de blâmer la discipline des équipes. C'est presque toujours faux.

J'ai mis du temps à le comprendre, et je l'ai appris en mesurant un design system que j'avais construit moi-même. Il était bon, et il était utilisé. Il était juste rendu fidèlement une fois sur quatre.

Cause 1 — Le design system n'existe que dans Figma

C'est la cause racine, celle dont découlent toutes les autres.

Un design system n'est pas une bibliothèque de maquettes. C'est un contrat partagé entre deux mondes qui ne parlent pas la même langue. Tant qu'il n'existe que dans l'outil de design, c'est une proposition, pas une référence.

Du point de vue d'un développeur, la question est simple : est-ce que ce composant existe dans mon code, avec ce nom, et est-ce que je peux l'importer ? Si la réponse est non, il va le recoder. Ce n'est pas de la mauvaise volonté, c'est le chemin le plus court.

Le test : demandez à un développeur de votre équipe de construire un écran simple en n'utilisant que le design system. S'il doit à un moment ouvrir Figma pour relever une valeur à la main, votre système n'est pas un système.

Cause 2 — Les valeurs sont écrites en dur des deux côtés

Dans Figma, un bleu est un bleu. Dans le code, c'est un code hexadécimal recopié. Les deux coexistent sans lien. Quand la marque change de bleu, vous découvrez combien d'endroits il faut modifier.

La solution porte un nom : les design tokens. Le principe est simple à expliquer et difficile à appliquer rigoureusement.

Au lieu de définir une couleur par sa valeur, vous lui donnez un nom et un rôle. Vous ne dites plus « ce bouton est #2563EB », vous dites « ce bouton utilise la couleur d'action primaire ». La valeur réelle est définie à un seul endroit, et les deux mondes y font référence.

Trois niveaux à respecter pour que ça tienne :

• Le niveau brut. La palette, sans intention : bleu-500, bleu-600, espacement-4.
• Le niveau sémantique. Ce à quoi ça sert : couleur-action-primaire, couleur-texte-secondaire, espacement-section.
• Le niveau composant. Ce que le composant utilise : bouton-fond-primaire.

La plupart des équipes s'arrêtent au premier niveau. C'est ce qui explique pourquoi leurs tokens ne survivent pas au premier changement de marque : nommer une couleur « bleu-600 » ne dit pas quand l'utiliser.

Le niveau sémantique du design system de Streamnco, documenté dans Storybook. Chaque intention pointe vers une valeur de la palette, jamais vers une valeur brute.

Les tokens sont nécessaires, mais ils ne suffisent pas. Sur mon propre produit, les trois niveaux étaient en place, et seuls 26 % des composants mesurés sont rendus fidèlement (le détail est plus bas). Les écarts ne venaient pas de valeurs écrites en dur. Ils venaient de tokens parfaitement valides, combinés autrement que prévu : une carte au rayon plus grand, un fond rendu translucide, un badge passé en majuscules. Chacune de ces valeurs est un token. Aucune n'est celle du composant.

Les tokens empêchent les mauvaises valeurs. Ils n'empêchent pas les mauvaises combinaisons.

Cause 3 — Les structures ne correspondent pas

Un designer organise ses composants par logique visuelle. Un développeur organise son code par logique de composition. Quand les deux arborescences divergent, chaque correspondance devient une traduction mentale.

Exemple courant : dans Figma, une carte produit est un composant unique avec douze variantes. Dans le code, c'est une carte générique dans laquelle on place un contenu. Les deux approches sont défendables, mais elles ne se correspondent pas, et personne ne sait quelle variante Figma correspond à quelle combinaison de propriétés.

Le correctif demande une conversation que beaucoup d'équipes n'ont jamais eue : structurer les composants Figma comme le code les compose. Moins de composants, plus de propriétés. Des noms de variantes qui sont littéralement les noms de propriétés du code.

Ce n'est pas une concession du design au développement. C'est la condition pour que le système existe aux deux endroits.

Cause 4 — Rien ne relie explicitement un composant Figma à son équivalent en code

Même avec des structures alignées, le lien reste implicite. Le développeur doit deviner, ou demander.

C'est précisément le problème que Figma a cherché à résoudre avec Code Connect. Le principe : vous déclarez explicitement qu'un composant Figma correspond à tel composant de votre base de code. Quand un développeur inspecte la maquette, il ne voit plus du CSS généré automatiquement, il voit le vrai composant de votre système, avec sa syntaxe d'import.

C'est un changement de nature. On passe d'un système où le code est deviné à partir du visuel, à un système où le visuel pointe vers le code existant.

À noter : cela suppose un design system déjà structuré des deux côtés. Code Connect ne crée pas la cohérence, il la rend visible. Si vos composants ne correspondent pas, le brancher ne fera que documenter le désordre.

Cause 5 — La documentation vit ailleurs que le travail

Une documentation hébergée dans un troisième outil, mise à jour par une seule personne, consultée une fois à l'arrivée d'un nouveau, n'est pas de la documentation. C'est une archive.

La documentation utile est celle qui se trouve là où la décision se prend :

• Dans Figma, sur le composant lui-même : quand l'utiliser, quand ne pas l'utiliser.
• Dans le code, dans Storybook : le composant réel, manipulable, avec ses états.
• Dans la revue de code : un composant recodé à la main déclenche une question, pas un commentaire.

Storybook mérite une mention particulière, parce qu'il résout un problème précis : il donne aux designers un endroit où voir le système tel qu'il existe réellement, pas tel qu'il a été dessiné. C'est souvent la première fois qu'une équipe design constate l'écart.

Cause 6 — Rien ne vérifie la conformité

C'est la cause que la mesure a fait apparaître, et elle explique pourquoi les cinq premières ne suffisent pas.

Le design system de Streamnco avait un garde-fou automatique, un script lancé à chaque modification du code, qui refuse ce qui contourne le système : couleurs écrites en hexadécimal, rayons arbitraires, ombres codées en dur, valeurs brutes utilisées à la place des tokens. Sur le papier, c'est exactement ce qu'il faut.

Il avait deux angles morts.

Il ne bloquait que le cœur du système. Les composants eux-mêmes étaient vérifiés strictement. Les écrans qui les utilisent ne recevaient qu'un avertissement, qui ne bloquait rien. Or c'est dans les écrans que la dérive se produit : les 64 dérivés viennent tous d'un écran, qu'il ait recodé le composant ou modifié celui du système.

Il cherchait des valeurs interdites, pas des écarts. Un badge importé du design system, auquel l'écran ajoute une graisse, une casse et un interlettrage, ne contient aucune valeur interdite. Une carte recodée avec un rayon de 16 pixels au lieu de 10 non plus : le rayon de 16 pixels existe dans l'échelle des tokens, comme la taille de police de 12 pixels du badge. Le script les laissait passer, parce qu'il vérifiait le vocabulaire, pas la phrase.

Le garde-fou lancé sur le code en production : 37 avertissements hors du cœur, 0 erreur, la vérification passe. Aucun de ces avertissements ne concerne les écrans mesurés.

Le cœur lui-même n'y échappait pas. Le composant Badge de Streamnco a douze tokens de composant, dont un rayon défini comme une pastille, à 9999 pixels. Le composant n'en utilise aucun : il affiche un rayon de 8 pixels, écrit avec une classe standard. Rien d'interdit, donc rien de signalé. Le script déclarait le cœur « propre » alors qu'il contredisait ses propres tokens.

Vérifier la conformité, c'est vérifier trois choses différentes :

• Les valeurs. Pas de couleur ni de rayon en dur. C'est ce que la plupart des garde-fous font déjà.
• L'usage. Un composant du système est-il importé, ou recodé à côté ? Et quand il est importé, l'écran lui ajoute-t-il des classes qui changent son rendu ?
• Le rendu. Les valeurs affichées dans le navigateur sont-elles celles du composant de référence ? C'est la seule vérification qui attrape tout, et c'est celle que je décris plus bas.

Un design system sans vérification de l'usage et du rendu n'est pas surveillé. Il est seulement documenté.

Par où commencer si vous êtes dans cette situation

Ne refaites pas le design system. C'est la tentation, et c'est l'erreur. Le problème n'est presque jamais la qualité des composants.

Dans l'ordre :

1. Mesurez l'écart. Prenez trois écrans en production, dont un écran secondaire que personne ne regarde. Classez chaque composant : conforme, dérivé ou hors système. Notez aussi s'il a été recodé à la main ou importé puis modifié : ce ne sont pas les mêmes corrections. Le chiffre sera plus bas que prévu, et il rendra la conversation possible.
2. Posez les tokens sémantiques. Commencez par les couleurs et les espacements, les deux postes où l'incohérence se voit le plus. Niveau brut et niveau sémantique, pas plus pour l'instant.
3. Alignez cinq composants, pas cinquante. Prenez les cinq les plus utilisés. Structure identique des deux côtés, mêmes noms, mêmes propriétés.
4. Reliez-les explicitement. Code Connect ou, à défaut, une table de correspondance maintenue, visible des deux équipes.
5. Rendez le système visible dans le code. Storybook ou équivalent, avec les composants réels.
6. Vérifiez la conformité là où le système est utilisé. Faites porter les contrôles automatiques sur les écrans, pas seulement sur le cœur du système, et faites-les bloquer, pas seulement avertir.
7. Remesurez à intervalle fixe. Les mêmes trois écrans, la même définition, chaque trimestre ou à chaque version majeure. Un chiffre isolé est un constat. Une série de chiffres montre si la dérive recule.
8. Ensuite seulement, étendez.

Ce que donne la mesure sur mon propre produit

J'ai appliqué l'étape 1 à Streamnco, le SaaS que je construis pour les streamers. Son design system n'a pas de version Figma : il vit directement dans le code, avec des tokens à trois niveaux, une documentation Storybook et un garde-fou automatique. Autrement dit, les étapes 2 et 5 de la liste ci-dessus étaient faites.

J'ai compté chaque composant visible qui a un équivalent nommé dans un design system : boutons, champs, sélecteurs, puces de filtre, cartes, libellés, badges, avatars, séparateurs, fils d'Ariane. Chaque instance compte. Pour chacun, j'ai relevé dans le navigateur les valeurs calculées (hauteur, rayon, couleurs, marges, police) et je les ai comparées à la variante la plus proche du design system, telle que Storybook la rend. Un composant est conforme si toutes les valeurs sont identiques, dérivé si une seule diffère.

L'écran de consultation mesuré, en production. En vert, les 9 puces de filtre conformes. En orange, les 15 composants dérivés : compteurs, cartes, pastilles, panneau et bouton. Les cartes floutées, réservées aux abonnés, ne sont pas comptées.

Le chiffre qui compte le plus est le zéro de la colonne « hors système ». Chaque composant à l'écran a son équivalent dans le design system. En comptant les dérivés comme conformes, on obtiendrait 100 %. La conformité réelle est de 26 %.

Le total est porté par l'écran secondaire, que personne ne regarde : 53 composants sur 86, 46 dérivés sur 64. C'est là que l'écart est toujours le plus grand, et c'est pour ça qu'il faut toujours l'inclure.

Le même badge, importé du design system. L'écran lui ajoute une graisse, une casse, un interlettrage et une taille de police écrite à la main. Résultat : deux pixels de plus en hauteur, et cinq écarts mesurables.

En regardant d'où viennent les 64 dérivés, deux problèmes différents apparaissent :

• 44 ont été recodés à la main. Le design system avait l'équivalent, et l'écran l'a refait : cartes, pastilles, fil d'Ariane. Le système n'était pas le chemin le plus court.
• 20 ont été importés, puis modifiés. Le composant du design system est bien là, mais l'écran lui ajoute des classes qui changent son rendu.

Ces deux problèmes n'appellent pas la même correction. Le premier demande de rendre le système plus simple à utiliser que la réécriture. Le second demande de limiter ce qu'on peut modifier sur un composant importé, ou d'ajouter au système les variantes qu'on contourne.

L'explication par la discipline ne tient pas : 41 composants sur 86 viennent directement du design system. Les développeurs le connaissaient et s'en servaient. Et le garde-fou automatique n'a rien vu, pour les deux raisons décrites en cause 6.

Les limites de cette mesure : trois écrans publics, un visiteur non connecté, un écran de bureau, le thème sombre. Les écrans réservés aux abonnés n'ont pas été mesurés.

La référence retenue est le composant tel que Storybook l'affiche, même là où il contredit ses propres tokens, comme le rayon du Badge. Le classement n'en dépend pas : les 18 badges et pastilles arrondis de la production ont tous au moins trois autres écarts.

Ce qu'il faut retenir

Un design system peut exister, être utilisé, et ne pas être respecté.

Les tokens empêchent les mauvaises valeurs, pas les mauvaises combinaisons. Tant que rien ne vérifie l'usage et le rendu, la dérive passe par des classes parfaitement légitimes.

La mesure de réussite n'est pas le nombre de composants documentés, ni même la part de composants importés. C'est la proportion d'interface en production rendue fidèlement par le système. L'adoption ne se décrète pas, elle se mesure.

Pour aller plus loin

• De Figma à Storybook sans perdre les décisions de design
• Mes projets

Votre design system existe mais ne sert pas ? Je travaille sur cette jonction entre design et code, des tokens jusqu'à la mise en production. Parlons-en.