siesa-ui-kit 1.0.2 → 1.0.4

package/src/components/NavigationRailTypes/README.md

@@ -1,573 +1,573 @@
-# NavigationRailTypes
-
-Barra de navegación lateral del sistema de diseño Siesa que permite dos modos visuales distintos: **collapsed** (solo iconos) y **expanded** (con labels y búsqueda).
-
-## 📋 Tabla de Contenidos
-
-1. [Descripción](#descripción)
-2. [Características](#características)
-3. [Especificaciones de Diseño](#especificaciones-de-diseño)
-4. [Uso](#uso)
-5. [Props](#props)
-6. [Estados](#estados)
-7. [Ejemplos](#ejemplos)
-8. [Accesibilidad](#accesibilidad)
-9. [Dark Mode](#dark-mode)
-10. [Referencias](#referencias)
-
----
-
-## Descripción
-
-El componente **NavigationRailTypes** es una barra de navegación lateral responsive que proporciona navegación vertical en aplicaciones de escritorio. Soporta dos modos de visualización que se pueden cambiar dinámicamente mediante el botón de collapse/expand.
-
-### Caso de Uso Principal
-
-- **Navegación principal en aplicaciones desktop**: Menú lateral principal
-- **Aplicaciones con múltiples módulos**: Agrupar opciones de navegación
-- **Dashboard y sistemas administrativos**: Acceso rápido a secciones
-- **Aplicaciones de desktop**: Similar a sidebars en VS Code, Figma, etc.
-
----
-
-## Características
-
-✅ **Dos modos de visualización:**
-- **Collapsed**: 80px width, solo iconos
-- **Expanded**: 215px width, con labels y búsqueda integrada
-
-✅ **Items de navegación:**
-- Iconos personalizables (16x16px)
-- Labels descriptivos (solo en expanded)
-- Estados: default, hover, active, disabled
-- Badges de notificación (dot rojo o contador)
-
-✅ **Búsqueda integrada:**
-- Solo visible en modo expanded
-- Input con icono de búsqueda
-- Placeholder "Buscar módulo"
-
-✅ **Footer con acciones:**
-- Botón "Recientes" (clock icon)
-- Botón collapse/expand con animación
-- Divisores visuales
-
-✅ **Dark Mode:**
-- Soporte completo para light/dark
-- Colores adaptados automáticamente
-
-✅ **Accesibilidad:**
-- Focus rings adaptativos
-- ARIA labels en botones
-- Navegación por teclado
-
-✅ **Animaciones:**
-- Transición suave al collapse/expand
-- Hover effects en items
-- Rotación del chevron
-
----
-
-## Especificaciones de Diseño
-
-### Dimensiones
-
-| Propiedad | Collapsed | Expanded |
-|-----------|-----------|----------|
-| **Width** | 80px | 215px |
-| **Height** | 900px | 900px |
-| **Item Height** | Automático | Automático |
-| **Border Radius** | N/A | 8px (items) |
-
-### Espaciado (Spacing)
-
-| Elemento | Padding | Margin | Gap |
-|----------|---------|--------|-----|
-| **Item** (collapsed) | `px-4 py-1` | N/A | `gap-3` |
-| **Item** (expanded) | `px-4 py-2` | N/A | `gap-3` |
-| **Search** (expanded) | `px-3 py-3` | N/A | `gap-2` |
-| **Footer** | `px-3` | N/A | `gap-3` |
-
-### Tipografía
-
-| Elemento | Familia | Tamaño | Peso | Line Height |
-|----------|---------|--------|------|-------------|
-| **Label Item** | SiesaBT | 14px | Regular | 20px |
-| **Button Label** | SiesaBT | 14px | Bold | 20px |
-| **Placeholder** | Inter | 14px | Regular | 20px |
-
-### Colores (Light Mode)
-
-| Elemento | Color | Hex |
-|----------|-------|-----|
-| **Background** | background-primary | #ffffff |
-| **Border** | border-primary | #e4e4e7 |
-| **Text** | content-primary | #18181b |
-| **Icon** | content-secondary | #a1a1aa |
-| **Icon Hover** | content-custom-primary | #0e79fd |
-| **Active Bg** | background-custom-primary | #dbeefe |
-
-### Colores (Dark Mode)
-
-| Elemento | Color | Hex |
-|----------|-------|-----|
-| **Background** | background-primary/dark | #09090b |
-| **Border** | border-primary/dark | #3f3f46 |
-| **Text** | content-primary/dark | #fafafa |
-| **Icon** | content-secondary/dark | #a1a1aa |
-| **Icon Hover** | content-custom-primary/dark | #bfe2fe |
-| **Active Bg** | background-custom-primary/dark | #0e5ab0 |
-
-### Sombras
-
-| Elemento | Sombra |
-|----------|--------|
-| **Search Button** | `shadow-button-inset` |
-| **Search Input** | `shadow-sm` |
-| **Items** | Ninguna |
-
----
-
-## Uso
-
-### Importación
-
-```tsx
-import { NavigationRailTypes } from '@/components/NavigationRailTypes';
-import type { NavigationRailItem } from '@/components/NavigationRailTypes';
-```
-
-### Instalación de Dependencias
-
-Este componente reutiliza:
-- `Button` - Botones en footer
-- `Input` - Input de búsqueda (input nativo mejorado)
-- `Divider` - Líneas divisoras
-- `DropdownItemCollapsible` - Items en modo expandido
-
-Asegúrate de tener estos componentes instalados.
-
----
-
-## Props
-
-### NavigationRailTypesProps
-
-```typescript
-interface NavigationRailTypesProps {
-  /**
-   * Si el rail está colapsado (iconos solo) o expandido
-   * @default true
-   */
-  collapsed?: boolean;
-
-  /**
-   * Items de navegación a mostrar
-   * @default []
-   */
-  items?: NavigationRailItem[];
-
-  /**
-   * Si mostrar el botón "Recientes" en footer
-   * @default true
-   */
-  showRecentButton?: boolean;
-
-  /**
-   * Callback cuando collapsed cambia
-   */
-  onCollapsedChange?: (collapsed: boolean) => void;
-
-  /**
-   * Callback cuando se clickea un item
-   */
-  onItemClick?: (index: number, item: NavigationRailItem) => void;
-
-  /**
-   * Classes CSS adicionales
-   */
-  className?: string;
-}
-```
-
-### NavigationRailItem
-
-```typescript
-interface NavigationRailItem {
-  /**
-   * Identificador único
-   */
-  id: string;
-
-  /**
-   * Etiqueta del item
-   */
-  label: string;
-
-  /**
-   * Icono (16x16px recomendado)
-   */
-  icon: ReactNode;
-
-  /**
-   * Si está activo
-   * @default false
-   */
-  active?: boolean;
-
-  /**
-   * Si está deshabilitado
-   * @default false
-   */
-  disabled?: boolean;
-
-  /**
-   * Callback onClick
-   */
-  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
-
-  /**
-   * URL para navegación
-   */
-  href?: string;
-
-  /**
-   * ARIA label para accesibilidad
-   */
-  ariaLabel?: string;
-
-  /**
-   * Badge de notificación (dot)
-   */
-  badge?: boolean;
-
-  /**
-   * Contador de notificaciones (99+ para >99)
-   */
-  badgeCount?: number;
-
-  /**
-   * Color del badge
-   * @default 'red'
-   */
-  badgeColor?: 'red' | 'blue' | 'green' | 'yellow' | 'orange';
-}
-```
-
----
-
-## Estados
-
-### Estado Default (No Interactuado)
-
-```
-Collapsed:
-- Icon color: content-secondary (#a1a1aa)
-- Opacity: 100%
-- Cursor: pointer
-
-Expanded:
-- Text color: content-primary (#18181b)
-- Icon color: content-secondary (#a1a1aa)
-- Background: transparent
-- Opacity: 100%
-```
-
-### Estado Hover
-
-```
-Collapsed:
-- Icon color: content-custom-primary (#0e79fd)
-- Opacity: 80%
-- Scale: 1.05
-
-Expanded:
-- Background: background-custom-primary (#dbeefe)
-- Text color: content-custom-primary (#0e79fd)
-- Icon color: content-custom-primary (#0e79fd)
-```
-
-### Estado Active
-
-```
-Collapsed:
-- Icon color: content-custom-primary (#0e79fd)
-- Background: Subtle overlay
-
-Expanded:
-- Background: background-custom-primary (#dbeefe)
-- Text color: content-custom-primary (#0e79fd)
-- Icon color: content-custom-primary (#0e79fd)
-```
-
-### Estado Disabled
-
-```
-Collapsed & Expanded:
-- Opacity: 50%
-- Cursor: not-allowed
-- Pointer events: none
-```
-
-### Estado Focus
-
-```
-Collapsed & Expanded:
-- Ring: 4px solid primary-custom-400 (#60b6fa)
-- Ring offset: 2px background-primary (#ffffff)
-- Outline: none
-```
-
----
-
-## Ejemplos
-
-### Ejemplo Básico
-
-```tsx
-import { NavigationRailTypes } from '@/components/NavigationRailTypes';
-import { HomeIcon, UsersIcon, SettingsIcon } from '@heroicons/react/outline';
-
-export function AppLayout() {
-  const [collapsed, setCollapsed] = useState(true);
-
-  const navItems = [
-    {
-      id: 'home',
-      label: 'Home',
-      icon: <HomeIcon className="size-4" />,
-      active: true,
-    },
-    {
-      id: 'users',
-      label: 'Users',
-      icon: <UsersIcon className="size-4" />,
-    },
-    {
-      id: 'settings',
-      label: 'Settings',
-      icon: <SettingsIcon className="size-4" />,
-    },
-  ];
-
-  return (
-    <div className="flex h-screen">
-      <NavigationRailTypes
-        collapsed={collapsed}
-        items={navItems}
-        onCollapsedChange={setCollapsed}
-        onItemClick={(index, item) => {
-          console.log('Navigated to:', item.id);
-        }}
-      />
-      <main className="flex-1 overflow-auto">
-        {/* Contenido principal */}
-      </main>
-    </div>
-  );
-}
-```
-
-### Con Badges de Notificación
-
-```tsx
-const navItems = [
-  {
-    id: 'messages',
-    label: 'Messages',
-    icon: <MessageIcon className="size-4" />,
-    badge: true, // Dot rojo simple
-  },
-  {
-    id: 'notifications',
-    label: 'Notifications',
-    icon: <BellIcon className="size-4" />,
-    badgeCount: 12, // Contador numérico
-    badgeColor: 'blue',
-  },
-];
-```
-
-### Con Items Deshabilitados
-
-```tsx
-const navItems = [
-  {
-    id: 'premium',
-    label: 'Premium Features',
-    icon: <StarIcon className="size-4" />,
-    disabled: true, // No clickeable
-  },
-];
-```
-
-### Con Navegación Router
-
-```tsx
-import { useNavigate } from 'react-router-dom';
-
-export function Navigation() {
-  const navigate = useNavigate();
-
-  const navItems = [
-    {
-      id: 'dashboard',
-      label: 'Dashboard',
-      icon: <DashboardIcon className="size-4" />,
-      onClick: () => navigate('/dashboard'),
-    },
-    {
-      id: 'users',
-      label: 'Manage Users',
-      icon: <UsersIcon className="size-4" />,
-      onClick: () => navigate('/users'),
-    },
-  ];
-
-  return (
-    <NavigationRailTypes
-      items={navItems}
-      onItemClick={(_, item) => item.onClick?.({} as any)}
-    />
-  );
-}
-```
-
----
-
-## Accesibilidad
-
-### Features de Accesibilidad
-
-✅ **Focus Management:**
-- Focus rings visibles (4px) en todos los items
-- Focus visible en botones collapse/expand
-- Orden tab lógico de arriba a abajo
-
-✅ **ARIA Attributes:**
-- `aria-label` en botones sin texto visible (iconOnly)
-- `role="button"` implícito en elementos clickeables
-- `disabled` attribute para items deshabilitados
-
-✅ **Navegación por Teclado:**
-- Tab/Shift+Tab para moverse entre items
-- Enter/Space para activar items
-- Escape para cerrar (si es popover)
-
-✅ **Colores y Contraste:**
-- Ratio de contraste WCAG AA/AAA
-- No depender solo del color para indicar estado
-- Iconos con fallback a text
-
-✅ **Semántica:**
-- Botones semánticos (`<button>`)
-- Labels asociados a inputs
-- Estructura lógica del DOM
-
----
-
-## Dark Mode
-
-El componente soporta dark mode automáticamente. Los colores se invierten cuando se activa:
-
-```tsx
-<div className="dark">
-  <NavigationRailTypes {...props} />
-</div>
-```
-
-### Colores en Dark Mode
-
-| Light | Dark |
-|-------|------|
-| `#ffffff` bg | `#09090b` bg |
-| `#18181b` text | `#fafafa` text |
-| `#a1a1aa` icon | `#a1a1aa` icon |
-| `#0e79fd` primary | `#bfe2fe` primary |
-| `#e4e4e7` border | `#3f3f46` border |
-
-### Utilidades CSS para Dark Mode
-
-El componente usa clases de dark mode nativas de Tailwind:
-
-```tsx
-// Ejemplos en el código
-className="dark:bg-background-primary"
-className="dark:text-content-primary"
-className="dark:border-border-primary"
-```
-
----
-
-## Referencias
-
-- **Figma Design**: [NavigationRailTypes Node 6135-36219](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-36219&m=dev)
-- **Sistema de Colores**: `docs/colors.md`
-- **Sistema de Tipografía**: `docs/typography.md`
-- **Sistema de Spacing**: `docs/spacing.md`
-- **Sistema de Sombras**: `docs/shadows.md`
-- **Componente Button**: `src/components/Button`
-- **Componente DropdownItemCollapsible**: `src/components/DropdownItemCollapsible`
-- **Componente Input**: `src/components/Input`
-- **Componente Divider**: `src/components/Divider`
-
----
-
-## Historial de Cambios
-
-### v1.0.0 (Inicial)
-
-- ✨ Componente NavigationRailTypes creado
-- ✨ Soporte para modo collapsed/expanded
-- ✨ Badges de notificación
-- ✨ Búsqueda integrada
-- ✨ Dark mode completo
-- ✨ Historias de Storybook
-- ✨ Documentación completa
-
----
-
-## Notas de Implementación
-
-### Reutilización de Componentes
-
-Este componente reutiliza:
-
-1. **Button** - Para los botones en footer
-2. **Divider** - Para separadores visuales
-3. **DropdownItemCollapsible** - Para items en modo expandido
-4. **Input** - Mejorado con input nativo para búsqueda
-
-### Consideraciones de Performance
-
-- Los items se renderizan conmigo un array `map()`
-- No hay virtualization aún (500px altura para algunos browsers)
-- Para 100+ items, considerar virtualización
-
-### Compatibilidad
-
-- React 18+
-- Tailwind CSS 3+
-- Navegadores modernos (Chrome, Firefox, Safari, Edge)
-
----
-
-## FAQ
-
-**P: ¿Puedo personalizar el ancho del rail?**
-R: Actualmente, el ancho está fijo (80px collapsed, 215px expanded). Para personalizar, modifica las clases `w-[80px]` y `w-[215px]` en el componente.
-
-**P: ¿Cómo integro con React Router?**
-R: Usa el callback `onItemClick` para navegar:
-```tsx
-onItemClick={(_, item) => navigate(`/${item.id}`)}
-```
-
-**P: ¿Puedo agregar más iconos?**
-R: Sí, pasa cualquier ReactNode como prop `icon` en los items.
-
-**P: ¿El rail es responsive para mobile?**
-R: No actualmente. Para mobile, considera un dropdown o hamburger menu.
-
-**P: ¿Puedo cambiar los colores?**
-R: Sí, todos los colores usan tokens CSS del sistema. Modifica las clases Tailwind para personalizar.
+# NavigationRailTypes
+
+Barra de navegación lateral del sistema de diseño Siesa que permite dos modos visuales distintos: **collapsed** (solo iconos) y **expanded** (con labels y búsqueda).
+
+## 📋 Tabla de Contenidos
+
+1. [Descripción](#descripción)
+2. [Características](#características)
+3. [Especificaciones de Diseño](#especificaciones-de-diseño)
+4. [Uso](#uso)
+5. [Props](#props)
+6. [Estados](#estados)
+7. [Ejemplos](#ejemplos)
+8. [Accesibilidad](#accesibilidad)
+9. [Dark Mode](#dark-mode)
+10. [Referencias](#referencias)
+
+---
+
+## Descripción
+
+El componente **NavigationRailTypes** es una barra de navegación lateral responsive que proporciona navegación vertical en aplicaciones de escritorio. Soporta dos modos de visualización que se pueden cambiar dinámicamente mediante el botón de collapse/expand.
+
+### Caso de Uso Principal
+
+- **Navegación principal en aplicaciones desktop**: Menú lateral principal
+- **Aplicaciones con múltiples módulos**: Agrupar opciones de navegación
+- **Dashboard y sistemas administrativos**: Acceso rápido a secciones
+- **Aplicaciones de desktop**: Similar a sidebars en VS Code, Figma, etc.
+
+---
+
+## Características
+
+✅ **Dos modos de visualización:**
+- **Collapsed**: 80px width, solo iconos
+- **Expanded**: 215px width, con labels y búsqueda integrada
+
+✅ **Items de navegación:**
+- Iconos personalizables (16x16px)
+- Labels descriptivos (solo en expanded)
+- Estados: default, hover, active, disabled
+- Badges de notificación (dot rojo o contador)
+
+✅ **Búsqueda integrada:**
+- Solo visible en modo expanded
+- Input con icono de búsqueda
+- Placeholder "Buscar módulo"
+
+✅ **Footer con acciones:**
+- Botón "Recientes" (clock icon)
+- Botón collapse/expand con animación
+- Divisores visuales
+
+✅ **Dark Mode:**
+- Soporte completo para light/dark
+- Colores adaptados automáticamente
+
+✅ **Accesibilidad:**
+- Focus rings adaptativos
+- ARIA labels en botones
+- Navegación por teclado
+
+✅ **Animaciones:**
+- Transición suave al collapse/expand
+- Hover effects en items
+- Rotación del chevron
+
+---
+
+## Especificaciones de Diseño
+
+### Dimensiones
+
+| Propiedad | Collapsed | Expanded |
+|-----------|-----------|----------|
+| **Width** | 80px | 215px |
+| **Height** | 900px | 900px |
+| **Item Height** | Automático | Automático |
+| **Border Radius** | N/A | 8px (items) |
+
+### Espaciado (Spacing)
+
+| Elemento | Padding | Margin | Gap |
+|----------|---------|--------|-----|
+| **Item** (collapsed) | `px-4 py-1` | N/A | `gap-3` |
+| **Item** (expanded) | `px-4 py-2` | N/A | `gap-3` |
+| **Search** (expanded) | `px-3 py-3` | N/A | `gap-2` |
+| **Footer** | `px-3` | N/A | `gap-3` |
+
+### Tipografía
+
+| Elemento | Familia | Tamaño | Peso | Line Height |
+|----------|---------|--------|------|-------------|
+| **Label Item** | SiesaBT | 14px | Regular | 20px |
+| **Button Label** | SiesaBT | 14px | Bold | 20px |
+| **Placeholder** | Inter | 14px | Regular | 20px |
+
+### Colores (Light Mode)
+
+| Elemento | Color | Hex |
+|----------|-------|-----|
+| **Background** | background-primary | #ffffff |
+| **Border** | border-primary | #e4e4e7 |
+| **Text** | content-primary | #18181b |
+| **Icon** | content-secondary | #a1a1aa |
+| **Icon Hover** | content-custom-primary | #0e79fd |
+| **Active Bg** | background-custom-primary | #dbeefe |
+
+### Colores (Dark Mode)
+
+| Elemento | Color | Hex |
+|----------|-------|-----|
+| **Background** | background-primary/dark | #09090b |
+| **Border** | border-primary/dark | #3f3f46 |
+| **Text** | content-primary/dark | #fafafa |
+| **Icon** | content-secondary/dark | #a1a1aa |
+| **Icon Hover** | content-custom-primary/dark | #bfe2fe |
+| **Active Bg** | background-custom-primary/dark | #0e5ab0 |
+
+### Sombras
+
+| Elemento | Sombra |
+|----------|--------|
+| **Search Button** | `shadow-button-inset` |
+| **Search Input** | `shadow-sm` |
+| **Items** | Ninguna |
+
+---
+
+## Uso
+
+### Importación
+
+```tsx
+import { NavigationRailTypes } from '@/components/NavigationRailTypes';
+import type { NavigationRailItem } from '@/components/NavigationRailTypes';
+```
+
+### Instalación de Dependencias
+
+Este componente reutiliza:
+- `Button` - Botones en footer
+- `Input` - Input de búsqueda (input nativo mejorado)
+- `Divider` - Líneas divisoras
+- `DropdownItemCollapsible` - Items en modo expandido
+
+Asegúrate de tener estos componentes instalados.
+
+---
+
+## Props
+
+### NavigationRailTypesProps
+
+```typescript
+interface NavigationRailTypesProps {
+  /**
+   * Si el rail está colapsado (iconos solo) o expandido
+   * @default true
+   */
+  collapsed?: boolean;
+
+  /**
+   * Items de navegación a mostrar
+   * @default []
+   */
+  items?: NavigationRailItem[];
+
+  /**
+   * Si mostrar el botón "Recientes" en footer
+   * @default true
+   */
+  showRecentButton?: boolean;
+
+  /**
+   * Callback cuando collapsed cambia
+   */
+  onCollapsedChange?: (collapsed: boolean) => void;
+
+  /**
+   * Callback cuando se clickea un item
+   */
+  onItemClick?: (index: number, item: NavigationRailItem) => void;
+
+  /**
+   * Classes CSS adicionales
+   */
+  className?: string;
+}
+```
+
+### NavigationRailItem
+
+```typescript
+interface NavigationRailItem {
+  /**
+   * Identificador único
+   */
+  id: string;
+
+  /**
+   * Etiqueta del item
+   */
+  label: string;
+
+  /**
+   * Icono (16x16px recomendado)
+   */
+  icon: ReactNode;
+
+  /**
+   * Si está activo
+   * @default false
+   */
+  active?: boolean;
+
+  /**
+   * Si está deshabilitado
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Callback onClick
+   */
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
+
+  /**
+   * URL para navegación
+   */
+  href?: string;
+
+  /**
+   * ARIA label para accesibilidad
+   */
+  ariaLabel?: string;
+
+  /**
+   * Badge de notificación (dot)
+   */
+  badge?: boolean;
+
+  /**
+   * Contador de notificaciones (99+ para >99)
+   */
+  badgeCount?: number;
+
+  /**
+   * Color del badge
+   * @default 'red'
+   */
+  badgeColor?: 'red' | 'blue' | 'green' | 'yellow' | 'orange';
+}
+```
+
+---
+
+## Estados
+
+### Estado Default (No Interactuado)
+
+```
+Collapsed:
+- Icon color: content-secondary (#a1a1aa)
+- Opacity: 100%
+- Cursor: pointer
+
+Expanded:
+- Text color: content-primary (#18181b)
+- Icon color: content-secondary (#a1a1aa)
+- Background: transparent
+- Opacity: 100%
+```
+
+### Estado Hover
+
+```
+Collapsed:
+- Icon color: content-custom-primary (#0e79fd)
+- Opacity: 80%
+- Scale: 1.05
+
+Expanded:
+- Background: background-custom-primary (#dbeefe)
+- Text color: content-custom-primary (#0e79fd)
+- Icon color: content-custom-primary (#0e79fd)
+```
+
+### Estado Active
+
+```
+Collapsed:
+- Icon color: content-custom-primary (#0e79fd)
+- Background: Subtle overlay
+
+Expanded:
+- Background: background-custom-primary (#dbeefe)
+- Text color: content-custom-primary (#0e79fd)
+- Icon color: content-custom-primary (#0e79fd)
+```
+
+### Estado Disabled
+
+```
+Collapsed & Expanded:
+- Opacity: 50%
+- Cursor: not-allowed
+- Pointer events: none
+```
+
+### Estado Focus
+
+```
+Collapsed & Expanded:
+- Ring: 4px solid primary-custom-400 (#60b6fa)
+- Ring offset: 2px background-primary (#ffffff)
+- Outline: none
+```
+
+---
+
+## Ejemplos
+
+### Ejemplo Básico
+
+```tsx
+import { NavigationRailTypes } from '@/components/NavigationRailTypes';
+import { HomeIcon, UsersIcon, SettingsIcon } from '@heroicons/react/outline';
+
+export function AppLayout() {
+  const [collapsed, setCollapsed] = useState(true);
+
+  const navItems = [
+    {
+      id: 'home',
+      label: 'Home',
+      icon: <HomeIcon className="size-4" />,
+      active: true,
+    },
+    {
+      id: 'users',
+      label: 'Users',
+      icon: <UsersIcon className="size-4" />,
+    },
+    {
+      id: 'settings',
+      label: 'Settings',
+      icon: <SettingsIcon className="size-4" />,
+    },
+  ];
+
+  return (
+    <div className="flex h-screen">
+      <NavigationRailTypes
+        collapsed={collapsed}
+        items={navItems}
+        onCollapsedChange={setCollapsed}
+        onItemClick={(index, item) => {
+          console.log('Navigated to:', item.id);
+        }}
+      />
+      <main className="flex-1 overflow-auto">
+        {/* Contenido principal */}
+      </main>
+    </div>
+  );
+}
+```
+
+### Con Badges de Notificación
+
+```tsx
+const navItems = [
+  {
+    id: 'messages',
+    label: 'Messages',
+    icon: <MessageIcon className="size-4" />,
+    badge: true, // Dot rojo simple
+  },
+  {
+    id: 'notifications',
+    label: 'Notifications',
+    icon: <BellIcon className="size-4" />,
+    badgeCount: 12, // Contador numérico
+    badgeColor: 'blue',
+  },
+];
+```
+
+### Con Items Deshabilitados
+
+```tsx
+const navItems = [
+  {
+    id: 'premium',
+    label: 'Premium Features',
+    icon: <StarIcon className="size-4" />,
+    disabled: true, // No clickeable
+  },
+];
+```
+
+### Con Navegación Router
+
+```tsx
+import { useNavigate } from 'react-router-dom';
+
+export function Navigation() {
+  const navigate = useNavigate();
+
+  const navItems = [
+    {
+      id: 'dashboard',
+      label: 'Dashboard',
+      icon: <DashboardIcon className="size-4" />,
+      onClick: () => navigate('/dashboard'),
+    },
+    {
+      id: 'users',
+      label: 'Manage Users',
+      icon: <UsersIcon className="size-4" />,
+      onClick: () => navigate('/users'),
+    },
+  ];
+
+  return (
+    <NavigationRailTypes
+      items={navItems}
+      onItemClick={(_, item) => item.onClick?.({} as any)}
+    />
+  );
+}
+```
+
+---
+
+## Accesibilidad
+
+### Features de Accesibilidad
+
+✅ **Focus Management:**
+- Focus rings visibles (4px) en todos los items
+- Focus visible en botones collapse/expand
+- Orden tab lógico de arriba a abajo
+
+✅ **ARIA Attributes:**
+- `aria-label` en botones sin texto visible (iconOnly)
+- `role="button"` implícito en elementos clickeables
+- `disabled` attribute para items deshabilitados
+
+✅ **Navegación por Teclado:**
+- Tab/Shift+Tab para moverse entre items
+- Enter/Space para activar items
+- Escape para cerrar (si es popover)
+
+✅ **Colores y Contraste:**
+- Ratio de contraste WCAG AA/AAA
+- No depender solo del color para indicar estado
+- Iconos con fallback a text
+
+✅ **Semántica:**
+- Botones semánticos (`<button>`)
+- Labels asociados a inputs
+- Estructura lógica del DOM
+
+---
+
+## Dark Mode
+
+El componente soporta dark mode automáticamente. Los colores se invierten cuando se activa:
+
+```tsx
+<div className="dark">
+  <NavigationRailTypes {...props} />
+</div>
+```
+
+### Colores en Dark Mode
+
+| Light | Dark |
+|-------|------|
+| `#ffffff` bg | `#09090b` bg |
+| `#18181b` text | `#fafafa` text |
+| `#a1a1aa` icon | `#a1a1aa` icon |
+| `#0e79fd` primary | `#bfe2fe` primary |
+| `#e4e4e7` border | `#3f3f46` border |
+
+### Utilidades CSS para Dark Mode
+
+El componente usa clases de dark mode nativas de Tailwind:
+
+```tsx
+// Ejemplos en el código
+className="dark:bg-background-primary"
+className="dark:text-content-primary"
+className="dark:border-border-primary"
+```
+
+---
+
+## Referencias
+
+- **Figma Design**: [NavigationRailTypes Node 6135-36219](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6135-36219&m=dev)
+- **Sistema de Colores**: `docs/colors.md`
+- **Sistema de Tipografía**: `docs/typography.md`
+- **Sistema de Spacing**: `docs/spacing.md`
+- **Sistema de Sombras**: `docs/shadows.md`
+- **Componente Button**: `src/components/Button`
+- **Componente DropdownItemCollapsible**: `src/components/DropdownItemCollapsible`
+- **Componente Input**: `src/components/Input`
+- **Componente Divider**: `src/components/Divider`
+
+---
+
+## Historial de Cambios
+
+### v1.0.0 (Inicial)
+
+- ✨ Componente NavigationRailTypes creado
+- ✨ Soporte para modo collapsed/expanded
+- ✨ Badges de notificación
+- ✨ Búsqueda integrada
+- ✨ Dark mode completo
+- ✨ Historias de Storybook
+- ✨ Documentación completa
+
+---
+
+## Notas de Implementación
+
+### Reutilización de Componentes
+
+Este componente reutiliza:
+
+1. **Button** - Para los botones en footer
+2. **Divider** - Para separadores visuales
+3. **DropdownItemCollapsible** - Para items en modo expandido
+4. **Input** - Mejorado con input nativo para búsqueda
+
+### Consideraciones de Performance
+
+- Los items se renderizan conmigo un array `map()`
+- No hay virtualization aún (500px altura para algunos browsers)
+- Para 100+ items, considerar virtualización
+
+### Compatibilidad
+
+- React 18+
+- Tailwind CSS 3+
+- Navegadores modernos (Chrome, Firefox, Safari, Edge)
+
+---
+
+## FAQ
+
+**P: ¿Puedo personalizar el ancho del rail?**
+R: Actualmente, el ancho está fijo (80px collapsed, 215px expanded). Para personalizar, modifica las clases `w-[80px]` y `w-[215px]` en el componente.
+
+**P: ¿Cómo integro con React Router?**
+R: Usa el callback `onItemClick` para navegar:
+```tsx
+onItemClick={(_, item) => navigate(`/${item.id}`)}
+```
+
+**P: ¿Puedo agregar más iconos?**
+R: Sí, pasa cualquier ReactNode como prop `icon` en los items.
+
+**P: ¿El rail es responsive para mobile?**
+R: No actualmente. Para mobile, considera un dropdown o hamburger menu.
+
+**P: ¿Puedo cambiar los colores?**
+R: Sí, todos los colores usan tokens CSS del sistema. Modifica las clases Tailwind para personalizar.