Todos los artículos

Front-end11 min de lectura

Storybook: cómo empezar y hasta dónde vale la pena ir

Storybook 10 desde cero: instalar, escribir stories, probar interacción y accesibilidad en Vitest y decidir, nivel por nivel, hasta dónde ir en tu proyecto.

También en Português, English, Français

Storybook es una de esas herramientas de las que todos oyeron hablar y que poca gente usa bien. O el proyecto nunca la instala, o la instala, escribe tres stories del botón y la abandona, o intenta cubrir todo y termina dedicando más tiempo a mantener stories que a construir pantallas.

Este post toma el camino del medio: muestra cómo empezar en pocos minutos y organiza lo que viene después en niveles, para que decidas hasta dónde tiene sentido ir en tu proyecto.

Un aviso honesto: todo lo de aquí se hizo en un proyecto real con Storybook 10.6, React 19 y Vite. Las stories del post corren como pruebas y pasan, y la verificación de accesibilidad se comprobó rompiendo a propósito una story con un botón sin nombre.

TL;DR#

  • Storybook es una vitrina de tus componentes, fuera de la app, en todos sus estados: vacío, cargando, con error, con un texto enorme.
  • Empezar es un comando: npm create storybook@latest. Detecta el framework y ya configura pruebas y accesibilidad.
  • Una story es solo un componente con datos. El formato actual (CSF) es un objeto con args.
  • Las stories se vuelven pruebas. Con el addon de Vitest, cada story se renderiza en un navegador real, y play simula el clic y revisa el resultado.
  • Hasta dónde ir: para casi todo proyecto alcanzan las stories de los componentes visuales, las pruebas de interacción y la accesibilidad. Las pruebas visuales y una documentación cuidada tienen sentido en un design system y en componentes compartidos.
  • No escribas stories de páginas que dependen de una API. Una buena story es de un componente que recibe todo por props.

Para qué sirve#

Sin Storybook, para ver un componente en un estado específico tienes que navegar la app hasta la pantalla correcta, con los datos correctos. Ver la tarjeta de pedido con un nombre de cliente enorme significa crear un cliente con un nombre enorme. Ver la lista vacía significa borrar los pedidos.

Con Storybook, cada estado se vuelve una story: una entrada fija que se abre con un clic. Eso ayuda en cuatro cosas:

  • Desarrollar el componente aislado, sin depender de backend, login ni navegación.
  • Detectar casos límite que casi nunca aparecen en la app: texto largo, lista vacía, valor cero.
  • Conversar con diseño y producto, mostrando todos los estados en un solo lugar.
  • Probar, porque cada story puede volverse una prueba automática.

Nivel 0: instalar#

En un proyecto existente, en la raíz:

npm create storybook@latest

El instalador revisa las dependencias del proyecto y elige la configuración. En un proyecto con React y Vite, la versión 10.6 instaló:

  • Storybook con el framework @storybook/react-vite;
  • @storybook/addon-vitest, que convierte las stories en pruebas;
  • @storybook/addon-a11y, que corre la verificación de accesibilidad;
  • @storybook/addon-docs, que genera la página de documentación de cada componente;
  • @storybook/addon-mcp, la integración con asistentes de IA (más al final);
  • Playwright con Chromium, que las pruebas usan para renderizar las stories.

Y creó dos scripts:

npm run storybook        # opens Storybook at localhost:6006
npm run build-storybook  # generates a static site in storybook-static/

La configuración queda en .storybook/:

.storybook/main.ts
import type { StorybookConfig } from '@storybook/react-vite';
 
const config: StorybookConfig = {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    '@chromatic-com/storybook',
    '@storybook/addon-vitest',
    '@storybook/addon-a11y',
    '@storybook/addon-docs',
    '@storybook/addon-mcp',
  ],
  framework: '@storybook/react-vite',
};
 
export default config;

El instalador también crea una carpeta src/stories con ejemplos (botón, encabezado, página). Vale mirarla una vez y borrarla.

También funciona con Angular: la documentación indica Angular 18 o más nuevo, y los conceptos de abajo son los mismos. Los ejemplos de este post están en React.

Nivel 1: stories de los componentes visuales#

Los ejemplos usan los componentes de una lista de pedidos, los mismos del post sobre smart y dumb components: OrderCard, OrderList y StatusFilter. Reciben todo por props, y justamente por eso son fáciles de llevar a Storybook.

Una story vive al lado del componente, en un archivo .stories.tsx:

OrderCard.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { expect, fn } from 'storybook/test';
import { OrderCard } from './OrderCard';
 
const meta = {
  title: 'Orders/OrderCard',
  component: OrderCard,
  tags: ['autodocs'],
  args: {
    order: { id: '42', customer: 'Ana Souza', total: 189.9, status: 'paid' },
    onSelect: fn(),
  },
} satisfies Meta<typeof OrderCard>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Default: Story = {};
 
