Tout savoir sur les design systems : quand la documentation favorise l'adoption

Si vous n'avez pas encore lu nos précédents articles sur le sujet, consultez Tout savoir sur les design systems : qu'est-ce qu'un design system ? et Tout savoir sur les design systems : comment créer votre design system.

Lorsque les équipes de Razorpay oubliaient de petits détails, le head of design, Saurabh Soni, savait que le problème n'était pas la qualité, mais la communication. « Avant le déploiement de Blade [notre design system], il était facile de passer à côté de nombreuses subtilités, comme les différents états de boutons ou la façon dont une erreur dans un champ de texte doit être traitée, » explique Saurabh. Les développeurs essayaient de coder en dur et de tout construire manuellement, risquant des oublis. »

Ce challenge se retrouve dans toutes les organisations. « On peut dire que les designers et les développeurs parlent une langue différente », explique Lukas Oppermann, staff system designer chez GitHub. Ce fossé linguistique entraîne souvent des conventions de nommage et des propriétés de composants incohérentes, mais aussi des attentes divergentes quant à l'apparence et à l'expérience utilisateur d'un produit. Une bonne documentation comble cette lacune en faisant le lien entre l’intention et la mise en œuvre. Mais la documentation ne doit pas se contenter de cataloguer des composants : elle doit saisir le comment et le pourquoi des décisions de design. Sans ces guides complets, même les design systems soigneusement conçus accumulent de la poussière numérique.

Lorsqu'elle est bien réalisée, la documentation aide les équipes à :

• Comprendre les principes de design et les détails de mise en œuvre
• Prendre des décisions cohérentes sur tous les produits et toutes les plateformes
• Intégrer efficacement les nouveaux membres de l'équipe
• Faciliter la communication entre designers et développeurs

Identifier votre source de vérité

La première question n'est pas quoi écrire, mais où le placer. « Lorsque l'on souhaite maintenir une certaine cohérence, l'une des choses les plus difficiles est de déterminer sa source de vérité », explique Raul Menezes, design system and platform engineer chez Bumble. Ce phénomène s'intensifie à mesure que les design systems évoluent et que les équipes s'agrandissent. L'époque où des PDF statiques étaient stockés dans des disques partagés et devenaient immédiatement obsolètes est révolue. Entre les sites de documentation dédiés et les espaces de travail collaboratifs, les équipes n'ont jamais eu autant d'options différentes à disposition.

Tout créer de A à Z

Les sites de documentation personnalisée sont parfaits pour les grandes organisations où les design systems doivent être étroitement intégrés aux outils et aux processus. Les design systems Material Design de Google, Carbon d'IBM et Evo d'eBay utilisent des sites de documentation personnalisée pour des publics internes et externes, avec du contenu restreint et des chemins spécialisés pour différents groupes d'utilisateurs.

« Les gens veulent simplement faire le meilleur travail possible », explique Ryan Tinsley, staff product designer chez eBay. « Nos équipes ont considérablement amélioré leur travail en consultant notre documentation. Les office hours (sessions de questions-réponses) d'aujourd'hui sont radicalement différentes maintenant que nous avons un guide. Les équipes savent toujours à quoi se référer et comment présenter la marque conformément aux bonnes pratiques. »

Plutôt que de créer des destinations distinctes pour la documentation de la marque et celle des produits, eBay a créé un guide unifié. « Nous souhaitions unifier les guides pour ces deux composantes afin que les utilisateurs n'aient pas à changer de plateforme pour vivre différentes expériences », souligne Ryan. Pour que cela fonctionne, l'équipe d'eBay a développé des outils sur mesure qui exportent les modifications de Figma directement vers leur CMS, permettant aux designers et aux autres équipes d'accéder aux dernières mises à jour du guide dès que leur utilisation est validée.

Tirer parti des plateformes existantes

Le plugin Storybook Connect for Figma vous permet de lier les composants de Storybook aux designs Figma. Vous pouvez ainsi comparer facilement la mise en œuvre aux spécifications de design.

Toutes les équipes n'ont pas besoin de ce niveau de complexité. Les petites équipes commencent souvent par utiliser des outils collaboratifs tels que Notion ou Confluence, en priorisant une configuration rapide et une maintenance simplifiée. De nombreuses équipes combinent les approches : les spécifications techniques dans Storybook et les directives de design dans des formats plus accessibles, complétées par des plugins personnalisés. Chez Razorpay, on a découvert que la documentation ne devait pas se contenter d'expliquer l'existant, mais qu'elle devait aussi répondre aux besoins des différentes équipes. L'entreprise a alors développé un plugin sur mesure, RazorSharp, qui fait le lien entre la documentation de design et la mise en œuvre. L'essentiel est de sélectionner des outils qui répondent à vos besoins actuels tout en permettant une évolution future.

Les éléments à inclure dans votre documentation

En plus de l'emplacement de la documentation, vous avez une autre décision importante à prendre : ce qu'elle doit contenir. Voici les éléments indispensables :

