UI Kit du Lab. ANSSI

Introduction

Le UI Kit du Lab. ANSSI est une bibliothèque de composants Svelte, pensée pour accélérer la création d’interfaces cohérentes et accessibles au sein des divers produits du Lab ANSSI.

Cette bibliothèque propose à la fois des composants Svelte et leurs équivalents WebComponents, facilitant leur intégration dans différents environnements front-end.

Le projet s’appuie sur des outils modernes tels que SvelteKit, Vite, Storybook et Vitest pour garantir une expérience de développement fluide, des tests robustes et une documentation interactive.

Pour commencer

Prérequis

• Node.js (version recommandée : >= 24)
• Svelte (version recommandée : >= 5.37.3)
• Vite (version recommandée : >= 7.0.6)
• Storybook (version recommandée : >= 9.1.1)
• pnpm (voir la version exacte spécifiée dans le package.json)

Développement en local

Clonez le dépôt puis installez les dépendances :

git clone https://github.com/betagouv/lab-anssi-ui-kit.git
cd lab-anssi-ui-kit
pnpm install

Documentation interactive

Storybook est intégré à ce dépôt afin de fournir des exemples d’utilisation, la liste des props et des cas d’usage pour chaque composant. Les stories sont regroupées dans le dossier stories/ et sont écrites en respectant le format CSF de Storybook.

Pour explorer et tester les composants en local, lancez Storybook à l'aide de la commande :

pnpm run storybook:dev

Suite à l'exécution de cette commande, Storybook se lancera automatiquement en ouvrant une fenêtre de votre navigateur par défaut vers l'url http://localhost:6006.

[!NOTE] Le Storybook est également déployé en ligne sur GitHub Pages et est consultable à l'url suivante : https://betagouv.github.io/lab-anssi-ui-kit/

Usage

L'intégralité des composants présents dans ce dépôts sont publiés sur NPM afin qu'ils puissent être consommés dans différents environnements front-end. La bibliothèque expose ses composants dans un dossier dist/ qui est construit à l'aide de la commande pnpm run build.

Ainsi, pour pouvoir consommer les éléments de cette librairie dans votre projet, vous devrez commencer par installer le package à l'aide de cette commande :

pnpm add -D @lab-anssi/ui-kit@latest

Vous pouvez ensuite importer les composants dans vos projets Svelte ou utiliser les WebComponents générés dans n’importe quelle application web.

Exemple d’import Svelte

import { Alerte, CentreAide, ResumePssi } from "@lab-anssi/ui-kit";

Exemple d'utilisation des WebComponents

Les WebComponents sont disponibles dans le dossier dist/webcomponents et peuvent être intégrés dans n’importe quel projet HTML/JS en commençant par importer la librairie WebComponents à l'aide du script suivant :

<script src="https://lab-anssi-ui-kit-prod-s3-assets.cellar-c2.services.clever-cloud.com/1.23.2/lab-anssi-ui-kit.iife.js"></script>

Une fois cet import effectué, les WebComponents sont prêts à être consommés dans votre projet :

<lab-anssi-centre-aide nom-service="MonService" liens="[...]"></lab-anssi-centre-aide>

Release

• Mettre à jour le package.json avec la nouvelle version

• Exécuter pnpm install

• Faire un commit et une PR [VERSION] Passe à la version X.X.X

• Valider la PR puis la merger

• Dans GitHub > Release cliquer sur le bouton Draft a new release

• Dans le formulaire New release :

  • Dérouler la liste puis cliquer sur Create new tag

  • Nommer le tag v.X.X.X

  • La target reste main

  • Release title : v.X.X.X

  • Release notes : utiliser le template ci-dessous :

    # :package: Nouveaux Composants
    
    - **DSFR** - Ajoute le composant `<COMPOSANT>` – [#<ID_PR>](LIEN_PR)
    - **LAB** - Ajoute le composant `<COMPOSANT>` – [#<ID_PR>](LIEN_PR)
    
    # 🐞 Corrections et améliorations
    
    - **DSFR <NOM_COMPOSANT>** - <DESCRIPTION> – [#<ID_PR>](LIEN_PR)
    - **LAB <NOM_COMPOSANT>** - <DESCRIPTION> – [#<ID_PR>](LIEN_PR)

  • Cliquer sur Publish release

• Aller dans les actions GitHub > Publication du package sur NPM et lancer la publication sur la version vX.X.X