Grace
Guides

Développer les composants avec Storybook

Consulter, documenter et prévisualiser le design system Grace depuis Storybook et son serveur MCP local.

Storybook expose les composants partagés de Grace dans un catalogue local. Son addon MCP permet aux agents de code de découvrir leurs props et leurs stories au lieu de les déduire du nom ou du code source.

Le catalogue est un outil de développement du frontend. Il n'ajoute aucune route à l'application Grace et n'est pas déployé avec elle.

Scope et baseline

Le catalogue couvre chaque composant React rendu ré-exporté publiquement par platform/frontend/src/components/ui/index.ts, y compris les icônes ré-exportées depuis Icon.tsx. Les composants ordinaires ont une story colocalisée ; le jeu d'icônes peut être couvert par une unique story galerie typée et découvrable. Les hooks, helpers, types, fonctions de style, routes/pages et organisms locaux restent hors scope tant qu'ils ne sont pas promus dans cette entrée publique.

La cible est une couverture complète de ce périmètre. Le baseline honnête du 2026-08-20 ne documente que Button : les 25 composants d'icône ne sont pas encore représentés, et aucune couverture des autres exports n'est revendiquée. La migration se fait lorsqu'un composant du scope est créé ou modifié ; une campagne de rattrapage demande une tranche explicitement autorisée.

Démarrer le catalogue et le MCP

Depuis la racine :

mise run storybook

Le script npm reste l'équivalent package-local et le propriétaire des options de sécurité :

cd platform/frontend
npm ci
npm run storybook

Le serveur écoute uniquement sur la boucle locale, à l'adresse http://127.0.0.1:6006. Le catalogue est aussi ouvrable via http://localhost:6006.

Le script impose le port 6006 : s'il est occupé, Storybook s'arrête au lieu de choisir un autre port qui rendrait la configuration MCP incorrecte.

Consulter le composant documenté

Au 2026-08-20, le seul composant documenté est l'atome Button, avec les stories :

  • Primary ;
  • Ghost ;
  • Danger ;
  • Disabled.

Les 25 composants d'icône ré-exportés depuis Icon.tsx ne sont pas encore représentés dans le catalogue.

Ouvre la documentation locale du bouton pour modifier ses contrôles variant et size. Dans une story ouverte, l'onglet Accessibility affiche les violations, passes et résultats inconclusifs détectés par axe. Ce contrôle automatique complète les tests et la revue clavier ; il ne prouve pas à lui seul une conformité WCAG AA.

Utiliser Storybook depuis un agent

La racine du dépôt déclare le serveur storybook dans .mcp.json :

{
  "storybook": {
    "type": "http",
    "url": "http://127.0.0.1:6006/mcp"
  }
}

Démarre Storybook avant la session de l'agent ou recharge ses serveurs MCP après le démarrage. Le MCP est un conseil de reconnaissance, jamais une autorité : avant d'utiliser un composant du catalogue, l'agent appelle dans cet ordre :

  1. list-all-documentation pour découvrir les composants et les story IDs disponibles ;
  2. get-documentation pour lire les props et exemples du composant choisi ;
  3. get-storybook-story-instructions avant de créer ou modifier une story ;
  4. preview-stories après une modification visuelle pour obtenir l'URL de contrôle.

Les manifestes viennent des stories CSF/MDX et du docgen : leurs props, descriptions et exemples doivent rester fidèles au code. Une fixture invalide ou seulement pédagogique porte !manifest. Si Storybook est arrêté, l'appel MCP doit échouer explicitement : l'agent signale la limitation, il n'invente ni prop ni état pour la contourner.

Adapter l'import proposé

Le manifeste expérimental déduit actuellement @grace/frontend depuis le nom du package privé. Ce package n'est pas publié et ne définit pas d'export public : dans le frontend, conserve les imports relatifs existants via components/ui.

Ajouter ou maintenir une story

