Générer et maintenir le styleguide

Pour établir le styleguide plusieurs fichiers sont déjà présents dans Scampi-Twig : le template de la page, des fragments à inclure et un partial scss pour les règles css propres au styleguide.

Ce site présente son propre styleguide.

Template de la page

Le fichier styleguide.twig (rangé dans *pages/*) comporte déjà quelques contenus prêts à enrichir.

Un styleguide est une excellente base pour mettre en place les premiers styles et pour faire un premier audit d'accessibilité lorsqu'il sera complété par les composants les plus usuels du site. On peut commencer par modifier la déclaration *extends* pour étendre le layout de base du projet au lieu du layout de base standard. Puis on inclut ou on modifie des fragments rangés dans templates/styleguide/.

Fragments

Scampi-Twig est livré avec plus d'une vingtaine de fragments standard prêts à inclure situés dans *templates/styleguide/*. Vous pouvez soit les modifier directement soit les dupliquer, les renommer et remplacer l'inclusion si vous souhaitez conserver les originaux.

Ces fragments sont préfixés avec un numéro identifiant la partie du styleguide concernée :

  • 1-xxx : identité visuelle
  • 2-xxx : éléments de contenu courants
  • 3-xxx : boutons et formulaires
  • 4-xxx : composants du projet

Identité visuelle

On y place le(s) logo(s), la palette de couleurs, les fontes utilisées, les icônes…

Couleurs

Le module de scampi [u-palette](/scampi/documentation/u-palette.html) associé au fragment *1-colors.twig* facilite l'affichage de la gamme des couleurs.

Les variables essentielles de couleurs sont déjà prévues dans le module. Sa documentation explique comment en ajouter.

Fontes

Le fragment *1-fonts.twig* est à adapter au projet pour lister les fontes utilisées et leurs déclinaisons de graisse et style. Il peut être utile d'y faire figurer aussi les noms des variables de la font-stack correspondant aux font-families utilisées dans le projet.

On crée ensuite des règles scss dans le partial du styleguide pour que les noms des fontes reflètent leur apparence.

En complément, le pangramme *(1-pangram.twig)* permet de présenter tous les caractères et diacritiques présents dans la langue française. On vérifie ainsi facilement que la fonte choisie est bien complète pour notre langue. Si vous utilisez plusieurs langues sur le site avec des alphabets différents ou des lettres ne figurant pas dans ce pangramme, vous pouvez en ajouter un échantillon dans le fragment.

Icônes

Dans le fichier *1-icons.twig* on insère toutes les icônes utilisées dans le projet. À titre d'exemple ce fragment comporte les trois icônes livrées avec Scampi-Twig. Nous recommandons et utilisons des icônes svg réunies dans un sprite : voir le module [svg-icons](/scampi/documentation/svg-icons.html) et le tutoriel [Construire et utiliser un sprite svg](/scampi-twig/documentation/sprite-svg.html) pour plus d'informations.

On vérifiera ainsi que les icônes s'affichent toutes correctement et contrôler cette page dans les différents navigateurs.

Éléments de contenu courants

Il n'y a en principe pas de raisons de devoir modifier ou retirer les fragments inclus dans cette partie. Ils représentent toutes les typologies de contenu : paragraphes, listes, tableaux, titres et intertitres, medias. Pour une large part, ces fragments sont tirés de [Tiny Typo](http://tinytypo.tetue.net/) de Romy Duhem-Verdière.

Formulaires et interactions

Selon la nature du projet, ces fragments seront éventuellement à compléter avec des éléments de formulaire plus complexes ou différents types de messages. Ils reflètent ce qui nous a semble constituer les éléments les plus couramment rencontrés.

Nous y avons ajouté la démonstration du module [textarea-counter](/scampi/documentation/textarea-counter.html), un composant accessible décomptant le nombre de caractères restant lorsque le champ de saisie en limite le nombre (fragment *3-textarea-counter*).

Composants

Et enfin viennent les démonstrations des composants les plus courants du site (ou tous, selon ce qui vous semblera utile). Nous avons placé dans ce répertoire tous les modèles (patterns, snippets, selon la terminologie) des modules d'interface de Scampi. Incluez ceux que vous utilisez, ajoutez ceux que vous créez.

Nous avons d'ores et déjà inclus les fragments des composants obligatoires au regard du RGAA : skip-link et breadcrumb.

_styleguide.scss

Un fichier est prévu pour styler spécifiquement le styleguide en tant que tel, par exemple les titres des parties du styleguide, les galeries d'icônes et illustrations, le rendu des fontes, la palette de couleurs, etc.

On préfixe toutes les classes spécifiques au styleguide avec `sg-` pour éviter les conflits entre les feuilles de style du projet et celle-ci.

Modules recommandés

  • le module collapse pour plier/déplier les différents chapitres du styleguide ;
  • le module u-palette pour afficher les échantillons de couleurs.

Ces deux modules sont assortis de scripts. Deux options sont possibles : les joindre à tous les autres scripts du projet ou créer un fichier spécifique les concaténant qui sera importé en plus de main.js uniquement dans cette page. La même alternative existe pour les scss : soit dans la scss maître, soit les ajouter uniquement dans la page concernée.