Commencer
Le kit Web est conçu pour gérer l'implémentation du design système de l'autonomie pour les navigateurs Internet sur les ordinateurs (de bureau ou portable) et appareils mobiles (téléphone ou tablette).
Le kit React Native est quand à lui destiné à une utilisation dans le cadre d’une application mobile (livrée sur un store).
Web Components
Pour une utilisation dans le contexte d'une application web
React Native
Pour une utilisation dans le contexte d'une application mobile
Vidéo tutoriel (8 min)
Découvrez comment implémenter la librairie et utiliser des composants.
1. Introduction
Bonjour et Bienvenue dans ce tutoriel !
On va voir ensemble comment créer un projet et utiliser les composants du Design System de l’Autonomie, ou DSA, en prenant comme exemple la boite de dialogue.
La documentation pour chaque composant du DSA est divisée en plusieurs partie :
- Usage : Quand utiliser le composant, exemple d’usages corrects et incorrects.
- Style : Anatomie du composant, et différentes variantes.
- Web : Utilisation du custom element, donc du composant technique
- Accessibilité : Pour comprendre comment l’utilisation de ce composant peut impacter l’accessibilité de vos utilisateurs
- Exemples d’utilisation
La boîte de dialogue permet d’interrompre le parcours d’un utilisateur, généralement pour des tâches peu fréquentes et/ou courtes. Par exemple, lui demander une réponse immédiate, afficher un message important ou lui demander une confirmation. On va voir pas à pas comment l’intégrer dans un projet, le configurer, et surtout comment l’utiliser correctement en respectant l’accessibilité.
2. Création du projet avec Vite + installation du package
Pour la démonstration, je vais repartir de zéro avec un projet Vite.
Donc on va d’abord créer un nouveau projet Vite, qui s’appellera dialog-demo, en Typescript.
On va ensuite aller dans le répertoire créé, et installer les packages de base.
pnpm create vite@latest dialog-demo --template vanilla-ts
cd dialog-demo
pnpm install
Ensuite on va ajouter nos packages du design system de l’autonomie, c’est à dire le package web-components, qui va nous donner les différents custom elements (les web components), et le package assets, qui va contenir les styles.
On peut ensuite lancer notre projet.
pnpm install --save @ds-autonomie/assets @ds-autonomie/web-components
pnpm dev
Dans l’éditeur de code, on va d’abord importer polices de caractère, ainsi que les styles du DSA.
index.html
<link rel="preconnect" href="<https://fonts.googleapis.com>" />
<link rel="preconnect" href="<https://fonts.gstatic.com>" crossorigin />
<link href="<https://fonts.googleapis.com/css2?family=Cabin:ital,wght@0,400..700;1,400..700&family=Montserrat:ital,wght@0,400..700;1,400..700&display=swap>" rel="stylesheet" />
Puis, dans style.css, on peut enlever ce que Vite nous a mis, et on ajoute les imports, du package assets, et du package web-components.
style.css
@import "@ds-autonomie/assets/css/dsa-theme.min.css";
@import "@ds-autonomie/web-components/dist/themes/dsa-wc-theme.min.css";
Tout est maintenant en place pour pouvoir ajouter nos composants.
3. Mise en place du composant
a. Aperçu de la documentation
La documentation du composant Dialog nous montre les différentes options disponibles pour ce composant.
On a donc :
- les attributs et propriétés
- les méthodes
- les slots
- les événements
Dans notre exemple, nous allons utiliser l’attribut label pour le titre de la boite de dialogue, le slot par défaut pour le contenu principal, et le slot footer pour y mettre les boutons.
Et nous utiliserons également les méthodes show et hide afin de gérer l’affichage de la boite de dialogue."
b. Import et ajout des éléments dans la page
Dans notre fichier main.ts, on importe simplement les composants. On aura besoin du dsa-dialog, mais également du dsa-button pour l’utiliser à l’intérieur de la boîte de dialogue, et en tant que déclencheur pour l’ouverture de celle-ci.
On importe également les types associés car on en aura besoin plus tard.
main.ts
import './style.css';
import "@ds-autonomie/web-components/dist/components/dialog/dialog.js";
import type { DSADialog } from "@ds-autonomie/web-components";
import "@ds-autonomie/web-components/dist/components/button/button.js";
import { DSAButton } from "@ds-autonomie/web-components";
Puis dans le index.html, on ajoute le bouton qui va ouvrir la boîte de dialogue, et la structure du dsa-dialog.
index.html
<dsa-button id="open-dialog">Ouvrir la boîte de dialogue</dsa-button>
<dsa-dialog id="demo-dialog" label="Bienvenue 👋">
<p>Merci de rejoindre le <strong>Design System de l’Autonomie</strong> ! Notre objectif est de vous aider à créer des interfaces cohérentes, accessibles et simples à utiliser.</p>
<p style="margin-top: 1rem">Vous trouverez ici des <strong>composants réutilisables</strong>, des <strong>bonnes pratiques UX</strong> et des <strong>guides d’accessibilité</strong> pour vos projets.</p>
<dsa-button slot="footer" id="skip" variant="tertiary">Passer</dsa-button>
<dsa-button slot="footer" id="learn-more">Explorer la documentation</dsa-button>
</dsa-dialog>
Donc ici on a bien :
- l’attribut label avec le titre de la boite de dialogue,
- le contenu de la boite de dialogue dans le slot principal
- et ensuite dans le slot footer 2 boutons, un bouton “Passer” et un autre bouton “Explorer la documentation”
Sur chacun des éléments, donc les 3 boutons et la dialog, on a ajouté des identifiants afin de pouvoir les trouver dans le code javascript, et ajouter de l’interactivité.
c. Gestion des interactions
On a maintenant la structure HTML, et il nous reste à ajouter un peu de JavaScript pour gérer l’ouverture et la fermeture de la boite de dialogue.
Donc, dans notre fichier main.ts on vient ajouter cette logique.
main.ts
const dialog = document.querySelector<DSADialog>("#demo-dialog")!;
document
.querySelector<DSAButton>("#open-dialog")!
.addEventListener("click", () => dialog.show());
document
.querySelector<DSAButton>("#skip")!
.addEventListener("click", () => dialog.hide());
document
.querySelector<DSAButton>("#learn-more")!
.addEventListener("click", () => {
alert("Allons explorer !");
dialog.hide();
});
On va chercher notre dialog, et on va chercher le bouton d’ouverture, auquel on va ajouter un event listener pour écouter les clics. Et au clic donc on reprend notre dialog, et on utilise la méthode show pour pouvoir l’afficher.
Et on fait la même chose avec les deux boutons qui sont à l’intérieur de la dialog, le bouton “Passer” pour lequel on va utiliser la méthode hide, et le bouton “Explorer la documentation” où là on va pour le test juste ajouter une alerte et aussi cacher la dialog.
Et donc maintenant si je clique sur le bouton j’ai bien la dialog qui s’affiche. On voit bien ici le label, le contenu, et à l’intérieur du footer, les deux boutons.
Si je clique sur “Passer” la boite de dialogue se ferme. Si je clique sur “Explorer la documentation” on a bien une alerte et la boite de dialogue se ferme.
On peut aussi fermer la fenêtre en cliquant à l’extérieur de la boite de dialogue ou avec la touche Échap.
d. Focus sur l’accessibilité
Le composant Dialog du DSA intègre déjà les bonnes pratiques d’accessibilité. Il est construit suivant le modèle de conception du W3C.
- A l’ouverture, le focus est déplacé sur la boîte de dialogue, et est piégé à l’intérieur tant qu’elle est ouverte.
- La boîte de dialogue possède un role="dialog" et un attribut aria-modal="true"
- Le nom accessible du dialog lui est donné par l’attribut label ou le contenu du slot du même nom.
- Et la fermeture est possible via la touche Échap.
- A la fermeture, le focus revient sur l’élément déclencheur.”
Vous pouvez trouver plus de détail concernant l’accessibilité du dsa-dialog sur la page dédiée dans la documentation.
4. Conclusion
Voilà, vous savez maintenant comment utiliser le composant Dialog du Design System de l’Autonomie ! On a vu comment créer un projet, installer les composants, ajouter un dsa-dialog, gérer son ouverture et sa fermeture, et vérifier que l’accessibilité est respectée.
N’oubliez pas d’explorer la documentation pour découvrir d’autres variantes et composants pour pouvoir les intégrer à vos projets.
Quiz
Ce quiz permet d’insister sur certaines notions fondamentales, et aider les nouveaux arrivants dans leur montée en compétences.