siesa-ui-kit 1.0.2 → 1.0.4

package/src/components/NavigationRailPanel/README.md

@@ -1,461 +1,461 @@
-# NavigationRailPanel
-
-Panel de navegación vertical (rail) que puede contener múltiples secciones de items, búsqueda y encabezados. Se usa típicamente en aplicaciones con navegación compleja que requieren una estructura jerárquica.
-
-## 📋 Tabla de Contenidos
-
-1. [Descripción](#descripción)
-2. [Características](#características)
-3. [Props](#props)
-4. [Estructura](#estructura)
-5. [Ejemplos de Uso](#ejemplos-de-uso)
-6. [Especificaciones de Figma](#especificaciones-de-figma)
-7. [Colores y Dark Mode](#colores-y-dark-mode)
-8. [Espaciado](#espaciado)
-9. [Accesibilidad](#accesibilidad)
-10. [Referencias](#referencias)
-
----
-
-## Descripción
-
-El componente `NavigationRailPanel` es un contenedor de navegación vertical que organiza elementos en una estructura jerárquica. Está diseñado para uso en aplicaciones complejas que requieren navegación por categorías, búsqueda de items y menús expandibles.
-
-### Casos de Uso
-
-- Aplicaciones con muchas opciones de navegación
-- Paneles de administración con menús colapsables
-- Sistemas de gestión con categorización
-- Aplicaciones POS con categorías de productos
-- Navegación de módulos en aplicaciones empresariales
-
----
-
-## Características
-
-✅ **Estructura Flexible**
-- Soporte para secciones con encabezados
-- Items simples y colapsables
-- Items anidados con indentación automática
-
-✅ **Búsqueda Integrada**
-- Input de búsqueda con placeholder personalizable
-- Callbacks de cambio de valor
-- Controlable desde el padre
-
-✅ **Encabezado Personalizable**
-- DropdownItemHeading reutilizado
-- Icono, label, descripción y acción
-- Callback para acción
-
-✅ **Dark Mode Completo**
-- Todos los elementos inversos en dark mode
-- Colores adaptativos
-- Accesibilidad mantenida
-
-✅ **Estados Visuales**
-- Hover, focus, active, disabled
-- Transiciones suaves
-- Focus rings adaptativos
-
-✅ **Scroll**
-- El body es scrolleable
-- Encabezado y búsqueda fijos
-- Comportamiento nativo del navegador
-
-✅ **Componentes Reutilizados**
-- `DropdownItemHeading` - Para el encabezado
-- `DropdownItemCollapsible` - Para items colapsables
-- `Input` - Para la búsqueda
-- `Divider` - Para separadores
-
----
-
-## Props
-
-### NavigationRailPanelProps
-
-```typescript
-interface NavigationRailPanelProps {
-  // Dimensiones
-  height?: number | string;           // Por defecto: 900
-  width?: number | string;            // Por defecto: 248
-
-  // Encabezado
-  showHeading?: boolean;              // Por defecto: true
-  heading?: {
-    label: string;
-    description?: string;
-    showDescription?: boolean;
-    iconName?: string;
-    actionLabel?: string;
-    showAction?: boolean;
-    onActionClick?: () => void;
-  };
-
-  // Búsqueda
-  showSearch?: boolean;               // Por defecto: true
-  search?: {
-    placeholder?: string;             // Por defecto: "Buscar módulo"
-    value?: string;
-    onChange?: (value: string) => void;
-    showLabel?: boolean;              // Por defecto: false
-    showLink?: boolean;               // Por defecto: true
-  };
-
-  // Contenido
-  sections?: NavigationRailPanelSectionProps[];
-  items?: NavigationRailPanelItemProps[];
-
-  // Clases CSS
-  className?: string;
-  panelClassName?: string;
-}
-```
-
-### NavigationRailPanelSectionProps
-
-```typescript
-interface NavigationRailPanelSectionProps {
-  heading?: string;                   // Encabezado de la sección
-  items: NavigationRailPanelItemProps[];
-  showDivider?: boolean;              // Por defecto: true
-  className?: string;
-}
-```
-
-### NavigationRailPanelItemProps
-
-```typescript
-interface NavigationRailPanelItemProps {
-  label: string;                      // Texto del item
-  icon?: ReactNode;                   // Icono opcional
-  isCollapsible?: boolean;            // Por defecto: false
-  children?: DropdownItemCollapsibleChildProps[];
-  defaultOpen?: boolean;              // Por defecto: false
-  disabled?: boolean;                 // Por defecto: false
-  onClick?: (e: React.MouseEvent) => void;
-  onOpenChange?: (open: boolean) => void;
-  className?: string;
-}
-```
-
----
-
-## Estructura
-
-### Layout Principal
-
-```
-┌─────────────────────────┐
-│   Encabezado (Opcional) │  <- DropdownItemHeading
-├─────────────────────────┤
-│   Búsqueda (Opcional)   │  <- Input
-├─────────────────────────┤
-│   Body (Scrolleable)    │
-│ ┌─────────────────────┐ │
-│ │  Section Heading    │ │
-│ │  Item 1 (Simple)    │ │
-│ │  Item 2 (Collapsible)│
-│ │  ├─ Sub Item 1      │ │
-│ │  └─ Sub Item 2      │ │
-│ │  ---                │ │
-│ │  Section Heading    │ │
-│ │  Item 3             │ │
-│ │  Item 4             │ │
-│ └─────────────────────┘ │
-└─────────────────────────┘
-```
-
-### Especificaciones
-
-| Elemento | Ancho | Altura | Padding | Border Radius |
-|----------|-------|--------|---------|---------------|
-| Panel | 248px | Variable | 12px | 0px |
-| Encabezado | 224px | Auto | 8v, 16h | 8px |
-| Búsqueda | 224px | 40px | 8v, 16h | 6px |
-| Item | 224px | 32px | 8v, 16p | 8px |
-| Section Heading | 224px | Auto | 12t, 4b | 0px |
-
----
-
-## Ejemplos de Uso
-
-### Ejemplo Simple con Secciones
-
-```tsx
-import { NavigationRailPanel } from '@/components/NavigationRailPanel';
-
-export function Dashboard() {
-  return (
-    <NavigationRailPanel
-      height={900}
-      showHeading={true}
-      heading={{
-        label: 'Settings',
-        description: 'Configure your preferences',
-        iconName: 'cog-6-tooth',
-      }}
-      showSearch={true}
-      sections={[
-        {
-          heading: 'NAVIGATION',
-          items: [
-            { label: 'Dashboard', isCollapsible: false },
-            { label: 'Analytics', isCollapsible: false },
-          ],
-        },
-        {
-          heading: 'MANAGEMENT',
-          items: [
-            {
-              label: 'Users',
-              isCollapsible: true,
-              children: [
-                { label: 'Active Users' },
-                { label: 'Inactive Users' },
-              ],
-            },
-          ],
-        },
-      ]}
-    />
-  );
-}
-```
-
-### Ejemplo sin Encabezado y Búsqueda
-
-```tsx
-<NavigationRailPanel
-  showHeading={false}
-  showSearch={false}
-  items={[
-    { label: 'Dashboard' },
-    { label: 'Users' },
-    { label: 'Settings' },
-  ]}
-/>
-```
-
-### Ejemplo con Callbacks
-
-```tsx
-<NavigationRailPanel
-  heading={{
-    label: 'Menu',
-    actionLabel: 'Clear',
-    showAction: true,
-    onActionClick: () => console.log('Clear clicked'),
-  }}
-  search={{
-    placeholder: 'Search...',
-    onChange: (value) => console.log('Search:', value),
-  }}
-  items={[
-    {
-      label: 'Item 1',
-      onClick: () => console.log('Item 1 clicked'),
-    },
-    {
-      label: 'Category',
-      isCollapsible: true,
-      onOpenChange: (open) => console.log('Toggled:', open),
-      children: [
-        { label: 'Sub Item' },
-      ],
-    },
-  ]}
-/>
-```
-
-### Ejemplo con Items Deshabilitados
-
-```tsx
-<NavigationRailPanel
-  items={[
-    { label: 'Active', disabled: false },
-    { label: 'Disabled', disabled: true },
-    {
-      label: 'Category',
-      isCollapsible: true,
-      disabled: true,
-      children: [
-        { label: 'Sub Item 1' },
-        { label: 'Sub Item 2', disabled: true },
-      ],
-    },
-  ]}
-/>
-```
-
----
-
-## Especificaciones de Figma
-
-- **Nodo**: 6134-34415
-- **URL**: https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6134-34415
-
-### Dimensiones
-
-- Altura: 900px (variable)
-- Ancho: 248px (estándar)
-- Padding: 12px (todo)
-- Border radius: 0px (panel completo)
-
-### Tipografía
-
-| Elemento | Escala | Font Weight | Size | Line Height |
-|----------|--------|------------|------|------------|
-| Encabezado | Label/Small | 700 (Bold) | 14px | 20px |
-| Descripción | Paragraph/Tiny | 400 | 12px | 16px |
-| Section Heading | Paragraph/Tiny | 400 | 12px | 16px |
-| Item | Paragraph/Small | 400 | 14px | 20px |
-| Acción | Paragraph/XXSmall | 400 | 10px | 12px |
-
----
-
-## Colores y Dark Mode
-
-### Light Mode
-
-| Elemento | Color | Hex |
-|----------|-------|-----|
-| Background | bg-primary | #ffffff |
-| Border | border-primary | #e4e4e7 |
-| Heading text | content-primary | #18181b |
-| Section heading | content-tertiary | #71717a |
-| Item text | content-primary | #18181b |
-| Icon | content-secondary | #a1a1aa |
-| Hover bg | background-custom-primary | #dbeefe |
-
-### Dark Mode
-
-| Elemento | Color | Hex |
-|----------|-------|-----|
-| Background | dark:bg-zinc-900 | #18181b |
-| Border | dark:border-zinc-800 | #3f3f46 |
-| Heading text | dark:content-primary-dark | #fafafa |
-| Section heading | dark:content-tertiary-dark | #a1a1aa |
-| Item text | dark:content-primary-dark | #fafafa |
-| Icon | dark:content-secondary | #a1a1aa |
-| Hover bg | dark:bg-background-custom-primary-dark | #0e5ab0 |
-
-### Tokens Utilizados
-
-- **Colores**: `content-primary`, `content-secondary`, `content-tertiary`, `bg-primary`, `border-primary`, `background-custom-primary`
-- **Dark Mode**: Se invierten automáticamente con prefijo `dark:`
-- **No hay colores hardcodeados**: Todo usa el sistema de tokens
-
----
-
-## Espaciado
-
-| Elemento | Valor | Px |
-|----------|-------|-----|
-| Panel padding | 3 | 12px |
-| Item padding (h) | 4 | 16px |
-| Item padding (v) | 2 | 8px |
-| Gap entre items | 0.5 | 2px |
-| Gap entre elemento e icono | 3 | 12px |
-| Section heading pt | 3 | 12px |
-| Section heading pb | 1 | 4px |
-| Divider margin top | 3 | 12px |
-
----
-
-## Accesibilidad
-
-✅ **Focus Management**
-- Focus rings adaptativos de 4px
-- Offset de 2px en light mode
-- Offset transparente en dark mode
-- Color focus: primary-custom-400 (#60b6fa)
-
-✅ **Keyboard Navigation**
-- Tab para navegar entre items
-- Enter/Space para activar
-- Arrow keys para items colapsables (heredado de DropdownItemCollapsible)
-
-✅ **ARIA**
-- Roles semánticos (button, heading, menuitem)
-- aria-disabled para items deshabilitados
-- aria-expanded para items colapsables
-
-✅ **Colores**
-- Contraste AA/AAA mantenido
-- No depender solo de color para indicar estado
-- Íconos con suficiente contraste
-
----
-
-## Dark Mode
-
-El componente es **100% compatible con dark mode**:
-
-```tsx
-// El componente detecta automáticamente el tema
-<NavigationRailPanel
-  // Automáticamente invierte colores en dark mode
-  showHeading={true}
-  showSearch={true}
-/>
-```
-
-### Cambios en Dark Mode
-
-1. **Background**: white (#ffffff) → zinc-900 (#18181b)
-2. **Border**: border-primary (#e4e4e7) → border-zinc-800 (#3f3f46)
-3. **Text**: content-primary (#18181b) → content-primary-dark (#fafafa)
-4. **Icon hover**: dbeefe (#dbeefe) → 0e5ab0 (#0e5ab0)
-5. **Focus ring offset**: blanco → zinc-900
-
----
-
-## Estados Visuales
-
-### Default
-- Sin interacción
-- Colores base
-
-### Hover
-- Background sutil: `background-custom-primary`
-- Cursor pointer
-- Transición suave
-
-### Focus
-- Focus ring de 4px
-- Color: `primary-custom-400`
-- Offset: 2px (light) / transparent (dark)
-
-### Active
-- Item colapsable expandido
-- Indicado por chevron rotado
-
-### Disabled
-- Opacidad: 50%
-- Cursor: not-allowed
-- Sin hover/focus interactivo
-
----
-
-## Referencias
-
-### Documentación del Sistema
-
-- [@see docs/colors.md](../../../docs/colors.md) - Sistema de colores
-- [@see docs/typography.md](../../../docs/typography.md) - Sistema tipográfico
-- [@see docs/spacing.md](../../../docs/spacing.md) - Sistema de espaciado
-- [@see docs/shadows.md](../../../docs/shadows.md) - Sistema de sombras
-
-### Componentes Relacionados
-
-- [@see ../DropdownItemHeading](../DropdownItemHeading) - Encabezado reutilizado
-- [@see ../DropdownItemCollapsible](../DropdownItemCollapsible) - Items colapsables
-- [@see ../Input](../Input) - Búsqueda
-- [@see ../Divider](../Divider) - Separadores
-
-### Figma
-
-- [NavigationRailPanel en Figma](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6134-34415)
-- [Design System Documentation](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit)
+# NavigationRailPanel
+
+Panel de navegación vertical (rail) que puede contener múltiples secciones de items, búsqueda y encabezados. Se usa típicamente en aplicaciones con navegación compleja que requieren una estructura jerárquica.
+
+## 📋 Tabla de Contenidos
+
+1. [Descripción](#descripción)
+2. [Características](#características)
+3. [Props](#props)
+4. [Estructura](#estructura)
+5. [Ejemplos de Uso](#ejemplos-de-uso)
+6. [Especificaciones de Figma](#especificaciones-de-figma)
+7. [Colores y Dark Mode](#colores-y-dark-mode)
+8. [Espaciado](#espaciado)
+9. [Accesibilidad](#accesibilidad)
+10. [Referencias](#referencias)
+
+---
+
+## Descripción
+
+El componente `NavigationRailPanel` es un contenedor de navegación vertical que organiza elementos en una estructura jerárquica. Está diseñado para uso en aplicaciones complejas que requieren navegación por categorías, búsqueda de items y menús expandibles.
+
+### Casos de Uso
+
+- Aplicaciones con muchas opciones de navegación
+- Paneles de administración con menús colapsables
+- Sistemas de gestión con categorización
+- Aplicaciones POS con categorías de productos
+- Navegación de módulos en aplicaciones empresariales
+
+---
+
+## Características
+
+✅ **Estructura Flexible**
+- Soporte para secciones con encabezados
+- Items simples y colapsables
+- Items anidados con indentación automática
+
+✅ **Búsqueda Integrada**
+- Input de búsqueda con placeholder personalizable
+- Callbacks de cambio de valor
+- Controlable desde el padre
+
+✅ **Encabezado Personalizable**
+- DropdownItemHeading reutilizado
+- Icono, label, descripción y acción
+- Callback para acción
+
+✅ **Dark Mode Completo**
+- Todos los elementos inversos en dark mode
+- Colores adaptativos
+- Accesibilidad mantenida
+
+✅ **Estados Visuales**
+- Hover, focus, active, disabled
+- Transiciones suaves
+- Focus rings adaptativos
+
+✅ **Scroll**
+- El body es scrolleable
+- Encabezado y búsqueda fijos
+- Comportamiento nativo del navegador
+
+✅ **Componentes Reutilizados**
+- `DropdownItemHeading` - Para el encabezado
+- `DropdownItemCollapsible` - Para items colapsables
+- `Input` - Para la búsqueda
+- `Divider` - Para separadores
+
+---
+
+## Props
+
+### NavigationRailPanelProps
+
+```typescript
+interface NavigationRailPanelProps {
+  // Dimensiones
+  height?: number | string;           // Por defecto: 900
+  width?: number | string;            // Por defecto: 248
+
+  // Encabezado
+  showHeading?: boolean;              // Por defecto: true
+  heading?: {
+    label: string;
+    description?: string;
+    showDescription?: boolean;
+    iconName?: string;
+    actionLabel?: string;
+    showAction?: boolean;
+    onActionClick?: () => void;
+  };
+
+  // Búsqueda
+  showSearch?: boolean;               // Por defecto: true
+  search?: {
+    placeholder?: string;             // Por defecto: "Buscar módulo"
+    value?: string;
+    onChange?: (value: string) => void;
+    showLabel?: boolean;              // Por defecto: false
+    showLink?: boolean;               // Por defecto: true
+  };
+
+  // Contenido
+  sections?: NavigationRailPanelSectionProps[];
+  items?: NavigationRailPanelItemProps[];
+
+  // Clases CSS
+  className?: string;
+  panelClassName?: string;
+}
+```
+
+### NavigationRailPanelSectionProps
+
+```typescript
+interface NavigationRailPanelSectionProps {
+  heading?: string;                   // Encabezado de la sección
+  items: NavigationRailPanelItemProps[];
+  showDivider?: boolean;              // Por defecto: true
+  className?: string;
+}
+```
+
+### NavigationRailPanelItemProps
+
+```typescript
+interface NavigationRailPanelItemProps {
+  label: string;                      // Texto del item
+  icon?: ReactNode;                   // Icono opcional
+  isCollapsible?: boolean;            // Por defecto: false
+  children?: DropdownItemCollapsibleChildProps[];
+  defaultOpen?: boolean;              // Por defecto: false
+  disabled?: boolean;                 // Por defecto: false
+  onClick?: (e: React.MouseEvent) => void;
+  onOpenChange?: (open: boolean) => void;
+  className?: string;
+}
+```
+
+---
+
+## Estructura
+
+### Layout Principal
+
+```
+┌─────────────────────────┐
+│   Encabezado (Opcional) │  <- DropdownItemHeading
+├─────────────────────────┤
+│   Búsqueda (Opcional)   │  <- Input
+├─────────────────────────┤
+│   Body (Scrolleable)    │
+│ ┌─────────────────────┐ │
+│ │  Section Heading    │ │
+│ │  Item 1 (Simple)    │ │
+│ │  Item 2 (Collapsible)│
+│ │  ├─ Sub Item 1      │ │
+│ │  └─ Sub Item 2      │ │
+│ │  ---                │ │
+│ │  Section Heading    │ │
+│ │  Item 3             │ │
+│ │  Item 4             │ │
+│ └─────────────────────┘ │
+└─────────────────────────┘
+```
+
+### Especificaciones
+
+| Elemento | Ancho | Altura | Padding | Border Radius |
+|----------|-------|--------|---------|---------------|
+| Panel | 248px | Variable | 12px | 0px |
+| Encabezado | 224px | Auto | 8v, 16h | 8px |
+| Búsqueda | 224px | 40px | 8v, 16h | 6px |
+| Item | 224px | 32px | 8v, 16p | 8px |
+| Section Heading | 224px | Auto | 12t, 4b | 0px |
+
+---
+
+## Ejemplos de Uso
+
+### Ejemplo Simple con Secciones
+
+```tsx
+import { NavigationRailPanel } from '@/components/NavigationRailPanel';
+
+export function Dashboard() {
+  return (
+    <NavigationRailPanel
+      height={900}
+      showHeading={true}
+      heading={{
+        label: 'Settings',
+        description: 'Configure your preferences',
+        iconName: 'cog-6-tooth',
+      }}
+      showSearch={true}
+      sections={[
+        {
+          heading: 'NAVIGATION',
+          items: [
+            { label: 'Dashboard', isCollapsible: false },
+            { label: 'Analytics', isCollapsible: false },
+          ],
+        },
+        {
+          heading: 'MANAGEMENT',
+          items: [
+            {
+              label: 'Users',
+              isCollapsible: true,
+              children: [
+                { label: 'Active Users' },
+                { label: 'Inactive Users' },
+              ],
+            },
+          ],
+        },
+      ]}
+    />
+  );
+}
+```
+
+### Ejemplo sin Encabezado y Búsqueda
+
+```tsx
+<NavigationRailPanel
+  showHeading={false}
+  showSearch={false}
+  items={[
+    { label: 'Dashboard' },
+    { label: 'Users' },
+    { label: 'Settings' },
+  ]}
+/>
+```
+
+### Ejemplo con Callbacks
+
+```tsx
+<NavigationRailPanel
+  heading={{
+    label: 'Menu',
+    actionLabel: 'Clear',
+    showAction: true,
+    onActionClick: () => console.log('Clear clicked'),
+  }}
+  search={{
+    placeholder: 'Search...',
+    onChange: (value) => console.log('Search:', value),
+  }}
+  items={[
+    {
+      label: 'Item 1',
+      onClick: () => console.log('Item 1 clicked'),
+    },
+    {
+      label: 'Category',
+      isCollapsible: true,
+      onOpenChange: (open) => console.log('Toggled:', open),
+      children: [
+        { label: 'Sub Item' },
+      ],
+    },
+  ]}
+/>
+```
+
+### Ejemplo con Items Deshabilitados
+
+```tsx
+<NavigationRailPanel
+  items={[
+    { label: 'Active', disabled: false },
+    { label: 'Disabled', disabled: true },
+    {
+      label: 'Category',
+      isCollapsible: true,
+      disabled: true,
+      children: [
+        { label: 'Sub Item 1' },
+        { label: 'Sub Item 2', disabled: true },
+      ],
+    },
+  ]}
+/>
+```
+
+---
+
+## Especificaciones de Figma
+
+- **Nodo**: 6134-34415
+- **URL**: https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6134-34415
+
+### Dimensiones
+
+- Altura: 900px (variable)
+- Ancho: 248px (estándar)
+- Padding: 12px (todo)
+- Border radius: 0px (panel completo)
+
+### Tipografía
+
+| Elemento | Escala | Font Weight | Size | Line Height |
+|----------|--------|------------|------|------------|
+| Encabezado | Label/Small | 700 (Bold) | 14px | 20px |
+| Descripción | Paragraph/Tiny | 400 | 12px | 16px |
+| Section Heading | Paragraph/Tiny | 400 | 12px | 16px |
+| Item | Paragraph/Small | 400 | 14px | 20px |
+| Acción | Paragraph/XXSmall | 400 | 10px | 12px |
+
+---
+
+## Colores y Dark Mode
+
+### Light Mode
+
+| Elemento | Color | Hex |
+|----------|-------|-----|
+| Background | bg-primary | #ffffff |
+| Border | border-primary | #e4e4e7 |
+| Heading text | content-primary | #18181b |
+| Section heading | content-tertiary | #71717a |
+| Item text | content-primary | #18181b |
+| Icon | content-secondary | #a1a1aa |
+| Hover bg | background-custom-primary | #dbeefe |
+
+### Dark Mode
+
+| Elemento | Color | Hex |
+|----------|-------|-----|
+| Background | dark:bg-zinc-900 | #18181b |
+| Border | dark:border-zinc-800 | #3f3f46 |
+| Heading text | dark:content-primary-dark | #fafafa |
+| Section heading | dark:content-tertiary-dark | #a1a1aa |
+| Item text | dark:content-primary-dark | #fafafa |
+| Icon | dark:content-secondary | #a1a1aa |
+| Hover bg | dark:bg-background-custom-primary-dark | #0e5ab0 |
+
+### Tokens Utilizados
+
+- **Colores**: `content-primary`, `content-secondary`, `content-tertiary`, `bg-primary`, `border-primary`, `background-custom-primary`
+- **Dark Mode**: Se invierten automáticamente con prefijo `dark:`
+- **No hay colores hardcodeados**: Todo usa el sistema de tokens
+
+---
+
+## Espaciado
+
+| Elemento | Valor | Px |
+|----------|-------|-----|
+| Panel padding | 3 | 12px |
+| Item padding (h) | 4 | 16px |
+| Item padding (v) | 2 | 8px |
+| Gap entre items | 0.5 | 2px |
+| Gap entre elemento e icono | 3 | 12px |
+| Section heading pt | 3 | 12px |
+| Section heading pb | 1 | 4px |
+| Divider margin top | 3 | 12px |
+
+---
+
+## Accesibilidad
+
+✅ **Focus Management**
+- Focus rings adaptativos de 4px
+- Offset de 2px en light mode
+- Offset transparente en dark mode
+- Color focus: primary-custom-400 (#60b6fa)
+
+✅ **Keyboard Navigation**
+- Tab para navegar entre items
+- Enter/Space para activar
+- Arrow keys para items colapsables (heredado de DropdownItemCollapsible)
+
+✅ **ARIA**
+- Roles semánticos (button, heading, menuitem)
+- aria-disabled para items deshabilitados
+- aria-expanded para items colapsables
+
+✅ **Colores**
+- Contraste AA/AAA mantenido
+- No depender solo de color para indicar estado
+- Íconos con suficiente contraste
+
+---
+
+## Dark Mode
+
+El componente es **100% compatible con dark mode**:
+
+```tsx
+// El componente detecta automáticamente el tema
+<NavigationRailPanel
+  // Automáticamente invierte colores en dark mode
+  showHeading={true}
+  showSearch={true}
+/>
+```
+
+### Cambios en Dark Mode
+
+1. **Background**: white (#ffffff) → zinc-900 (#18181b)
+2. **Border**: border-primary (#e4e4e7) → border-zinc-800 (#3f3f46)
+3. **Text**: content-primary (#18181b) → content-primary-dark (#fafafa)
+4. **Icon hover**: dbeefe (#dbeefe) → 0e5ab0 (#0e5ab0)
+5. **Focus ring offset**: blanco → zinc-900
+
+---
+
+## Estados Visuales
+
+### Default
+- Sin interacción
+- Colores base
+
+### Hover
+- Background sutil: `background-custom-primary`
+- Cursor pointer
+- Transición suave
+
+### Focus
+- Focus ring de 4px
+- Color: `primary-custom-400`
+- Offset: 2px (light) / transparent (dark)
+
+### Active
+- Item colapsable expandido
+- Indicado por chevron rotado
+
+### Disabled
+- Opacidad: 50%
+- Cursor: not-allowed
+- Sin hover/focus interactivo
+
+---
+
+## Referencias
+
+### Documentación del Sistema
+
+- [@see docs/colors.md](../../../docs/colors.md) - Sistema de colores
+- [@see docs/typography.md](../../../docs/typography.md) - Sistema tipográfico
+- [@see docs/spacing.md](../../../docs/spacing.md) - Sistema de espaciado
+- [@see docs/shadows.md](../../../docs/shadows.md) - Sistema de sombras
+
+### Componentes Relacionados
+
+- [@see ../DropdownItemHeading](../DropdownItemHeading) - Encabezado reutilizado
+- [@see ../DropdownItemCollapsible](../DropdownItemCollapsible) - Items colapsables
+- [@see ../Input](../Input) - Búsqueda
+- [@see ../Divider](../Divider) - Separadores
+
+### Figma
+
+- [NavigationRailPanel en Figma](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=6134-34415)
+- [Design System Documentation](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit)