Chez Wonderlabs, j'ai construit la bibliothèque de composants réutilisables de l'équipe et la fondation de design system en dessous, pour une PWA de carte de crédit servant plus de 50 000 utilisateurs, avec une équipe front-end de trois personnes. Nous sommes tombés dans le piège qui attrape la plupart des équipes. Nous avons commencé par les composants. Cela semble productif. On conçoit des boutons, des cartes, des modales, et on livre des artefacts. Mais sans tokens en dessous, ces composants sont construits sur du sable.
Pourquoi commencer par les composants vous coûte plus tard
Chez Wonderlabs, nous avons conçu des composants pendant des mois avant de formaliser les tokens. Quand nous nous sommes alignés sur la structure des tokens, nous avons dû auditer chaque composant et remplacer les valeurs codées en dur. Cela a mangé plus d'un sprint et a introduit des régressions. Ce n'est pas un risque hypothétique. C'est ce qui arrive.
Le problème est que quand vous concevez un bouton avant de définir vos tokens de couleur, vous prenez des décisions qui ressemblent à des décisions de design mais sont en fait des décisions de données. Vous choisissez un bleu pour l'action principale. Quel bleu ? Comment se rapporte-t-il à la couleur de marque ? De quoi l'état hover est-il dérivé ? Qu'est-ce qui change en mode sombre ? Sans tokens, ce sont des valeurs arbitraires intégrées dans le composant. Quand la marque se rafraîchit ou qu'un second produit a besoin du système, vous ne mettez pas à jour un token. Vous traquez les valeurs codées en dur dans chaque composant.
L'ordre correct
- 1. Design tokens : échelles de couleurs brutes, échelles typographiques, échelle d'espacement, rayons de bordure, élévation, mouvement. Ce sont vos valeurs primitives.
- 2. Tokens sémantiques : mappez les tokens bruts vers l'intention. --color-brand-blue-500 devient --color-action-default. Cette couche gère le thème et le mode sombre.
- 3. Primitives : styles Figma de base et CSS custom properties Angular dérivés des tokens sémantiques. Pas encore de composant.
- 4. Composants de base : Button, Input, Badge, Tag. Chacun référence uniquement des tokens. Aucune valeur codée en dur.
- 5. Composants composites : DataTable, FormGroup, NavigationBar construits à partir des composants de base.
- 6. Templates de page : patterns de layout utilisés à travers le produit.
Architecture de tokens : le JSON comme source unique de vérité
La décision technique la plus importante dans un design system est de garder les tokens Figma et les tokens code synchronisés. L'approche qui fonctionne est un fichier JSON de tokens, versionné dans le dépôt, que le code traite comme la source unique de vérité. Une étape de build comme Style Dictionary transforme ce JSON en CSS custom properties pour Angular, en constantes Swift pour iOS, ou tout ce dont la plateforme a besoin. La façon dont ce JSON arrive là est un choix avec deux réponses. Écrivez-le dans le code et synchronisez-le vers Figma avec un plugin comme Tokens Studio, ou écrivez-le dans Figma Variables et exportez-le. Choisissez une direction et mettez-la par écrit, parce qu'une équipe qui ne choisit jamais se retrouve avec deux sources qui ont divergé et aucun moyen de dire laquelle a raison. Chez Wonderlabs, j'ai pris la deuxième voie, dans mes derniers mois là-bas en 2023, une fois que Figma Variables existait : des tokens définis dans Figma Variables, exportés en JSON, transformés avec Style Dictionary en CSS custom properties consommées par nos composants Angular, qui reposaient sur Angular Material. Storybook n'est arrivé qu'un peu, vers la fin.
Décidez du format du fichier de tokens avant d'écrire le premier token, parce que les deux formes en circulation ne se mélangent pas dans un même fichier. L'exemple ci-dessous est en Style Dictionary v3, où chaque token est un objet avec une clé value. Style Dictionary v4 et le DTCG Design Tokens Format Module utilisent plutôt $value et $type. J'ai utilisé v3 chez Wonderlabs et l'extrait le reflète. Sur un nouveau projet aujourd'hui, j'écrirais la forme DTCG, parce que c'est là que va l'outillage, puis je vérifierais que chaque plugin et chaque étape de build de la chaîne la lit vraiment.
{
"color": {
"brand": {
"blue": {
"50": { "value": "#EFF6FF" },
"100": { "value": "#DBEAFE" },
"500": { "value": "#3B82F6" },
"700": { "value": "#1D4ED8" },
"900": { "value": "#1E3A8A" }
}
},
"action": {
"default": { "value": "{color.brand.blue.500}" },
"hover": { "value": "{color.brand.blue.700}" },
"disabled": { "value": "{color.brand.blue.100}" }
}
},
"spacing": {
"xs": { "value": "4px" },
"sm": { "value": "8px" },
"md": { "value": "16px" },
"lg": { "value": "24px" },
"xl": { "value": "32px" },
"2xl": { "value": "48px" }
}
}La gouvernance fait partie du système, pas un problème ultérieur
Un design system sans processus de contribution devient un fourre-tout en quelques mois. Définissez tôt qui peut ajouter des tokens, qui peut ajouter des composants, et quel est le processus de revue. Même dans une équipe front-end de trois personnes ce n'est pas optionnel. Un composant livré avec un pattern d'accessibilité cassé est utilisé à travers de nombreuses fonctionnalités avant que le bug ne remonte. Un workflow basé sur les PR avec un designer et un développeur comme reviewers obligatoires détecte la plupart des problèmes avant qu'ils ne se propagent.
Le versionnage compte plus que la plupart des équipes ne l'attendent quand elles commencent. Quand vous changez une API de composant ou renommez un token, les équipes consommatrices ont besoin de temps pour migrer. Nous n'avons jamais eu ce problème chez Wonderlabs. Trois personnes, un seul produit, et la bibliothèque livrée à l'intérieur de l'application, donc il y avait exactement un consommateur et un renommage tenait en un seul commit. Le jour où un deuxième produit reprend la bibliothèque, ça ne tient plus. C'est la partie que je mettrais en place dès le départ la prochaine fois : la bibliothèque publiée comme un package npm scopé, le versionnage sémantique à chaque release, et des schematics Angular pour les migrations cassantes. Sans cela, les équipes restent indéfiniment sur d'anciennes versions et vous finissez par maintenir deux versions du système.
Un design system est un produit, pas un projet. Il a besoin de maintenance, de versionnage, de documentation et d'une équipe qui le possède. Traitez-le comme une construction unique et il pourrira en un an.
Intégration Angular : CSS custom properties et overrides de thème
La forme que je lui donnerais la prochaine fois, pour Angular : le design system publié comme un package npm scopé et consommé via les bibliothèques Angular dans un monorepo. Les composants exposent leurs styles via des CSS custom properties mappées depuis le fichier de tokens. Les applications consommatrices thématisent en surchargeant ces custom properties au niveau du host, jamais en modifiant le code du composant. C'est l'architecture qui rend le multi-marque viable. Une deuxième marque devient un deuxième jeu de valeurs de tokens appliqué au niveau du host, pas un fork du code des composants.
Si je recommençais ce système, les tokens seraient le premier livrable. Avant qu'un seul composant n'existe dans Figma, l'échelle de couleurs, le mapping de tokens sémantiques et l'échelle d'espacement vont dans un fichier de tokens revu. Chaque décision de composant prise après a une fondation à référencer. Le retravail que vous évitez vaut bien plus que le temps supplémentaire passé sur les tokens au début.
Références
- Style Dictionary. https://styledictionary.com/
- DTCG Design Tokens Format Module. https://www.designtokens.org/tr/2025.10/format/
- Tokens Studio. https://tokens.studio/
- Figma Variables. https://help.figma.com/hc/en-us/articles/15339657135383-Guide-to-variables-in-Figma
- Semantic versioning. https://semver.org/
- Angular schematics. https://angular.dev/tools/cli/schematics