Principes de design

Chaque design system a besoin de principes de design clairement définis qui guident les décisions, de la stratégie générale aux plus petits détails. Lorsque vous expliquez le raisonnement à l'origine des décisions, les équipes comprennent mieux les objectifs et comment les appliquer avec cohérence.

Bibliothèque de composants

Pour chaque composant, inclure :

• Consignes d'utilisation et bonnes pratiques
• Spécifications de design englobant l'anatomie, les dimensions et le comportement
• Exemples pratiques et cas d'usage
• Extraits de code et détails de mise en œuvre
• Prototypes interactifs illustrant les états et les variations

Guide de style visuel

Documentez les décisions de design qui définissent l'esthétique de votre marque :

• Palette de couleurs avec directives d'utilisation
• Système typographique spécifiant la hiérarchisation et les bonnes pratiques
• Bibliothèques d'icônes avec spécifications de design
• Normes d'images et d'illustrations, directives d'accessibilité comprises

Implémentation technique

Aidez les développeurs à mettre en œuvre votre design system avec :

• Une documentation des API et des propriétés des composants
• Des exigences en matière d'accessibilité et de procédures de test
• Des considérations relatives aux performances
• Guides d'intégration pour différents frameworks
• Des conventions de nommage claires et une documentation des tokens

Directives d'accessibilité

Définissez clairement les exigences en matière d'accessibilité :

• Niveaux de conformité WCAG pour les composants
• Comportement du lecteur d'écran
• Modèles de navigation au clavier
• Exigences relatives au contraste des couleurs
• Tailles des cibles d'interaction

Chez eBay, l'équipe en charge des design systems a constaté tout l'intérêt de fournir des informations aussi détaillées que possible : « Les utilisateurs ont soif de documentation, affirme Ryan. Même avec un design system aussi complet que le nôtre, on nous pose souvent des questions sur des cas limites ou sur la documentation de tel ou tel scénario. Ces retours continus nous incitent à affiner et à développer nos ressources. Les partenaires ne se contentent pas de consommer passivement la documentation, ils participent à sa construction. »

Favorisez l'adoption avec Code Connect

Code Connect vous permet de personnaliser des extraits de code dans Dev Mode de Figma, facilitant ainsi la mise en œuvre et l'accès à votre design system par les développeurs directement depuis Figma.

Comment maintenir la documentation à jour et la faire évoluer

L'un des enjeux les plus fréquents en matière de documentation est de savoir comment la maintenir à jour à mesure que votre équipe se développe. Une documentation obsolète peut donner lieu des designs incohérents, ce qui finit par entacher la crédibilité du design system. Bien que mettre à jour une documentation demande du travail, les avantages sont considérables : une intégration plus rapide, moins de divergences et une expérience plus cohérente.

Maintenir la documentation à jour

« Ce que vous voyez dans le design, vous l'obtenez dans le code », observe Kamlesh de Razorpay. Cet alignement résulte de choix délibérés sur la manière dont la documentation est structurée, maintenue à jour et modifiée. « Nous comptons environ 70 designers et 100 développeurs front-end », ajoute Saurabh. « Au sein de ces équipes, trois designers et cinq développeurs sont dédiés à notre design system. » Cette équipe centrale soutient la communauté grâce à des sessions de questions-réponse régulières, des groupes de discussion et un programme de représentation qui regroupe des designers de diverses équipes.

À mesure que votre design system évolue, il est essentiel de disposer de processus clairs pour la gestion des mises à jour et des contributions. Le processus doit trouver l'équilibre entre une gouvernance centralisée et les contributions de la communauté, permettant ainsi une certaine flexibilité tout en respectant les normes. Voici quelques outils et processus que vous pourriez envisager d'adopter :

• Directives relatives aux contributions : établissez des directives claires pour que vos équipes puissent proposer des modifications ou des ajouts, y compris des templates, des guides de style et des processus de révision.
• Contrôle des versions : utilisez la gestion sémantique des versions pour communiquer la portée et l'impact de chaque mise à jour. Cela aide votre équipe à comprendre les différences entre les versions et à anticiper la mise à niveau.
• Journaux des modifications : conservez une liste détaillée et continue des modifications dans chaque version, y compris les nouvelles fonctionnalités, les corrections de bugs et les modifications majeures, ainsi que les étapes de migration.
• Assurance qualité : mettez en place plusieurs points de contrôle pour vérifier la qualité, tels que des boucles de feedback, des révisions régulières et des systèmes de linting.

Les équipes chargée des design systems et de la technologie du design d'eBay ont un tableau à jour de l'état des composants, montrant l'avancée de la mise en œuvre sur différentes plateformes. Comme l'explique Cordelia McGee-Tubb, staff design technologist chez eBay : « Beaucoup de nos développeurs utilisent cette API d'état des composants pour vérifier l'existence du composant dans le framework, la mise à jour par rapport à la version de Figma et la documentation du guide. Cela a été une grande réussite. » L'entreprise a également développé un linter personnalisé pour valider sa documentation. Ce dernier évalue l'utilisation des composants au regard des directives, vérifie que les informations d'accessibilité sont complètes, garantit que toutes les images ont un texte alternatif et signale les incohérences de nommage ou de structure.

