siesa-ui-kit 1.0.4 → 1.0.5

package/src/components/NavigationBar/README.md

@@ -1,469 +1,469 @@
-# NavigationBar
-
-Barra de navegación inferior (Bottom Navigation Bar) para aplicaciones móviles del sistema de diseño Siesa UI Kit.
-
-## 📋 Descripción
-
-El **NavigationBar** es un componente de navegación diseñado específicamente para aplicaciones móviles. Permite al usuario navegar entre 3-5 vistas principales de la aplicación mediante una barra fija en la parte inferior de la pantalla.
-
-## 🔄 Navegación Responsive
-
-**El NavigationRail se convierte en NavigationBar cuando es responsive.**
-
-Esta es una práctica recomendada de UX para optimizar el espacio en diferentes dispositivos:
-- **Desktop/Tablet (≥768px)**: Usar **NavigationRail** (navegación lateral vertical)
-- **Mobile (<768px)**: Usar **NavigationBar** (navegación inferior horizontal)
-
-El patrón responsive permite aprovechar mejor el espacio disponible: en desktop se usa el espacio lateral, mientras que en móvil se usa el espacio inferior para mantener el contenido principal en el centro de la pantalla.
-
-## 🎨 Características
-
-- ✅ Soporte para 3-5 ítems de navegación (recomendado)
-- ✅ Cada ítem incluye icono + label
-- ✅ Indicador visual de ítem activo (fondo azul claro)
-- ✅ Estados: active, hover, disabled
-- ✅ Dark mode completo
-- ✅ Accesibilidad con ARIA labels
-- ✅ TypeScript con types estrictos
-- ✅ Iconos de 16x16px según especificaciones de Figma
-- ✅ Tipografía Label XXSmall (10px Bold)
-
-## 📦 Instalación
-
-```tsx
-import { NavigationBar } from '@/components/NavigationBar';
-import type { NavigationBarItem } from '@/components/NavigationBar';
-```
-
-## 🚀 Uso Básico
-
-### Ejemplo Simple
-
-```tsx
-import { NavigationBar } from '@/components/NavigationBar';
-import { HomeIcon, SearchIcon, ProfileIcon } from '@/icons';
-
-const items = [
-  { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
-  { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-  { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
-];
-
-function App() {
-  return <NavigationBar items={items} activeItemId="home" />;
-}
-```
-
-### Ejemplo con Estado Controlado
-
-```tsx
-import { useState } from 'react';
-import { NavigationBar } from '@/components/NavigationBar';
-import { HomeIcon, SearchIcon, HeartIcon, ProfileIcon } from '@/icons';
-
-function App() {
-  const [activeTab, setActiveTab] = useState('home');
-
-  const items = [
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
-    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
-  ];
-
-  return (
-    <NavigationBar
-      items={items}
-      activeItemId={activeTab}
-      onItemClick={(id) => setActiveTab(id)}
-    />
-  );
-}
-```
-
-### Ejemplo con Ítem Deshabilitado
-
-```tsx
-const items = [
-  { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-  { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-  {
-    id: 'favorites',
-    icon: <HeartIcon />,
-    label: 'Favoritos',
-    disabled: true, // Ítem deshabilitado
-  },
-  { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
-];
-
-<NavigationBar items={items} activeItemId="home" />;
-```
-
-## 📐 Props
-
-### NavigationBarProps
-
-| Prop           | Tipo                       | Default               | Descripción                                          |
-| -------------- | -------------------------- | --------------------- | ---------------------------------------------------- |
-| `items`        | `NavigationBarItem[]`      | **Required**          | Lista de ítems del navigation bar (máximo 5)         |
-| `activeItemId` | `string`                   | `undefined`           | ID del ítem actualmente activo                       |
-| `onItemClick`  | `(id: string) => void`     | `undefined`           | Función que se ejecuta cuando se hace click en ítem  |
-| `className`    | `string`                   | `''`                  | Clases CSS adicionales para el contenedor            |
-| `ariaLabel`    | `string`                   | `'Navegación Principal'` | Etiqueta accesible para el navigation bar            |
-
-### NavigationBarItem
-
-| Prop        | Tipo                    | Default     | Descripción                              |
-| ----------- | ----------------------- | ----------- | ---------------------------------------- |
-| `id`        | `string`                | **Required** | Identificador único del ítem             |
-| `icon`      | `ReactNode`             | **Required** | Icono del ítem (componente React)        |
-| `label`     | `string`                | **Required** | Label del ítem (texto debajo del icono)  |
-| `active`    | `boolean`               | `false`     | Si el ítem está activo                   |
-| `disabled`  | `boolean`               | `false`     | Si el ítem está deshabilitado            |
-| `onClick`   | `(id: string) => void`  | `undefined` | Función onClick del ítem individual      |
-| `ariaLabel` | `string`                | `undefined` | Etiqueta accesible para el ítem          |
-
-## 🎨 Variantes
-
-### Por Cantidad de Ítems
-
-#### 3 Ítems (Mínimo Recomendado)
-
-```tsx
-<NavigationBar
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
-  ]}
-  activeItemId="home"
-/>
-```
-
-**Uso:** Aplicaciones simples con pocas secciones principales.
-
-#### 4 Ítems (Óptimo)
-
-```tsx
-<NavigationBar
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
-    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
-  ]}
-  activeItemId="home"
-/>
-```
-
-**Uso:** Balance perfecto entre funcionalidad y usabilidad.
-
-#### 5 Ítems (Máximo Recomendado)
-
-```tsx
-<NavigationBar
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
-    { id: 'notifications', icon: <BellIcon />, label: 'Alertas' },
-    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
-  ]}
-  activeItemId="home"
-/>
-```
-
-**Uso:** Máximo de ítems para mantener buena experiencia de usuario.
-
-## 🎯 Estados
-
-### Estado Normal
-
-```tsx
-<NavigationBar
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
-  ]}
-  activeItemId="home"
-/>
-```
-
-El ítem activo muestra un fondo azul claro en light mode o azul oscuro transparente en dark mode.
-
-### Estado Hover
-
-Los ítems inactivos muestran un overlay ligero al pasar el mouse sobre ellos.
-
-### Estado Disabled
-
-```tsx
-<NavigationBar
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar', disabled: true },
-    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
-  ]}
-  activeItemId="home"
-/>
-```
-
-Los ítems deshabilitados tienen opacidad reducida y no responden a clicks.
-
-## 📱 Uso Responsive
-
-El NavigationBar está diseñado específicamente para **móviles**. En desktop, debes usar **NavigationRail** (navegación lateral).
-
-### Patrón Responsive: NavigationRail → NavigationBar
-
-**Implementación recomendada para aplicaciones responsive:**
-
-```tsx
-import { NavigationBar } from '@/components/NavigationBar';
-import { NavigationRail } from '@/components/NavigationRail';
-
-function ResponsiveApp() {
-  const [activeTab, setActiveTab] = useState('home');
-
-  const navItems = [
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
-    { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
-  ];
-
-  return (
-    <div className="min-h-screen">
-      {/* NavigationRail para desktop/tablet (≥768px) */}
-      <div className="hidden md:block">
-        <NavigationRail
-          items={navItems}
-          activeItemId={activeTab}
-          onItemClick={setActiveTab}
-        />
-      </div>
-
-      {/* Contenido principal */}
-      <main className="md:ml-20 pb-20 md:pb-0">
-        {/* Tu contenido aquí */}
-      </main>
-
-      {/* NavigationBar para móvil (<768px) */}
-      <div className="md:hidden fixed bottom-0 left-0 right-0 z-50">
-        <NavigationBar
-          items={navItems}
-          activeItemId={activeTab}
-          onItemClick={setActiveTab}
-        />
-      </div>
-    </div>
-  );
-}
-```
-
-### Fijar en la Parte Inferior (Solo Móvil)
-
-```tsx
-import { NavigationBar } from '@/components/NavigationBar';
-
-function MobileApp() {
-  return (
-    <div className="min-h-screen flex flex-col">
-      {/* Contenido principal */}
-      <main className="flex-1 pb-20">{/* Tu contenido aquí */}</main>
-
-      {/* Navigation Bar fijo en bottom */}
-      <div className="fixed bottom-0 left-0 right-0 z-50">
-        <NavigationBar items={items} activeItemId={activeTab} />
-      </div>
-    </div>
-  );
-}
-```
-
-### Breakpoints Recomendados
-
-```tsx
-// Tailwind breakpoints para la conversión
-// mobile    : <768px  → NavigationBar (inferior)
-// tablet+   : ≥768px  → NavigationRail (lateral)
-
-<div className="md:hidden">      {/* Solo móvil */}
-  <NavigationBar />
-</div>
-
-<div className="hidden md:block"> {/* Tablet y desktop */}
-  <NavigationRail />
-</div>
-```
-
-## 🌓 Dark Mode
-
-El componente soporta dark mode completo automáticamente usando la estrategia `class` de Tailwind CSS.
-
-```tsx
-// El componente detecta automáticamente el modo oscuro
-<NavigationBar items={items} activeItemId="home" />
-```
-
-### Colores en Dark Mode
-
-| Elemento              | Light Mode                 | Dark Mode                           |
-| --------------------- | -------------------------- | ----------------------------------- |
-| Fondo principal       | `bg-bg-primary` (#ffffff)  | `dark:bg-dark-bg-primary` (#18181b) |
-| Icono activo (fondo)  | `bg-primary-custom-100`    | `dark:bg-primary-custom-100/20`     |
-| Icono/texto           | `text-content-primary`     | `dark:text-dark-content-primary`    |
-| Hover (inactivo)      | `hover:bg-hover-overlay`   | `dark:hover:bg-hover-overlay-dark`  |
-
-## ♿ Accesibilidad
-
-### ARIA Labels
-
-```tsx
-<NavigationBar
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio', ariaLabel: 'Ir a Inicio' },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar', ariaLabel: 'Buscar contenido' },
-    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil', ariaLabel: 'Ver mi perfil' },
-  ]}
-  ariaLabel="Navegación Principal de la Aplicación"
-  activeItemId="home"
-/>
-```
-
-### Atributos ARIA Automáticos
-
-- `role="navigation"`: Identifica el componente como navegación
-- `aria-label`: Descripción del navigation bar completo
-- `aria-current="page"`: Marca el ítem activo
-- `aria-label` en cada ítem: Descripción de la acción del ítem
-
-## 💡 Mejores Prácticas
-
-### ✅ Hacer
-
-1. **Usar entre 3-5 ítems** para mejor usabilidad
-2. **Iconos simples y reconocibles** de 16x16px
-3. **Labels cortos** (máximo 10 caracteres)
-4. **Primer ítem como "Inicio"** o vista principal
-5. **Fijar en bottom** con `position: fixed`
-6. **Considerar safe-area-inset-bottom** en dispositivos con notch
-
-```tsx
-// ✅ CORRECTO
-<NavigationBar
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
-  ]}
-  activeItemId="home"
-/>
-```
-
-### ❌ Evitar
-
-1. **NO usar más de 5 ítems**
-2. **NO usar labels largos** ("Configuración Avanzada" → "Ajustes")
-3. **NO usar en desktop** (usar sidebar o tabs)
-4. **NO cambiar orden de ítems** dinámicamente
-5. **NO omitir el indicador de ítem activo**
-
-```tsx
-// ❌ INCORRECTO - Demasiados ítems
-<NavigationBar
-  items={[
-    { id: '1', icon: <Icon1 />, label: 'Item 1' },
-    { id: '2', icon: <Icon2 />, label: 'Item 2' },
-    { id: '3', icon: <Icon3 />, label: 'Item 3' },
-    { id: '4', icon: <Icon4 />, label: 'Item 4' },
-    { id: '5', icon: <Icon5 />, label: 'Item 5' },
-    { id: '6', icon: <Icon6 />, label: 'Item 6' }, // ❌ Demasiados
-    { id: '7', icon: <Icon7 />, label: 'Item 7' }, // ❌ Demasiados
-  ]}
-/>
-```
-
-## 🎨 Especificaciones de Diseño
-
-### Tipografía
-
-- **Label**: 10px Bold (Label XXSmall según `docs/typography.md`)
-- **Line Height**: 12px
-- **Font Family**: SiesaBT Bold
-
-### Espaciado
-
-- **Padding contenedor**: 16px (`p-4`)
-- **Gap entre ítems**: 8px (`gap-2`)
-- **Gap icono-label**: 4px (`gap-1`)
-- **Padding icon-container**: 16px horizontal, 4px vertical (`px-4 py-1`)
-
-### Iconos
-
-- **Tamaño**: 16x16px (`w-4 h-4`)
-- **Formato**: SVG con `stroke="currentColor"`
-- **Estilo**: Outline (no fill)
-
-### Colores
-
-- **Fondo activo (light)**: `#dbeefe` (`bg-primary-custom-100`)
-- **Fondo activo (dark)**: `rgba(219, 238, 254, 0.2)` (`dark:bg-primary-custom-100/20`)
-- **Texto/Icono**: Token `content-primary` / `dark-content-primary`
-
-## 🔗 Ver También
-
-- [Figma - NavigationBar](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4348-22539)
-- [Documentación de Colores](../../docs/colors.md)
-- [Documentación de Tipografía](../../docs/typography.md)
-- [Documentación de Espaciado](../../docs/spacing.md)
-- [NavigationRail](../NavigationRail) - Componente similar para desktop
-
-## 📚 Ejemplos de Casos de Uso
-
-### E-commerce App
-
-```tsx
-<NavigationBar
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
-    { id: 'cart', icon: <CartIcon />, label: 'Carrito' },
-    { id: 'profile', icon: <UserIcon />, label: 'Cuenta' },
-  ]}
-/>
-```
-
-### Social Media App
-
-```tsx
-<NavigationBar
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-    { id: 'search', icon: <SearchIcon />, label: 'Explorar' },
-    { id: 'notifications', icon: <BellIcon />, label: 'Alertas' },
-    { id: 'favorites', icon: <HeartIcon />, label: 'Guardados' },
-    { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
-  ]}
-/>
-```
-
-### Banking App
-
-```tsx
-<NavigationBar
-  items={[
-    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
-    { id: 'payments', icon: <PaymentIcon />, label: 'Pagos' },
-    { id: 'cards', icon: <CardIcon />, label: 'Tarjetas' },
-    { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
-  ]}
-/>
-```
-
----
-
-**Versión**: 1.0.0
-**Última actualización**: 2025-11-20
-**Mantenido por**: Equipo Siesa UI Kit
+# NavigationBar
+
+Barra de navegación inferior (Bottom Navigation Bar) para aplicaciones móviles del sistema de diseño Siesa UI Kit.
+
+## 📋 Descripción
+
+El **NavigationBar** es un componente de navegación diseñado específicamente para aplicaciones móviles. Permite al usuario navegar entre 3-5 vistas principales de la aplicación mediante una barra fija en la parte inferior de la pantalla.
+
+## 🔄 Navegación Responsive
+
+**El NavigationRail se convierte en NavigationBar cuando es responsive.**
+
+Esta es una práctica recomendada de UX para optimizar el espacio en diferentes dispositivos:
+- **Desktop/Tablet (≥768px)**: Usar **NavigationRail** (navegación lateral vertical)
+- **Mobile (<768px)**: Usar **NavigationBar** (navegación inferior horizontal)
+
+El patrón responsive permite aprovechar mejor el espacio disponible: en desktop se usa el espacio lateral, mientras que en móvil se usa el espacio inferior para mantener el contenido principal en el centro de la pantalla.
+
+## 🎨 Características
+
+- ✅ Soporte para 3-5 ítems de navegación (recomendado)
+- ✅ Cada ítem incluye icono + label
+- ✅ Indicador visual de ítem activo (fondo azul claro)
+- ✅ Estados: active, hover, disabled
+- ✅ Dark mode completo
+- ✅ Accesibilidad con ARIA labels
+- ✅ TypeScript con types estrictos
+- ✅ Iconos de 16x16px según especificaciones de Figma
+- ✅ Tipografía Label XXSmall (10px Bold)
+
+## 📦 Instalación
+
+```tsx
+import { NavigationBar } from '@/components/NavigationBar';
+import type { NavigationBarItem } from '@/components/NavigationBar';
+```
+
+## 🚀 Uso Básico
+
+### Ejemplo Simple
+
+```tsx
+import { NavigationBar } from '@/components/NavigationBar';
+import { HomeIcon, SearchIcon, ProfileIcon } from '@/icons';
+
+const items = [
+  { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+  { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+  { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+];
+
+function App() {
+  return <NavigationBar items={items} activeItemId="home" />;
+}
+```
+
+### Ejemplo con Estado Controlado
+
+```tsx
+import { useState } from 'react';
+import { NavigationBar } from '@/components/NavigationBar';
+import { HomeIcon, SearchIcon, HeartIcon, ProfileIcon } from '@/icons';
+
+function App() {
+  const [activeTab, setActiveTab] = useState('home');
+
+  const items = [
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ];
+
+  return (
+    <NavigationBar
+      items={items}
+      activeItemId={activeTab}
+      onItemClick={(id) => setActiveTab(id)}
+    />
+  );
+}
+```
+
+### Ejemplo con Ítem Deshabilitado
+
+```tsx
+const items = [
+  { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+  { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+  {
+    id: 'favorites',
+    icon: <HeartIcon />,
+    label: 'Favoritos',
+    disabled: true, // Ítem deshabilitado
+  },
+  { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+];
+
+<NavigationBar items={items} activeItemId="home" />;
+```
+
+## 📐 Props
+
+### NavigationBarProps
+
+| Prop           | Tipo                       | Default               | Descripción                                          |
+| -------------- | -------------------------- | --------------------- | ---------------------------------------------------- |
+| `items`        | `NavigationBarItem[]`      | **Required**          | Lista de ítems del navigation bar (máximo 5)         |
+| `activeItemId` | `string`                   | `undefined`           | ID del ítem actualmente activo                       |
+| `onItemClick`  | `(id: string) => void`     | `undefined`           | Función que se ejecuta cuando se hace click en ítem  |
+| `className`    | `string`                   | `''`                  | Clases CSS adicionales para el contenedor            |
+| `ariaLabel`    | `string`                   | `'Navegación Principal'` | Etiqueta accesible para el navigation bar            |
+
+### NavigationBarItem
+
+| Prop        | Tipo                    | Default     | Descripción                              |
+| ----------- | ----------------------- | ----------- | ---------------------------------------- |
+| `id`        | `string`                | **Required** | Identificador único del ítem             |
+| `icon`      | `ReactNode`             | **Required** | Icono del ítem (componente React)        |
+| `label`     | `string`                | **Required** | Label del ítem (texto debajo del icono)  |
+| `active`    | `boolean`               | `false`     | Si el ítem está activo                   |
+| `disabled`  | `boolean`               | `false`     | Si el ítem está deshabilitado            |
+| `onClick`   | `(id: string) => void`  | `undefined` | Función onClick del ítem individual      |
+| `ariaLabel` | `string`                | `undefined` | Etiqueta accesible para el ítem          |
+
+## 🎨 Variantes
+
+### Por Cantidad de Ítems
+
+#### 3 Ítems (Mínimo Recomendado)
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+**Uso:** Aplicaciones simples con pocas secciones principales.
+
+#### 4 Ítems (Óptimo)
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+**Uso:** Balance perfecto entre funcionalidad y usabilidad.
+
+#### 5 Ítems (Máximo Recomendado)
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+    { id: 'notifications', icon: <BellIcon />, label: 'Alertas' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+**Uso:** Máximo de ítems para mantener buena experiencia de usuario.
+
+## 🎯 Estados
+
+### Estado Normal
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+El ítem activo muestra un fondo azul claro en light mode o azul oscuro transparente en dark mode.
+
+### Estado Hover
+
+Los ítems inactivos muestran un overlay ligero al pasar el mouse sobre ellos.
+
+### Estado Disabled
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio', active: true },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar', disabled: true },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+Los ítems deshabilitados tienen opacidad reducida y no responden a clicks.
+
+## 📱 Uso Responsive
+
+El NavigationBar está diseñado específicamente para **móviles**. En desktop, debes usar **NavigationRail** (navegación lateral).
+
+### Patrón Responsive: NavigationRail → NavigationBar
+
+**Implementación recomendada para aplicaciones responsive:**
+
+```tsx
+import { NavigationBar } from '@/components/NavigationBar';
+import { NavigationRail } from '@/components/NavigationRail';
+
+function ResponsiveApp() {
+  const [activeTab, setActiveTab] = useState('home');
+
+  const navItems = [
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'favorites', icon: <HeartIcon />, label: 'Favoritos' },
+    { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+  ];
+
+  return (
+    <div className="min-h-screen">
+      {/* NavigationRail para desktop/tablet (≥768px) */}
+      <div className="hidden md:block">
+        <NavigationRail
+          items={navItems}
+          activeItemId={activeTab}
+          onItemClick={setActiveTab}
+        />
+      </div>
+
+      {/* Contenido principal */}
+      <main className="md:ml-20 pb-20 md:pb-0">
+        {/* Tu contenido aquí */}
+      </main>
+
+      {/* NavigationBar para móvil (<768px) */}
+      <div className="md:hidden fixed bottom-0 left-0 right-0 z-50">
+        <NavigationBar
+          items={navItems}
+          activeItemId={activeTab}
+          onItemClick={setActiveTab}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+### Fijar en la Parte Inferior (Solo Móvil)
+
+```tsx
+import { NavigationBar } from '@/components/NavigationBar';
+
+function MobileApp() {
+  return (
+    <div className="min-h-screen flex flex-col">
+      {/* Contenido principal */}
+      <main className="flex-1 pb-20">{/* Tu contenido aquí */}</main>
+
+      {/* Navigation Bar fijo en bottom */}
+      <div className="fixed bottom-0 left-0 right-0 z-50">
+        <NavigationBar items={items} activeItemId={activeTab} />
+      </div>
+    </div>
+  );
+}
+```
+
+### Breakpoints Recomendados
+
+```tsx
+// Tailwind breakpoints para la conversión
+// mobile    : <768px  → NavigationBar (inferior)
+// tablet+   : ≥768px  → NavigationRail (lateral)
+
+<div className="md:hidden">      {/* Solo móvil */}
+  <NavigationBar />
+</div>
+
+<div className="hidden md:block"> {/* Tablet y desktop */}
+  <NavigationRail />
+</div>
+```
+
+## 🌓 Dark Mode
+
+El componente soporta dark mode completo automáticamente usando la estrategia `class` de Tailwind CSS.
+
+```tsx
+// El componente detecta automáticamente el modo oscuro
+<NavigationBar items={items} activeItemId="home" />
+```
+
+### Colores en Dark Mode
+
+| Elemento              | Light Mode                 | Dark Mode                           |
+| --------------------- | -------------------------- | ----------------------------------- |
+| Fondo principal       | `bg-bg-primary` (#ffffff)  | `dark:bg-dark-bg-primary` (#18181b) |
+| Icono activo (fondo)  | `bg-primary-custom-100`    | `dark:bg-primary-custom-100/20`     |
+| Icono/texto           | `text-content-primary`     | `dark:text-dark-content-primary`    |
+| Hover (inactivo)      | `hover:bg-hover-overlay`   | `dark:hover:bg-hover-overlay-dark`  |
+
+## ♿ Accesibilidad
+
+### ARIA Labels
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio', ariaLabel: 'Ir a Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar', ariaLabel: 'Buscar contenido' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil', ariaLabel: 'Ver mi perfil' },
+  ]}
+  ariaLabel="Navegación Principal de la Aplicación"
+  activeItemId="home"
+/>
+```
+
+### Atributos ARIA Automáticos
+
+- `role="navigation"`: Identifica el componente como navegación
+- `aria-label`: Descripción del navigation bar completo
+- `aria-current="page"`: Marca el ítem activo
+- `aria-label` en cada ítem: Descripción de la acción del ítem
+
+## 💡 Mejores Prácticas
+
+### ✅ Hacer
+
+1. **Usar entre 3-5 ítems** para mejor usabilidad
+2. **Iconos simples y reconocibles** de 16x16px
+3. **Labels cortos** (máximo 10 caracteres)
+4. **Primer ítem como "Inicio"** o vista principal
+5. **Fijar en bottom** con `position: fixed`
+6. **Considerar safe-area-inset-bottom** en dispositivos con notch
+
+```tsx
+// ✅ CORRECTO
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'profile', icon: <ProfileIcon />, label: 'Perfil' },
+  ]}
+  activeItemId="home"
+/>
+```
+
+### ❌ Evitar
+
+1. **NO usar más de 5 ítems**
+2. **NO usar labels largos** ("Configuración Avanzada" → "Ajustes")
+3. **NO usar en desktop** (usar sidebar o tabs)
+4. **NO cambiar orden de ítems** dinámicamente
+5. **NO omitir el indicador de ítem activo**
+
+```tsx
+// ❌ INCORRECTO - Demasiados ítems
+<NavigationBar
+  items={[
+    { id: '1', icon: <Icon1 />, label: 'Item 1' },
+    { id: '2', icon: <Icon2 />, label: 'Item 2' },
+    { id: '3', icon: <Icon3 />, label: 'Item 3' },
+    { id: '4', icon: <Icon4 />, label: 'Item 4' },
+    { id: '5', icon: <Icon5 />, label: 'Item 5' },
+    { id: '6', icon: <Icon6 />, label: 'Item 6' }, // ❌ Demasiados
+    { id: '7', icon: <Icon7 />, label: 'Item 7' }, // ❌ Demasiados
+  ]}
+/>
+```
+
+## 🎨 Especificaciones de Diseño
+
+### Tipografía
+
+- **Label**: 10px Bold (Label XXSmall según `docs/typography.md`)
+- **Line Height**: 12px
+- **Font Family**: SiesaBT Bold
+
+### Espaciado
+
+- **Padding contenedor**: 16px (`p-4`)
+- **Gap entre ítems**: 8px (`gap-2`)
+- **Gap icono-label**: 4px (`gap-1`)
+- **Padding icon-container**: 16px horizontal, 4px vertical (`px-4 py-1`)
+
+### Iconos
+
+- **Tamaño**: 16x16px (`w-4 h-4`)
+- **Formato**: SVG con `stroke="currentColor"`
+- **Estilo**: Outline (no fill)
+
+### Colores
+
+- **Fondo activo (light)**: `#dbeefe` (`bg-primary-custom-100`)
+- **Fondo activo (dark)**: `rgba(219, 238, 254, 0.2)` (`dark:bg-primary-custom-100/20`)
+- **Texto/Icono**: Token `content-primary` / `dark-content-primary`
+
+## 🔗 Ver También
+
+- [Figma - NavigationBar](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4348-22539)
+- [Documentación de Colores](../../docs/colors.md)
+- [Documentación de Tipografía](../../docs/typography.md)
+- [Documentación de Espaciado](../../docs/spacing.md)
+- [NavigationRail](../NavigationRail) - Componente similar para desktop
+
+## 📚 Ejemplos de Casos de Uso
+
+### E-commerce App
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Buscar' },
+    { id: 'cart', icon: <CartIcon />, label: 'Carrito' },
+    { id: 'profile', icon: <UserIcon />, label: 'Cuenta' },
+  ]}
+/>
+```
+
+### Social Media App
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'search', icon: <SearchIcon />, label: 'Explorar' },
+    { id: 'notifications', icon: <BellIcon />, label: 'Alertas' },
+    { id: 'favorites', icon: <HeartIcon />, label: 'Guardados' },
+    { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+  ]}
+/>
+```
+
+### Banking App
+
+```tsx
+<NavigationBar
+  items={[
+    { id: 'home', icon: <HomeIcon />, label: 'Inicio' },
+    { id: 'payments', icon: <PaymentIcon />, label: 'Pagos' },
+    { id: 'cards', icon: <CardIcon />, label: 'Tarjetas' },
+    { id: 'profile', icon: <UserIcon />, label: 'Perfil' },
+  ]}
+/>
+```
+
+---
+
+**Versión**: 1.0.0
+**Última actualización**: 2025-11-20
+**Mantenido por**: Equipo Siesa UI Kit