Comment structurer un Storybook qui serve de contrat

Storybook n'est pas une galerie

En 2024, sur près de 17 millions de sites analysés par le Web Almanac, seulement 29 % des sites mobiles avaient un texte au contraste suffisant. Sept sur dix se lisent mal sur un téléphone, et presque aucun ne l'a voulu : personne n'a vérifié. Beaucoup d'équipes installent Storybook, écrivent vingt histoires et l'abandonnent au bout de trois mois. Le problème n'est pas l'outil : il a servi de vitrine et non de ce qu'il peut être, le contrat visuel et de comportement entre le design, le développement et la QA. Un contrat dit ce qui existe, comment on l'utilise, dans quels états cela peut se trouver et ce qui n'est pas permis. Il ne remplace ni les décisions de design ni le contrat des API ; c'est la preuve la plus utile du comportement de l'interface.

1. Une hiérarchie, avec des dépendances qui descendent

Nous utilisons l'Atomic Design comme vocabulaire de composition —atomes, molécules, organismes— et nous l'étendons quand cela aide à gouverner le produit :

Fondations → Atomes → Molécules → Organismes → Sections → Pages

• Fondations : couleurs, typographie, espacements, motifs visuels. Ce ne sont pas des composants : ce sont les règles.
• Atomes : bouton, champ, icône, badge. Ils ne connaissent aucune règle métier, même s'ils ont un comportement propre.
• Molécules : un champ avec son étiquette et son erreur ; une carte.
• Organismes : en-tête, pied de page, un formulaire complet.
• Sections : blocs de contenu configurables par propriétés, au lieu d'être copiés page par page.
• Pages : elles orchestrent les données, les routes et le contexte ; la logique de présentation réutilisable vit en dessous.

C'est une convention d'architecture, non une loi universelle. La règle qui la rend utile est la direction : une couche de base n'importe jamais une couche de produit. Cela n'empêche pas qu'un changement de jeton ou de composant partagé touche les pages —il doit les toucher—, mais cela rend l'impact traçable et oblige ceux qui le consomment à vérifier.

Savez-vous aujourd'hui quels écrans changent si la couleur principale de votre marque change demain ?

2. Les fondations, comme un texte qui se lit

Avant le premier bouton, documentez les fondations sous forme de pages narratives dans Storybook lui-même : la palette et le moment où l'on utilise chaque couleur, la typographie et sa hiérarchie, les motifs visuels. Et qu'elles vivent sous forme de jetons (tokens) : la couleur ne s'écrit pas dans le composant, elle se prend dans le jeton. Ainsi, changer de marque, c'est changer un jeton, et la régression visuelle vous dit ce qui a changé d'autre. (Le format standard des jetons est encore un brouillon, et son propre texte demande de ne pas l'implémenter pour l'instant : les jetons se définissent dans votre système et s'exportent quand le standard se stabilisera.)

3. Chaque histoire répond à quatre questions

1. Ce que c'est et quand on l'utilise (et quand on ne l'utilise pas).
2. Ses variantes : tailles, tons, avec ou sans icône.
3. Ses états : en chargement, vide, en erreur, désactivé, en cours d'envoi, et les cas limites —textes longs, données incomplètes, réponses lentes—. C'est là que l'expérience se fracture.
4. Son accessibilité : comment un lecteur d'écran l'annonce, ce qui se passe avec le clavier et le focus, ce qui se passe si l'utilisateur a demandé moins de mouvement.

// Illustratif (Storybook 9, CSF3). Suppose : type Story = StoryObj<typeof meta>
// et que expect est importé depuis le chemin des utilitaires de test de votre version.
export const ConError: Story = {
  args: { etiqueta: "Correo", error: "Escriba un correo válido" },
  play: async ({ canvas }) => {
    const campo = canvas.getByLabelText("Correo");
    await expect(campo).toHaveAttribute("aria-invalid", "true");
    await expect(canvas.getByRole("alert")).toBeVisible();
  },
};

L'histoire fixe un état d'erreur et vérifie sa sémantique : que le champ est marqué comme invalide et que le message est exposé comme alerte. Cela la rapproche d'un contrat. Pour les parcours critiques, en plus, on valide à la main avec le clavier et avec un lecteur d'écran : l'automatique ne couvre pas tout.

4. Trois types de revue, pas un seul

• Tests d'interaction : que les états et le comportement soient ceux attendus, comme dans l'exemple.
• Revue automatique d'accessibilité sur chaque histoire : contraste, rôles, noms accessibles. Attention à ses limites : en moyenne, les tests automatiques trouvent 57 % des problèmes d'accessibilité (Deque, sur plus de 13 000 pages), et la règle de la taille minimale des cibles tactiles de WCAG 2.2 est désactivée d'origine dans l'outil le plus utilisé. Il faut l'activer à la main ; le reste est couvert par la revue au clavier et au lecteur d'écran.
• Régression visuelle : celle qui détecte qu'un changement de jeton a déplacé quelque chose sur vingt écrans que personne n'a ouverts.

Ensemble, ils transforment un catalogue en contrat.

5. Le contexte, depuis la barre d'outils

Si votre produit utilise plusieurs langues ou un thème clair et sombre, exposez-les comme des contrôles globaux de Storybook, reliés par des décorateurs aux mêmes fournisseurs de contexte que l'application réelle. Servez-vous-en pour explorer les combinaisons à risque —le bouton qui ne tient pas en allemand, le texte qui disparaît en mode sombre— et définissez quelles combinaisons sont toujours testées.

6. Il se publie tout seul

Un Storybook que quelqu'un doit penser à publier est déjà périmé. Il se publie automatiquement à l'intégration des changements approuvés, comme une référence que le design, la QA et le client peuvent ouvrir, avec l'accès qu'exige la sensibilité du produit. C'est cette référence qui est revue, pas une capture d'écran dans un chat.

7. Quand quelque chose monte d'un niveau

Les primitives de la marque —bouton, champ, typographie— naissent dans le système dès le premier jour. Pour le reste :

• La répétition est un signal, non un seuil. Un motif se consolide lorsque son intention et ses variantes sont déjà stables ; abstraire trop tôt coûte souvent plus cher qu'un doublon visible. En pratique, cela se produit rarement avant la troisième utilisation.
• Partager entre projets demande de la gouvernance. Quand un second produit a besoin des mêmes composants, le système devient un paquet avec un responsable clair, des versions et un chemin d'adoption ; c'est là que Storybook devient souvent la référence la plus utile, sans remplacer la documentation des décisions.

Ce qui nous manque encore, dit à voix haute

Nous revoyons l'accessibilité de façon automatique sur chaque histoire, mais aujourd'hui la revue signale et ne bloque pas. L'étape que beaucoup d'équipes repoussent —et que nous exigeons comme prochaine— est qu'un défaut d'accessibilité ou un état cassé arrête la publication, comme un test rouge. Un contrat qui ne peut pas arrêter un changement n'est qu'une suggestion.

Prochain dans la série : Les paradigmes du frontend moderne, sans fumée · Ce que doit avoir un frontend professionnel avant d'aller en production.