siesa-ui-kit 1.0.2 → 1.0.4

package/src/components/NavigationRailItem/NavigationRailItem.stories.tsx

@@ -1,667 +1,667 @@
-import type { Meta, StoryObj } from '@storybook/react';
-import React from 'react';
-import { NavigationRailItem } from './NavigationRailItem';
-
-/**
- * NavigationRailItem - Componente de item para NavigationRail
- *
- * Componente independiente para items individuales de la barra de navegación vertical.
- * Implementado pixel-perfect según Figma (node 4294-22931) con soporte completo
- * para todos los estados, badges y dark mode.
- *
- * **Características principales:**
- * - Ancho fijo de 56px según especificaciones de Figma
- * - Estados completos: Enabled, Hover, Selected, Focus, Disabled
- * - Badges de notificación con contador (1-99+)
- * - Tipografía Label XXSmall (10px Bold) del sistema de diseño
- * - Dark mode completo con estrategia 'class'
- * - Focus rings adaptativos con sombras para accesibilidad
- * - Soporte para iconos 16x16px de cualquier librería
- *
- * **Especificaciones de Figma:**
- * - Ancho: 56px (w-14)
- * - Icon container: 32px altura, 16px de padding horizontal, rounded-full
- * - Label: 10px Bold, leading 12px
- * - Gap: 4px entre icon y label
- * - Badge: 13x13px, posición absolute (-top-0.5, left-[34px])
- * - Estados visuales definidos por Figma con colores y sombras específicas
- *
- * **Paleta de colores (según docs/colors.md):**
- * - Primary Custom 600 (#0e79fd) - Color primario
- * - Primary Custom 100 (#dbeefe) - Hover/Selected background
- * - Content Primary - Color de texto por defecto
- * - Content Tertiary - Color de texto deshabilitado
- * - Red 700 (#b91c1c) - Color del badge
- *
- * **Mejores prácticas:**
- * - JSDoc completo con @see references
- * - Tokens del sistema (NO colores hardcodeados)
- * - Dark mode en todos los estados
- * - Focus rings adaptativos
- * - Props con defaults y tipos estrictos
- * - Accesibilidad ARIA completa
- *
- * @see docs/colors.md - Sistema de colores
- * @see docs/typography.md - Sistema tipográfico
- * @see docs/spacing.md - Sistema de espaciado
- * @see docs/shadows.md - Sistema de sombras
- * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22931
- */
-const meta = {
-  title: 'Siesa UI Kit/Navigation/NavigationRailItem',
-  component: NavigationRailItem,
-  parameters: {
-    layout: 'centered',
-    docs: {
-      description: {
-        component: 'Item individual de NavigationRail con soporte completo para estados, badges y dark mode. Diseñado para ser usado dentro de un contenedor NavigationRail o de forma independiente.',
-      },
-    },
-    backgrounds: {
-      default: 'light',
-      values: [
-        { name: 'light', value: '#ffffff' },
-        { name: 'gray', value: '#f3f4f6' },
-        { name: 'dark', value: '#18181b' },
-      ],
-    },
-  },
-  tags: ['autodocs'],
-  argTypes: {
-    icon: {
-      description: 'Icono a mostrar (16x16px recomendado)',
-      table: {
-        type: { summary: 'ReactNode' },
-        category: 'Contenido',
-      },
-      control: false,
-    },
-    label: {
-      control: 'text',
-      description: 'Texto del label que aparece debajo del icono',
-      table: {
-        type: { summary: 'string' },
-        category: 'Contenido',
-      },
-    },
-    selected: {
-      control: 'boolean',
-      description: 'Si el item está seleccionado actualmente',
-      table: {
-        type: { summary: 'boolean' },
-        defaultValue: { summary: 'false' },
-        category: 'Estado',
-      },
-    },
-    disabled: {
-      control: 'boolean',
-      description: 'Si el item está deshabilitado (no interactivo, opacity 55%)',
-      table: {
-        type: { summary: 'boolean' },
-        defaultValue: { summary: 'false' },
-        category: 'Estado',
-      },
-    },
-    badge: {
-      control: 'boolean',
-      description: 'Mostrar badge de notificación (dot rojo simple)',
-      table: {
-        type: { summary: 'boolean' },
-        defaultValue: { summary: 'false' },
-        category: 'Notificaciones',
-      },
-    },
-    badgeCount: {
-      control: { type: 'number', min: 0, max: 999 },
-      description: 'Número a mostrar en el badge (reemplaza el dot, 99+ para >99)',
-      table: {
-        type: { summary: 'number' },
-        category: 'Notificaciones',
-      },
-    },
-    onClick: {
-      description: 'Callback cuando se hace click en el item',
-      table: {
-        type: { summary: '() => void' },
-        category: 'Eventos',
-      },
-      control: false,
-    },
-    ariaLabel: {
-      control: 'text',
-      description: 'Label para accesibilidad (ARIA). Por defecto usa el label prop',
-      table: {
-        type: { summary: 'string' },
-        category: 'Accesibilidad',
-      },
-    },
-    id: {
-      control: 'text',
-      description: 'ID único del item para identificarlo en navegación',
-      table: {
-        type: { summary: 'string' },
-        category: 'Identidad',
-      },
-    },
-    showLabelText: {
-      control: 'boolean',
-      description: 'Si el label debe ser visible (para variar entre icon-only)',
-      table: {
-        type: { summary: 'boolean' },
-        defaultValue: { summary: 'true' },
-        category: 'Visibilidad',
-      },
-    },
-    showIcon: {
-      control: 'boolean',
-      description: 'Si el icono debe ser visible',
-      table: {
-        type: { summary: 'boolean' },
-        defaultValue: { summary: 'true' },
-        category: 'Visibilidad',
-      },
-    },
-  },
-} satisfies Meta<typeof NavigationRailItem>;
-
-export default meta;
-type Story = StoryObj<typeof meta>;
-
-// ===== ICONO DE EJEMPLO =====
-const HomeIcon = () => (
-  <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
-    <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>
-    <polyline points="9 22 9 12 15 12 15 22"/>
-  </svg>
-);
-
-const BellIcon = () => (
-  <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
-    <path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/>
-    <path d="M13.73 21a2 2 0 0 1-3.46 0"/>
-  </svg>
-);
-
-const SearchIcon = () => (
-  <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
-    <circle cx="11" cy="11" r="8"/>
-    <path d="m21 21-4.35-4.35"/>
-  </svg>
-);
-
-const SettingsIcon = () => (
-  <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
-    <circle cx="12" cy="12" r="3"/>
-    <path d="M12 1v6m0 6v6M4.22 4.22l4.24 4.24m5.08 5.08l4.24 4.24M1 12h6m6 0h6M4.22 19.78l4.24-4.24m5.08-5.08l4.24-4.24"/>
-  </svg>
-);
-
-const StarIcon = () => (
-  <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" stroke="currentColor" strokeWidth="2">
-    <polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/>
-  </svg>
-);
-
-// ===== STORIES =====
-
-/**
- * Estado por defecto: item habilitado, no seleccionado, sin badge
- */
-export const Default: Story = {
-  args: {
-    id: 'home',
-    icon: <HomeIcon />,
-    label: 'Inicio',
-    selected: false,
-    disabled: false,
-    badge: false,
-  },
-};
-
-/**
- * Estado seleccionado: background celeste claro, icono azul
- */
-export const Selected: Story = {
-  args: {
-    ...Default.args,
-    selected: true,
-  },
-};
-
-/**
- * Con badge de notificación (dot rojo simple)
- */
-export const WithBadge: Story = {
-  args: {
-    ...Default.args,
-    id: 'notifications',
-    icon: <BellIcon />,
-    label: 'Notificaciones',
-    badge: true,
-  },
-};
-
-/**
- * Con badge contador numérico
- */
-export const WithBadgeCount: Story = {
-  args: {
-    ...Default.args,
-    id: 'notifications',
-    icon: <BellIcon />,
-    label: 'Notificaciones',
-    badgeCount: 5,
-  },
-};
-
-/**
- * Con badge contador mostrando 99+ (cuando count > 99)
- */
-export const WithBadgeCountMax: Story = {
-  args: {
-    ...Default.args,
-    id: 'notifications',
-    icon: <BellIcon />,
-    label: 'Notificaciones',
-    badgeCount: 150,
-  },
-};
-
-/**
- * Item deshabilitado: opacity 55%, no interactivo
- */
-export const Disabled: Story = {
-  args: {
-    ...Default.args,
-    id: 'premium',
-    icon: <StarIcon />,
-    label: 'Premium',
-    disabled: true,
-  },
-};
-
-/**
- * Item deshabilitado con badge: el badge también se ve afectado por la opacidad
- */
-export const DisabledWithBadge: Story = {
-  args: {
-    ...Default.args,
-    id: 'premium',
-    icon: <StarIcon />,
-    label: 'Premium',
-    disabled: true,
-    badgeCount: 3,
-  },
-};
-
-/**
- * Solo icono (sin label)
- */
-export const IconOnly: Story = {
-  args: {
-    ...Default.args,
-    showLabelText: false,
-  },
-};
-
-/**
- * Solo label (sin icono)
- */
-export const LabelOnly: Story = {
-  args: {
-    ...Default.args,
-    showIcon: false,
-  },
-};
-
-/**
- * Galería de todos los estados básicos
- */
-export const AllStates: Story = {
-  args: { ...Default.args },
-  render: () => (
-    <div className="flex flex-col gap-12 p-8">
-      {/* Fila 1: Estados básicos */}
-      <div className="flex gap-8 items-center justify-center p-4 bg-white dark:bg-zinc-900 rounded-lg">
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-content-tertiary">Enabled</p>
-          <NavigationRailItem
-            id="home"
-            icon={<HomeIcon />}
-            label="Inicio"
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-content-tertiary">Hover</p>
-          <NavigationRailItem
-            id="search"
-            icon={<SearchIcon />}
-            label="Buscar"
-            className="hover:shadow-md"
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-content-tertiary">Selected</p>
-          <NavigationRailItem
-            id="home"
-            icon={<HomeIcon />}
-            label="Inicio"
-            selected={true}
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-content-tertiary">Disabled</p>
-          <NavigationRailItem
-            id="premium"
-            icon={<StarIcon />}
-            label="Premium"
-            disabled={true}
-          />
-        </div>
-      </div>
-
-      {/* Fila 2: Con badges */}
-      <div className="flex gap-8 items-center justify-center p-4 bg-white dark:bg-zinc-900 rounded-lg">
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-content-tertiary">Badge Dot</p>
-          <NavigationRailItem
-            id="notifications"
-            icon={<BellIcon />}
-            label="Notificaciones"
-            badge={true}
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-content-tertiary">Badge Count: 5</p>
-          <NavigationRailItem
-            id="notifications"
-            icon={<BellIcon />}
-            label="Notificaciones"
-            badgeCount={5}
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-content-tertiary">Badge Count: 99+</p>
-          <NavigationRailItem
-            id="notifications"
-            icon={<BellIcon />}
-            label="Notificaciones"
-            badgeCount={150}
-          />
-        </div>
-      </div>
-
-      {/* Fila 3: Variaciones de visibilidad */}
-      <div className="flex gap-8 items-center justify-center p-4 bg-white dark:bg-zinc-900 rounded-lg">
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-content-tertiary">Con Icon + Label</p>
-          <NavigationRailItem
-            id="home"
-            icon={<HomeIcon />}
-            label="Inicio"
-            showIcon={true}
-            showLabelText={true}
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-content-tertiary">Solo Icon</p>
-          <NavigationRailItem
-            id="home"
-            icon={<HomeIcon />}
-            label="Inicio"
-            showIcon={true}
-            showLabelText={false}
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-content-tertiary">Solo Label</p>
-          <NavigationRailItem
-            id="home"
-            icon={<HomeIcon />}
-            label="Inicio"
-            showIcon={false}
-            showLabelText={true}
-          />
-        </div>
-      </div>
-    </div>
-  ),
-};
-
-/**
- * NavigationRail de ejemplo con múltiples items
- */
-export const NavigationRailExample: Story = {
-  args: { ...Default.args },
-  render: () => (
-    <div className="flex items-start h-screen bg-white dark:bg-zinc-900 border-r border-border-primary dark:border-dark-border-primary p-2">
-      <div className="flex flex-col gap-3 items-center">
-        <NavigationRailItem
-          id="home"
-          icon={<HomeIcon />}
-          label="Inicio"
-          selected={true}
-        />
-        <NavigationRailItem
-          id="search"
-          icon={<SearchIcon />}
-          label="Buscar"
-        />
-        <NavigationRailItem
-          id="notifications"
-          icon={<BellIcon />}
-          label="Notificaciones"
-          badgeCount={3}
-        />
-        <NavigationRailItem
-          id="settings"
-          icon={<SettingsIcon />}
-          label="Configuración"
-        />
-      </div>
-    </div>
-  ),
-  parameters: {
-    layout: 'fullscreen',
-  },
-};
-
-/**
- * Dark Mode: todos los estados en modo oscuro
- */
-export const DarkMode: Story = {
-  args: { ...Default.args },
-  render: () => (
-    <div className="dark flex flex-col gap-12 p-8 bg-zinc-900 rounded-lg">
-      {/* Fila 1: Estados básicos */}
-      <div className="flex gap-8 items-center justify-center p-4 bg-zinc-800 rounded-lg">
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-gray-400">Enabled</p>
-          <NavigationRailItem
-            id="home"
-            icon={<HomeIcon />}
-            label="Inicio"
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-gray-400">Hover</p>
-          <NavigationRailItem
-            id="search"
-            icon={<SearchIcon />}
-            label="Buscar"
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-gray-400">Selected</p>
-          <NavigationRailItem
-            id="home"
-            icon={<HomeIcon />}
-            label="Inicio"
-            selected={true}
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-gray-400">Disabled</p>
-          <NavigationRailItem
-            id="premium"
-            icon={<StarIcon />}
-            label="Premium"
-            disabled={true}
-          />
-        </div>
-      </div>
-
-      {/* Fila 2: Con badges */}
-      <div className="flex gap-8 items-center justify-center p-4 bg-zinc-800 rounded-lg">
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-gray-400">Badge Dot</p>
-          <NavigationRailItem
-            id="notifications"
-            icon={<BellIcon />}
-            label="Notificaciones"
-            badge={true}
-          />
-        </div>
-        <div className="text-center">
-          <p className="text-xs font-bold mb-4 text-gray-400">Badge Count: 5</p>
-          <NavigationRailItem
-            id="notifications"
-            icon={<BellIcon />}
-            label="Notificaciones"
-            badgeCount={5}
-          />
-        </div>
-      </div>
-    </div>
-  ),
-  parameters: {
-    backgrounds: {
-      default: 'dark',
-    },
-  },
-};
-
-/**
- * Interacción: demostrando click handlers y state management
- */
-export const Interactive: Story = {
-  args: { ...Default.args },
-  render: function Render() {
-    const [selectedId, setSelectedId] = React.useState('home');
-    const items = [
-      { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-      { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-      { id: 'notifications', icon: <BellIcon />, label: 'Notificaciones', badgeCount: 3 },
-      { id: 'settings', icon: <SettingsIcon />, label: 'Configuración' },
-    ];
-
-    return (
-      <div className="flex gap-8">
-        {/* Navigation Rail */}
-        <nav className="flex flex-col gap-3 items-center p-2 bg-white dark:bg-zinc-900 border-r border-border-primary dark:border-dark-border-primary rounded-lg">
-          {items.map((item) => (
-            <NavigationRailItem
-              key={item.id}
-              id={item.id}
-              icon={item.icon}
-              label={item.label}
-              badgeCount={item.badgeCount}
-              selected={selectedId === item.id}
-              onClick={() => setSelectedId(item.id)}
-            />
-          ))}
-        </nav>
-
-        {/* Content */}
-        <div className="flex-1 p-6 bg-gray-50 dark:bg-zinc-800 rounded-lg">
-          <h2 className="text-lg font-bold mb-4 dark:text-white">
-            {items.find((item) => item.id === selectedId)?.label}
-          </h2>
-          <p className="text-content-secondary dark:text-dark-content-secondary">
-            Seleccionado: <code className="bg-gray-200 dark:bg-zinc-700 px-2 py-1 rounded text-sm">{selectedId}</code>
-          </p>
-        </div>
-      </div>
-    );
-  },
-};
-
-/**
- * Variaciones de labels largos
- */
-export const LongLabels: Story = {
-  args: { ...Default.args },
-  render: () => (
-    <div className="flex gap-8 items-center justify-center p-4 bg-white dark:bg-zinc-900 rounded-lg">
-      <div className="text-center">
-        <p className="text-xs font-bold mb-4 text-content-tertiary">Label corto</p>
-        <NavigationRailItem
-          id="home"
-          icon={<HomeIcon />}
-          label="Inicio"
-        />
-      </div>
-      <div className="text-center">
-        <p className="text-xs font-bold mb-4 text-content-tertiary">Label mediano</p>
-        <NavigationRailItem
-          id="search"
-          icon={<SearchIcon />}
-          label="Búsqueda"
-        />
-      </div>
-      <div className="text-center">
-        <p className="text-xs font-bold mb-4 text-content-tertiary">Label largo con wrap</p>
-        <NavigationRailItem
-          id="notifications"
-          icon={<BellIcon />}
-          label="Notificaciones"
-        />
-      </div>
-    </div>
-  ),
-};
-
-/**
- * Accesibilidad: demostrando ARIA labels y keyboard navigation
- */
-export const Accessibility: Story = {
-  args: { ...Default.args },
-  render: () => (
-    <div className="flex flex-col gap-6 p-6 bg-white dark:bg-zinc-900 rounded-lg">
-      <div>
-        <h3 className="text-sm font-bold mb-4 dark:text-white">Con aria-label personalizado:</h3>
-        <div className="flex gap-4">
-          <NavigationRailItem
-            id="home"
-            icon={<HomeIcon />}
-            label="Home"
-            ariaLabel="Ir a la página de inicio del sitio"
-          />
-          <NavigationRailItem
-            id="search"
-            icon={<SearchIcon />}
-            label="Search"
-            ariaLabel="Abrir el formulario de búsqueda"
-          />
-        </div>
-      </div>
-
-      <div>
-        <h3 className="text-sm font-bold mb-4 dark:text-white">Con estado disabled:</h3>
-        <div className="flex gap-4">
-          <NavigationRailItem
-            id="premium"
-            icon={<StarIcon />}
-            label="Premium"
-            disabled={true}
-            ariaLabel="Función Premium deshabilitada: requiere actualizar a Premium"
-          />
-        </div>
-      </div>
-
-      <p className="text-xs text-content-secondary dark:text-dark-content-secondary">
-        Prueba navegar con Tab. El componente soporta keyboard focus y tiene aria-label completo para screen readers.
-      </p>
-    </div>
-  ),
-};
+import type { Meta, StoryObj } from '@storybook/react';
+import React from 'react';
+import { NavigationRailItem } from './NavigationRailItem';
+
+/**
+ * NavigationRailItem - Componente de item para NavigationRail
+ *
+ * Componente independiente para items individuales de la barra de navegación vertical.
+ * Implementado pixel-perfect según Figma (node 4294-22931) con soporte completo
+ * para todos los estados, badges y dark mode.
+ *
+ * **Características principales:**
+ * - Ancho fijo de 56px según especificaciones de Figma
+ * - Estados completos: Enabled, Hover, Selected, Focus, Disabled
+ * - Badges de notificación con contador (1-99+)
+ * - Tipografía Label XXSmall (10px Bold) del sistema de diseño
+ * - Dark mode completo con estrategia 'class'
+ * - Focus rings adaptativos con sombras para accesibilidad
+ * - Soporte para iconos 16x16px de cualquier librería
+ *
+ * **Especificaciones de Figma:**
+ * - Ancho: 56px (w-14)
+ * - Icon container: 32px altura, 16px de padding horizontal, rounded-full
+ * - Label: 10px Bold, leading 12px
+ * - Gap: 4px entre icon y label
+ * - Badge: 13x13px, posición absolute (-top-0.5, left-[34px])
+ * - Estados visuales definidos por Figma con colores y sombras específicas
+ *
+ * **Paleta de colores (según docs/colors.md):**
+ * - Primary Custom 600 (#0e79fd) - Color primario
+ * - Primary Custom 100 (#dbeefe) - Hover/Selected background
+ * - Content Primary - Color de texto por defecto
+ * - Content Tertiary - Color de texto deshabilitado
+ * - Red 700 (#b91c1c) - Color del badge
+ *
+ * **Mejores prácticas:**
+ * - JSDoc completo con @see references
+ * - Tokens del sistema (NO colores hardcodeados)
+ * - Dark mode en todos los estados
+ * - Focus rings adaptativos
+ * - Props con defaults y tipos estrictos
+ * - Accesibilidad ARIA completa
+ *
+ * @see docs/colors.md - Sistema de colores
+ * @see docs/typography.md - Sistema tipográfico
+ * @see docs/spacing.md - Sistema de espaciado
+ * @see docs/shadows.md - Sistema de sombras
+ * @see https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22931
+ */
+const meta = {
+  title: 'Siesa UI Kit/Navigation/NavigationRailItem',
+  component: NavigationRailItem,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component: 'Item individual de NavigationRail con soporte completo para estados, badges y dark mode. Diseñado para ser usado dentro de un contenedor NavigationRail o de forma independiente.',
+      },
+    },
+    backgrounds: {
+      default: 'light',
+      values: [
+        { name: 'light', value: '#ffffff' },
+        { name: 'gray', value: '#f3f4f6' },
+        { name: 'dark', value: '#18181b' },
+      ],
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    icon: {
+      description: 'Icono a mostrar (16x16px recomendado)',
+      table: {
+        type: { summary: 'ReactNode' },
+        category: 'Contenido',
+      },
+      control: false,
+    },
+    label: {
+      control: 'text',
+      description: 'Texto del label que aparece debajo del icono',
+      table: {
+        type: { summary: 'string' },
+        category: 'Contenido',
+      },
+    },
+    selected: {
+      control: 'boolean',
+      description: 'Si el item está seleccionado actualmente',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'Estado',
+      },
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Si el item está deshabilitado (no interactivo, opacity 55%)',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'Estado',
+      },
+    },
+    badge: {
+      control: 'boolean',
+      description: 'Mostrar badge de notificación (dot rojo simple)',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        category: 'Notificaciones',
+      },
+    },
+    badgeCount: {
+      control: { type: 'number', min: 0, max: 999 },
+      description: 'Número a mostrar en el badge (reemplaza el dot, 99+ para >99)',
+      table: {
+        type: { summary: 'number' },
+        category: 'Notificaciones',
+      },
+    },
+    onClick: {
+      description: 'Callback cuando se hace click en el item',
+      table: {
+        type: { summary: '() => void' },
+        category: 'Eventos',
+      },
+      control: false,
+    },
+    ariaLabel: {
+      control: 'text',
+      description: 'Label para accesibilidad (ARIA). Por defecto usa el label prop',
+      table: {
+        type: { summary: 'string' },
+        category: 'Accesibilidad',
+      },
+    },
+    id: {
+      control: 'text',
+      description: 'ID único del item para identificarlo en navegación',
+      table: {
+        type: { summary: 'string' },
+        category: 'Identidad',
+      },
+    },
+    showLabelText: {
+      control: 'boolean',
+      description: 'Si el label debe ser visible (para variar entre icon-only)',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'true' },
+        category: 'Visibilidad',
+      },
+    },
+    showIcon: {
+      control: 'boolean',
+      description: 'Si el icono debe ser visible',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'true' },
+        category: 'Visibilidad',
+      },
+    },
+  },
+} satisfies Meta<typeof NavigationRailItem>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ===== ICONO DE EJEMPLO =====
+const HomeIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"/>
+    <polyline points="9 22 9 12 15 12 15 22"/>
+  </svg>
+);
+
+const BellIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <path d="M18 8A6 6 0 0 0 6 8c0 7-3 9-3 9h18s-3-2-3-9"/>
+    <path d="M13.73 21a2 2 0 0 1-3.46 0"/>
+  </svg>
+);
+
+const SearchIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <circle cx="11" cy="11" r="8"/>
+    <path d="m21 21-4.35-4.35"/>
+  </svg>
+);
+
+const SettingsIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
+    <circle cx="12" cy="12" r="3"/>
+    <path d="M12 1v6m0 6v6M4.22 4.22l4.24 4.24m5.08 5.08l4.24 4.24M1 12h6m6 0h6M4.22 19.78l4.24-4.24m5.08-5.08l4.24-4.24"/>
+  </svg>
+);
+
+const StarIcon = () => (
+  <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor" stroke="currentColor" strokeWidth="2">
+    <polygon points="12 2 15.09 8.26 22 9.27 17 14.14 18.18 21.02 12 17.77 5.82 21.02 7 14.14 2 9.27 8.91 8.26 12 2"/>
+  </svg>
+);
+
+// ===== STORIES =====
+
+/**
+ * Estado por defecto: item habilitado, no seleccionado, sin badge
+ */
+export const Default: Story = {
+  args: {
+    id: 'home',
+    icon: <HomeIcon />,
+    label: 'Inicio',
+    selected: false,
+    disabled: false,
+    badge: false,
+  },
+};
+
+/**
+ * Estado seleccionado: background celeste claro, icono azul
+ */
+export const Selected: Story = {
+  args: {
+    ...Default.args,
+    selected: true,
+  },
+};
+
+/**
+ * Con badge de notificación (dot rojo simple)
+ */
+export const WithBadge: Story = {
+  args: {
+    ...Default.args,
+    id: 'notifications',
+    icon: <BellIcon />,
+    label: 'Notificaciones',
+    badge: true,
+  },
+};
+
+/**
+ * Con badge contador numérico
+ */
+export const WithBadgeCount: Story = {
+  args: {
+    ...Default.args,
+    id: 'notifications',
+    icon: <BellIcon />,
+    label: 'Notificaciones',
+    badgeCount: 5,
+  },
+};
+
+/**
+ * Con badge contador mostrando 99+ (cuando count > 99)
+ */
+export const WithBadgeCountMax: Story = {
+  args: {
+    ...Default.args,
+    id: 'notifications',
+    icon: <BellIcon />,
+    label: 'Notificaciones',
+    badgeCount: 150,
+  },
+};
+
+/**
+ * Item deshabilitado: opacity 55%, no interactivo
+ */
+export const Disabled: Story = {
+  args: {
+    ...Default.args,
+    id: 'premium',
+    icon: <StarIcon />,
+    label: 'Premium',
+    disabled: true,
+  },
+};
+
+/**
+ * Item deshabilitado con badge: el badge también se ve afectado por la opacidad
+ */
+export const DisabledWithBadge: Story = {
+  args: {
+    ...Default.args,
+    id: 'premium',
+    icon: <StarIcon />,
+    label: 'Premium',
+    disabled: true,
+    badgeCount: 3,
+  },
+};
+
+/**
+ * Solo icono (sin label)
+ */
+export const IconOnly: Story = {
+  args: {
+    ...Default.args,
+    showLabelText: false,
+  },
+};
+
+/**
+ * Solo label (sin icono)
+ */
+export const LabelOnly: Story = {
+  args: {
+    ...Default.args,
+    showIcon: false,
+  },
+};
+
+/**
+ * Galería de todos los estados básicos
+ */
+export const AllStates: Story = {
+  args: { ...Default.args },
+  render: () => (
+    <div className="flex flex-col gap-12 p-8">
+      {/* Fila 1: Estados básicos */}
+      <div className="flex gap-8 items-center justify-center p-4 bg-white dark:bg-zinc-900 rounded-lg">
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-content-tertiary">Enabled</p>
+          <NavigationRailItem
+            id="home"
+            icon={<HomeIcon />}
+            label="Inicio"
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-content-tertiary">Hover</p>
+          <NavigationRailItem
+            id="search"
+            icon={<SearchIcon />}
+            label="Buscar"
+            className="hover:shadow-md"
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-content-tertiary">Selected</p>
+          <NavigationRailItem
+            id="home"
+            icon={<HomeIcon />}
+            label="Inicio"
+            selected={true}
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-content-tertiary">Disabled</p>
+          <NavigationRailItem
+            id="premium"
+            icon={<StarIcon />}
+            label="Premium"
+            disabled={true}
+          />
+        </div>
+      </div>
+
+      {/* Fila 2: Con badges */}
+      <div className="flex gap-8 items-center justify-center p-4 bg-white dark:bg-zinc-900 rounded-lg">
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-content-tertiary">Badge Dot</p>
+          <NavigationRailItem
+            id="notifications"
+            icon={<BellIcon />}
+            label="Notificaciones"
+            badge={true}
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-content-tertiary">Badge Count: 5</p>
+          <NavigationRailItem
+            id="notifications"
+            icon={<BellIcon />}
+            label="Notificaciones"
+            badgeCount={5}
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-content-tertiary">Badge Count: 99+</p>
+          <NavigationRailItem
+            id="notifications"
+            icon={<BellIcon />}
+            label="Notificaciones"
+            badgeCount={150}
+          />
+        </div>
+      </div>
+
+      {/* Fila 3: Variaciones de visibilidad */}
+      <div className="flex gap-8 items-center justify-center p-4 bg-white dark:bg-zinc-900 rounded-lg">
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-content-tertiary">Con Icon + Label</p>
+          <NavigationRailItem
+            id="home"
+            icon={<HomeIcon />}
+            label="Inicio"
+            showIcon={true}
+            showLabelText={true}
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-content-tertiary">Solo Icon</p>
+          <NavigationRailItem
+            id="home"
+            icon={<HomeIcon />}
+            label="Inicio"
+            showIcon={true}
+            showLabelText={false}
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-content-tertiary">Solo Label</p>
+          <NavigationRailItem
+            id="home"
+            icon={<HomeIcon />}
+            label="Inicio"
+            showIcon={false}
+            showLabelText={true}
+          />
+        </div>
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * NavigationRail de ejemplo con múltiples items
+ */
+export const NavigationRailExample: Story = {
+  args: { ...Default.args },
+  render: () => (
+    <div className="flex items-start h-screen bg-white dark:bg-zinc-900 border-r border-border-primary dark:border-dark-border-primary p-2">
+      <div className="flex flex-col gap-3 items-center">
+        <NavigationRailItem
+          id="home"
+          icon={<HomeIcon />}
+          label="Inicio"
+          selected={true}
+        />
+        <NavigationRailItem
+          id="search"
+          icon={<SearchIcon />}
+          label="Buscar"
+        />
+        <NavigationRailItem
+          id="notifications"
+          icon={<BellIcon />}
+          label="Notificaciones"
+          badgeCount={3}
+        />
+        <NavigationRailItem
+          id="settings"
+          icon={<SettingsIcon />}
+          label="Configuración"
+        />
+      </div>
+    </div>
+  ),
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+/**
+ * Dark Mode: todos los estados en modo oscuro
+ */
+export const DarkMode: Story = {
+  args: { ...Default.args },
+  render: () => (
+    <div className="dark flex flex-col gap-12 p-8 bg-zinc-900 rounded-lg">
+      {/* Fila 1: Estados básicos */}
+      <div className="flex gap-8 items-center justify-center p-4 bg-zinc-800 rounded-lg">
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-gray-400">Enabled</p>
+          <NavigationRailItem
+            id="home"
+            icon={<HomeIcon />}
+            label="Inicio"
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-gray-400">Hover</p>
+          <NavigationRailItem
+            id="search"
+            icon={<SearchIcon />}
+            label="Buscar"
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-gray-400">Selected</p>
+          <NavigationRailItem
+            id="home"
+            icon={<HomeIcon />}
+            label="Inicio"
+            selected={true}
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-gray-400">Disabled</p>
+          <NavigationRailItem
+            id="premium"
+            icon={<StarIcon />}
+            label="Premium"
+            disabled={true}
+          />
+        </div>
+      </div>
+
+      {/* Fila 2: Con badges */}
+      <div className="flex gap-8 items-center justify-center p-4 bg-zinc-800 rounded-lg">
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-gray-400">Badge Dot</p>
+          <NavigationRailItem
+            id="notifications"
+            icon={<BellIcon />}
+            label="Notificaciones"
+            badge={true}
+          />
+        </div>
+        <div className="text-center">
+          <p className="text-xs font-bold mb-4 text-gray-400">Badge Count: 5</p>
+          <NavigationRailItem
+            id="notifications"
+            icon={<BellIcon />}
+            label="Notificaciones"
+            badgeCount={5}
+          />
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    backgrounds: {
+      default: 'dark',
+    },
+  },
+};
+
+/**
+ * Interacción: demostrando click handlers y state management
+ */
+export const Interactive: Story = {
+  args: { ...Default.args },
+  render: function Render() {
+    const [selectedId, setSelectedId] = React.useState('home');
+    const items = [
+      { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+      { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+      { id: 'notifications', icon: <BellIcon />, label: 'Notificaciones', badgeCount: 3 },
+      { id: 'settings', icon: <SettingsIcon />, label: 'Configuración' },
+    ];
+
+    return (
+      <div className="flex gap-8">
+        {/* Navigation Rail */}
+        <nav className="flex flex-col gap-3 items-center p-2 bg-white dark:bg-zinc-900 border-r border-border-primary dark:border-dark-border-primary rounded-lg">
+          {items.map((item) => (
+            <NavigationRailItem
+              key={item.id}
+              id={item.id}
+              icon={item.icon}
+              label={item.label}
+              badgeCount={item.badgeCount}
+              selected={selectedId === item.id}
+              onClick={() => setSelectedId(item.id)}
+            />
+          ))}
+        </nav>
+
+        {/* Content */}
+        <div className="flex-1 p-6 bg-gray-50 dark:bg-zinc-800 rounded-lg">
+          <h2 className="text-lg font-bold mb-4 dark:text-white">
+            {items.find((item) => item.id === selectedId)?.label}
+          </h2>
+          <p className="text-content-secondary dark:text-dark-content-secondary">
+            Seleccionado: <code className="bg-gray-200 dark:bg-zinc-700 px-2 py-1 rounded text-sm">{selectedId}</code>
+          </p>
+        </div>
+      </div>
+    );
+  },
+};
+
+/**
+ * Variaciones de labels largos
+ */
+export const LongLabels: Story = {
+  args: { ...Default.args },
+  render: () => (
+    <div className="flex gap-8 items-center justify-center p-4 bg-white dark:bg-zinc-900 rounded-lg">
+      <div className="text-center">
+        <p className="text-xs font-bold mb-4 text-content-tertiary">Label corto</p>
+        <NavigationRailItem
+          id="home"
+          icon={<HomeIcon />}
+          label="Inicio"
+        />
+      </div>
+      <div className="text-center">
+        <p className="text-xs font-bold mb-4 text-content-tertiary">Label mediano</p>
+        <NavigationRailItem
+          id="search"
+          icon={<SearchIcon />}
+          label="Búsqueda"
+        />
+      </div>
+      <div className="text-center">
+        <p className="text-xs font-bold mb-4 text-content-tertiary">Label largo con wrap</p>
+        <NavigationRailItem
+          id="notifications"
+          icon={<BellIcon />}
+          label="Notificaciones"
+        />
+      </div>
+    </div>
+  ),
+};
+
+/**
+ * Accesibilidad: demostrando ARIA labels y keyboard navigation
+ */
+export const Accessibility: Story = {
+  args: { ...Default.args },
+  render: () => (
+    <div className="flex flex-col gap-6 p-6 bg-white dark:bg-zinc-900 rounded-lg">
+      <div>
+        <h3 className="text-sm font-bold mb-4 dark:text-white">Con aria-label personalizado:</h3>
+        <div className="flex gap-4">
+          <NavigationRailItem
+            id="home"
+            icon={<HomeIcon />}
+            label="Home"
+            ariaLabel="Ir a la página de inicio del sitio"
+          />
+          <NavigationRailItem
+            id="search"
+            icon={<SearchIcon />}
+            label="Search"
+            ariaLabel="Abrir el formulario de búsqueda"
+          />
+        </div>
+      </div>
+
+      <div>
+        <h3 className="text-sm font-bold mb-4 dark:text-white">Con estado disabled:</h3>
+        <div className="flex gap-4">
+          <NavigationRailItem
+            id="premium"
+            icon={<StarIcon />}
+            label="Premium"
+            disabled={true}
+            ariaLabel="Función Premium deshabilitada: requiere actualizar a Premium"
+          />
+        </div>
+      </div>
+
+      <p className="text-xs text-content-secondary dark:text-dark-content-secondary">
+        Prueba navegar con Tab. El componente soporta keyboard focus y tiene aria-label completo para screen readers.
+      </p>
+    </div>
+  ),
+};