Storybook est le catalogue vivant de vos composants UI. Au lieu d’avoir un fichier de documentation séparé qui se déphase du code, Storybook lit directement vos composants, expose leurs props, et génère un playground interactif. Designers et développeurs naviguent dans la même librairie.
Composants documentés
100%
Chaque composant avec tous ses variants et états documentés
Régression visuelle
-90%
de bugs UI détectés avant mise en production (tests Chromatic)
i
Storybook en chiffres
Utilisé par plus de 2M de développeurs dans le monde. Airbnb, Uber, Storyblocks et des milliers d’équipes l’adoptent comme standard de documentation de composants. Le temps de développement de nouvelles features diminue de 30 à 50 % quand les composants sont documentés dans Storybook.
Le Contexte
Pourquoi Storybook ?
i
Storybooks en production
Pour vous donner un aperçu concret, voici 4 Storybooks de design systems réels :
- Mermaid Diagram : Composants de diagrammes interactifs avec preview live
- Adobe Spectrum : Web components officiels Adobe (Alert Banner)
- Strapi Design System : Design system open source avec focus accessibilité
- Sketchbook UI : Bibliothèque de composants avec variants personnalisables
📖
Quand l'utiliser
Dès 15+ composants ou 3+ développeurs : Storybook devient indispensable. En dessous, une documentation MDX légère suffit : le surcoût de maintenance dépasserait les bénéfices.
🧠
Analogie
Storybook, c’est le showroom de votre concessionnaire : chaque composant y est exposé sous toutes ses finitions, avec sa fiche technique, un essai interactif et des options configurables. Sans showroom, vos composants restent dans l’atelier : invisibles pour les designers et les nouveaux développeurs.
SANS STORYBOOK
Documentation dispersée
- Composants dans le code, personne ne les voit
- Props devinées en lisant le source
- Pas de preview isolé : il faut lancer l’app complète
- Les variants sont des surprises en production
AVEC STORYBOOK
Library vivante
- Chaque composant documenté avec ses états
- Props exposées avec contrôles interactifs
- Preview instantané sans contexte applicatif
- Tests visuels qui catchent les régressions
Installation
# Installation automatique
npx storybook@latest init
# Installation manuelle (React + Vite)
npx storybook@latest init --type react
# Lancer Storybook
npm run storybook
# Build statique (pour déploiement)
npm run build-storybook 1
Initialisation
Lancez npx storybook@latest init : Storybook détecte votre framework et configure automatiquement.
2
Première story
Créez une story pour votre composant le plus simple (Button, Badge) pour valider le setup.
3
Addons essentiels
Installez a11y, viewport et backgrounds pour couvrir les cas d'usage de base.
4
Autodocs
Ajoutez tags: ['autodocs'] pour générer la documentation automatiquement depuis votre code.
5
Déploiement
Build statique (npm run build-storybook) et déploiement sur Chromatic, Netlify ou GitHub Pages.
Structure d’une story
Chaque story expose un composant avec ses différents états.
import { Button } from './Button';
export default {
title: 'Components/Button',
component: Button,
tags: ['autodocs'],
argTypes: {
variant: {
control: 'select',
options: ['primary', 'secondary',
'ghost'],
},
size: {
control: 'radio',
options: ['sm', 'md', 'lg'],
},
disabled: { control: 'boolean' },
},
};
export const Primary = {
args: {
variant: 'primary',
children: 'Primary Button',
},
};
export const Secondary = {
args: {
variant: 'secondary',
children: 'Secondary Button',
},
};
export const Disabled = {
args: {
disabled: true,
children: 'Disabled',
},
};// Les contrôles génèrent une UI interactive
export const Playground = {
args: {
variant: 'primary',
size: 'md',
children: 'Cliquez ici',
},
parameters: {
controls: { expanded: true },
},
};
// Story avec état désactivé
export const Loading = {
args: {
children: 'Chargement...',
disabled: true,
variant: 'primary',
},
};Args et contrôles interactifs
Les args sont les props passées au composant. Les argTypes définissent comment les manipuler dans l’interface Storybook.
export default {
title: 'Components/Card',
component: Card,
argTypes: {
variant: {
control: 'select',
options: ['default', 'elevated', 'outlined'],
},
padding: {
control: { type: 'range', min: 0, max: 32, step: 4 },
},
border: { control: 'color' },
elevation: {
control: { type: 'number', min: 0, max: 5 },
},
},
};Documentation automatique
La documentation auto-générée (tags: ['autodocs']) crée une page docs pour chaque composant.
Analyse Technique : Initié
Button.stories.tsx
Button
Variants· Test·Documentation auto
export default {
title: 'Components/Button',
component: Button,
tags: ['autodocs'],
parameters: {
docs: {
description: {
component: 'Un bouton réutilisable avec plusieurs variantes.
' +
'Utilisé dans : Header, Formulaires, Modales.
' +
'Accessibilité : supporte le focus clavier, aria-label intégré.',
},
},
},
};Avec autodocs, Storybook génère automatiquement :
- La liste des props avec leurs types (lus depuis TypeScript/PropTypes)
- Les stories comme exemples interactifs
- La description du composant
- Les sous-composants et leur API
Tests d’interaction
Les tests d’interaction simulent des clics et vérifient le comportement.
import { userEvent, expect } from '@storybook/test';
export const Clickable = {
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
const button = canvas.getByRole('button');
// Simuler un clic
await userEvent.click(button);
// Vérifier l'état après clic
const badge = canvas.getByTestId('count');
await expect(badge).toHaveTextContent('1');
},
};
export const Form = {
play: async ({ canvasElement }) => {
const input = within(canvasElement)
.getByPlaceholderText('Email');
await userEvent.type(input, 'test@test.com');
await userEvent.click(
within(canvasElement).getByText('Submit')
);
},
};Addons essentiels
a11y
Tests d’accessibilité automatiques (axe-core). Détecte les problèmes de contraste, labels ARIA manquants, rôles invalides.
viewport
Test responsive avec des presets mobile, tablette, desktop. Vérifiez que chaque composant s’adapte à tous les écrans.
backgrounds
Changez l’arrière-plan pour tester le contraste des composants sur fond clair, sombre, coloré.
controls
Manipulez les props en live avec des contrôles générés automatiquement : select, radio, range, color, boolean.
actions
Logger les clics, soumissions et autres événements sans configuration. Idéal pour debugger.
measure
Outil de mesure visuelle directement dans Storybook. Vérifiez les espacements et alignements.
?
Design System Complet
Comment organiser votre écosystème de composants UI avec des Design Tokens, Atomic Design et une documentation intégrée ?
Découvrez l'article complet
en un clic
Des zones d'ombre ?
Storybook est-il utile pour un petit projet ?
Pour un projet solo ou une petite équipe (< 3 personnes), Storybook peut être overkill. Une documentation MDX légère ou un fichier Storybook minimal suffit. Ajoutez Storybook complet quand l'équipe grandit ou que vous avez besoin de tests visuels automatisés.
Comment déployer Storybook ?
Storybook produit un build statique (npm run build-storybook). Vous pouvez le déployer sur Netlify, Vercel, GitHub Pages, ou Chromatic (service dédié avec tests visuels inclus). Chromatic est la solution la plus intégrée.
Storybook fonctionne-t-il avec TypeScript ?
Oui, nativement. Storybook utilise les types TypeScript pour générer automatiquement la documentation des props. Plus besoin de comments JSDoc : les interfaces TS sont la source de vérité.
Quelle est la différence entre Component Story Format (CSF) et MDX ?
CSF (Component Story Format) est le format standard : des fichiers JS/TS qui exportent des stories. MDX Stories sont des fichiers
.mdx qui mélangent documentation narrative et stories. CSF est recommandé pour la maintenabilité ; MDX pour des pages de documentation riches.Checklist Storybook
Intégration Storybook
0/10Vos progrès sont sauvegardés localement sur votre appareil. Aucune donnée n'est collectée. La durée de conservation dépend de la durée de rétention des données de votre navigateur.
"
Storybook, c’est bien plus qu’un outil : c’est une documentation vivante qui sync toute l’équipe autour d’un langage commun.
Gaëtan Solis
Fondateur, Bao-Link
Orfèvre Digital
Prêt à lancer votre projet ?
Je donne vie à vos idées en créant des sites web et applications intuitifs, esthétiques et fonctionnels.
Disponible
Articles Connexes
2
Prérequis
Atomic Design : Architecture de Composants UI
L'Atomic Design est une méthodologie de conception de systèmes de composants UI. Organisez votre bibliothèque en Atomes, Molécules, Organismes, Templates et Pages.
Cluster
Connexe
Composants UI : Le Hub de votre Design System
Construisez et organisez votre bibliothèque de composants UI : design tokens, atomic design, Figma ↔ code, Storybook, et workflow complet du design au déploiement.
Inspiration
Découvrez d'autres projets
Développement 21 juillet 2026
Bao-Link Documentation : De WordPress à un Écosystème Centré Utilisateur
Le projet Bao-Link raconte l'évolution du site et de ses outils: la création d'un premier site WordPress vitrine, puis le passage à Astro avec un site 100% sur mesure, sans template, centré sur le SEO et l'expérience utilisateur ainsi que les projets liés : diag-application et personas.
Astro WordPress # Migration
Voir le projet 
Développement 16 juillet 2026
ACM : Refonte E-commerce avec Astro, Express & WordPress
Étude de cas complète : migration d'un site e-commerce WordPress/WooCommerce vers une architecture Astro SSR + proxy Express, avec déploiement et optimisation SEO.
Astro Express WordPress
Voir le projet 
Développement 16 juillet 2026
Soair : La Transition Numérique Complète
Étude de cas complète : création d'un site WordPress professionnel puis migration vers Hugo pour des performances optimales et un SEO décuplé.
# Soair WordPress Hugo
Voir le projet 