Brouillon à relire par Paul
Ce texte est un brouillon. Paul Périgault le relira et le réécrira avant publication.
Architecture
Cette page décrit les paquets, leurs dépendances, la chaîne de livraison et l’infrastructure. Chaque fait renvoie au fichier qui l’établit.
Paquets et sens des dépendances
Le dépôt compte six paquets npm et une application de documentation. astro dépend de css, et css dépend de tokens. Un import qui remonte ce sens est une erreur (AGENTS.md).
| Paquet | Rôle | Dépend de |
|---|---|---|
| @paulperigault/tokens | source DTCG, couleur et contraste | rien à l’exécution |
| @paulperigault/css | base, reset, polices, @theme Tailwind v4 | tokens |
| @paulperigault/astro | composants .astro, behaviors, variants() | css, tokens |
| @paulperigault/guards | contrôles de taille, couleurs, couches, images | rien à l’exécution |
| @paulperigault/create | CLI create, add, eject, diff | rien à l’exécution |
| @paulperigault/mcp | serveur MCP stdio en lecture seule | tokens, guards |
| apps/docs | documentation vivante du design system | tous les paquets |
Chaîne de livraison
Chaque modification passe par les workflows de .github/workflows. Le tableau liste ce que chacun vérifie.
| Contrôle | Vérification | Fichier |
|---|---|---|
| Commitlint | Commits de la PR, puis titre et corps : Conventional Commits | ci.yml |
| Verify | npm run verify : guards, lint, format, tests, build, pack | ci.yml |
| E2E | Build puis Chromium : axe WCAG 2.2 AA, 1.4.12, 2.5.8, mouvement réduit | ci.yml |
| Site | Site généré par la CLI, installé sur les tarballs, puis verify | ci.yml |
| Visuel | Captures sur 13 projets de matrice, références non versionnées | visual.yml |
| CodeQL | Analyse JavaScript et TypeScript, à chaque push, PR et lundi | codeql.yml |
| Supply chain | Signatures npm, scripts d’installation, audit haut, SBOM | supply-chain.yml |
| Scorecard | Note OpenSSF sur main, chaque mardi ; métadonnées publiées | scorecard.yml |
Le job ci échoue si l’un des jobs requis échoue ou est annulé. Dependabot fusionne automatiquement les correctifs et mineures vers main, pas les majeures.
Publication
Seul le workflow release.yml publie. Il ne publie rien tant que la branche main n’existe pas, selon son propre commentaire. Dans l’ordre :
- release-please prépare la PR de release sur main.
- Le job publish tourne dans npm-publish, avec id-token: write, sans NPM_TOKEN.
- Avant publication : build, npm audit signatures, puis SBOM CycloneDX.
- publish-new.mjs publie les versions absentes avec provenance. Préversion : dist-tag next.
La garde prepublishOnly refuse une publication hors CI.
Infrastructure
L’infrastructure est décrite en OpenTofu, dans la stack du portfolio et non dans ce dépôt. Selon docs/manual-steps.md, le plan prévoit :
- infra/github adopte le dépôt, puis crée main, les rulesets et npm-publish ;
- infra/ crée le projet Pages des docs et l’enregistrement DNS design.paulperigault.dev.
L’apply se fait à la main, par le propriétaire. Tant que les jetons ne couvrent pas le dépôt, le job tofu-plan saute son plan. L’hébergeur des docs n’est pas décidé : voir l’ADR-0004.
Choix cloud
- Statique : la sortie du build est un ensemble de fichiers.
- Sans serveur : la recherche Pagefind charge son index dans le navigateur.
- Sans cookie : aucun cookie n’est posé par le code de apps/docs.
- Hébergeur non décidé : voir l’ADR-0004.