Storybook

¿Qué es Storybook?

Storybook es un taller para componentes de UI. Renderiza un componente de forma aislada, fuera de tu aplicación, para que puedas desarrollarlo sin tener que navegar hasta la página correspondiente o cumplir con ciertas condiciones específicas. Cada estado que sea relevante se convierte en una story, y la colección de stories se transforma en documentación viva.

Comenzó como una herramienta de desarrollo y evolucionó hacia mucho más: un auditor de accesibilidad, una superficie para pruebas de interacción y un objetivo para regresiones visuales. Para los equipos que construyen sistemas de diseño o librerías de componentes compartidos, suele ser la herramienta de front-end más valiosa después del propio framework.

Stories

Un archivo de stories exporta un objeto meta por defecto y una exportación nombrada por cada estado.

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

export default {
  title: "Components/Button",
  component: Button,
  args: { children: "Save" },
  argTypes: {
    variant: {
      control: "select",
      options: ["primary", "secondary", "ghost"],
    },
  },
};

export const Primary = {
  args: { variant: "primary" },
};

export const Secondary = {
  args: { variant: "secondary" },
};

export const Disabled = {
  args: { disabled: true },
};

El title determina dónde aparece el componente en la barra lateral. El component vincula la story con el componente para que Storybook pueda inferir las props y generar la documentación. Cada exportación nombrada es una story.

Args y controles

Los args son las props que una story pasa al componente. Storybook los convierte en un panel de controls, permitiéndote cambiar los valores en tiempo real sin necesidad de editar el código.

// Card.stories.jsx
export default {
  title: "Components/Card",
  component: Card,
  args: {
    title: "Pro plan",
    description: "Everything you need to ship.",
    elevated: false,
  },
};

Debido a que los args son datos estructurados, también alimentan los autodocs, pueden compartirse entre stories y pueden ser reutilizados por los tests de interacción. Definir el markup inline en una función render funciona, pero se pierden los controles en vivo y la fuente única de verdad, por lo que es preferible usar args.

Decoradores y contexto

Algunos componentes necesitan un provider, un tema o un envoltorio de layout. Los decoradores proporcionan ese contexto alrededor de una story.

// preview.jsx
export default {
  decorators: [
    (Story) => (
      <ThemeProvider theme="dark">
        <div style={{ padding: "1rem" }}>
          <Story />
        </div>
      </ThemeProvider>
    ),
  ],
};

Un decorador puede ser global, por archivo o por story, lo que facilita la revisión de un componente en diferentes temas o locales sin necesidad de modificar el componente en sí.

Autodocs

Storybook puede generar una página de documentación a partir de tus stories y sus args. Con autodocs activado, cada componente obtiene una página que enumera sus props, controles y cada story, la cual se mantiene sincronizada automáticamente ya que se genera desde la misma fuente. Puedes enriquecerla con una descripción, notas de uso y ejemplos de código utilizando la API parameters.docs.

Pruebas de interacción

Una story puede definir una play function que se ejecuta después de que el componente se renderiza. Utiliza las mismas consultas y eventos que Testing Library, por lo que el modelo mental se transfiere directamente.

// Search.stories.jsx
import { expect, userEvent, within } from "@storybook/test";

export const TypesAndSubmits = {
  play: async ({ canvasElement }) => {
    const canvas = within(canvasElement);

    await userEvent.type(canvas.getByLabelText("Search"), "vitest");
    await userEvent.click(canvas.getByRole("button", { name: "Go" }));

    await expect(canvas.getByText("3 results")).toBeVisible();
  },
};

Debido a que la prueba se ejecuta dentro de Storybook, puedes observarla paso a paso, lo que hace que la depuración sea mucho más sencilla que analizar una ejecución fallida en CI. Estas mismas stories pueden ejecutarse en modo headless en CI utilizando el test runner de Storybook.

Accesibilidad y pruebas visuales

El addon de accesibilidad ejecuta axe en cada story y reporta las infracciones en el panel del addon, agrupadas por impacto. Detecta etiquetas faltantes, contraste deficiente, ARIA inválido y problemas similares mientras desarrollas, lo cual es mucho más económico que corregirlos más tarde.

Las herramientas de regresión visual capturan una captura de pantalla por story y la comparan con una línea base. Debido a que cada estado ya es una story, obtienes una amplia cobertura visual con muy poco esfuerzo adicional. Una captura de pantalla modificada señala un cambio visual no deseado para su revisión.

Dónde encaja Storybook

Storybook se sitúa entre las pruebas unitarias y las pruebas end-to-end. No es un reemplazo de ninguna de las dos. Utilízalo para desarrollar y documentar componentes de forma aislada, para probar estados interactivos con funciones play y para auditar la accesibilidad y los aspectos visuales. Mantén las pruebas de lógica rápidas en Vitest, el comportamiento de los componentes en Testing Library y los flujos completos en Playwright.

Mejores prácticas

• Escribe una story por cada estado significativo, incluyendo carga (loading), vacío y error.
• Prioriza el uso de args sobre el marcado inline para que los controles y la documentación se mantengan actualizados.
• Ubica las stories junto a sus componentes y nómbralas según su propósito.
• Utiliza decorators para providers, temas y layouts en lugar de duplicar wrappers.
• Añade play functions para las interacciones y ejecútalas en el CI.
• Activa el addon de accesibilidad y corrige las violaciones a medida que aparezcan.
• Publica el Storybook compilado como documentación viva.

Errores comunes

• Escribir únicamente una historia “Default” y omitir estados reales.
• Hardcodear props en render, perdiendo así los controles y la documentación.
• Tratar Storybook como un reemplazo de las pruebas unitarias o end-to-end.
• Permitir que las historias se desincronicen de las props reales del componente.
• Ignorar las advertencias de accesibilidad hasta que se acumulan.
• Duplicar la configuración del provider en cada historia en lugar de utilizar un decorator.

Próximos pasos

Storybook convierte los componentes en un catálogo documentado y testeable. Combínalo con Testing Library para las consultas dentro de las play functions, Vitest para las pruebas de lógica y Playwright para los flujos end-to-end. Después, elige el componente que más reutilices y crea stories para cada uno de sus estados posibles.