Storybook per componenti frontend

Nel moderno sviluppo front-end, la modularità è la chiave. Costruire componenti riutilizzabili, documentati e testabili è diventato essenziale per garantire scalabilità, manutenibilità e collaborazione efficace tra team.

In questo contesto, Storybook è uno strumento imprescindibile: una sandbox interattiva per costruire e documentare UI component in isolamento, con supporto nativo a test visivi, accessibility check e integrazione con framework come React, Vue, Angular e Svelte.

Cos'è Storybook

Storybook è un ambiente di sviluppo open-source che consente di visualizzare, testare e documentare i componenti UI in isolamento dal contesto dell'applicazione.

Questo consente ai designer, sviluppatori e stakeholder di interagire con ogni singolo componente come se fosse un micro-prodotto autonomo.

Perché usarlo?

• Isolamento: ogni componente può essere sviluppato e testato separatamente, riducendo i side-effect.
• Documentazione interattiva: le “storie” fungono da documentazione vivente, utile anche per onboarding e QA.
• Testing visivo e comportamentale: supporta snapshot, ovvero l'immagine dello stato del componente in un dato momento, ma anche test di regressione visiva, accessibility check e interaction test.
• Design System: è la base perfetta per costruire e mantenere un sistema di design aziendale scalabile.

Setup base con React

Per iniziare, supponiamo di avere un progetto React già configurato con Vite o Create React App. Ecco come aggiungere Storybook:

npx storybook@latest init

Questo comando configura automaticamente la struttura delle storie (*.stories.jsx|ts|tsx) e aggiunge gli script necessari nel package.json.

Una volta avviato Storybook (npm run storybook), vedrai un’interfaccia grafica nel browser con una sidebar navigabile e i componenti interattivi.

Scrivere una storia: il pattern base

Supponiamo di avere un semplice bottone:

// Button.jsx
export const Button = ({ label, onClick }) => (
  {label}
);

La relativa storia sarà:

// Button.stories.jsx
import { Button } from './Button';

export default {
  title: 'UI/Button',
  component: Button,
};

export const Primary = () =>  alert('Clicked')} />;

Ogni export rappresenta una “storia”, ovvero una variante visualizzabile del componente. Puoi usarle per descrivere tutti gli stati possibili di quel componente: Loading, Disabled, WithIcon, Danger, ecc.

Documentazione automatica

Storybook genera automaticamente una documentazione leggibile per ogni componente usando i metadata forniti (argTypes, JSDoc, TypeScript).

Con l’addon Docs puoi ottenere un’interfaccia simile a quella di un Design System, con esempi interattivi, prop tables e tipizzazione.

npm install @storybook/addon-docs

E nel tuo main.js:

addons: ['@storybook/addon-docs']

Test dei componenti con Storybook

Test visivi con Chromatic

Chromatic (realizzato dagli stessi autori di Storybook) permette di eseguire snapshot visivi e controlli di regressione visuale direttamente su CI.

Interaction Test (user events)

Con @storybook/testing-library puoi simulare click, hover, input e altri eventi:

export const Clickable = {
  args: { label: 'Click me' },
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);
    await userEvent.click(canvas.getByText('Click me'));
    expect(someMockFunction).toHaveBeenCalled();
  },
};

Accessibility Check

Con l’addon @storybook/addon-a11y puoi verificare problemi di accessibilità in tempo reale:

npm install @storybook/addon-a11y

Best Practice per usare Storybook in modo efficace

Storybook è potente, ma per ottenere il massimo è fondamentale seguire alcune best practice consolidate nella community. Ecco le più importanti, con esempi consultabili online.

1. Organizza i componenti in modo semantico

Usa una gerarchia chiara nei titoli delle storie (title) per riflettere la struttura del tuo design system o dell’interfaccia.

 
export default {
  title: 'Form/Inputs/TextField',
  component: TextField,
};

Esempio reale: Storybook di Adobe Spectrum

Ben organizzato, con categorie chiare e documentazione approfondita.

2. Sfrutta gli Args per creare storie dinamiche

Usa args per rendere i componenti interattivi e configurabili direttamente dal pannello Storybook, riducendo il codice ripetitivo.

export const Default = {
  args: {
    label: 'Invia',
    disabled: false,
  },
};

Esempio reale: Chakra UI Storybook

Ogni componente è dimostrato con args interattivi e use case chiari.

3. Documenta con JSDoc o TypeScript

La documentazione automatica diventa più utile quando le props sono descritte accuratamente. Usa commenti JSDoc o tipizzazione TypeScript.

/**
 * Pulsante principale dell’interfaccia.
 * @param label Etichetta visualizzata.
 * @param onClick Callback al click.
 */
export const Button = ({ label, onClick }: ButtonProps) => ...

Esempio reale: Shopify Polaris Storybook

Una documentazione impeccabile e tipizzata.

4. Usa addon essenziali

• @storybook/addon-a11y → per l’accessibilità
• @storybook/addon-interactions → per simulare eventi utente
• @storybook/addon-controls → per manipolare props in UI
• @storybook/addon-docs → per generare documentazione professionale

Esempio reale: Carbon Design System by IBM

Con test di accessibilità e stories per ogni stato del componente.

5. Integra con il tuo CI/CD e con il design system

Storybook non è solo uno strumento di sviluppo: può diventare parte del tuo pipeline di delivery, usando tool come Chromatic o GitHub Actions per pubblicare la documentazione aggiornata ad ogni PR.

Guida utile: Deploy Storybook with GitHub Actions

Integrare Storybook nel workflow aziendale

In un contesto professionale, Storybook può diventare un asset strategico:

• Per il team di sviluppo: semplifica la comunicazione e il refactoring.
• Per il team di design: garantisce allineamento visivo e comportamentale.
• Per stakeholder e QA: offre una vetrina interattiva dell’interfaccia, accessibile anche da chi non ha il codice.

Puoi anche deployare automaticamente la tua documentazione con GitHub Pages, Vercel o Netlify.

Vuoi portare queste best practice nella tua azienda?

Se stai costruendo un progetto moderno in React, Vue o qualsiasi altro framework basato su componenti, Storybook è il tuo alleato naturale. Una base solida per un design system ben fatto, una documentazione viva e una UI più affidabile.

Con l’aiuto del team Unitiva, puoi:

• standardizzare componenti e naming convention
• documentare in modo efficace per dev e stakeholder
• automatizzare il testing visivo e l’accessibilità
• creare un Design System scalabile e manutenibile

Scrivici per una consulenza su misura!