Les stories des composants ordinaires du scope vivent à côté du composant dans platform/frontend/src/components/ui/ et portent le suffixe .stories.tsx. Le jeu d'icônes peut être couvert par une unique story galerie typée et découvrable. Les stories utilisent CSF3 typé (Meta/StoryObj et satisfies), un export nommé UpperCamelCase, le composant réel et les tokens chargés par src/index.css.

La meta porte autodocs et exactement un tag de cycle de vie : experimental, stable ou deprecated. Une story couvre le défaut, les variantes et les états publics qui changent une décision ou une interaction — notamment les états disabled, loading, empty, error ou denied quand le composant les expose. args est le moyen par défaut ; render ne sert qu'à une composition nécessaire ; un play prouve une interaction, un clavier ou un focus observable.

Une story reste déterministe : pas de requête ou service live, secret, routing, store, règle métier, date courante ou hasard. Si un composant promu dans ce scope exige ultérieurement un transport, utiliser des fixtures fixes et des handlers MSW par story pour les cas success/error/loading ; ne pas installer MSW avant ce besoin réel. Une modification ou suppression du composant met à jour ou retire sa story dans le même changement ; une story deprecated nomme son remplacement.

Le catalogue est volontairement incomplet au baseline. Ajoute ou mets à jour une story lorsqu'un composant du scope est créé ou modifié, plutôt que par campagne spéculative.

Construire le catalogue statique

npm run storybook:build

La commande produit platform/frontend/dist/storybook. Cet artefact permet une revue humaine, mais ne lance aucun processus MCP : /mcp n'existe que pendant npm run storybook.

Le job frontend de CI exécute ce build pour détecter une story ou une configuration cassée.

Interactions et accessibilité

L'addon a11y actuel détecte localement les violations axe : il complète, sans remplacer, la revue des rôles, noms accessibles, parcours clavier, focus et états définis par DESIGN.md. La tranche initiale n'installe pas @storybook/addon-vitest, donc run-story-tests n'est pas disponible et aucune commande test:storybook n'existe encore.

Lors du premier changement d'un composant du scope qui exige un play, ajouter l'addon Vitest compatible Vite, une commande test:storybook isolée et le gate CI associé, avec parameters.a11y.test: "error". Les histoires deviennent alors des tests de composants dans un vrai navigateur ; jusque-là, le build statique est le gate Storybook vérifié.

Sécurité et limites

  • Le serveur écoute exclusivement sur 127.0.0.1, impose le port 6006 et ne doit pas être exposé sur le LAN ou Internet.
  • N'injecte aucun secret dans une variable destinée à Storybook, une story, une fixture ou un manifeste ; ne publie pas le catalogue sans décision séparée sur l'accès, les secrets et les dépendances.
  • L'addon MCP et les manifestes sont en preview : leurs APIs et schémas ne sont pas des contrats stables.
  • platform/frontend/package-lock.json résout valibot@1.2.0 via @storybook/addon-mcp. L'avis de sécurité GitHub sur le comportement record()/flatten() de Valibot affecte les versions <=1.4.1 et est corrigé en 1.4.2. Cette dépendance demande une remédiation sécurité séparée ; la frontière locale reste obligatoire, mais ne constitue pas un correctif.

Contrôles avant livraison

Depuis platform/frontend :

npx eslint .storybook src/components/ui/Button.stories.tsx
npm run storybook:build
npm run build
npm test

Depuis la racine :

mise run docs:check

Le dépôt ne définit actuellement aucune tâche mise run check; utilise les tâches canoniques ci-dessus sans créer un second agrégateur implicite.

Sources officielles (vérifiées le 2026-08-20)

Gérer les talents de l’organisation

Créer, vérifier, publier et désactiver les talents propres à votre organisation.

Référence

Référence d'usage : outils MCP et dashboard.

On this page

Scope et baselineDémarrer le catalogue et le MCPConsulter le composant documentéUtiliser Storybook depuis un agentAjouter ou maintenir une storyConstruire le catalogue statiqueInteractions et accessibilitéSécurité et limitesContrôles avant livraisonSources officielles (vérifiées le 2026-08-20)