FSHSP-125 Storybook embarqué : le projet consommateur a sa propre doc

[LBU4SH]

Un projet en sources copiées possédait son code mais aucune doc : il lui restait un Storybook hébergé qui décrit nos composants, pas ses copies éditées. ng add @4sh/ui-kit-schematics --with-storybook lui donne le sien.

ng add @4sh/ui-kit-schematics --with-storybook
npm run storybook

Ce qui est posé

• La doc de chaque composant : story et MDX, à côté de ses sources.
• La configuration Storybook : storybook/ (main, preview, thème du manager, sélecteur de marque, pages Foundations / Spécifications / Configuration), cibles angular.json, devDependencies, scripts npm.
• La chaîne qui alimente la doc : scripts/docs.config.mjs et le bloc <ConfigTable>.

Deux choses font que cette doc appartient au projet. Les tables Theming sont lues sur ses propres .scss au build : elles décrivent ses valeurs, rebranding compris. Et les globs couvrent tout src/app/shared/components/** — une story écrite à côté d'un composant maison apparaît sans toucher à la configuration.

Désactivé par défaut : sans Storybook, story et MDX sont deux fichiers qui importent des packages absents. Le choix est retenu dans ui-kit.json, et update s'y tient.

Décisions

• Liens Figma retirés à la copie (48 stories) : le consommateur n'a pas accès à notre fichier, l'onglet Design n'ouvrirait qu'une porte fermée.
• Pages transverses limitées à Foundations, Spécifications et Configuration. Introduction, NpmPackage et Overview parlent du kit lui-même et restent ici.
• Compodoc inclus : une devDependency, le builder le pilote lui-même, et sans lui l'onglet API s'affiche sans description.
• --components retiré de ng add : le prompt qui s'ouvre deux secondes plus tard fait le même travail à la barre d'espace, et c'était le seul chemin cassé de la commande (le CLI transmettait une chaîne là où le schéma attend un tableau). L'option reste sur ng generate …:add, pour l'usage scripté.

Quatre pièges levés en montant un vrai projet

Aucun n'était visible sur un arbre virtuel :

1. Le CLI reformate à Prettier ce qu'un schematic écrit : {/* … */} en ressort en {/_ … _/}, MDX invalide, et l'indexeur Storybook refusait les 53 pages. L'en-tête de traçabilité passe par un export const.
2. @storybook/angular réclame des peers qu'un projet Angular moderne n'a plus (build-angular, platform-browser-dynamic, animations) : sans elles au package.json, npm résout un majeur antérieur et l'install échoue. animations est le plus retors — le build passe, et c'est au premier rendu que tout s'arrête.
3. Le builder Storybook exige output sur les assets du browserTarget, que ng new n'écrit plus.
4. Colors.mdx importe tokens.manifest.json : chemins du monorepo réadressés, et tokens:build chaîné avant le build plutôt que laissé au postinstall.

Vérification

ng new sur Angular 22, puis un seul ng add --with-storybook --all, puis npm run build-storybook : build réussi, 579 stories et 64 pages indexées. Rendu contrôlé dans le navigateur — la story s'affiche, l'onglet API est renseigné par Compodoc, la table Theming résout ses valeurs sur les SCSS du projet (44px, 16px), la page Colors lit le manifeste de tokens du projet.

Reste à trancher (hors périmètre)

• Les extraits de code de ui-icon.mdx importent @4sh/ui-kit, un package que le consommateur n'a pas : c'est de la prose à reprendre côté kit, pas un import à résoudre.
• Le lien vers le Storybook hébergé dans les README du compagnon n'a plus lieu d'être une fois la doc locale en place.

🤖 Generated with Claude Code