Design-system-of-a-down NPM

Design System Pôle Emploi

L'outil de Design System / Styleguide est Fractal. Cet outil, basé sur NodeJS, n'est pas associé à un langage ou framework en particulier et peut être construit à partir de simple HTML / CSS / JS statiques.

Installation

Installation depuis le Terminal :

Déplacez-vous à l'endroit ou sera copié le repo GIT : commande cd /path/to/folder
Important : Pour que les maquettes et le design system puissent communiquer entre eux, il est important que les deux soient dans le même répertoire parent comme ci-dessous
```
  repertoire_commun
   ├── design-system
   └── pole-webdesign
```
Cloner le repo : git clone ssh://git@git-scm.pole-emploi.intra:2222/studio-pole-emploi/design-system.git
Installer Fractal et toutes les dépendances :
- cd ./design-system && npm install

Pour en savoir plus le fonctionnement de Fractal vous pouvez consulter sa documentation

Mise en oeuvre du Design System

Deux types de tâches sont à accomplir pour compiler et générer le Design System :

Les tâches Gulp dans un premier temps vont s'occuper des assets (SCSS, JavaScript, ...) pour les réunir dans le bon ordre, les rassembler pour être récupérables par Fractal
Les tâches Fractal de génération et visualisation du Design System

Ces tâches sont rassemblées en deux tâches raccourcies, ce sont les tâches à employer pour lancer le Design System :

npm run dev ouvre Fractal sur un serveur local, synchronisé avec Browsersync. C'est la tâche à privilégier au quotidien?
npm run prod compilation en HTML statique. Cette méthode génère le dossier dist statique. Il est utilisé pour le script Jenkins pour déployer sur le serveur PE.

Interface

L'interface du Design System affiche différentes zones d'information :

Un panneau latéral de navigation (recherche, documentation et composants)
Une prévisualisation (preview) d'un composant sélectionné, au sein d'un élément <iframe>
Un panel d'onglets concernant le composant sélectionné (Notes, HTML, NJK)

Les Styles CSS

Les styles CSS des Maquettes et Composants de Pôle Emploi sont fondés sur Sass (syntaxe .scss).

Ces fichiers CSS sont un assemblage de plusieurs sources, dans cet ordre :

