La librairie de style de tous les outils LSSD

Ce que contient la librairie

La librairie ne contient que du CSS. Elle ne fournit ni JavaScript, ni gabarit de page : chaque outil écrit son HTML (templates Django, composants React…) avec ces classes.

Le principe : une version figée, copiée au build

ui.lssd.fr publie chaque version de la librairie dans une archive qui ne change plus jamais. Un outil choisit une version, la télécharge pendant la construction de son image Docker, vérifie son empreinte SHA-256, puis la compile avec Tailwind avec le reste de son CSS. Le navigateur ne charge que le CSS compilé, servi par l’outil lui-même.

• Jamais de lien direct vers un fichier de ui.lssd.fr dans une page : Tailwind ne compile pas un CSS distant, et une panne du site casserait l’affichage de tous les outils.
• Une mise à jour est un choix : un outil passe à une nouvelle version en changeant un numéro, puis il se teste avant le déploiement.
• Si ui.lssd.fr est indisponible, seule la construction d’une image échoue ; les outils en production continuent de fonctionner.

Installation

Version actuelle : 1.0.0, empreinte SHA-256 :

b34c40a92021933668b2da0fa9d52ab2b738d0a257890a8bc893260c3110c388

Les autres versions et leurs empreintes sont sur la page Versions.

1. Télécharger la librairie dans l’image Docker

Ajoutez une étape au Dockerfile de l’outil. ADD --checksum refuse l’archive si son empreinte ne correspond pas : personne ne peut la remplacer en cours de route.

# syntax=docker/dockerfile:1

# --- lssd-ui: the pinned LSSD UI library, checksum verified ---
FROM python:3.13-slim AS lssd-ui
ARG LSSD_UI_VERSION=1.0.0
ARG LSSD_UI_SHA256=b34c40a92021933668b2da0fa9d52ab2b738d0a257890a8bc893260c3110c388
ADD --checksum=sha256:${LSSD_UI_SHA256} \
    https://ui.lssd.fr/releases/v${LSSD_UI_VERSION}/lssd-ui-${LSSD_UI_VERSION}.tar.gz /tmp/lssd-ui.tar.gz
RUN mkdir /out && tar -xzf /tmp/lssd-ui.tar.gz -C /out

Puis copiez-la à côté de l’entrée Tailwind, dans l’étape qui compile le CSS et dans l’étape de développement, par exemple dans static/css/vendor/lssd-ui/ :

COPY --from=lssd-ui /out/lssd-ui/ static/css/vendor/lssd-ui/

Ajoutez static/css/vendor/ au .gitignore : la librairie n’est jamais commitée dans l’outil, l’image la récupère à chaque construction.

2. Importer la librairie dans l’entrée Tailwind

/* static/css/input.css */
@import "tailwindcss";
@import "./vendor/lssd-ui/index.css";

/* Tell Tailwind where the classes are used. */
@source "../../templates";

L’ordre compte : Tailwind d’abord, LSSD UI ensuite. Le CSS propre à l’outil, s’il en a, vient après et n’utilise que les variables de la librairie.

3. Compiler avec Tailwind

Projet sans Node (Django, site statique) : le CLI autonome de Tailwind, dans l’image.

RUN tailwindcss --input static/css/input.css --output static/css/app.css --minify

Projet Node : @tailwindcss/vite ou @tailwindcss/postcss, avec la même étape lssd-ui et le même @import. Jamais de Tailwind chargé par CDN.

4. Préparer la page

<!DOCTYPE html>
<html lang="fr" data-theme="light">
<head>
  <link rel="preconnect" href="https://api.fontshare.com">
  <link rel="preconnect" href="https://cdn.fontshare.com" crossorigin>
  <link rel="stylesheet" href="https://api.fontshare.com/v2/css?f[]=general-sans@400,500,600,700&amp;f[]=cabinet-grotesk@500,700,800&amp;display=swap">
  <link rel="stylesheet" href="/static/css/app.css">
</head>
<body class="bg-bg text-ink font-sans antialiased">
  <header class="lssd-header">…</header>
</body>
</html>

Pensez à autoriser Fontshare dans la politique de sécurité du contenu (CSP) : style-src 'self' https://api.fontshare.com et font-src 'self' https://api.fontshare.com https://cdn.fontshare.com.

5. En développement

compose.override.yaml monte le code de l’outil dans le conteneur, ce qui masque le dossier copié par l’image. Déclarez ce dossier comme volume anonyme : Docker le remplit avec le contenu de l’image.

services:
  web:
    volumes:
      - ./:/app
      - /app/static/css/vendor

Après un changement de version, recréez ces volumes : docker compose up -d --build --renew-anon-volumes.

Thème clair et sombre

Le thème clair s’applique par défaut. L’outil pose data-theme="light" ou data-theme="dark" sur <html>, d’après le réglage de l’utilisateur ou, à défaut, prefers-color-scheme. Posez l’attribut avant le premier affichage (script chargé dans le <head>) pour éviter un flash de la mauvaise couleur.

// Before the first paint: stored choice, otherwise the system setting.
var stored = null;
try { stored = localStorage.getItem("lssd-theme"); } catch (error) {}
var dark = window.matchMedia("(prefers-color-scheme: dark)").matches;
document.documentElement.setAttribute("data-theme", stored || (dark ? "dark" : "light"));

Les variables changent de valeur avec l’attribut ; les classes ne changent pas. Pour un détail propre au thème sombre, utilisez la variante dark: (par exemple dark:hidden sur une icône).

Mettre à jour un outil

1. Lisez les notes de la nouvelle version sur la page Versions.
2. Changez LSSD_UI_VERSION et LSSD_UI_SHA256 dans le Dockerfile.
3. Reconstruisez : docker compose up -d --build --renew-anon-volumes.
4. Vérifiez les écrans dans les deux thèmes, de 360px à 1440px de large, puis commitez la montée de version seule.

Les numéros de version suivent la gestion sémantique :

Règles d’intégration

Il manque un composant ? Il s’ajoute dans la librairie, pas dans l’outil : voyez la section suivante.

Faire évoluer la librairie

Toute évolution passe par le dépôt de LSSD UI, puis par une nouvelle version que chaque outil adopte à son rythme.

1. Modifiez les fichiers de lib/ et vérifiez le rendu dans cette documentation (docker compose up, puis http://localhost:8001).
2. Documentez le changement dans site/ : composant, règle ou token.
3. Changez le numéro dans VERSION et ajoutez sa section en tête de CHANGELOG.md.
4. Publiez l’archive : docker compose run --rm web python scripts/release.py.
5. Déployez ui.lssd.fr. La construction de l’image refuse un changement de lib/ qui n’a pas été publié dans une nouvelle version.