export const Selected: Story = {
  args: { selected: true },
};
 
export const LongCustomerName: Story = {
  args: {
    order: { id: '43', customer: 'Maria Aparecida dos Santos Albuquerque Ferreira', total: 12999.5, status: 'pending' },
  },
};
 
export const ClickingDetailsSendsTheId: Story = {
  play: async ({ args, canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'Details' }));
    await expect(args.onSelect).toHaveBeenCalledWith('42');
  },
};

Leyendo de arriba hacia abajo:

  • meta describe el componente: el nombre en la barra lateral (title), qué componente es y los args predeterminados, que son las props.
  • fn() crea una función espía para onSelect. En Storybook, cada llamada aparece en el panel de acciones.
  • Cada export es una story. Default usa los args predeterminados, Selected cambia solo lo necesario, LongCustomerName prueba el caso límite del nombre enorme.
  • tags: ['autodocs'] genera una página de documentación con todas las stories y una tabla de las props, sacada de los tipos de TypeScript.

Lo que merece una story es el estado, no una variación al azar. Para una tarjeta de pedido: el predeterminado, el seleccionado, el nombre largo, el valor alto. Para una lista: vacía y con elementos.

OrderList.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { expect, fn } from 'storybook/test';
import { OrderList } from './OrderList';
 
const meta = {
  title: 'Orders/OrderList',
  component: OrderList,
  args: { selectedId: null, onSelect: fn(), orders: [] },
} satisfies Meta<typeof OrderList>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Empty: Story = {
  play: async ({ canvas }) => {
    await expect(canvas.getByText('No orders here yet.')).toBeVisible();
  },
};
 
export const WithOrders: Story = {
  args: {
    selectedId: '2',
    orders: [
      { id: '1', customer: 'Ana', total: 89, status: 'paid' },
      { id: '2', customer: 'Bruno', total: 240, status: 'pending' },
      { id: '3', customer: 'Carla', total: 1320, status: 'shipped' },
    ],
  },
};

Nivel 2: controls y documentación#

Este nivel viene casi gratis. Como las props están en args, Storybook arma solo el panel Controls: puedes cambiar el nombre del cliente, el estado o el valor directamente en pantalla y ver reaccionar al componente. Es excelente para mostrar el componente a quien no programa.

Y autodocs junta todo en una página por componente. Para un componente compartido, esa página suele reemplazar a un README que nadie actualiza.

Nivel 3: pruebas de interacción#

Aquí Storybook deja de ser vitrina y se vuelve una herramienta de pruebas. La función play corre después de que la story aparece en pantalla: hace clic, escribe y revisa.

Vuelve a la última story de OrderCard: ClickingDetailsSendsTheId hace clic en el botón "Details" y revisa que onSelect se llamó con el id '42'. Los componentes con estado propio también funcionan:

StatusFilter.stories.tsx
import type { Meta, StoryObj } from '@storybook/react-vite';
import { useState } from 'react';
import { expect } from 'storybook/test';
import { StatusFilter, type StatusFilterValue } from './StatusFilter';
 
const meta = {
  title: 'Orders/StatusFilter',
  component: StatusFilter,
  args: { value: 'all', onChange: () => {} },
  // Keeps the value in local state so the story behaves like the real screen.
  render: function Render(args) {
    const [value, setValue] = useState<StatusFilterValue>(args.value);
    return <StatusFilter value={value} onChange={setValue} />;
  },
} satisfies Meta<typeof StatusFilter>;
 
export default meta;
type Story = StoryObj<typeof meta>;
 
export const Interactive: Story = {
  play: async ({ canvas, userEvent }) => {
    await userEvent.click(canvas.getByRole('button', { name: 'paid' }));
    await expect(canvas.getByRole('button', { name: 'paid' })).toHaveClass('active');
  },
};

El render guarda el valor en un useState, para que la story se comporte como la pantalla real, y play hace clic en "paid" y revisa que el botón quedó activo.

Lo más importante: con el addon de Vitest, toda story es una prueba, incluso las que no tienen play. La story que solo renderiza ya prueba que el componente no se rompe con esos datos. Para correr todo:

npx vitest run --project=storybook

En el proyecto del post: 6 archivos, 15 pruebas, todas pasando, en un Chromium real, sin abrir ventana. Y puedes correr el mismo comando en la CI:

.github/workflows/storybook.yml
name: Storybook tests
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm ci
      - run: npx playwright install --with-deps chromium
      - run: npx vitest run --project=storybook

Nivel 4: accesibilidad#

El addon de accesibilidad corre axe, la misma biblioteca de varias extensiones de navegador, en cada story. El instalador lo configura así:

.storybook/preview.tsx
import type { Preview } from '@storybook/react-vite';
 
const preview: Preview = {
  parameters: {
    a11y: {
      // 'todo': shows violations in the UI only. 'error': fails the test.
      test: 'todo',
    },
  },
};
 
export default preview;

