Créer un styleguide avec SC5-Styleguide

Comment créer un Styleguide avec CS5 ?

Qu'est ce qu'un styleguide ?

Un styleguide est une documentation qui liste l'ensemble des styles des éléments et composants de votre projet. Qu'il s'agisse d'un site internet ou d'une application mobile vous pourrez mettre cette documentation à disposition de vos collaborateurs. Aussi leur permettra de faciliter l'intégration ou la modification de certains composants. Pour chaque élément présent dans le styleguide vous trouverez :

un aperçu de l'élément
les styles CSS et variables associées
le markup HTML
si le composant nécessite l'utilisation du javascript alors vous pourrez y intégrer le code correspondant

Exemple pour des titres ou des boutons :

Vous trouverez plusieurs exemples de styleguides sur styleguides.io.

Utilisation de SC5-Styleguide

SC5-Styleguide est basé sur KSS. Il est agrémenté de fonctionnalités très utiles. Son interface utilisateur est très astucieuse puisqu'elle est construite avec AngularJS. Il prend en charge les styles SASS, LESS, PostCSS ainsi que les feuilles de style CSS pures.

Ses atouts

Voir et rechercher vos styles : affichez, recherchez et testez facilement vos styles avec l'interface utilisateur AngularJS.
Consulter les variables et styles associés : le flux de traitement KSS reconnaît les styles et variables liés au composant actuel, ce qui vous permet de voir tous les éléments associés au même endroit.
Modifications à la volée : avec l'outil de conception, vous pouvez modifier les variables SASS, LESS ou PostCSS directement via l'interface Web. Toutes les modifications peuvent être enregistrées dans le fichier d'origine.
Prévisualiser les styles sur tous les appareils : toutes les modifications sont automatiquement mises à jour et appliquées via des web sockets sur tous les appareils, sans rechargement pendant les modifications. Vous êtes également averti des erreurs de compilation.
Utilisation des directives AngularJS : Les sections de balisages HTML définies dans les blocs KSS sont compilées dynamiquement. Il est donc possible d'utiliser les directives Angular dans le styleguide.
Styles encapsulés : Tous les composants sont encapsulés dans le Shadow DOM, ce qui permet une encapsulation complète du style.
Facile à personnaliser : Si vous n'aimez pas l'aspect du styleguide par défaut, il est facile de personnaliser l'interface utilisateur intégrée à l'aide des variables SASS ou en remplaçant les styles CSS.
Open-source : SC5-Styleguide est entièrement open-source.

Installation

Pré-requis : il faut que vous ayez npm et gulp d'installés sur votre machine. Voici un exemple de structure de projet :

Rendez-vous à la racine de votre projet et entrez la commande : npm install sc5-styleguide --save-dev Cette commande va installer le plugin Gulp SC5-Styleguide. Vient ensuite la configuration du gulpfile.js : Dès lors que vous avez configuré le gulpfile lié aux informations de votre projet, vous allez pouvoir commencer à créer votre styleguide !

Création du styleguide

Pour commencer, rendez-vous à la racine de votre projet et entrez la commande : gulp watch Accédez ensuite à l'URL http://localhost:3000.

Ajouter du contenu sur la page d'accueil de votre styleguide

Pour créer une page d'accueil (Overview) dans votre styleguide, il vous suffit d'éditer le fichier styleguide.md qui se trouve à la racine de votre projet, SC5-Styleguide interprétera le markdown pour générer du HTML.

Créer vos composants

Prenons pour exemple les couleurs utilisées dans votre projet : Comme on le voit dans le fichier ci-dessus, l'ensemble de la documentation se fait dans les commentaires CSS :

Styleguide 1.0 va permettre de générer le premier onglet "Colors & typography" du menu, la première ligne du commentaire sera la titre du composant, la seconde ligne sera la description du composant
Styleguide 1.1 va ajouter un élément "Mains colors" à l'onglet "Colors & typography", en respectant la hiérarchie
Les lignes du dessous correspondent à la description du composant
La dernière ligne permet de générer le bloc contentant le markup HTML : Pour afficher le markup, il suffit d'ajouter le texte "markup:" et à la ligne ajouter le markup correspondant.
La variables $modifier va récupérer la valeur des variables listées dans la description pour les appliquer aux élements du markup HTML.

Ce qui donnera cette page dans le styleguide :

Si vous souhaitez afficher le bloc CSS, ajouter le css du composant sous le commentaire CSS, comme dans l'exemple ci-dessous :

Ce qui vous donnera cette page :

Pour ne pas afficher une partie de votre CSS il faut encapsuler votre css entre les lignes :

// styleguide:ignore:start
// styleguide:ignore:end

Vous pouvez maintenant créer tous vos composants pour votre styleguide. L'avantage est que vous pouvez ajouter ces commentaires CSS dans un projet déjà existant pour générer un styleguide. Plus besoin de partir de zéro pour chaque styleguide.

Déployer le styleguide sur un serveur distant

Pour visualiser votre styleguide sur une URL distante, il faut d'abord générer le styleguide avec la commande : gulp styleguide Il suffira ensuite d'uploader sur votre serveur le dossier "styleguide" qui s'est généré dans votre projet.

Conclusion

Avec cet article vous pouvez constater qu'il n'est pas si compliqué de générer un styleguide pour vos collaborateurs ou vos clients. En plus, ce styleguide sera visualisable sur mobile, tablette et desktop et vous pourrez le faire évoluer à tout moment si vous avez besoin d'ajouter de nouveaux composants à votre projet. Aussi, si vous souhaitez en savoir plus sur l'utilisation de SC5-Styleguide, rendez-vous sur le site officiel styleguide.sc5.io ou sur le github du projet https://github.com/SC5/sc5-styleguide.