Documentación & Storybook

Por Qué Importa la Documentación

Un sistema de diseño es tan bueno como su documentación. Sin documentación clara, los desarrolladores no sabrán cómo usar los componentes correctamente y la adopción sufrirá. La gran documentación incluye ejemplos interactivos, directrices de uso y referencias de API.

Comenzando con Storybook

Storybook es el estándar de la industria para construir y documentar componentes de interfaz en aislamiento.

# Inicializar Storybook en tu proyecto
npx storybook@latest init

# Iniciar servidor de desarrollo de Storybook
npm run storybook

# Construir Storybook estático para despliegue
npm run build-storybook

Escribiendo Historias

Las historias definen los diferentes estados y variaciones de tus componentes:

// Button.stories.tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './Button';

const meta: Meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    variant: {
      control: 'select',
      options: ['primary', 'secondary', 'outline', 'ghost'],
      description: 'El estilo visual del botón',
    },
    size: {
      control: 'radio',
      options: ['sm', 'md', 'lg'],
    },
    isLoading: {
      control: 'boolean',
    },
    disabled: {
      control: 'boolean',
    },
  },
};

export default meta;
type Story = StoryObj;

// Variante primaria (predeterminada)
export const Primary: Story = {
  args: {
    children: 'Botón Primario',
    variant: 'primary',
  },
};

// Todas las variantes
export const Variants: Story = {
  render: () => (
    

      Primario
      Secundario
      Contorno
      Fantasma
    
  ),
};

// Todos los tamaños
export const Sizes: Story = {
  render: () => (
    

      Pequeño
      Mediano
      Grande
    
  ),
};

// Estado de carga
export const Loading: Story = {
  args: {
    children: 'Guardando...',
    isLoading: true,
  },
};

// Con icono
export const WithIcon: Story = {
  render: () => (
    
      
      Enviar Correo
    
  ),
};

Autodocs (Documentación Automática)

Storybook puede generar automáticamente documentación desde tus tipos TypeScript y comentarios JSDoc:

// Button.tsx
export interface ButtonProps {
  /** El estilo visual del botón */
  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
  
  /** El tamaño del botón */
  size?: 'sm' | 'md' | 'lg';
  
  /** Muestra un spinner de carga y deshabilita el botón */
  isLoading?: boolean;
  
  /** El contenido a mostrar dentro del botón */
  children: React.ReactNode;
  
  /** Llamado cuando se hace clic en el botón */
  onClick?: () => void;
}

/**
 * Componente de interfaz principal para interacción del usuario.
 * Usa botones para activar acciones, enviar formularios o navegar.
 */
export const Button = ({ variant = 'primary', size = 'md', ...props }: ButtonProps) => {
  // ...
};

// En *.stories.tsx, agrega la etiqueta autodocs
const meta: Meta = {
  title: 'Components/Button',
  component: Button,
  tags: ['autodocs'],  // Habilita documentación automática
};

Documentación MDX

Combina Markdown con JSX para páginas de documentación ricas:

{/* Button.mdx */}
import { Canvas, Meta, Story, Controls } from '@storybook/blocks';
import * as ButtonStories from './Button.stories';



# Button

Los botones activan acciones, envían formularios o navegan a nuevas páginas.

## Directrices de Uso

- Usa botones **Primarios** para la acción principal en una página
- Usa botones **Secundarios** para acciones menos importantes  
- Usa botones de **Contorno** para acciones de cancelar o retroceder
- Solo un botón Primario por sección

## Ejemplo Interactivo





## Todas las Variantes



## Accesibilidad

- Siempre incluye texto visible o aria-label
- Los botones son enfocables con el teclado
- El estado de carga anuncia a lectores de pantalla

## Qué Hacer y Qué No

✅ **Hacer**
- Usa verbos de acción: "Guardar", "Enviar", "Eliminar"
- Mantén el texto corto y claro

❌ **No Hacer**  
- No uses texto vago como "Haz clic aquí"
- No uses múltiples botones primarios en una sección

Complementos de Storybook

Pruebas de Regresión Visual

// Instalar Chromatic
npm install --save-dev chromatic

// Agregar a package.json
{
  "scripts": {
    "chromatic": "chromatic --project-token=YOUR_TOKEN"
  }
}

// Ejecutar pruebas visuales
npm run chromatic

// O en CI (GitHub Actions)
// .github/workflows/chromatic.yml
name: Chromatic
on: push
jobs:
  chromatic:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: npx chromatic --project-token=${{ secrets.CHROMATIC_TOKEN }}

Herramientas Alternativas de Documentación