Con 'todo', los problemas aparecen en el panel pero no rompen nada. Con 'error', se vuelven fallas de prueba. Para comprobarlo, creé una story con un botón que solo tiene un ícono y ningún texto. Con 'error', la prueba falló con la regla button-name de axe: los botones necesitan un texto que un lector de pantalla pueda leer.

Un camino que funciona bien: empieza con 'todo', corrige lo que aparezca y pasa a 'error' cuando esté limpio. A partir de ahí, un componente nuevo con problemas de accesibilidad no entra.

Un límite importante: la verificación automática detecta una parte de los problemas, como falta de nombre, contraste y atributos incorrectos. El orden de lectura, el foco y si la experiencia tiene sentido con un lector de pantalla siguen necesitando pruebas manuales.

Nivel 5: pruebas visuales#

Las pruebas de interacción revisan el comportamiento. Las pruebas visuales revisan la apariencia: toman una captura de cada story y la comparan con la anterior, avisando cuando cambió un píxel. Es lo que detecta el cambio de CSS que rompió un componente en otra pantalla.

El addon que agregó el instalador (@chromatic-com/storybook) conecta Storybook con Chromatic, un servicio pago del mismo equipo de Storybook. En noviembre de 2026, el plan gratuito daba 5.000 snapshots por mes, solo en Chrome.

Vale la pena cuando mucha gente toca los mismos componentes, como en un design system. En una app pequeña, suele costar más atención (revisar diferencias que eran esperadas) de la que ahorra.

Nivel 6: IA#

addon-mcp conecta Storybook con asistentes de IA. Según la documentación, el agente pasa a conocer tus componentes y su documentación, genera stories y corre las pruebas de interacción y accesibilidad para revisar su propio trabajo. La propia documentación advierte que estas funciones están en preview y pueden cambiar.

El valor real aparece cuando el Storybook ya está bien cuidado: el agente reutiliza los componentes que existen en lugar de inventar otros. En un Storybook con tres stories abandonadas, no tiene mucho de qué aprender.

Hasta dónde ir#

Mi recomendación, por tipo de proyecto:

Hasta el nivel 4 vale para casi todo proyecto. De ahí en adelante, depende de cuánta gente usa los mismos componentes
  • App pequeña, una o dos personas: niveles 0 a 3, solo en los componentes visuales que reutilizas. La ganancia es desarrollar aislado y tener pruebas de interacción gratis.
  • App de equipo: niveles 0 a 4, con las pruebas corriendo en la CI y la accesibilidad en 'error'.
  • Design system o biblioteca compartida: todos los niveles. Aquí Storybook es el producto: documentación, catálogo y garantía de que nada cambió sin querer.

Y lo que yo no haría en ningún caso:

  • Stories de páginas enteras que buscan datos. Exigen simular la API, la autenticación y las rutas, y se rompen con cada cambio del backend. Si la pantalla tiene una parte visual importante, sepárala en un componente que reciba props y escribe su story.
  • Una story para cada combinación de props. Seis tamaños por cuatro colores por dos estados no ayudan a nadie. Elige los estados que importan y deja el resto al panel de controls.
  • Perseguir el 100% de cobertura. La story de un componente que nadie reutiliza y nadie toca es mantenimiento sin retorno.
  • Stories que nadie corre. Si las stories no están en la CI, se rompen en silencio y Storybook se vuelve un museo.

Errores comunes#

  • Un componente que busca datos dentro de sí mismo. No entra en Storybook sin simular la API. La solución casi siempre es separar la parte visual, que recibe todo por props.
  • Args grandes copiados en cada story. Pon los datos predeterminados en meta.args y cambia solo lo necesario en cada story.
  • Acciones sin fn(). Sin la función espía, play no puede revisar qué se llamó, y el panel de acciones queda vacío.
  • Dejar los ejemplos del instalador. El botón y la página de ejemplo ensucian la barra lateral y las pruebas.
  • Accesibilidad siempre en 'todo'. Un aviso que nunca se vuelve error termina ignorado.

Checklist#

  • Storybook instalado con npm create storybook@latest, ejemplos borrados.
  • Stories al lado de los componentes visuales, con los estados que importan (predeterminado, vacío, largo, error).
  • Datos predeterminados en meta.args, funciones de evento con fn().
  • autodocs en los componentes compartidos.
  • play en los comportamientos importantes (clic, escritura, selección).
  • npx vitest run --project=storybook corriendo en la CI.
  • Accesibilidad en 'error' cuando el proyecto esté limpio.
  • Pruebas visuales solo si mucha gente toca los mismos componentes.
  • Ninguna story de una página que dependa de una API.

Referencias#

  • Front-end
  • storybook
  • react
  • pruebas
  • design-system
  • accesibilidad

Escrito por

Ingeniera de software y diseñadora. Escribo sobre lo que encuentro construyendo apps, APIs y productos.

Comentarios

Para comentar, entra con tu cuenta de GitHub.