Les variables communes à tous les univers PE (prévues pour écraser les valeurs par défaut de Boostrtrap)
Les variables spécifiques à un univers PE (ex. candidat, entreprise, etc.)
Bootstrap 4.6.1 (contenant les valeurs de variables par défaut ainsi qu'un fichier reset)
La feuille de style de base pe-base.scss
Et les styles spécifiques à chacun des composants, si besoin

Les Scripts JavaScript

Les scripts utilisés dans les univers Pôle Emploi sont :

jQuery 1.9.1
popper
Bootstrap JS 4.6.1
Bootstrap-accessibility.js (source ?)
bootstrap-slider (input slider)
short-and-sweet (limite de caractères de inputs)

Fractal

Architecture générale du Design System

La structure du projet, pour être compatible avec Fractal doit être de la sorte :

├── src
│   ├── components
│   └── docs
├── fractal.config.js
├── package.json
├── public
├── dist

Description des dossiers et fichiers concernés :

fractal.config.js : configuration globale de Fractal (titre du projet, theme utilisé, langage employé pour les composants, sources des assets, destination de la compilation, etc.)
/src : dossier source comportant les composants, les assets, les feuilles de styles, les fichiers JS, etc.
/src/components : dossier source des composants, chacun dans son propre sous-dossier.
/src/docs : dossier source des pages de documentation relatives au Design System.
/public : dossier compilé temporaire, résultat des tâches Gulp de concaténation et transformation des assets source. Dossier servant de source de référence à Fractal (non versionné)
/dist : dossier compilé final, résultat de la compilation Fractal du Design System (non versionné)

Personnalisation du thème de Fractal

Le thème original de Fractal se nomme Mandelbrot. Il est customisable en partie dans le fichier fractal.config.js (skin global, intitulés, etc.)

Mandelbrot est cependant limité en terme de configuration.

Le fichier fractal-theme-overrides.css, créé pour l'occasion, applique des styles spécifiquement adaptés pour Pôle Emploi.

Ce fichier est déclaré dans fractal.config.js de cette manière :

const Theme = require('@frctl/mandelbrot')({
    styles: [
        'default',
        '/fractal-theme-overrides.css'
    ],

Rappel des tâches principales

Une fois le Design System et ses dépendances installés, les tâches de compilation sont les suivantes :

npm run dev ouvre Fractal sur un serveur local, synchronisé avec Browsersync
npm run prod compilation en HTML statique. Cette méthode génère le dossier dist statique. Utilisé pour le script Jenkins pour déployer sur le serveur PE.

Alimenter la Navigation et la documentation du DS

Les items de navigation sont ajoutés automatiquement dans le panneau latéral :

Les pages statiques de documentation : fichiers markdown placés dans le dossier src/docs
Les composants : dossiers placés dans le dossier src/components

Règles d'écriture

Quand on souhaite parler d'un élément html, un paragraphe par exemple, on écrira "l'élément <p>".

Quand on souhaite parler d'un attribut html, le type par exemple, on écrira "l'attribut type".

Quand on souhaite parler d'une classe CSS, la classe de texte caché par exemple, on écrira "la classe sr-only".

Créer une entrée à collapse

Il est possible d'avoir une entrée (document et composant) qui se déploie et contient des enfants. Pour y arriver, il faut créer dans src/docs ou src/components un dossier qui va servir de conteneur. En ajoutant des enfants (sous-documents dans la partie docs, sous-composants dans la partie composants)dont le nom est différent du dossier qui les accueille, Fractal va automatiquement créer une arborescence entre eux.

├── components
│   ├── composant
│   │   ├── sous-composant
│   │   │   └── ...
│   │   ├── sous-composant
│   │   └── ...

Créer un "regroupement" de composants

Dans le dossier src/components, créer un nouveau dossier nom-regroupement qui va accueillir les composants à regrouper. À la racine de ce dossier, ajouter un fichier de config nom-regroupement.config.js avec la variable root à true. Ensuite il suffit de placer les dossiers de composants dans notre dossier nom-regroupement.

├── components
│   ├── regroupement
│   │   ├── regroupement.config.js
│   │   ├── composant
│   │   └── ...

module.exports = {
    root: true,
    name: "Formulaire"
}

Alimenter en Composants

Les Composants (alert, modal, breadcrumb, etc.) nécessitent une structure et une configuration spécifiques.

Hierarchie des composants :

├── components
│   ├── _preview.njk
│   ├── alert
│   │   ├── alert.config.js
│   │   ├── alert.accessibility.md
│   │   ├── alert.docmacro.md
│   │   ├── alert.njk
│   │   ├── alert.scss
│   │   ├── alert.js
│   │   └── readme.md

Les informations concernant chaque composant sont rassemblées au sein d'un dossier à son nom, comportant :

nom-composant.njk (ici alert.njk): Le code source du composant au format Nunjucks .
readme.md: La documentation du composant en markdown. Cette documentation est affichée dans l'onglet "Notes" sous le visuel du composant.
nom-composant.config.js (ici alert.config.js): La configuration (variantes, styles spécifiques) du composant au format d'un objet JS.
nom-composant.accessibility.md (ici alert.accessibility.md): La documentation sur les spécificités d'accessibilité du composant en markdown. Fait parti des panneaux ajoutés dans la customisation du thème Fractal.
nom-composant.scss (ici alert.scss): Styles sass du composant. Sera compilé automatiquement via Gulp.
nom-composant.js (ici alert.js): script JS supplémentaire. Sera importé dans _preview.njk via Fractal
nom-composant.docmacro.md (ici alert.docmacro.md): Documentation de la macro s'il y en a une. Reprend en md un exemple d'appel à la macro et un détail de tous ses paramètres (nom, type, obligatoir ou non, valeur par défaut, description)

Détail du fichier de config d'un composant-type :

module.exports = {
    variants: [
        {
            preview: "@preview--candidat",
            name: "candidat",
            context: {
                text: "mes styles appliqués sont : pe-candidat"
            }
        },
        {
            preview: "@preview--entreprise",
            : "prototype",
            name: "entreprise",
            context: {
                text: "mes styles appliqués sont : pe-entreprise"
            }
        }
    ]
}

Importer des scripts externes dans un composant

Pour certains composants, il sera nécessaire d'importer un ou plusieurs scripts externes. Ces scripts doivent se trouver dans le répetoire assets/js. Pour les importer automatiquement dans la preview du composant, il suffira de renseigner le ou les noms des fichiers à importer dans le contexte du composant, via une clé scripts ayant pour valeur un tableau d'un ou plusieurs scripts.

Cette clé peut se trouver aussi bien dans le contexte global, qu'uniquement dans le contexte de certaines variantes du composant.

...
context: {
    scripts: ['bootstrap-slider.min.js']
}
...

Styliser les Composants

La tâche gulp styles génère les fichiers suivants dans src/assets/css (qui serviront de source à Fractal) :

styles-pe.css
styles-pe-candidat.css
styles-pe-entreprise.css
styles-pe-conseiller.css

Ces fichiers CSS sont un assemblage de plusieurs sources, dans cet ordre :

les variables communes à tous les univers PE (dans src/assets/sass/variables-pe/)
les variables spécifiques à un univers PE (dans src/assets/sass/variables-pe/)
Bootstrap 4.6.1 (récupéré de node_modules)
Et les styles spéficiques à chacun des composants, si besoin (dans components/**/*.scss)

Méthodologie générale :

Le fichier Bootstrap a pour rôle d'indiquer des valeurs de variables (constantes) par défaut (ex. $primary: $blue !default;). Il est également le garant des styles par défaut de l'ensemble des composants des projets Pôle Emploi.
Les fichiers de variables (variables-pe.scss, variables-pe-candidat.scss, etc.) ne doivent contenir que des modificateurs de variables (qui diraient par exemple $primary: hotpink;) et non des nouvelles variables non existantes dans Bootstrap.
Les fichiers CSS associés à chaque composant (ex. alert.scss) devraient être optionnels et ne devraient comporter que des variables, voire des styles spécifiques, non existants dans Bootstrap.
Et enfin, les fichiers styles-pe-***.scss servent à importer les différentes autres sources de styles dans le bon ordre.

Exemple pour le fichier styles-pe-entreprise.scss :

// Import des variables Pôle Emploi globales
@import 'variables-pe/variables-pe.scss';

// Import des variables Pôle Emploi Entreprise
@import 'variables-pe/variables-pe-entreprise.scss';

// Import de Bootstrap
@import "./node_modules/bootstrap/scss/bootstrap";

// Import des styles spécifiques de chaque composant
@import '../../components/**/*.scss';

Au final, le composant alert, selon son univers, affichera les styles suivants :

Styles de base de Bootstrap (display, etc.)
Variables de couleurs globales (variables-pe/variables-pe.scss) ou variables de couleurs d'un univers précis (ex. variables-pe/variables-pe-entreprise.scss) destinées à écraser les variables Bootstrap
Styles spéficiques au composant qui ne seraient pas couverts par Bootstrap.

Prévisualiser les Composants

Les previews des composants sont générés au sein d'une iframe afin de "scoper" les styles CSS et ne pas hériter de styles du thème.

Un fichier _preview.njk, présent à la racine du dossier de composants indique quels assets et styles sont appliqués à chaque composant selon son univers :

un composant commun à tous les univers sera affiché via _preview.njk (les styles appliqués sont /styles-pe.css)
un composant de l'univers Candidat sera affiché via le variant candidat décrit dans preview.config.js (les styles appliqués sont /styles-pe-candidat.css)
un composant de l'univers Entreprise sera affiché le variant entreprise décrit dans preview.config.js (les styles appliqués sont /styles-pe-entreprise.css)
etc.

Processus d'intégration des icônes

En entrée

Le dossier icons, présent dans src/assets/ contient un double lot d'icônes :

ico : contient les icônes de taille petite (16px) triés au sein de dossiers. Exemple : Action/Action-close.svg
ico-lg : contient les icônes de taille petite (48px) triés au sein de dossiers. Exemple : Action/Action-close.svg
les fichiers svg ne comportent aucun élément <title>, <decription>, etc.

Scripts exécutés

Plusieurs tâches Gulp sont exécutées dans cet ordre : icons_clean, icons_rename, icons_json et icons_clean_tmp.

Plus d'infos sur le processus : https://stackoverflow.com/questions/42167040/gulp-get-all-svgs-in-json

Tâche de nettoyage `icons_clean`

Minification via SVGOMG
Ajout d'une classe icon-*iconName*
Ajout des attributs aria-hidden="true" et focusable="false"
Renommage du nom de l'icône. (le répertoire des catégories est conservé pour la tâche icons_json)
Export des icones dans un dossier temporaire public/icons_tmp (sera utilisé par la tâche icons_json)

Tâche de nettoyage `icons_rename`

Copie des icones vers le répertoire final public/icons/ (sans les repertoires de catégories)

Transformation en fichier JSON `icons_json`

Génération d'un JSON des icones depuis le dossier temporaire vers public/icons/icons.json

Nettoyage du fichier temporaire `icons_clean_tmp`

On supprime le dossier créé temporairement pour le traitement JSON public/icons_tmp

En sortie

Le dossier icons, présent dans public/icons/ contient un double lot d'icônes :

ico : contient les icônes de taille petite (16px) sans dossier intermédiaire. Exemple : close.svg
ico-lg : contient les icônes de taille petite (48px) sans dossier intermédiaire. Exemple : close.svg
les fichiers svg comportent des attributs suivants (exemple pour l'icône "close") class="icon icon-close" aria-hidden="true" focusable="false".

@frctl/fractal @frctl/mandelbrot @frctl/nunjucks bootstrap del gulp gulp-beautify gulp-concat gulp-file-contents-to-json gulp-gzip gulp-json-transform gulp-rename gulp-sass gulp-sass-glob gulp-svgmin gulp-tar lodash.merge sass

1.0.0

1 year ago