Configurar parámetros y decoradores en Storybook te permite documentar tus componentes con Markdown y modificar su apariencia visual sin tocar el código fuente. Si trabajas con un design system o construyes una librería de componentes en React, dominar estas dos herramientas te ahorra horas de explicaciones y mejora la experiencia de quienes consumen tu trabajo.

La idea es simple: los parámetros controlan la metadata y documentación de tu historia, mientras que los decoradores envuelven tu componente en un wrapper para cambiar cómo se ve dentro del canvas de Storybook.

Cómo agregar documentación a un componente con parámetros en Storybook

Los parámetros se declaran dentro del objeto parameters y aceptan configuraciones específicas. Una de las más útiles es docs, que conecta tu historia con un archivo Markdown externo donde describes el propósito del componente, sus tipos de uso y cualquier regla de diseño relevante [01:30].

La estructura básica se ve así:

js import buttonDocumentation from './button.md';

export default { parameters: { docs: { page: null, description: { component: buttonDocumentation, }, }, }, };

El archivo button.md vive junto a tu componente y puede contener desde un título hasta ejemplos de uso completos. Storybook lo renderiza automáticamente en la pestaña de documentación.

¿Para qué sirve el archivo .md en Storybook? Funciona como la fuente de verdad de tu componente. Ahí explicas cuándo usarlo, cuándo no, y qué variantes existen, sin contaminar el código JavaScript.

Por qué documentar componentes evita ambigüedades

Imagina que un desarrollador encuentra tu botón pero no sabe si acepta texto, números o si debe usarse en formularios. Sin documentación, abre un canal de Slack o pregunta en una daily. Con un Markdown bien escrito, resuelve la duda en segundos. Esa es la diferencia entre un componente reusable y uno olvidado.

Qué hace un decorador en Storybook y cómo modificar la UI del canvas

Por defecto, Storybook coloca tu componente en la esquina superior izquierda del canvas. Funcional, pero poco amigable cuando quieres ver márgenes, alineaciones o el componente en un contexto más realista. Los decoradores resuelven esto envolviendo tu historia en un elemento padre al que puedes aplicarle estilos [04:20].

La mecánica consiste en crear un wrapper HTML, insertar la historia como hijo y retornar ese wrapper:

js export default { decorators: [ (story) => { const decorator = document.createElement('div'); decorator.style.margin = '24px'; decorator.appendChild(story()); return decorator; }, ], };

Aquí pasan tres cosas clave: creas un div con document.createElement, le aplicas estilos en línea y usas appendChild para inyectar la historia dentro. El story() es la función que Storybook te entrega como argumento y representa tu componente real.

¿Cómo aplico estilos a un decorador en Storybook? Puedes usar decorator.style para estilos en línea o asignarle una clase con decorator.classList.add() y definirla en tu CSS. Ambas opciones son válidas.

Cómo conectar decoradores con tus design tokens

Si tu equipo trabaja con Figma y maneja foundations de espaciado, los valores que uses en el decorador deberían respetar esos tokens. En el ejemplo se usa un margen de 24 píxeles, que coincide con un valor de espaciado definido en el sistema de diseño. Esa coherencia es la que mantiene a tu librería alineada con el equipo de producto.

Cuándo usar parámetros y cuándo usar decoradores

Aunque ambos viven en el default export de tu archivo de historia, cumplen funciones distintas:

• Parámetros: configuran metadata, documentación, backgrounds, viewports y comportamiento de add-ons.
• Decoradores: modifican el árbol del DOM alrededor de tu componente para cambiar su presentación visual.
• Combinación: puedes usar ambos en la misma historia sin conflictos, ya que operan en capas diferentes.

Una buena práctica es centralizar decoradores comunes (como un padding general) en preview.js para que se apliquen a todas las historias del proyecto, y dejar los específicos en archivos individuales cuando un componente necesita un trato especial.

Para inspeccionar visualmente los estilos que aplica el decorador puedes abrir el inspector del navegador, pero ese flujo se vuelve tedioso rápido. Por eso Storybook ofrece add-ons en la barra superior que muestran propiedades, accesibilidad y viewports sin salir del entorno [09:50].

Cuéntame en los comentarios qué decorador creaste para tu primer componente y si decidiste documentarlo con Markdown o con MDX.