Cómo estructurar un Storybook que sirva de contrato

Storybook no es una galería

En 2024, de casi 17 millones de sitios analizados por el Web Almanac, solo el 29 % de los sitios móviles tenía texto con contraste suficiente. Siete de cada diez no se leen bien en un celular, y casi ninguno lo hizo a propósito: nadie revisó. Muchos equipos instalan Storybook, escriben veinte historias y lo abandonan a los tres meses. El problema no es la herramienta: se usó como vitrina y no como lo que puede ser, el contrato visual y de comportamiento entre diseño, desarrollo y QA. Un contrato dice qué existe, cómo se usa, en qué estados puede estar y qué no se vale. No sustituye las decisiones de diseño ni el contrato de las API; es la evidencia más útil de cómo se comporta la interfaz.

1. Una jerarquía, con dependencias que fluyen hacia abajo

Usamos Atomic Design como vocabulario de composición —átomos, moléculas, organismos— y lo extendemos cuando ayuda a gobernar el producto:

Fundamentos → Átomos → Moléculas → Organismos → Secciones → Páginas

• Fundamentos: colores, tipografía, espaciado, patrones visuales. No son componentes: son las reglas.
• Átomos: botón, campo, ícono, insignia. No conocen reglas del negocio, aunque tengan comportamiento propio.
• Moléculas: un campo con su etiqueta y su error; una tarjeta.
• Organismos: encabezado, pie, un formulario completo.
• Secciones: bloques de contenido configurables por propiedades, en lugar de copiarse por página.
• Páginas: orquestan datos, rutas y contexto; la lógica de presentación reutilizable vive abajo.

Es una convención de arquitectura, no una ley universal. La regla que la hace útil es la dirección: una capa base nunca importa una capa de producto. Eso no evita que un cambio de token o de componente compartido afecte a las páginas —debe afectarlas—, pero hace el impacto trazable y obliga a verificar a quienes lo consumen.

¿Sabe hoy qué pantallas cambian si mañana cambia el color principal de su marca?

2. Los fundamentos, como texto que se lee

Antes del primer botón, documente los fundamentos como páginas narrativas dentro del propio Storybook: la paleta y cuándo se usa cada color, la tipografía y su jerarquía, los patrones visuales. Y que vivan como tokens: el color no se escribe en el componente, se toma del token. Así, cambiar la marca es cambiar un token, y la regresión visual le dice qué más cambió. (El formato estándar de tokens todavía es un borrador, y su propio texto pide no implementarlo aún: los tokens se definen en su sistema y se exportan cuando el estándar se estabilice.)

3. Cada historia responde cuatro preguntas

1. Qué es y cuándo se usa (y cuándo no).
2. Sus variantes: tamaños, tonos, con ícono o sin él.
3. Sus estados: cargando, vacío, con error, deshabilitado, enviando, y los casos límite —textos largos, datos incompletos, respuestas lentas—. Ahí es donde la experiencia se fractura.
4. Su accesibilidad: cómo lo anuncia un lector de pantalla, qué pasa con el teclado y el foco, qué pasa si el usuario pidió menos movimiento.

// Ilustrativo (Storybook 9, CSF3). Asume: type Story = StoryObj<typeof meta>
// y que expect se importa de la ruta de utilidades de prueba de su versión.
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();
  },
};

La historia fija un estado de error y comprueba su semántica: que el campo se marca como inválido y que el mensaje se expone como alerta. Eso la acerca a un contrato. Para los flujos críticos, además, se valida a mano con teclado y con lector de pantalla: lo automático no lo cubre todo.

4. Tres tipos de revisión, no uno

• Pruebas de interacción: que los estados y el comportamiento sean los esperados, como en el ejemplo.
• Revisión automática de accesibilidad en cada historia: contraste, roles, nombres accesibles. Ojo con sus límites: en promedio, las pruebas automáticas encuentran el 57 % de los problemas de accesibilidad (Deque, sobre más de 13,000 páginas), y la regla del tamaño mínimo de los botones táctiles de WCAG 2.2 viene apagada de fábrica en la herramienta más usada. Hay que encenderla a mano; el resto lo cubre la revisión con teclado y lector de pantalla.
• Regresión visual: la que detecta que un cambio de token movió algo en veinte pantallas que nadie abrió.

Juntas son lo que convierte un catálogo en contrato.

5. El contexto, desde la barra de herramientas

Si su producto usa varios idiomas o tema claro y oscuro, expóngalos como controles globales de Storybook, conectados por decoradores a los mismos proveedores de contexto de la aplicación real. Úselos para explorar las combinaciones de riesgo —el botón que no cabe en alemán, el texto que desaparece en oscuro— y defina qué combinaciones se prueban siempre.

6. Se publica solo

Un Storybook que alguien tiene que acordarse de publicar ya está desactualizado. Se publica automáticamente al integrar cambios aprobados, como referencia que diseño, QA y el cliente pueden abrir, con el acceso que exija la sensibilidad del producto. Esa referencia es la que se revisa, no una captura en un chat.

7. Cuándo algo sube de nivel

Los primitivos de la marca —botón, campo, tipografía— nacen como parte del sistema desde el primer día. Para lo demás:

• La repetición es una señal, no un umbral. Un patrón se consolida cuando su intención y sus variantes ya son estables; abstraer antes suele costar más que un duplicado visible. En la práctica, eso rara vez ocurre antes del tercer uso.
• Compartir entre proyectos pide gobierno. Cuando un segundo producto necesita los mismos componentes, el sistema se vuelve un paquete con dueño claro, versiones y una ruta de adopción; ahí Storybook suele volverse la referencia más útil, sin sustituir la documentación de decisiones.

Lo que todavía nos falta, dicho en voz alta

Revisamos accesibilidad de forma automática en cada historia, pero hoy la revisión avisa y no bloquea. El paso que muchos equipos posponen —y que exigimos como siguiente— es que una falla de accesibilidad o un estado roto detenga la publicación, igual que una prueba roja. Un contrato que no puede detener un cambio es solo una sugerencia.

Siguiente en la serie: Paradigmas del frontend moderno, sin humo · Qué debe tener un frontend profesional antes de salir a producción.