Il était une fois storybook, mon styleguide

Vous êtes développeur et vous n’êtes pas accro à l’intégration ? Vous êtes designer et vous en avez assez que le projet ne ressemble pas à vos maquettes ? Vous venez d’arriver dans votre entreprise et vous êtes un peu paumé ? Une solution existe : le styleguide.

Chez Cap Collectif, nous avons décidé de nous y mettre et avons instauré un tout nouveau guide de style pour notre plateforme ! Celui ci a été créé avec ReactJS et storybook.

Un styleguide, quézaco ?

La petite explication

Globalement, un styleguide est une documentation décrivant les règles de style à appliquer sur un ensemble d’éléments.

Pour cet article, nous allons nous concentrer sur le guide de style d’une plateforme numérique. Celui ci pourra contenir les typographies utilisées dans le projet, les grilles, les couleurs, les boutons, les éléments d’un formulaire etc.

C’est une ressource pour les designers, les développeurs et les chefs de produit puisqu’il permet de regrouper les différents composants d’un projet à un seul et même endroit. Cette bibliothèque d’éléments pré-conçus est une référence commune lorsqu’il s’agit de discuter de changements visuels sur un projet.

Voici un petit aperçu de celui d’Evergreen :

On peut y trouver leurs différents éléments graphiques mais aussi une bibliothèque de tous leurs composants (incluant leur usage, leur code et leur propriétés).

Chez Cap Collectif, nous avons choisi de créer notre guide de style avec des composants réutilisables directement dans notre projet.

C’est sympa, mais à quoi ça sert ?

On crée des composants purement UI qui sont ensuite utilisés dans le code du projet et dans le guide de style. Cela va permettre :

  • D’avoir une meilleure cohérence entre le code et le design. Le styleguide est donc toujours à jour, puisqu’il se base sur notre code.
  • D’avoir un code plus propre. On évite la duplication inutile et on améliore l’existant si des changements sont à faire. Et ce, tout en faisant attention aux “best practices” ! Notre projet devient un assemblage de composants, plus simple pour s’y retrouver.
  • De faciliter la maintenabilité du code pour les développeurs. Si un élément change, il changera partout, plus besoin d’aller chercher dans 50 fichiers pour changer 1 élément.
  • D’avoir une meilleur cohésion et communication au sein de l’équipe produit puisque l’on travaille tous sur une seule et même référence qu’est le styleguide. Le designer transmet ses maquettes au développeur front qui s’occupe d’en faire différents composants. Ceux-ci seront visibles par toute l’équipe sur le guide de style.
Le plus long est de l’intégrer à son projet, mais une fois en place, c’est un gain de temps pour tout le monde.

Pour quel type de projet ?

Un guide de style est surtout utile pour des projets qui sont amenés à évoluer dans le temps.

La manière dont vous allez utiliser votre styleguide dépend de vos attentes et de votre besoin.

Vous pouvez l’utiliser comme :

  • Repère listant les différents éléments pour que les développeurs sachent quel style utiliser.
  • Bibliothèque de composants que vous allez directement utiliser et assembler pour former votre projet (la solution de Cap Collectif).
  • Styleguide indépendant utilisable en open source.

etc.

On peut tout aussi bien créer un styleguide sur un projet existant que sur un nouveau projet car il peut évoluer de manière autonome.

Construire son guide de style

Sur notre plateforme, nous utilisons une multitude de composants créés en ReactJS. Nous avons donc décidé de faire notre styleguide sous forme de composant réutilisable avec cette bibliothèque. Pour ce faire, nous avons recherché un outil permettant de développer cette idée de la meilleure manière possible et nous sommes tombés sur Storybook.

Préambule

Avant de vous présenter ce dernier, un petit paragraphe me semble nécessaire afin de vous expliquer comment vous organiser afin de créer votre guide de style.