Wart Burggraaf, consultant en UX design et fondateur, s'est donné pour mission d'automatiser la gestion des design systems. Découvrez ses réflexions sur la gestion des contributions aux design systems.

Assurer l'accessibilité à tous

Les membres de l'équipe n'ont pas tous les mêmes besoins en termes de documentation. Pour réussir, il est essentiel de comprendre les besoins propres à chaque groupe. Chez Alaska Airlines, les designers ont lutté pour obtenir une mise en œuvre parfaite, au pixel près, tandis que les développeurs ont reçu des designs mal alignés. June Lee, product designer, s'est concentrée sur la documentation des fonctionnalités clés lors de la migration de son design system Auro vers Figma. « Je me suis vraiment concentrée sur la formation de nos designers, pour qu'ils puissent comprendre ce que Figma peut faire », souligne-t-elle. « J’ai pu constater que les designers utilisaient mieux Figma, ce qui a réduit les conflits entre designers et développeurs. » Voici ce que chaque type de collaborateur pourrait trouver le plus utile :

Pour les designers

• Exemples visuels et modèles d'usage
• Variantes de composants et états
• Mise en œuvre des tokens de design
• Systèmes de grille et espacement
• Bibliothèques d'assets et ressources

Pour les développeurs

• Spécifications techniques
• Documentation de l'API
• Guides d'intégration
• Exigences de test
• Considérations relatives aux performances

Pour les product managers

• Vue d’ensemble du design system
• Guide de sélection des composants
• Roadmap des fonctionnalités
• Notes de version et mises à jour

Ana Boyer, design advocate chez Figma, a animé une table ronde « Design to Code » avec Bumble, GitHub et HP. Lors de cet événement, les invités ont discuté des difficultés communes à leurs équipes de design systems pour relier design et code. Ils partagent également leurs premières impressions sur Code Connect.

Recueillir du feedback et mesurer l'impact

Chez Razorpay, le succès du design system ne se mesure pas seulement par le taux d'adoption, mais par l'impact réel sur les workflows et la collaboration. L'entreprise se fixe des objectifs concrets : les équipes qui développent de nouvelles fonctionnalités doivent utiliser leur design system pour 70 % de leurs travaux de design, tandis que les produits existants visent les 50 %. « Nous avons interrogé nos designers et nos développeurs, et 80 % d'entre eux ont déclaré se sentir plus productifs avec notre design system Blade que sans », explique Saurav Rastogi, designer.

Lorsque vous rassemblez des retours et des preuves pour votre propre design system, ne vous arrêtez pas aux simples vues de pages pour comprendre comment la documentation influence le comportement. Appuyez-vous sur des tests utilisateurs et des entretiens pour recueillir des retours complets. En priorisant l'amélioration continue et l'itération, vous vous assurez que votre design system reste un outil précieux et efficace pour votre équipe, même lorsque vos produits et vos processus évoluent.

Des outils tels que Design System Analytics de Figma peuvent fournir des informations précieuses pour les comptes Organisation et Entreprise sur la manière dont votre design system est utilisé et sur les possibilités d'amélioration. Restez connecté pour découvrir les prochaines mises à jour de cette fonctionnalité !

Préparer le passage à l'échelle

Une documentation efficace ne se contente pas de détailler ce qui existe : elle permet aussi aux équipes de collaborer pour créer de meilleures expériences. Investir dans des outils et des processus qui maintiennent la documentation à jour se révèle payant en termes d'adoption et de cohérence. Lorsque vous envisagez de développer et d'améliorer votre documentation, gardez en tête les éléments suivants :

• Prenez en compte les environnements de travail des équipes grâce à des outils intégrés et des solutions personnalisées
• Établissez des ponts entre les disciplines en créant ce que Lukas Oppermann de GitHub appelle « un troisième langage », qui permet aux designers et aux développeurs de réellement communiquer
• Créez des parcours de contribution clairs grâce à des équipes dédiées et une implication régulière de la communauté.
• Mesurez l'impact du design system en suivant les améliorations de la productivité et de la collaboration entre les équipes

L'avenir s'oriente vers des approches plus intégrées, où la documentation accompagne le travail lui-même. Lorsque la documentation évolue en même temps que le design system, l'adoption se fait naturellement. L'objectif n'est pas d'avoir une documentation parfaite, mais une documentation qui aide les équipes à exceller dans leurs tâches.

Quels autres thèmes aimeriez-vous aborder ? Tweetez vos questions en mentionnant @figma. Découvrez comment Figma aide les équipes à assurer la cohérence, à faire passer le design à l'échelle et à rester en phase avec le développement grâce à nos fonctionnalités de design systems. Vous pouvez également demander une démonstration.