======================================== Charte de l'interface de Zeste de Savoir ======================================== Les styles de Zeste de Savoir sont complexes, formés de l'empilement d'années de contributions par des personnes très différentes. Pour qu'ils restent maintenables, ce document propose une norme et des recommandations. Normalisation des styles ======================== Afin de garantir une cohérence à l'interface de Zeste de Savoir, plusieurs éléments graphiques sont normés. On ne parle pas ici de composants graphiques tels des boutons, des dialogues…, mais plutôt des éléments graphiques qui les composent : couleurs, polices, tailles, ombres… Tout développement graphique sur Zeste de Savoir **doit** respecter cette norme (avec quelques exceptions mentionnées ci-après). .. note:: Pourquoi tant de normes ? Le premier argument a déjà été cité : garantir une certaine cohérence à l'interface de Zeste de Savoir. Il y en a un second : ne pouvoir choisir que parmi une liste restreinte de possibilités permet de gagner du temps : on ne passe plus deux heures à essayer toutes les valeurs possibles entre deux tailles ou deux couleurs ; on prend la plus proche qui rend bien et *voilà*. Aussi, ça évite de *deviner* quelle valeur choisir au hasard. On peut enfin ajouter un troisième argument : ces normes ont été étudiées dans une optique d’accessibilité — à supposer qu'elles soient correctement utilisées (elles ne dispensent pas de vérifier les contrastes, par exemple). .. note:: Toutes ces normes sont `récapitulées sur un site web compagnon à la conception d'interfaces pour Zeste de Savoir `_, avec moyen de copier facilement les variables SCSS et d'estimer la couleur la plus proche de la palette automatiquement. **Vous travaillez sur ZdS sans accès à internet ?** Ce site web compagnon fonctionne même hors-ligne, à condition de l'avoir chargé une fois dans votre navigateur — retournez simplement sur le site même sans connexion. .. note:: Un `paquet npm `_ est également disponible si vous voulez réutiliser ces normes dans des projets affiliés à Zeste de Savoir. Couleurs -------- Zeste de Savoir utilise une palette de couleurs limitée. Lorsque vous choisissez une couleur pour quelque chose, vous devez piocher dedans. .. figure:: ../images/ui/colours.png :align: center .. seealso:: Cette palette est également `disponible en version interactive `__, avec un outil pour déterminer la couleur la plus proche d'une couleur donnée dans la palette. La palette est rendue disponible dans le code SCSS du site sous la forme de variables prêtes à l'emploi. Les noms des variables sont indiquées sur l'illustration plus haut, en combinant le nom indiqué sous le titre avec le numéro de la couleur (par exemple ``$purple-400``), et peuvent être copiés au clic sur la version interactive. Ainsi, n'écrivez pas : .. sourcecode:: scss .smoothie { color: #F0B429; } Mais plutôt : .. La coloration syntaxique ne comprend pas le dollar (cf https://github.com/pygments/pygments/issues/2130), donc pas de langage précisé .. sourcecode:: .smoothie { color: $accent-400; } .. attention:: Comme seules les couleurs de la palette doivent être utilisées, **vous ne devez pas utiliser les fonctions de traitement de couleur de Sass** (``lighten``, ``darken``, ``saturate``, ``desaturate``…). Si une couleur de votre choix vous semble trop claire ou trop sombre, utilisez la couleur d'à côté dans la palette. .. attention:: La seule exception à cette règle est le cas de couleurs de marque (par exemple, la couleur du bouton de connexion via Google ou Facebook). S'il manque des couleurs, il est toujours possible de réfléchir à ajuster la palette, mais vue la diversité proposée c'est relativement peu probable. Polices ------- Zeste de Savoir utilise trois polices de caractères sur le site : - une police sans empattement (``$font-sans-serif``), pour les textes de l'interface (il s'agit de Source Sans Pro, par défaut) ; - une police avec empattements (``$font-serif``), pour les contenus (cours, articles et billets) (Merriweather) ; - une police à chasse fixe (``$font-monospace``), pour les codes sources notamment (Source Code Pro). Vous pouvez utiliser ces polices via les variables SCSS sus-citées, qui incluent aussi les polices alternatives. Concernant les **tailles** de texte, elles sont également normalisées. Vous pouvez utiliser ces tailles (avec ces variables SCSS). .. figure:: ../images/ui/fonts.png :align: center .. seealso:: Cette liste est également `disponible en version interactive `__, avec prévisualisation pour les trois familles de police utilisées. Longueurs --------- Les longeurs des marges internes et externes, des tailles des blocs, des positionnements, …, sont également normalisées. Cela permet d'avoir une impression de cohérence globale à travers le site, en évitant d'utiliser toutes les longueurs existantes de façon aléatoire et chaotique. Vous pouvez utiliser ces longeurs (avec ces variables SCSS, si vous voulez). Le numéro dans le nom de la variable correspond à la longueur en pixels (ou en dixième de ``rem``). .. figure:: ../images/ui/lengths.png :align: center .. seealso:: Cette liste est également `disponible en version interactive `__. .. attention:: Cette norme peut être ignorée s'il s'agit d'aligner des éléments au pixel près. Cela dit, un code CSS moderne ne devrait pas nécessiter ce genre de choses. Par contre, certains éléments plus anciens du code de Zeste de Savoir sont concernés, et cette norme ne doit pas être un frein s'il s'agit de les faire évoluer. Ombres ------ Si un élément doit recevoir une ombre, utilisez l'une des six ombres standardisées ci-dessous. Plusieurs avantages : - ce sont des mixins, donc vous n'aurez pas à vous embêter à écrire le ``box-shadow`` alambiqué, simplement ``@import shadow-1`` ; - ces ombres sont conçues pour être naturelles, correspondant à une réelle ombre portée par une source de lumière unique. .. figure:: ../images/ui/shadows.png :align: center .. seealso:: Cette liste est également `disponible en version interactive `__. Arrondis -------- Si un élément doit avoir des coins arrondis, utilisez l'un de ces arrondis. Le dernier est configuré à une très grande valeur pour les cas où vous désirez avoir un élément circulaire (veuillez noter que pour qu'il soit effectivement circulaire, l'élément devra avoir des dimensions carrées). .. figure:: ../images/ui/radius.png :align: center .. seealso:: Cette liste est également `disponible en version interactive `__. Recommandations pour un SCSS propre =================================== Ces recommandations ne sont pas *obligatoires*, mais elles permettent d'assurer une cohérence du code SCSS du site et une plus grande facilité à rentrer dedans lorsque l'on est extérieur au projet. Utilisez *flexbox* et les grilles --------------------------------- CSS dispose de beaucoup d'options pour positionner les éléments les uns par rapport aux autres, mais certaines sont plus maintenables que d'autres. Il est recommandé **d'éviter au plus possible d'utiliser des positionnements absolus et des flottants**, au profit des outils CSS modernes et largement supportés que sont les `*flexboxes* `_ et les `grilles CSS `_. Conteneurisez le CSS -------------------- Non, chers *aficionados* de Docker, on ne parle pas de ça ici. Lorsque vous stylisez un élément en CSS, assurez-vous de ne styliser *que* ce que vous voulez. Évitez les règles avec une application beaucoup trop large qui affectent tout le site : ces règles ont tendance à être une horreur à maintenir, car elles font des effets de bord de partout, et la moindre modification peut casser une page totalement improbable à l'autre bout du site. Ainsi, préférez mettre tout le CSS stylisant un composant dans une classe parente unique dans le projet, par exemple : .. sourcecode:: scss .your-component { // Tout le CSS de ce composant là dedans, rien en dehors // Ainsi il ne pourra contaminer le reste du site } Si vous avez un composant avec de légères variations ça et là en fonction de son usage, bien sûr, ne réinventez pas la roue. Vous pouvez par exemple utiliser le modèle de Bulma, assez effiace, de modificateurs : .. sourcecode:: scss .your-component { // Tout le CSS de la version “de base” &.is-light { // CSS pour la version “light” } &.is-small { // CSS pour une petite version } &.has-dreams { // CSS pour la version qui a des rêves (?) } } …ce qui permet de les appliquer facilement à l'usage (en plus, c'est plutôt lisible). .. sourcecode:: html
Pensez à l'ordre des propriétés CSS ----------------------------------- Les navigateurs n'ont cure de l'ordre de déclaration des propriétés CSS (tant que les mêmes ne sont pas déclarées plusieurs fois), mais les placer dans un ordre logique aide grandement à la lecture du code, permettant plus facilement de saisir en un coup d'œil ce qui est déclaré, les éléments similaires étant groupés ensemble. Chacun⋅e aura sa logique, mais en voici une à titre indicatif : 1. positionnements (``position``, ``top``, ``left``, ``z-index``…) ; 2. affichage et modèle de boîte (``display``, ``overflow``, ``box-sizing`` ; ``width``, ``height``, ``margin``, ``padding`` ; ``border``, ``border-radius``…) ; 3. couleurs (``background``, ``color``…) ; 4. texte (``font-family``, ``font-size``, ``line-height``, ``text-align``, ``text-transform``…) ; 5. *les autres* (``cursor``…) ; 6. transformations et transitions, à la toute fin (``animate``, ``transition``, …). Et `en voici une autre `_. L'important reste que le code source soit clair et scannable facilement.