La première chose est de savoir ce que vous allez mettre dedans, quelle va être votre organisation et la structuration de vos éléments. Faites une liste des différents composants du site avec leurs déclinaisons possibles si ce n’est pas déjà fait par le designer. Allez de l’élément le plus simple (typographie, grille, icônes, font-size, couleurs, boutons, élément de formulaire, drag&drop etc.) au plus complexe (composant qui réunit plusieurs éléments). Structurez-les dans plusieurs catégories pour pouvoir vous y retrouver. Ensuite, lors du développement, il va falloir penser à leur réutilisation dans le projet. Vous ne concevez pas celui-ci juste pour faire beau mais pour qu’il soit utile.

Storybook

Storybook est un environnement de développement pour les composants UI. Il nous permet de visualiser nos composants avec leurs différents états et de les développer de manière à ce qu’ils soient interactifs.

Il peut être utilisé avec tous les langages front et est compatible avec différents frameworks que sont React, React Native, Vue, Angular et Polymer. C’est un outil qui marche en dehors de notre application.

À celui-ci s’ajoutent des modules complémentaires qui vont nous permettre, par exemple : d’afficher dynamiquement le code du composant ; de montrer les évènements produit par ce dernier ; de modifier les propriétés ; d’écrire des notes ; d’afficher nos composants sous différentes tailles d’écrans etc.

Storybook de grommet.io

Je vous laisse avec la documentation officielle pour procéder à l’installation (elle explique bien mieux que moi) : https://storybook.js.org/basics/introduction/

Voici quelques exemples en ligne d’utilisation de Storybook :

Quelques alternatives à Storybook :

Styled-component 💅

Pour concevoir des composants purement UI, nous avons opté pour Styled-component. C’est une bibliothèque qui va nous permettre d’écrire du css (et même du scss !) dans notre fichier JS. Nous avons trouvé cette méthode adaptée à notre projet car elle nous permet d’avoir un composant complet comprenant directement son style.
Styled-component est pour le coup intéressant à utiliser avec ReactJS et ses composants car on arrive à un front très modulable et adaptable. Il permet en plus d’adapter le style en fonction des props qu'on lui passe.

Pour plus de détails, vous avez le choix avec une introduction à styled component et la documentation officielle.

Cas pratique avec Storybook, ReactJS et Styled-component

Assez parlé, on veut un exemple ! Concrètement ça ressemble à quoi tout ça ?

1 — Créer un composant

Image.js

2 — Ajouter son composant au styleguide

Medias-stories.js

3 — Ajouter son composant dans le projet

ProjectListCard.js

Aller plus loin en ajoutant des tests de régression visuels

Parce qu’on aime les bonnes pratiques, il me semblait important de parler des tests unitaires. L’intégration continue est essentielle sur un projet qui est amené à évoluer afin d’éviter les problèmes de régression. Il existe différentes solutions pour tester les composants de storybook. Chez Cap Collectif, nous sommes adeptes de jest et ses snapshots. Il existe aussi une bibliothèque adaptée à storybook pour ReactJS, VueJS ou encore Angular : storybook chrome screenshot. Si celle-ci vous intéresse, elle fait l’objet d’un article assez complet sur Medium : “Screenshot testing with React and Storybook”.

Résultat final

En résumé

Un styleguide est une bibliothèque de composants UI réutilisables. C’est une référence commune pour toute l’équipe. Celui-ci permet d’avoir un code plus propre, plus cohérent et maintenable. Il est utile pour un projet qui est amené à évoluer dans le temps.

Pour avoir un front modulable et adaptable, il est possible d’avoir des composants complets, possédant directement leur style grâce à styled-component.

Pour visualiser nos composants de manière interactive, on préférera storybook, un environnement de développement pour les composants UI.

D’ailleurs, storybook vient tout juste de sortir sa 5ème version majeure. Parmi les nouveautés : une refonte complète de l’expérience développeur et une évolution de l’architecture front-end pour les modules complémentaires.

N’attendez plus, et instaurez un joli styleguide pour votre projet !

Bibliographie

https://medium.com/bleeding-edge/screenshot-testing-with-react-and-storybook-19ab7e49ec92

https://la-cascade.io/creer-un-guide-de-style/

http://styleguides.io/

https://storybook.js.org/

https://www.styled-components.com/

https://graphiste.com/blog/web-design-creer-style-guide

https://medium.com/storybookjs/storybook-5-0-db1d0f9c83b8