siesa-ui-kit 1.0.2 → 1.0.4

package/src/components/NavigationRailItem/README.md

@@ -1,476 +1,476 @@
-# NavigationRailItem
-
-Componente individual de item para la barra de navegación vertical (NavigationRail) del sistema de diseño Siesa UI Kit.
-
-## 📋 Descripción
-
-`NavigationRailItem` es un componente independiente que representa un item seleccionable dentro de una `NavigationRail`. Proporciona acceso rápido a destinos principales mediante un icono, label opcional y badges de notificación.
-
-**Implementación pixel-perfect** según Figma (node 4294-22931) con soporte completo para todos los estados, dark mode y accesibilidad.
-
-## 🎯 Características
-
-- ✅ **Ancho fijo de 56px** según especificaciones de Figma
-- ✅ **Estados completos**: Enabled, Hover, Selected, Focus, Disabled
-- ✅ **Badges de notificación**: Dot simple o contador numérico (99+ para >99)
-- ✅ **Tipografía del sistema**: Label XXSmall (10px Bold, leading 12px)
-- ✅ **Dark Mode completo**: Colores invertidos en todos los estados
-- ✅ **Focus rings adaptativos**: Accesibilidad y keyboard navigation
-- ✅ **Iconos flexibles**: Soporta cualquier librería (Heroicons, React Icons, etc.)
-- ✅ **ARIA completo**: aria-label, aria-current, aria-disabled
-- ✅ **Tokens del sistema**: NO colores hardcodeados
-
-## 📐 Especificaciones de Figma
-
-### Dimensiones
-- **Ancho**: 56px (w-14)
-- **Altura**: Auto (flex-col)
-- **Icon container**: 32px altura, 16px padding horizontal
-- **Gap icon-label**: 4px (gap-1)
-- **Border radius icon**: 9999px (rounded-full)
-
-### Estados Visuales
-
-| Estado | Background | Icon Color | Label Color | Cursor |
-|--------|-----------|-----------|-----------|--------|
-| **Enabled** | Transparent | content-primary | content-primary | pointer |
-| **Hover** | primary-custom-100 | primary-custom-600 | content-primary | pointer |
-| **Selected** | primary-custom-100 | primary-custom-600 | content-primary | pointer |
-| **Focus** | primary-custom-100 + ring | primary-custom-600 | content-primary | pointer |
-| **Disabled** | Transparent (opacity 55%) | content-tertiary | content-tertiary | not-allowed |
-
-### Badge
-
-- **Tamaño**: 13x13px
-- **Border radius**: rounded-full (9999px)
-- **Posición**: Absoluta (-top-0.5, left-[34px])
-- **Color**: Red 700 (#b91c1c)
-- **Tipografía**: 10px Bold
-- **Tipos**:
-  - **Dot**: Badge simple sin número
-  - **Contador**: Número 1-99+
-
-### Focus Ring (Accesibilidad)
-
-Según Figma node 4294-22931, el focus ring tiene estas características:
-
-```css
-ring: 2px (#60b6fa)
-offset: 2px (#dbeefe)
-shadow: 0px_0px_0px_2px_#dbeefe, 0px_1px_2px_0px_rgba(0,0,0,0.05), 0px_0px_0px_4px_#60b6fa
-```
-
-## 🎨 Dark Mode
-
-El componente invierte automáticamente sus colores en dark mode:
-
-- **Background**: bg-primary-custom-600/30
-- **Icon**: text-white (selected), dark-content-primary (default)
-- **Label**: dark-content-primary
-- **Focus ring**: dark-border-custom
-
-Usa la estrategia `class` de Tailwind CSS:
-
-```tsx
-<div className="dark">
-  <NavigationRailItem label="Inicio" selected={true} />
-</div>
-```
-
-## 💻 Uso
-
-### Instalación
-
-```bash
-npm install siesa-ui-kit
-```
-
-### Ejemplo Básico
-
-```tsx
-import { NavigationRailItem } from 'siesa-ui-kit/components/NavigationRailItem';
-import { HomeIcon } from '@heroicons/react/24/outline';
-
-export function App() {
-  return (
-    <NavigationRailItem
-      id="home"
-      icon={<HomeIcon />}
-      label="Inicio"
-      selected={true}
-      onClick={() => navigate('/')}
-    />
-  );
-}
-```
-
-### Con Badge
-
-```tsx
-import { BellIcon } from '@heroicons/react/24/outline';
-
-<NavigationRailItem
-  id="notifications"
-  icon={<BellIcon />}
-  label="Notificaciones"
-  badgeCount={5}
-/>
-```
-
-### Deshabilitado
-
-```tsx
-import { StarIcon } from '@heroicons/react/24/outline';
-
-<NavigationRailItem
-  id="premium"
-  icon={<StarIcon />}
-  label="Premium"
-  disabled={true}
-/>
-```
-
-### Solo Icono
-
-```tsx
-<NavigationRailItem
-  id="home"
-  icon={<HomeIcon />}
-  label="Inicio"
-  showLabelText={false}
-/>
-```
-
-### En un NavigationRail
-
-```tsx
-import { NavigationRail } from 'siesa-ui-kit/components/NavigationRail';
-import { NavigationRailItem } from 'siesa-ui-kit/components/NavigationRailItem';
-
-export function Navbar() {
-  const [selected, setSelected] = 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 },
-  ];
-
-  return (
-    <nav className="flex gap-3">
-      {items.map((item) => (
-        <NavigationRailItem
-          key={item.id}
-          id={item.id}
-          icon={item.icon}
-          label={item.label}
-          badgeCount={item.badgeCount}
-          selected={selected === item.id}
-          onClick={() => setSelected(item.id)}
-        />
-      ))}
-    </nav>
-  );
-}
-```
-
-## 📖 Props
-
-### `icon` (Required)
-
-```typescript
-icon: ReactNode
-```
-
-Icono a mostrar. Tamaño recomendado: 16x16px.
-
-**Ejemplos:**
-- Heroicons: `<HomeIcon />`
-- React Icons: `<FiHome />`
-- SVG inline: `<svg>...</svg>`
-
-### `label` (Required)
-
-```typescript
-label: string
-```
-
-Texto del label que aparece debajo del icono. Se muestra en tipografía Label XXSmall (10px Bold).
-
-### `selected`
-
-```typescript
-selected?: boolean
-// default: false
-```
-
-Si el item está seleccionado actualmente. Cambia el background a primary-custom-100 y el icono a primary-custom-600.
-
-### `disabled`
-
-```typescript
-disabled?: boolean
-// default: false
-```
-
-Si el item está deshabilitado. Reduce la opacidad a 55%, cambia el cursor a not-allowed y desactiva la interactividad.
-
-### `badge`
-
-```typescript
-badge?: boolean
-// default: false
-```
-
-Mostrar badge de notificación simple (dot rojo). Se ignora si `badgeCount` está definido.
-
-### `badgeCount`
-
-```typescript
-badgeCount?: number
-```
-
-Número a mostrar en el badge. Reemplaza el dot simple. Si es mayor a 99, muestra "99+".
-
-### `onClick`
-
-```typescript
-onClick?: () => void
-```
-
-Callback cuando se hace click en el item.
-
-**Nota:** Se ejecuta incluso si el item está disabled (pero el botón no es clickeable).
-
-### `ariaLabel`
-
-```typescript
-ariaLabel?: string
-```
-
-Label para accesibilidad (ARIA). Si no se proporciona, usa el valor de `label`.
-
-**Ejemplo:**
-```tsx
-<NavigationRailItem
-  label="Inicio"
-  ariaLabel="Ir a la página de inicio del sitio web"
-/>
-```
-
-### `id`
-
-```typescript
-id?: string
-```
-
-ID único del item. Se usa para identificarlo en navegación y se añade como atributo `data-item-id`.
-
-**Ejemplo:**
-```tsx
-<NavigationRailItem id="home" label="Inicio" />
-// Genera: <button data-item-id="home">...</button>
-```
-
-### `showLabelText`
-
-```typescript
-showLabelText?: boolean
-// default: true
-```
-
-Si el label debe ser visible. Útil para crear variaciones icon-only.
-
-### `showIcon`
-
-```typescript
-showIcon?: boolean
-// default: true
-```
-
-Si el icono debe ser visible. Útil para crear variaciones label-only.
-
-### `className`
-
-```typescript
-className?: string
-// default: ''
-```
-
-Clases CSS adicionales personalizadas.
-
-## 🎨 Diseño del Sistema
-
-### Colores (según `docs/colors.md`)
-
-| Token | Valor | Uso |
-|-------|-------|-----|
-| `primary-custom-600` | #0e79fd | Color principal del icono en estados selected/hover |
-| `primary-custom-100` | #dbeefe | Background del icon container en hover/selected |
-| `content-primary` | - | Color del texto y iconos por defecto |
-| `content-tertiary` | - | Color del texto deshabilitado |
-| `red-700` | #b91c1c | Color del badge |
-
-### Tipografía (según `docs/typography.md`)
-
-| Elemento | Estilo | Valores |
-|----------|--------|--------|
-| Label | Label XXSmall | 10px Bold, leading 12px |
-| Badge | Label Tiny | 10px Bold |
-
-### Espaciado (según `docs/spacing.md`)
-
-| Elemento | Espaciado |
-|----------|-----------|
-| Icon container padding | px-4 py-1 (16px h, 4px v) |
-| Gap icon-label | gap-1 (4px) |
-| Contenedor padding | px-0.5 (2px) |
-
-### Sombras (según `docs/shadows.md`)
-
-| Estado | Sombra |
-|--------|--------|
-| Focus | shadow-[0px_0px_0px_2px_rgba(219,238,254,1),0px_1px_2px_0px_rgba(0,0,0,0.05),0px_0px_0px_4px_rgba(96,182,250,1)] |
-
-## ♿ Accesibilidad
-
-El componente cumple con estándares WCAG:
-
-- ✅ **ARIA Labels**: `aria-label` personalizable
-- ✅ **ARIA State**: `aria-current="page"` cuando está selected
-- ✅ **Disabled State**: `aria-disabled` y `disabled` attributes
-- ✅ **Keyboard Navigation**: Focus ring adaptativo (2px)
-- ✅ **Color Contrast**: Ratios WCAG AA/AAA en light y dark mode
-- ✅ **Touch Targets**: Mínimo 44x44px (56x56px real)
-
-### Keyboard Navigation
-
-```html
-<!-- Tab para navegar -->
-<!-- Enter/Space para activar -->
-<!-- Navega entre items del NavigationRail -->
-```
-
-## 🔄 Relación con Otros Componentes
-
-### NavigationRail
-
-`NavigationRailItem` está diseñado para usarse dentro de `NavigationRail`, aunque puede usarse de forma independiente.
-
-```tsx
-import { NavigationRail } from 'siesa-ui-kit/components/NavigationRail';
-
-<NavigationRail
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio', selected: true },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-  ]}
-/>
-```
-
-### Button
-
-Comparte la misma estructura de estados y tokens que el componente `Button`:
-
-- Estados similares (default, hover, selected, focus, disabled)
-- Tipografía del sistema (aunque tamaños diferentes)
-- Focus rings adaptativos
-- Dark mode completo
-
-## 🧪 Testing
-
-### Data Attributes
-
-Para facilitar testing:
-
-```html
-<button data-item-id="home" data-testid="navigation-rail-item-home" data-badge>
-  ...
-</button>
-```
-
-### Ejemplos de Tests
-
-```typescript
-// Vitest / Jest
-import { render, screen } from '@testing-library/react';
-import { NavigationRailItem } from './NavigationRailItem';
-import { HomeIcon } from '@heroicons/react/24/outline';
-
-describe('NavigationRailItem', () => {
-  it('renders with label', () => {
-    render(<NavigationRailItem icon={<HomeIcon />} label="Inicio" id="home" />);
-    expect(screen.getByText('Inicio')).toBeInTheDocument();
-  });
-
-  it('shows badge count', () => {
-    render(
-      <NavigationRailItem
-        icon={<HomeIcon />}
-        label="Inicio"
-        id="home"
-        badgeCount={5}
-      />
-    );
-    expect(screen.getByText('5')).toBeInTheDocument();
-  });
-
-  it('disables when disabled prop is true', () => {
-    render(
-      <NavigationRailItem
-        icon={<HomeIcon />}
-        label="Inicio"
-        id="home"
-        disabled={true}
-      />
-    );
-    expect(screen.getByRole('button')).toBeDisabled();
-  });
-
-  it('calls onClick when clicked', () => {
-    const handleClick = vi.fn();
-    render(
-      <NavigationRailItem
-        icon={<HomeIcon />}
-        label="Inicio"
-        id="home"
-        onClick={handleClick}
-      />
-    );
-    screen.getByRole('button').click();
-    expect(handleClick).toHaveBeenCalled();
-  });
-});
-```
-
-## 📚 Referencias
-
-- **Figma**: [node 4294-22931](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22931)
-- **Docs de colores**: [docs/colors.md](../../docs/colors.md)
-- **Docs de tipografía**: [docs/typography.md](../../docs/typography.md)
-- **Docs de espaciado**: [docs/spacing.md](../../docs/spacing.md)
-- **Docs de sombras**: [docs/shadows.md](../../docs/shadows.md)
-- **Componente NavigationRail**: [NavigationRail](../NavigationRail/README.md)
-- **Componente Button**: [Button](../Button/README.md) (referencia de estructura)
-
-## 📝 Changelog
-
-### v1.0.0 (Inicial)
-
-- ✨ Componente NavigationRailItem creado
-- ✨ Todos los estados implementados (Enabled, Hover, Selected, Focus, Disabled)
-- ✨ Badges de notificación (dot y contador)
-- ✨ Dark Mode completo
-- ✨ Accesibilidad WCAG completa
-- ✨ Stories completas en Storybook
-- ✨ TypeScript types
-- ✨ JSDoc completo
-- ✨ README documentado
-
-## 📄 Licencia
-
-Parte del Sistema de Diseño Siesa UI Kit. © 2024 Siesa.
-
----
-
-**Última actualización**: 24 de diciembre de 2024
+# NavigationRailItem
+
+Componente individual de item para la barra de navegación vertical (NavigationRail) del sistema de diseño Siesa UI Kit.
+
+## 📋 Descripción
+
+`NavigationRailItem` es un componente independiente que representa un item seleccionable dentro de una `NavigationRail`. Proporciona acceso rápido a destinos principales mediante un icono, label opcional y badges de notificación.
+
+**Implementación pixel-perfect** según Figma (node 4294-22931) con soporte completo para todos los estados, dark mode y accesibilidad.
+
+## 🎯 Características
+
+- ✅ **Ancho fijo de 56px** según especificaciones de Figma
+- ✅ **Estados completos**: Enabled, Hover, Selected, Focus, Disabled
+- ✅ **Badges de notificación**: Dot simple o contador numérico (99+ para >99)
+- ✅ **Tipografía del sistema**: Label XXSmall (10px Bold, leading 12px)
+- ✅ **Dark Mode completo**: Colores invertidos en todos los estados
+- ✅ **Focus rings adaptativos**: Accesibilidad y keyboard navigation
+- ✅ **Iconos flexibles**: Soporta cualquier librería (Heroicons, React Icons, etc.)
+- ✅ **ARIA completo**: aria-label, aria-current, aria-disabled
+- ✅ **Tokens del sistema**: NO colores hardcodeados
+
+## 📐 Especificaciones de Figma
+
+### Dimensiones
+- **Ancho**: 56px (w-14)
+- **Altura**: Auto (flex-col)
+- **Icon container**: 32px altura, 16px padding horizontal
+- **Gap icon-label**: 4px (gap-1)
+- **Border radius icon**: 9999px (rounded-full)
+
+### Estados Visuales
+
+| Estado | Background | Icon Color | Label Color | Cursor |
+|--------|-----------|-----------|-----------|--------|
+| **Enabled** | Transparent | content-primary | content-primary | pointer |
+| **Hover** | primary-custom-100 | primary-custom-600 | content-primary | pointer |
+| **Selected** | primary-custom-100 | primary-custom-600 | content-primary | pointer |
+| **Focus** | primary-custom-100 + ring | primary-custom-600 | content-primary | pointer |
+| **Disabled** | Transparent (opacity 55%) | content-tertiary | content-tertiary | not-allowed |
+
+### Badge
+
+- **Tamaño**: 13x13px
+- **Border radius**: rounded-full (9999px)
+- **Posición**: Absoluta (-top-0.5, left-[34px])
+- **Color**: Red 700 (#b91c1c)
+- **Tipografía**: 10px Bold
+- **Tipos**:
+  - **Dot**: Badge simple sin número
+  - **Contador**: Número 1-99+
+
+### Focus Ring (Accesibilidad)
+
+Según Figma node 4294-22931, el focus ring tiene estas características:
+
+```css
+ring: 2px (#60b6fa)
+offset: 2px (#dbeefe)
+shadow: 0px_0px_0px_2px_#dbeefe, 0px_1px_2px_0px_rgba(0,0,0,0.05), 0px_0px_0px_4px_#60b6fa
+```
+
+## 🎨 Dark Mode
+
+El componente invierte automáticamente sus colores en dark mode:
+
+- **Background**: bg-primary-custom-600/30
+- **Icon**: text-white (selected), dark-content-primary (default)
+- **Label**: dark-content-primary
+- **Focus ring**: dark-border-custom
+
+Usa la estrategia `class` de Tailwind CSS:
+
+```tsx
+<div className="dark">
+  <NavigationRailItem label="Inicio" selected={true} />
+</div>
+```
+
+## 💻 Uso
+
+### Instalación
+
+```bash
+npm install siesa-ui-kit
+```
+
+### Ejemplo Básico
+
+```tsx
+import { NavigationRailItem } from 'siesa-ui-kit/components/NavigationRailItem';
+import { HomeIcon } from '@heroicons/react/24/outline';
+
+export function App() {
+  return (
+    <NavigationRailItem
+      id="home"
+      icon={<HomeIcon />}
+      label="Inicio"
+      selected={true}
+      onClick={() => navigate('/')}
+    />
+  );
+}
+```
+
+### Con Badge
+
+```tsx
+import { BellIcon } from '@heroicons/react/24/outline';
+
+<NavigationRailItem
+  id="notifications"
+  icon={<BellIcon />}
+  label="Notificaciones"
+  badgeCount={5}
+/>
+```
+
+### Deshabilitado
+
+```tsx
+import { StarIcon } from '@heroicons/react/24/outline';
+
+<NavigationRailItem
+  id="premium"
+  icon={<StarIcon />}
+  label="Premium"
+  disabled={true}
+/>
+```
+
+### Solo Icono
+
+```tsx
+<NavigationRailItem
+  id="home"
+  icon={<HomeIcon />}
+  label="Inicio"
+  showLabelText={false}
+/>
+```
+
+### En un NavigationRail
+
+```tsx
+import { NavigationRail } from 'siesa-ui-kit/components/NavigationRail';
+import { NavigationRailItem } from 'siesa-ui-kit/components/NavigationRailItem';
+
+export function Navbar() {
+  const [selected, setSelected] = 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 },
+  ];
+
+  return (
+    <nav className="flex gap-3">
+      {items.map((item) => (
+        <NavigationRailItem
+          key={item.id}
+          id={item.id}
+          icon={item.icon}
+          label={item.label}
+          badgeCount={item.badgeCount}
+          selected={selected === item.id}
+          onClick={() => setSelected(item.id)}
+        />
+      ))}
+    </nav>
+  );
+}
+```
+
+## 📖 Props
+
+### `icon` (Required)
+
+```typescript
+icon: ReactNode
+```
+
+Icono a mostrar. Tamaño recomendado: 16x16px.
+
+**Ejemplos:**
+- Heroicons: `<HomeIcon />`
+- React Icons: `<FiHome />`
+- SVG inline: `<svg>...</svg>`
+
+### `label` (Required)
+
+```typescript
+label: string
+```
+
+Texto del label que aparece debajo del icono. Se muestra en tipografía Label XXSmall (10px Bold).
+
+### `selected`
+
+```typescript
+selected?: boolean
+// default: false
+```
+
+Si el item está seleccionado actualmente. Cambia el background a primary-custom-100 y el icono a primary-custom-600.
+
+### `disabled`
+
+```typescript
+disabled?: boolean
+// default: false
+```
+
+Si el item está deshabilitado. Reduce la opacidad a 55%, cambia el cursor a not-allowed y desactiva la interactividad.
+
+### `badge`
+
+```typescript
+badge?: boolean
+// default: false
+```
+
+Mostrar badge de notificación simple (dot rojo). Se ignora si `badgeCount` está definido.
+
+### `badgeCount`
+
+```typescript
+badgeCount?: number
+```
+
+Número a mostrar en el badge. Reemplaza el dot simple. Si es mayor a 99, muestra "99+".
+
+### `onClick`
+
+```typescript
+onClick?: () => void
+```
+
+Callback cuando se hace click en el item.
+
+**Nota:** Se ejecuta incluso si el item está disabled (pero el botón no es clickeable).
+
+### `ariaLabel`
+
+```typescript
+ariaLabel?: string
+```
+
+Label para accesibilidad (ARIA). Si no se proporciona, usa el valor de `label`.
+
+**Ejemplo:**
+```tsx
+<NavigationRailItem
+  label="Inicio"
+  ariaLabel="Ir a la página de inicio del sitio web"
+/>
+```
+
+### `id`
+
+```typescript
+id?: string
+```
+
+ID único del item. Se usa para identificarlo en navegación y se añade como atributo `data-item-id`.
+
+**Ejemplo:**
+```tsx
+<NavigationRailItem id="home" label="Inicio" />
+// Genera: <button data-item-id="home">...</button>
+```
+
+### `showLabelText`
+
+```typescript
+showLabelText?: boolean
+// default: true
+```
+
+Si el label debe ser visible. Útil para crear variaciones icon-only.
+
+### `showIcon`
+
+```typescript
+showIcon?: boolean
+// default: true
+```
+
+Si el icono debe ser visible. Útil para crear variaciones label-only.
+
+### `className`
+
+```typescript
+className?: string
+// default: ''
+```
+
+Clases CSS adicionales personalizadas.
+
+## 🎨 Diseño del Sistema
+
+### Colores (según `docs/colors.md`)
+
+| Token | Valor | Uso |
+|-------|-------|-----|
+| `primary-custom-600` | #0e79fd | Color principal del icono en estados selected/hover |
+| `primary-custom-100` | #dbeefe | Background del icon container en hover/selected |
+| `content-primary` | - | Color del texto y iconos por defecto |
+| `content-tertiary` | - | Color del texto deshabilitado |
+| `red-700` | #b91c1c | Color del badge |
+
+### Tipografía (según `docs/typography.md`)
+
+| Elemento | Estilo | Valores |
+|----------|--------|--------|
+| Label | Label XXSmall | 10px Bold, leading 12px |
+| Badge | Label Tiny | 10px Bold |
+
+### Espaciado (según `docs/spacing.md`)
+
+| Elemento | Espaciado |
+|----------|-----------|
+| Icon container padding | px-4 py-1 (16px h, 4px v) |
+| Gap icon-label | gap-1 (4px) |
+| Contenedor padding | px-0.5 (2px) |
+
+### Sombras (según `docs/shadows.md`)
+
+| Estado | Sombra |
+|--------|--------|
+| Focus | shadow-[0px_0px_0px_2px_rgba(219,238,254,1),0px_1px_2px_0px_rgba(0,0,0,0.05),0px_0px_0px_4px_rgba(96,182,250,1)] |
+
+## ♿ Accesibilidad
+
+El componente cumple con estándares WCAG:
+
+- ✅ **ARIA Labels**: `aria-label` personalizable
+- ✅ **ARIA State**: `aria-current="page"` cuando está selected
+- ✅ **Disabled State**: `aria-disabled` y `disabled` attributes
+- ✅ **Keyboard Navigation**: Focus ring adaptativo (2px)
+- ✅ **Color Contrast**: Ratios WCAG AA/AAA en light y dark mode
+- ✅ **Touch Targets**: Mínimo 44x44px (56x56px real)
+
+### Keyboard Navigation
+
+```html
+<!-- Tab para navegar -->
+<!-- Enter/Space para activar -->
+<!-- Navega entre items del NavigationRail -->
+```
+
+## 🔄 Relación con Otros Componentes
+
+### NavigationRail
+
+`NavigationRailItem` está diseñado para usarse dentro de `NavigationRail`, aunque puede usarse de forma independiente.
+
+```tsx
+import { NavigationRail } from 'siesa-ui-kit/components/NavigationRail';
+
+<NavigationRail
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio', selected: true },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+  ]}
+/>
+```
+
+### Button
+
+Comparte la misma estructura de estados y tokens que el componente `Button`:
+
+- Estados similares (default, hover, selected, focus, disabled)
+- Tipografía del sistema (aunque tamaños diferentes)
+- Focus rings adaptativos
+- Dark mode completo
+
+## 🧪 Testing
+
+### Data Attributes
+
+Para facilitar testing:
+
+```html
+<button data-item-id="home" data-testid="navigation-rail-item-home" data-badge>
+  ...
+</button>
+```
+
+### Ejemplos de Tests
+
+```typescript
+// Vitest / Jest
+import { render, screen } from '@testing-library/react';
+import { NavigationRailItem } from './NavigationRailItem';
+import { HomeIcon } from '@heroicons/react/24/outline';
+
+describe('NavigationRailItem', () => {
+  it('renders with label', () => {
+    render(<NavigationRailItem icon={<HomeIcon />} label="Inicio" id="home" />);
+    expect(screen.getByText('Inicio')).toBeInTheDocument();
+  });
+
+  it('shows badge count', () => {
+    render(
+      <NavigationRailItem
+        icon={<HomeIcon />}
+        label="Inicio"
+        id="home"
+        badgeCount={5}
+      />
+    );
+    expect(screen.getByText('5')).toBeInTheDocument();
+  });
+
+  it('disables when disabled prop is true', () => {
+    render(
+      <NavigationRailItem
+        icon={<HomeIcon />}
+        label="Inicio"
+        id="home"
+        disabled={true}
+      />
+    );
+    expect(screen.getByRole('button')).toBeDisabled();
+  });
+
+  it('calls onClick when clicked', () => {
+    const handleClick = vi.fn();
+    render(
+      <NavigationRailItem
+        icon={<HomeIcon />}
+        label="Inicio"
+        id="home"
+        onClick={handleClick}
+      />
+    );
+    screen.getByRole('button').click();
+    expect(handleClick).toHaveBeenCalled();
+  });
+});
+```
+
+## 📚 Referencias
+
+- **Figma**: [node 4294-22931](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4294-22931)
+- **Docs de colores**: [docs/colors.md](../../docs/colors.md)
+- **Docs de tipografía**: [docs/typography.md](../../docs/typography.md)
+- **Docs de espaciado**: [docs/spacing.md](../../docs/spacing.md)
+- **Docs de sombras**: [docs/shadows.md](../../docs/shadows.md)
+- **Componente NavigationRail**: [NavigationRail](../NavigationRail/README.md)
+- **Componente Button**: [Button](../Button/README.md) (referencia de estructura)
+
+## 📝 Changelog
+
+### v1.0.0 (Inicial)
+
+- ✨ Componente NavigationRailItem creado
+- ✨ Todos los estados implementados (Enabled, Hover, Selected, Focus, Disabled)
+- ✨ Badges de notificación (dot y contador)
+- ✨ Dark Mode completo
+- ✨ Accesibilidad WCAG completa
+- ✨ Stories completas en Storybook
+- ✨ TypeScript types
+- ✨ JSDoc completo
+- ✨ README documentado
+
+## 📄 Licencia
+
+Parte del Sistema de Diseño Siesa UI Kit. © 2024 Siesa.
+
+---
+
+**Última actualización**: 24 de diciembre de 2024