siesa-ui-kit 1.0.4 → 1.0.5

package/docs/icons.md

@@ -1,1264 +1,1283 @@
-# Sistema de Iconos - Siesa UI Kit
-
-## 📋 Tabla de Contenidos
-
-1. [Introducción](#introducción)
-2. [Librería de Iconos](#librería-de-iconos)
-3. [Catálogo de Iconos](#catálogo-de-iconos)
-4. [Implementación](#implementación)
-5. [Guía de Uso](#guía-de-uso)
-6. [Accesibilidad](#accesibilidad)
-7. [Ejemplos de Código](#ejemplos-de-código)
-8. [Mejores Prácticas](#mejores-prácticas)
-9. [Referencia Rápida](#referencia-rápida)
-
----
-
-## Introducción
-
-El sistema de iconos de Siesa UI Kit está basado en **Heroicons Micro**, una librería de iconos SVG de 16x16px diseñada específicamente para interfaces de usuario modernas. Los iconos están optimizados para claridad a tamaños pequeños y se integran perfectamente con nuestro sistema de diseño.
-
-### Objetivos del Sistema de Iconos
-
-- **Consistencia Visual**: Todos los iconos mantienen el mismo peso visual y estilo
-- **Escalabilidad**: Iconos vectoriales que se adaptan a cualquier tamaño
-- **Accesibilidad**: Soporte para lectores de pantalla y temas oscuros
-- **Rendimiento**: SVG inline para carga rápida sin requests adicionales
-- **Flexibilidad**: Fácil personalización de tamaño, color y estilos
-
-### Principios de Diseño
-
-1. **Simplicidad**: Formas claras y reconocibles
-2. **Peso Consistente**: Todos los iconos tienen el mismo grosor de línea
-3. **Alineación Pixel-Perfect**: Optimizados para 16x16px
-4. **Color Heredado**: Usan `currentColor` para adaptarse al contexto
-
----
-
-## Librería de Iconos
-
-### Heroicons Micro
-
-**Especificaciones Técnicas:**
-- **Tamaño Base**: 16x16px (viewBox="0 0 16 16")
-- **Formato**: SVG inline
-- **Estilo**: Solid (relleno completo)
-- **Grosor**: 1.5px stroke weight equivalent
-- **Licencia**: MIT License
-
-**Ventajas:**
-- ✅ Diseñados específicamente para UI de 16px
-- ✅ Optimizados para claridad a tamaños pequeños
-- ✅ Mantenidos por el equipo de Tailwind CSS
-- ✅ Biblioteca completa y consistente
-- ✅ Excelente legibilidad en pantallas de alta densidad
-
----
-
-## Catálogo de Iconos
-
-### Iconos de Botón (Button)
-
-Iconos disponibles en `src/components/Button/icons.tsx`
-
-| Icono | Nombre | Uso Principal | Ubicación |
-|-------|--------|---------------|-----------|
-| ➕ | `PlusIcon` | Acciones de añadir/crear | Button.tsx:12 |
-| 🔽 | `ChevronDownIcon` | Menús desplegables | Button.tsx:12 |
-| ➡️ | `ArrowRightIcon` | Navegación/siguiente | Button.tsx:12 |
-| ✓ | `CheckIcon` | Confirmación/éxito | Button.tsx:14 |
-| ✕ | `XIcon` | Cerrar/cancelar | Button.tsx:14 |
-
-### Iconos de Input (Input)
-
-Iconos disponibles en `src/components/Input/icons.tsx`
-
-| Icono | Nombre | Uso Principal | Contexto |
-|-------|--------|---------------|----------|
-| ✉️ | `EnvelopeIcon` | Email input | Campo de correo electrónico |
-| ❓ | `QuestionMarkCircleIcon` | Ayuda contextual | Tooltips, hints |
-| 👤 | `UserIcon` | Usuario/perfil | Campos de nombre, login |
-| 🔒 | `LockClosedIcon` | Seguridad | Password, campos privados |
-| 🔍 | `MagnifyingGlassIcon` | Búsqueda | Search inputs |
-| 👁️ | `EyeIcon` | Ver contraseña | Toggle password visibility |
-| 👁️‍🗨️ | `EyeSlashIcon` | Ocultar contraseña | Toggle password visibility |
-| ✕ | `XMarkIcon` | Limpiar campo | Clear input |
-| ✓ | `CheckIcon` | Validación exitosa | Estado de éxito |
-| ⚠️ | `ExclamationCircleIcon` | Error/advertencia | Estado de error |
-
-**Total de Iconos Disponibles**: 16 (5 Button + 11 Input)
-
----
-
-## Implementación
-
-### Patrón de Implementación
-
-Utilizamos la librería `@heroicons/react` para todos los iconos estándar. El patrón consiste en envolver el icono de la librería para mantener consistencia y facilitar personalizaciones futuras.
-
-```typescript
-import { BeakerIcon } from '@heroicons/react/24/outline';
-
-interface IconProps {
-  className?: string;
-}
-
-export const IconName: React.FC<IconProps> = ({ className = 'size-5' }) => (
-  <BeakerIcon
-    className={className}
-    aria-hidden="true"
-  />
-);
-```
-
-### Características Clave
-
-1. **Librería Estándar**: Uso de Heroicons Outline (24x24px) vía `@heroicons/react/24/outline`.
-2. **TypeScript**: Interfaz `IconProps` para type safety.
-3. **Color Heredado**: Los iconos de la librería heredan automáticamente `fill="none" stroke="currentColor"`.
-4. **className**: Permite personalización con Tailwind CSS (ej: `size-5`, `text-primary`).
-5. **Accesibilidad**: Inclusión de `aria-hidden="true"` para iconos decorativos.
-
----
-
-## Guía de Uso
-
-### 1. Importación
-
-```typescript
-// Importar iconos específicos
-import { PlusIcon, CheckIcon } from '@/components/Button/icons';
-import { EnvelopeIcon, UserIcon } from '@/components/Input/icons';
-```
-
-### 2. Uso Básico
-
-```tsx
-// Icono básico (hereda color del texto padre)
-<PlusIcon />
-
-// Con tamaño personalizado
-<UserIcon className="w-5 h-5" />
-
-// Con color personalizado
-<CheckIcon className="w-4 h-4 text-green-600" />
-```
-
-### 3. En Componentes
-
-#### Button con Iconos
-
-```tsx
-import { Button } from '@/components/Button';
-import { PlusIcon, ArrowRightIcon } from '@/components/Button/icons';
-
-// Icon only button
-<Button iconOnly leftIcon={<PlusIcon />} ariaLabel="Añadir" />
-
-// Button con icono izquierdo
-<Button leftIcon={<PlusIcon />}>
-  Crear Nuevo
-</Button>
-
-// Button con icono derecho
-<Button rightIcon={<ArrowRightIcon />}>
-  Continuar
-</Button>
-
-// Button con ambos iconos
-<Button
-  leftIcon={<CheckIcon />}
-  rightIcon={<ArrowRightIcon />}
->
-  Guardar y Continuar
-</Button>
-```
-
-#### Input con Iconos
-
-```tsx
-import { Input } from '@/components/Input';
-import { EnvelopeIcon, EyeIcon } from '@/components/Input/icons';
-
-// Input con icono izquierdo
-<Input
-  leftIcon={<EnvelopeIcon />}
-  placeholder="correo@ejemplo.com"
-  type="email"
-/>
-
-// Input con icono derecho
-<Input
-  rightIcon={<EyeIcon />}
-  placeholder="Contraseña"
-  type="password"
-/>
-```
-
-### 4. Estados y Temas
-
-Los iconos heredan automáticamente el color del contexto:
-
-```tsx
-// En modo claro (hereda color del texto)
-<Button type="default">
-  <PlusIcon /> {/* Hereda text-primary-inverse-content */}
-</Button>
-
-// En modo oscuro (se adapta automáticamente)
-<div className="dark">
-  <Button type="outline">
-    <UserIcon /> {/* Hereda dark:text-dark-content-primary */}
-  </Button>
-</div>
-
-// Estados disabled
-<Button disabled>
-  <CheckIcon /> {/* Hereda opacity-50 del botón */}
-</Button>
-```
-
----
-
-## Modo Oscuro (Dark Mode)
-
-### Configuración de Tailwind CSS
-
-El modo oscuro en Siesa UI Kit se basa en la estrategia de clases de Tailwind CSS:
-
-```javascript
-// tailwind.config.js
-module.exports = {
-  darkMode: 'class', // ✅ Estrategia basada en clases (NO 'media')
-  // ...resto de la configuración
-}
-```
-
-Con esta configuración, el modo oscuro se activa añadiendo la clase `.dark` al elemento `<html>`:
-
-```html
-<!-- Modo claro -->
-<html>
-  <body>
-    <!-- Contenido en modo claro -->
-  </body>
-</html>
-
-<!-- Modo oscuro -->
-<html class="dark">
-  <body>
-    <!-- Contenido en modo oscuro -->
-  </body>
-</html>
-```
-
-### El Modificador `dark:`
-
-El modificador `dark:` de Tailwind funciona como un **prefijo condicional** que aplica estilos solo cuando la clase `.dark` está presente en un elemento padre (típicamente `<html>`).
-
-#### Sintaxis Básica
-
-```tsx
-// Patrón básico
-<Icon className="text-content-primary dark:text-dark-content-primary" />
-
-// El icono usa:
-// - text-content-primary en modo claro
-// - text-dark-content-primary en modo oscuro
-```
-
-#### Herencia de Color con currentColor
-
-Los iconos usan `fill="currentColor"`, lo que significa que heredan el color del texto del elemento padre:
-
-```tsx
-// El icono hereda el color del div padre
-<div className="text-content-primary dark:text-dark-content-primary">
-  <UserIcon /> {/* Automáticamente se adapta */}
-</div>
-
-// Equivalente a especificar el color directamente en el icono
-<UserIcon className="text-content-primary dark:text-dark-content-primary" />
-```
-
-### Combinando con Otros Modificadores
-
-El modificador `dark:` se puede combinar con hover, focus, active, y responsive:
-
-```tsx
-// Dark mode + Hover
-<button className="text-gray-700 hover:text-blue-600 dark:text-gray-300 dark:hover:text-blue-400">
-  <PlusIcon />
-</button>
-
-// Dark mode + Focus
-<input className="text-content-primary focus:text-primary-custom-600 dark:text-dark-content-primary dark:focus:text-blue-400">
-  <MagnifyingGlassIcon />
-</input>
-
-// Dark mode + Responsive
-<div className="text-gray-900 md:text-blue-600 dark:text-white dark:md:text-blue-400">
-  <CheckIcon />
-</div>
-
-// Dark mode + Group hover
-<div className="group">
-  <button className="text-gray-700 dark:text-gray-300">
-    <ArrowRightIcon className="
-      text-gray-500
-      group-hover:text-blue-600
-      dark:text-gray-400
-      dark:group-hover:text-blue-400
-    " />
-  </button>
-</div>
-```
-
-### Orden de Modificadores
-
-Tailwind CSS recomienda un orden específico para los modificadores:
-
-**Formato**: `{responsive}:{dark}:{state}:{utility}`
-
-```tsx
-// ✅ CORRECTO - Orden: responsive → dark → state → utility
-<button className="
-  md:text-gray-700
-  md:dark:text-gray-300
-  md:dark:hover:text-blue-400
-">
-  <PlusIcon />
-</button>
-
-// ❌ INCORRECTO - Orden equivocado
-<button className="
-  dark:md:hover:text-blue-400
-">
-  <PlusIcon />
-</button>
-```
-
-### Tabla de Estados con Hover
-
-| Estado | Light Mode | Dark Mode | Descripción |
-|--------|------------|-----------|-------------|
-| **Default** | `text-content-primary` | `dark:text-dark-content-primary` | Color principal del icono |
-| **Hover** | `hover:text-primary-custom-600` | `dark:hover:text-blue-400` | Color al pasar el mouse |
-| **Focus** | `focus:text-primary-custom-600` | `dark:focus:text-blue-400` | Color al enfocar |
-| **Active** | `active:text-primary-custom-700` | `dark:active:text-blue-500` | Color al hacer clic |
-| **Disabled** | `text-content-tertiary` | `dark:text-dark-content-tertiary` | Color deshabilitado |
-| **Error** | `text-error-content` | `dark:text-red-400` | Color de error |
-| **Success** | `text-green-600` | `dark:text-green-400` | Color de éxito |
-
-### Implementación del Toggle Dark Mode
-
-#### Implementación Básica con JavaScript
-
-```typescript
-// utils/darkMode.ts
-export const toggleDarkMode = () => {
-  const isDark = document.documentElement.classList.contains('dark');
-
-  if (isDark) {
-    document.documentElement.classList.remove('dark');
-    localStorage.setItem('theme', 'light');
-  } else {
-    document.documentElement.classList.add('dark');
-    localStorage.setItem('theme', 'dark');
-  }
-};
-
-// Cargar el tema al iniciar la aplicación
-export const loadTheme = () => {
-  const savedTheme = localStorage.getItem('theme');
-  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-
-  if (savedTheme === 'dark' || (!savedTheme && prefersDark)) {
-    document.documentElement.classList.add('dark');
-  } else {
-    document.documentElement.classList.remove('dark');
-  }
-};
-```
-
-#### Prevenir Flash de Contenido (FOUC)
-
-Añadir este script en el `<head>` del HTML antes de que React se cargue:
-
-```html
-<!-- index.html -->
-<head>
-  <script>
-    // Aplicar tema inmediatamente antes del render
-    (function() {
-      const theme = localStorage.getItem('theme');
-      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-
-      if (theme === 'dark' || (!theme && prefersDark)) {
-        document.documentElement.classList.add('dark');
-      }
-    })();
-  </script>
-</head>
-```
-
-### Ejemplos Completos
-
-#### Ejemplo 1: Toolbar de Iconos con Dark Mode
-
-```tsx
-import { Button } from '@/components/Button';
-import { PlusIcon, CheckIcon, XIcon } from '@/components/Button/icons';
-
-export const IconToolbar = () => {
-  return (
-    <div className="
-      flex gap-2 p-4
-      bg-white dark:bg-dark-bg-primary
-      border-b border-border-primary dark:border-dark-border-primary
-    ">
-      {/* Icono con hover adaptado */}
-      <Button
-        iconOnly
-        type="outline"
-        leftIcon={<PlusIcon />}
-        ariaLabel="Añadir"
-        className="
-          text-content-primary dark:text-dark-content-primary
-          hover:text-primary-custom-600 dark:hover:text-blue-400
-          hover:bg-gray-100 dark:hover:bg-gray-800
-        "
-      />
-
-      {/* Icono de éxito */}
-      <Button
-        iconOnly
-        type="outline"
-        leftIcon={<CheckIcon />}
-        ariaLabel="Guardar"
-        className="
-          text-green-600 dark:text-green-400
-          hover:text-green-700 dark:hover:text-green-300
-          hover:bg-green-50 dark:hover:bg-green-900/20
-        "
-      />
-
-      {/* Icono de error */}
-      <Button
-        iconOnly
-        type="outline"
-        leftIcon={<XIcon />}
-        ariaLabel="Cancelar"
-        className="
-          text-error-content dark:text-red-400
-          hover:text-red-700 dark:hover:text-red-300
-          hover:bg-red-50 dark:hover:bg-red-900/20
-        "
-      />
-    </div>
-  );
-};
-```
-
-#### Ejemplo 2: Formulario con Iconos Adaptativos
-
-```tsx
-import { Input } from '@/components/Input';
-import { UserIcon, LockClosedIcon, EnvelopeIcon } from '@/components/Input/icons';
-import { Button } from '@/components/Button';
-import { ArrowRightIcon, CheckIcon } from '@/components/Button/icons';
-
-export const AdaptiveForm = () => {
-  return (
-    <div className="
-      w-full max-w-md p-6
-      bg-white dark:bg-dark-bg-primary
-      border border-border-primary dark:border-dark-border-primary
-      rounded-2xl
-      shadow-base dark:shadow-lg
-    ">
-      <h2 className="
-        mb-6
-        text-content-primary dark:text-dark-content-primary
-        font-bold text-xl
-      ">
-        Iniciar Sesión
-      </h2>
-
-      <form className="space-y-4">
-        {/* Input de email con icono */}
-        <Input
-          label="Correo Electrónico"
-          type="email"
-          leftIcon={
-            <EnvelopeIcon className="
-              text-content-secondary dark:text-dark-content-secondary
-            " />
-          }
-          placeholder="tu@email.com"
-          className="
-            text-content-primary dark:text-dark-content-primary
-            bg-bg-primary dark:bg-dark-bg-secondary
-            border-border-primary dark:border-dark-border-primary
-            focus:border-primary-custom-600 dark:focus:border-blue-400
-          "
-        />
-
-        {/* Input de usuario con icono */}
-        <Input
-          label="Usuario"
-          leftIcon={
-            <UserIcon className="
-              text-content-secondary dark:text-dark-content-secondary
-            " />
-          }
-          placeholder="Tu usuario"
-          className="
-            text-content-primary dark:text-dark-content-primary
-            bg-bg-primary dark:bg-dark-bg-secondary
-          "
-        />
-
-        {/* Input de contraseña con icono */}
-        <Input
-          label="Contraseña"
-          type="password"
-          leftIcon={
-            <LockClosedIcon className="
-              text-content-secondary dark:text-dark-content-secondary
-            " />
-          }
-          placeholder="Tu contraseña"
-          className="
-            text-content-primary dark:text-dark-content-primary
-            bg-bg-primary dark:bg-dark-bg-secondary
-          "
-        />
-
-        {/* Botón de submit con icono */}
-        <Button
-          type="default"
-          fullWidth
-          rightIcon={<ArrowRightIcon />}
-          className="
-            bg-primary-custom-600 dark:bg-dark-bg-inverse
-            text-primary-inverse-content dark:text-dark-content-inverse
-            hover:bg-primary-custom-500 dark:hover:bg-dark-bg-inverse/90
-          "
-        >
-          Continuar
-        </Button>
-      </form>
-    </div>
-  );
-};
-```
-
-#### Ejemplo 3: Status Icons con Colores Adaptativos
-
-```tsx
-import { CheckIcon, ExclamationCircleIcon, XMarkIcon } from '@/components/Input/icons';
-
-export const StatusMessages = () => {
-  return (
-    <div className="space-y-3">
-      {/* Mensaje de éxito */}
-      <div className="
-        flex items-center gap-3 p-4
-        bg-green-50 dark:bg-green-900/20
-        border border-green-200 dark:border-green-800
-        rounded-lg
-      ">
-        <CheckIcon className="
-          w-5 h-5
-          text-green-600 dark:text-green-400
-        " />
-        <p className="
-          text-green-800 dark:text-green-300
-          font-medium
-        ">
-          Operación completada con éxito
-        </p>
-      </div>
-
-      {/* Mensaje de advertencia */}
-      <div className="
-        flex items-center gap-3 p-4
-        bg-yellow-50 dark:bg-yellow-900/20
-        border border-yellow-200 dark:border-yellow-800
-        rounded-lg
-      ">
-        <ExclamationCircleIcon className="
-          w-5 h-5
-          text-yellow-600 dark:text-yellow-400
-        " />
-        <p className="
-          text-yellow-800 dark:text-yellow-300
-          font-medium
-        ">
-          Advertencia: Revisa la información
-        </p>
-      </div>
-
-      {/* Mensaje de error */}
-      <div className="
-        flex items-center gap-3 p-4
-        bg-red-50 dark:bg-red-900/20
-        border border-red-200 dark:border-red-800
-        rounded-lg
-      ">
-        <XMarkIcon className="
-          w-5 h-5
-          text-error-content dark:text-red-400
-        " />
-        <p className="
-          text-red-800 dark:text-red-300
-          font-medium
-        ">
-          Error: No se pudo completar la operación
-        </p>
-      </div>
-    </div>
-  );
-};
-```
-
-#### Ejemplo 4: Icon Button con Group Hover
-
-```tsx
-import { ArrowRightIcon } from '@/components/Button/icons';
-
-export const NavigationCard = () => {
-  return (
-    <button className="
-      group
-      w-full p-6
-      bg-white dark:bg-dark-bg-primary
-      border border-border-primary dark:border-dark-border-primary
-      rounded-xl
-      hover:border-primary-custom-600 dark:hover:border-blue-400
-      hover:shadow-lg
-      transition-all
-      text-left
-    ">
-      <div className="flex items-center justify-between">
-        <div>
-          <h3 className="
-            mb-2
-            text-content-primary dark:text-dark-content-primary
-            font-bold text-lg
-            group-hover:text-primary-custom-600 dark:group-hover:text-blue-400
-          ">
-            Ir a la Configuración
-          </h3>
-          <p className="
-            text-content-secondary dark:text-dark-content-secondary
-            text-sm
-          ">
-            Administra las preferencias del sistema
-          </p>
-        </div>
-
-        {/* Icono que se anima y cambia de color en hover */}
-        <ArrowRightIcon className="
-          w-6 h-6
-          text-content-tertiary dark:text-dark-content-tertiary
-          group-hover:text-primary-custom-600 dark:group-hover:text-blue-400
-          group-hover:translate-x-1
-          transition-all
-        " />
-      </div>
-    </button>
-  );
-};
-```
-
-### Mejores Prácticas para Iconos en Dark Mode
-
-#### ✅ Hacer
-
-1. **Usar tokens semánticos que se adaptan automáticamente**
-   ```tsx
-   // ✅ CORRECTO - Los tokens ya incluyen dark mode
-   <UserIcon className="text-content-primary dark:text-dark-content-primary" />
-   ```
-
-2. **Aprovechar currentColor para heredar colores del padre**
-   ```tsx
-   // ✅ CORRECTO - El icono hereda el color
-   <div className="text-primary-custom-600 dark:text-blue-400">
-     <EnvelopeIcon />
-   </div>
-   ```
-
-3. **Usar colores más brillantes en dark mode**
-   ```tsx
-   // ✅ CORRECTO - Ajustar intensidad para dark mode
-   <CheckIcon className="text-green-600 dark:text-green-400" />
-   ```
-
-4. **Combinar con estados hover y focus**
-   ```tsx
-   // ✅ CORRECTO - Estados completos
-   <button className="
-     text-gray-700 dark:text-gray-300
-     hover:text-blue-600 dark:hover:text-blue-400
-   ">
-     <PlusIcon />
-   </button>
-   ```
-
-5. **Reducir opacidad de iconos secundarios en dark mode**
-   ```tsx
-   // ✅ CORRECTO - Jerarquía visual
-   <QuestionMarkCircleIcon className="
-     text-content-secondary/70 dark:text-dark-content-secondary/60
-   " />
-   ```
-
-#### ❌ Evitar
-
-1. **No usar el mismo color para light y dark mode**
-   ```tsx
-   // ❌ INCORRECTO - Sin dark variant
-   <UserIcon className="text-gray-900" />
-
-   // ✅ CORRECTO
-   <UserIcon className="text-gray-900 dark:text-gray-100" />
-   ```
-
-2. **No hardcodear colores sin considerar contraste**
-   ```tsx
-   // ❌ INCORRECTO - Pobre contraste en dark mode
-   <CheckIcon className="text-gray-300" />
-
-   // ✅ CORRECTO - Buen contraste en ambos modos
-   <CheckIcon className="text-green-600 dark:text-green-400" />
-   ```
-
-3. **No olvidar estados interactivos**
-   ```tsx
-   // ❌ INCORRECTO - Sin hover para dark mode
-   <button className="hover:text-blue-600">
-     <PlusIcon />
-   </button>
-
-   // ✅ CORRECTO
-   <button className="hover:text-blue-600 dark:hover:text-blue-400">
-     <PlusIcon />
-   </button>
-   ```
-
-4. **No usar colores muy oscuros en dark mode**
-   ```tsx
-   // ❌ INCORRECTO - Invisible en fondo oscuro
-   <XIcon className="text-gray-900 dark:text-gray-900" />
-
-   // ✅ CORRECTO - Visible en ambos modos
-   <XIcon className="text-gray-900 dark:text-gray-100" />
-   ```
-
-### Guía Rápida: Colores de Iconos por Contexto
-
-| Contexto | Light Mode | Dark Mode | Ejemplo |
-|----------|------------|-----------|---------|
-| **Icono Principal** | `text-content-primary` | `dark:text-dark-content-primary` | Iconos en botones principales |
-| **Icono Secundario** | `text-content-secondary` | `dark:text-dark-content-secondary` | Iconos decorativos |
-| **Icono Terciario** | `text-content-tertiary` | `dark:text-dark-content-tertiary` | Iconos de ayuda |
-| **Icono Interactivo** | `text-gray-700 hover:text-blue-600` | `dark:text-gray-300 dark:hover:text-blue-400` | Botones icon-only |
-| **Icono de Éxito** | `text-green-600` | `dark:text-green-400` | Check, confirmación |
-| **Icono de Error** | `text-error-content` | `dark:text-red-400` | X, advertencias |
-| **Icono de Info** | `text-blue-600` | `dark:text-blue-400` | Información, ayuda |
-| **Icono Deshabilitado** | `text-content-tertiary opacity-50` | `dark:text-dark-content-tertiary opacity-50` | Elementos inactivos |
-
-### Recursos Adicionales
-
-Para más información sobre el modo oscuro:
-- Ver `docs/dark-mode-guide.md` - Guía completa de Dark Mode en Tailwind CSS
-- Ver `docs/colors.md` - Sistema de colores completo con tokens dark mode
-- [Documentación oficial de Tailwind Dark Mode](https://tailwindcss.com/docs/dark-mode)
-
----
-
-## Accesibilidad
-
-### Consideraciones de Accesibilidad
-
-#### 1. Iconos Decorativos
-
-Cuando el icono acompaña texto visible, es decorativo:
-
-```tsx
-// ✅ CORRECTO: El texto describe la acción
-<Button leftIcon={<PlusIcon />}>
-  Crear Usuario
-</Button>
-// No se necesita aria-label adicional
-```
-
-#### 2. Iconos Funcionales (Icon-Only)
-
-Cuando el icono es el único elemento visual:
-
-```tsx
-// ✅ CORRECTO: Usar aria-label
-<Button
-  iconOnly
-  leftIcon={<PlusIcon />}
-  ariaLabel="Añadir nuevo elemento"
-/>
-
-// ❌ INCORRECTO: Sin aria-label
-<Button iconOnly leftIcon={<PlusIcon />} />
-// Los lectores de pantalla no sabrán la función
-```
-
-#### 3. Iconos con Significado
-
-En contextos donde el icono comunica información:
-
-```tsx
-// ✅ CORRECTO: Añadir rol y aria-label
-<span role="img" aria-label="Estado: Exitoso">
-  <CheckIcon className="text-green-600" />
-</span>
-
-// ✅ CORRECTO: Con texto de soporte visible
-<div className="flex items-center gap-2">
-  <ExclamationCircleIcon className="text-error-content" />
-  <span>Error en la validación</span>
-</div>
-```
-
-#### 4. Tooltips para Contexto Adicional
-
-```tsx
-// ✅ MEJOR PRÁCTICA: Icono + Tooltip
-<button
-  className="p-2"
-  aria-label="Ayuda"
-  title="Obtener ayuda sobre este campo"
->
-  <QuestionMarkCircleIcon />
-</button>
-```
-
-### Directrices WCAG 2.1
-
-- **Nivel A**: Todos los iconos funcionales deben tener texto alternativo
-- **Nivel AA**: Contraste mínimo 3:1 para iconos (se cumple con currentColor)
-- **Nivel AAA**: Proveer texto descriptivo adicional cuando sea posible
-
----
-
-## Ejemplos de Código
-
-### Ejemplo 1: Toolbar de Acciones
-
-```tsx
-import { Button } from '@/components/Button';
-import { PlusIcon, CheckIcon, XIcon } from '@/components/Button/icons';
-
-export const ActionToolbar = () => {
-  return (
-    <div className="flex gap-2 p-4 bg-bg-primary border-b border-border-primary">
-      {/* Botones icon-only con tooltips */}
-      <Button
-        iconOnly
-        size="base"
-        type="default"
-        leftIcon={<PlusIcon />}
-        ariaLabel="Añadir nuevo registro"
-        title="Añadir nuevo registro"
-      />
-
-      <Button
-        iconOnly
-        size="base"
-        type="outline"
-        leftIcon={<CheckIcon />}
-        ariaLabel="Guardar cambios"
-        title="Guardar cambios"
-      />
-
-      <Button
-        iconOnly
-        size="base"
-        type="plain"
-        leftIcon={<XIcon />}
-        ariaLabel="Cancelar operación"
-        title="Cancelar operación"
-      />
-    </div>
-  );
-};
-```
-
-### Ejemplo 2: Formulario de Login
-
-```tsx
-import { Input } from '@/components/Input';
-import { Button } from '@/components/Button';
-import {
-  UserIcon,
-  LockClosedIcon,
-  EyeIcon,
-  EyeSlashIcon
-} from '@/components/Input/icons';
-import { ArrowRightIcon } from '@/components/Button/icons';
-import { useState } from 'react';
-
-export const LoginForm = () => {
-  const [showPassword, setShowPassword] = useState(false);
-
-  return (
-    <form className="space-y-4 w-full max-w-sm">
-      {/* Usuario */}
-      <Input
-        label="Usuario"
-        name="username"
-        leftIcon={<UserIcon />}
-        placeholder="Ingrese su usuario"
-        required
-      />
-
-      {/* Contraseña con toggle */}
-      <Input
-        label="Contraseña"
-        name="password"
-        type={showPassword ? 'text' : 'password'}
-        leftIcon={<LockClosedIcon />}
-        rightIcon={
-          <button
-            type="button"
-            onClick={() => setShowPassword(!showPassword)}
-            className="cursor-pointer"
-            aria-label={showPassword ? 'Ocultar contraseña' : 'Mostrar contraseña'}
-          >
-            {showPassword ? <EyeSlashIcon /> : <EyeIcon />}
-          </button>
-        }
-        placeholder="Ingrese su contraseña"
-        required
-      />
-
-      {/* Submit */}
-      <Button
-        type="default"
-        size="base"
-        fullWidth
-        rightIcon={<ArrowRightIcon />}
-        htmlType="submit"
-      >
-        Iniciar Sesión
-      </Button>
-    </form>
-  );
-};
-```
-
-### Ejemplo 3: Search Input con Estados
-
-```tsx
-import { Input } from '@/components/Input';
-import {
-  MagnifyingGlassIcon,
-  XMarkIcon,
-  CheckIcon,
-  ExclamationCircleIcon
-} from '@/components/Input/icons';
-import { useState } from 'react';
-
-export const SearchInput = () => {
-  const [query, setQuery] = useState('');
-  const [status, setStatus] = useState<'idle' | 'searching' | 'success' | 'error'>('idle');
-
-  const getStatusIcon = () => {
-    switch (status) {
-      case 'success':
-        return <CheckIcon className="text-green-600" />;
-      case 'error':
-        return <ExclamationCircleIcon className="text-error-content" />;
-      default:
-        return null;
-    }
-  };
-
-  return (
-    <div className="w-full max-w-md">
-      <Input
-        label="Búsqueda"
-        value={query}
-        onChange={(e) => setQuery(e.target.value)}
-        leftIcon={<MagnifyingGlassIcon />}
-        rightIcon={
-          query ? (
-            <button
-              type="button"
-              onClick={() => setQuery('')}
-              aria-label="Limpiar búsqueda"
-              className="cursor-pointer hover:text-primary-custom-600"
-            >
-              <XMarkIcon />
-            </button>
-          ) : (
-            getStatusIcon()
-          )
-        }
-        placeholder="Buscar..."
-        helperText={
-          status === 'error' ? 'No se encontraron resultados' : undefined
-        }
-        error={status === 'error'}
-      />
-    </div>
-  );
-};
-```
-
----
-
-## Mejores Prácticas
-
-### ✅ Hacer
-
-1. **Usar iconos semánticamente apropiados**
-   ```tsx
-   // ✅ CORRECTO
-   <Button leftIcon={<PlusIcon />}>Añadir</Button>
-   <Button leftIcon={<CheckIcon />}>Guardar</Button>
-   ```
-
-2. **Mantener el tamaño de 16px en la mayoría de casos**
-   ```tsx
-   // ✅ CORRECTO - tamaño por defecto
-   <UserIcon className="w-4 h-4" />
-   ```
-
-3. **Usar currentColor para heredar el color del contexto**
-   ```tsx
-   // ✅ CORRECTO - el icono hereda el color
-   <div className="text-primary-custom-600">
-     <EnvelopeIcon />
-   </div>
-   ```
-
-4. **Proveer aria-label en botones icon-only**
-   ```tsx
-   // ✅ CORRECTO
-   <Button iconOnly leftIcon={<XIcon />} ariaLabel="Cerrar" />
-   ```
-
-5. **Agrupar iconos relacionados en el mismo archivo**
-   ```tsx
-   // ✅ CORRECTO - iconos de un componente juntos
-   // src/components/Button/icons.tsx
-   ```
-
-### ❌ Evitar
-
-1. **No mezclar diferentes estilos de iconos**
-   ```tsx
-   // ❌ INCORRECTO - mezclar Heroicons con otros
-   <PlusIcon /> {/* Heroicons Micro */}
-   <SomeOtherIcon /> {/* Otra librería */}
-   ```
-
-2. **No usar tamaños inconsistentes sin razón**
-   ```tsx
-   // ❌ INCORRECTO - tamaños arbitrarios
-   <UserIcon className="w-7 h-7" />
-   <EnvelopeIcon className="w-3 h-3" />
-   ```
-
-3. **No hardcodear colores directamente en el SVG**
-   ```tsx
-   // ❌ INCORRECTO - hardcodear fill
-   <svg fill="#0e79fd">...</svg>
-
-   // ✅ CORRECTO - usar currentColor
-   <svg fill="currentColor">...</svg>
-   ```
-
-4. **No omitir aria-label en iconos funcionales**
-   ```tsx
-   // ❌ INCORRECTO
-   <button><XIcon /></button>
-
-   // ✅ CORRECTO
-   <button aria-label="Cerrar"><XIcon /></button>
-   ```
-
-5. **No usar iconos como única forma de comunicación**
-   ```tsx
-   // ❌ INCORRECTO - solo icono sin contexto
-   <div><ExclamationCircleIcon /></div>
-
-   // ✅ CORRECTO - icono + texto
-   <div className="flex gap-2">
-     <ExclamationCircleIcon />
-     <span>Error: Campo requerido</span>
-   </div>
-   ```
-
-### Rendimiento
-
-- **✅ SVG Inline**: Mejor para iconos que se usan frecuentemente
-- **✅ Tree-shaking**: Importar solo los iconos necesarios
-- **✅ Evitar re-renders**: Los iconos son componentes puros
-- **✅ Memoización**: React.memo si se pasan como props frecuentemente
-
-```tsx
-// ✅ CORRECTO - memoizar icono si se pasa como prop
-const MemoizedIcon = React.memo(PlusIcon);
-
-// En componente padre
-<Button leftIcon={<MemoizedIcon />}>Añadir</Button>
-```
-
----
-
-## Referencia Rápida
-
-### Cheat Sheet: Importaciones
-
-```typescript
-// Iconos de Button
-import {
-  PlusIcon,           // Añadir/Crear
-  ChevronDownIcon,    // Dropdown
-  ArrowRightIcon,     // Navegación
-  CheckIcon,          // Confirmar
-  XIcon              // Cerrar/Cancelar
-} from '@/components/Button/icons';
-
-// Iconos de Input
-import {
-  EnvelopeIcon,             // Email
-  QuestionMarkCircleIcon,   // Ayuda
-  UserIcon,                 // Usuario
-  LockClosedIcon,           // Seguridad
-  MagnifyingGlassIcon,      // Búsqueda
-  EyeIcon,                  // Ver password
-  EyeSlashIcon,             // Ocultar password
-  XMarkIcon,                // Limpiar
-  CheckIcon,                // Éxito
-  ExclamationCircleIcon     // Error
-} from '@/components/Input/icons';
-```
-
-### Cheat Sheet: Tamaños Comunes
-
-| Clase Tailwind | Tamaño | Uso |
-|----------------|--------|-----|
-| `w-4 h-4` | 16px | **Default** - Botones, inputs |
-| `w-5 h-5` | 20px | Iconos destacados |
-| `w-6 h-6` | 24px | Headers, títulos |
-| `w-8 h-8` | 32px | Iconos grandes, heros |
-
-### Cheat Sheet: Colores Comunes
-
-```tsx
-// Primary
-<Icon className="text-primary-custom-600" />
-
-// Éxito (Verde)
-<CheckIcon className="text-green-600" />
-
-// Error (Rojo)
-<ExclamationCircleIcon className="text-error-content" />
-
-// Secundario (Gris)
-<Icon className="text-content-secondary" />
-
-// Dark Mode (automático)
-<Icon className="text-content-primary dark:text-dark-content-primary" />
-```
-
-### Cheat Sheet: Patrones de Uso
-
-```tsx
-// 1. Icon-only Button
-<Button iconOnly leftIcon={<PlusIcon />} ariaLabel="Añadir" />
-
-// 2. Button con texto e icono
-<Button leftIcon={<CheckIcon />}>Guardar</Button>
-
-// 3. Input con icono
-<Input leftIcon={<UserIcon />} placeholder="Usuario" />
-
-// 4. Toggle icon
-{visible ? <EyeIcon /> : <EyeSlashIcon />}
-
-// 5. Status icon
-{status === 'success' ? <CheckIcon /> : <ExclamationCircleIcon />}
-```
-
----
-
-## Añadir Nuevos Iconos
-
-### Proceso para Agregar un Icono
-
-1. **Obtener el SVG de Heroicons Micro**
-   - Visitar: https://heroicons.com
-   - Seleccionar versión "Micro" (16px)
-   - Copiar el código SVG
-
-2. **Crear el Componente React**
-   ```tsx
-   // En el archivo icons.tsx correspondiente
-   export const NewIcon: React.FC<IconProps> = ({ className = '' }) => (
-     <svg
-       xmlns="http://www.w3.org/2000/svg"
-       viewBox="0 0 16 16"
-       fill="currentColor"
-       className={className}
-     >
-       {/* Pegar path(s) del SVG */}
-       <path d="..." />
-     </svg>
-   );
-   ```
-
-3. **Documentar el Nuevo Icono**
-   - Añadir a la tabla de catálogo
-   - Incluir ejemplo de uso
-   - Especificar contexto apropiado
-
-4. **Testing**
-   - Verificar en modo claro y oscuro
-   - Probar diferentes tamaños
-   - Validar accesibilidad
-
-### Decisiones de Organización
-
-- **¿Dónde colocar el nuevo icono?**
-  - ¿Se usa en Button? → `src/components/Button/icons.tsx`
-  - ¿Se usa en Input? → `src/components/Input/icons.tsx`
-  - ¿Se usa en múltiples componentes? → Crear `src/shared/icons.tsx`
-
----
-
-## Recursos Adicionales
-
-### Enlaces Útiles
-
-- **Heroicons**: https://heroicons.com
-- **Documentación Heroicons**: https://github.com/tailwindlabs/heroicons
-- **WCAG Guidelines**: https://www.w3.org/WAI/WCAG21/quickref/
-- **SVG Accessibility**: https://css-tricks.com/accessible-svgs/
-
-### Archivos Relacionados
-
-- `src/components/Button/icons.tsx` - Iconos de botones
-- `src/components/Input/icons.tsx` - Iconos de inputs
-- `src/components/Button/Button.tsx` - Implementación de iconos en Button
-- `docs/colors.md` - Sistema de colores (para colores de iconos)
-- `docs/typography.md` - Sistema tipográfico
-
----
-
-**Última actualización**: 2025-11-11
-**Versión**: 1.0.0
-**Mantenedor**: Siesa UI Kit Team
+# Sistema de Iconos - Siesa UI Kit
+
+## 📋 Tabla de Contenidos
+
+1. [Introducción](#introducción)
+2. [Librería de Iconos](#librería-de-iconos)
+3. [Catálogo de Iconos](#catálogo-de-iconos)
+4. [Implementación](#implementación)
+5. [Guía de Uso](#guía-de-uso)
+6. [Accesibilidad](#accesibilidad)
+7. [Ejemplos de Código](#ejemplos-de-código)
+8. [Mejores Prácticas](#mejores-prácticas)
+9. [Referencia Rápida](#referencia-rápida)
+
+---
+
+## Introducción
+
+El sistema de iconos de Siesa UI Kit está basado en **Heroicons Micro**, una librería de iconos SVG de 16x16px diseñada específicamente para interfaces de usuario modernas. Los iconos están optimizados para claridad a tamaños pequeños y se integran perfectamente con nuestro sistema de diseño.
+
+### Objetivos del Sistema de Iconos
+
+- **Consistencia Visual**: Todos los iconos mantienen el mismo peso visual y estilo
+- **Escalabilidad**: Iconos vectoriales que se adaptan a cualquier tamaño
+- **Accesibilidad**: Soporte para lectores de pantalla y temas oscuros
+- **Rendimiento**: SVG inline para carga rápida sin requests adicionales
+- **Flexibilidad**: Fácil personalización de tamaño, color y estilos
+
+### Principios de Diseño
+
+1. **Simplicidad**: Formas claras y reconocibles
+2. **Peso Consistente**: Todos los iconos tienen el mismo grosor de línea
+3. **Alineación Pixel-Perfect**: Optimizados para 16x16px
+4. **Color Heredado**: Usan `currentColor` para adaptarse al contexto
+
+---
+
+## Librería de Iconos
+
+### Heroicons Micro
+
+**Especificaciones Técnicas:**
+- **Tamaño Base**: 16x16px (viewBox="0 0 16 16")
+- **Formato**: SVG inline
+- **Estilo**: Solid (relleno completo)
+- **Grosor**: 1.5px stroke weight equivalent
+- **Licencia**: MIT License
+
+**Ventajas:**
+- ✅ Diseñados específicamente para UI de 16px
+- ✅ Optimizados para claridad a tamaños pequeños
+- ✅ Mantenidos por el equipo de Tailwind CSS
+- ✅ Biblioteca completa y consistente
+- ✅ Excelente legibilidad en pantallas de alta densidad
+
+---
+
+## Catálogo de Iconos
+
+### Iconos de Botón (Button)
+
+Iconos disponibles en `src/components/Button/icons.tsx`
+
+| Icono | Nombre | Uso Principal | Ubicación |
+|-------|--------|---------------|-----------|
+| ➕ | `PlusIcon` | Acciones de añadir/crear | Button.tsx:12 |
+| 🔽 | `ChevronDownIcon` | Menús desplegables | Button.tsx:12 |
+| ➡️ | `ArrowRightIcon` | Navegación/siguiente | Button.tsx:12 |
+| ✓ | `CheckIcon` | Confirmación/éxito | Button.tsx:14 |
+| ✕ | `XIcon` | Cerrar/cancelar | Button.tsx:14 |
+
+### Iconos de Input (Input)
+
+Iconos disponibles en `src/components/Input/icons.tsx`
+
+| Icono | Nombre | Uso Principal | Contexto |
+|-------|--------|---------------|----------|
+| ✉️ | `EnvelopeIcon` | Email input | Campo de correo electrónico |
+| ❓ | `QuestionMarkCircleIcon` | Ayuda contextual | Tooltips, hints |
+| 👤 | `UserIcon` | Usuario/perfil | Campos de nombre, login |
+| 🔒 | `LockClosedIcon` | Seguridad | Password, campos privados |
+| 🔍 | `MagnifyingGlassIcon` | Búsqueda | Search inputs |
+| 👁️ | `EyeIcon` | Ver contraseña | Toggle password visibility |
+| 👁️‍🗨️ | `EyeSlashIcon` | Ocultar contraseña | Toggle password visibility |
+| ✕ | `XMarkIcon` | Limpiar campo | Clear input |
+| ✓ | `CheckIcon` | Validación exitosa | Estado de éxito |
+| ⚠️ | `ExclamationCircleIcon` | Error/advertencia | Estado de error |
+
+**Total de Iconos Disponibles**: 16 (5 Button + 11 Input)
+
+---
+
+## Implementación
+
+### Patrón de Implementación
+
+Todos los iconos siguen un patrón consistente:
+
+```typescript
+interface IconProps {
+  className?: string;
+}
+
+export const IconName: React.FC<IconProps> = ({ className = '' }) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 16 16"
+    fill="currentColor"
+    className={className}
+  >
+    <path d="..." />
+  </svg>
+);
+```
+
+### Características Clave
+
+1. **TypeScript**: Interfaz `IconProps` para type safety
+2. **currentColor**: El fill hereda el color del texto padre
+3. **className**: Permite personalización con Tailwind CSS
+4. **viewBox 16x16**: Tamaño base optimizado
+5. **Props mínimos**: Solo className para máxima flexibilidad
+
+### Tamaños de Iconos
+
+Los iconos se adaptan usando clases de Tailwind CSS:
+
+```typescript
+// En Button Component
+const iconSizeClasses = {
+  xs: 'w-4 h-4',   // 16px - todos los tamaños usan 16px
+  sm: 'w-4 h-4',   // 16px
+  base: 'w-4 h-4', // 16px (default)
+  l: 'w-4 h-4',    // 16px
+  xl: 'w-4 h-4',   // 16px
+};
+```
+
+**Decisión de Diseño**: Todos los botones usan iconos de 16px independientemente del tamaño del botón, según especificaciones de Figma.
+
+---
+
+## Guía de Uso
+
+### 1. Importación
+
+```typescript
+// Importar iconos específicos
+import { PlusIcon, CheckIcon } from '@/components/Button/icons';
+import { EnvelopeIcon, UserIcon } from '@/components/Input/icons';
+```
+
+### 2. Uso Básico
+
+```tsx
+// Icono básico (hereda color del texto padre)
+<PlusIcon />
+
+// Con tamaño personalizado
+<UserIcon className="w-5 h-5" />
+
+// Con color personalizado
+<CheckIcon className="w-4 h-4 text-green-600" />
+```
+
+### 3. En Componentes
+
+#### Button con Iconos
+
+```tsx
+import { Button } from '@/components/Button';
+import { PlusIcon, ArrowRightIcon } from '@/components/Button/icons';
+
+// Icon only button
+<Button iconOnly leftIcon={<PlusIcon />} ariaLabel="Añadir" />
+
+// Button con icono izquierdo
+<Button leftIcon={<PlusIcon />}>
+  Crear Nuevo
+</Button>
+
+// Button con icono derecho
+<Button rightIcon={<ArrowRightIcon />}>
+  Continuar
+</Button>
+
+// Button con ambos iconos
+<Button
+  leftIcon={<CheckIcon />}
+  rightIcon={<ArrowRightIcon />}
+>
+  Guardar y Continuar
+</Button>
+```
+
+#### Input con Iconos
+
+```tsx
+import { Input } from '@/components/Input';
+import { EnvelopeIcon, EyeIcon } from '@/components/Input/icons';
+
+// Input con icono izquierdo
+<Input
+  leftIcon={<EnvelopeIcon />}
+  placeholder="correo@ejemplo.com"
+  type="email"
+/>
+
+// Input con icono derecho
+<Input
+  rightIcon={<EyeIcon />}
+  placeholder="Contraseña"
+  type="password"
+/>
+```
+
+### 4. Estados y Temas
+
+Los iconos heredan automáticamente el color del contexto:
+
+```tsx
+// En modo claro (hereda color del texto)
+<Button type="default">
+  <PlusIcon /> {/* Hereda text-primary-inverse-content */}
+</Button>
+
+// En modo oscuro (se adapta automáticamente)
+<div className="dark">
+  <Button type="outline">
+    <UserIcon /> {/* Hereda dark:text-dark-content-primary */}
+  </Button>
+</div>
+
+// Estados disabled
+<Button disabled>
+  <CheckIcon /> {/* Hereda opacity-50 del botón */}
+</Button>
+```
+
+---
+
+## Modo Oscuro (Dark Mode)
+
+### Configuración de Tailwind CSS
+
+El modo oscuro en Siesa UI Kit se basa en la estrategia de clases de Tailwind CSS:
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  darkMode: 'class', // ✅ Estrategia basada en clases (NO 'media')
+  // ...resto de la configuración
+}
+```
+
+Con esta configuración, el modo oscuro se activa añadiendo la clase `.dark` al elemento `<html>`:
+
+```html
+<!-- Modo claro -->
+<html>
+  <body>
+    <!-- Contenido en modo claro -->
+  </body>
+</html>
+
+<!-- Modo oscuro -->
+<html class="dark">
+  <body>
+    <!-- Contenido en modo oscuro -->
+  </body>
+</html>
+```
+
+### El Modificador `dark:`
+
+El modificador `dark:` de Tailwind funciona como un **prefijo condicional** que aplica estilos solo cuando la clase `.dark` está presente en un elemento padre (típicamente `<html>`).
+
+#### Sintaxis Básica
+
+```tsx
+// Patrón básico
+<Icon className="text-content-primary dark:text-dark-content-primary" />
+
+// El icono usa:
+// - text-content-primary en modo claro
+// - text-dark-content-primary en modo oscuro
+```
+
+#### Herencia de Color con currentColor
+
+Los iconos usan `fill="currentColor"`, lo que significa que heredan el color del texto del elemento padre:
+
+```tsx
+// El icono hereda el color del div padre
+<div className="text-content-primary dark:text-dark-content-primary">
+  <UserIcon /> {/* Automáticamente se adapta */}
+</div>
+
+// Equivalente a especificar el color directamente en el icono
+<UserIcon className="text-content-primary dark:text-dark-content-primary" />
+```
+
+### Combinando con Otros Modificadores
+
+El modificador `dark:` se puede combinar con hover, focus, active, y responsive:
+
+```tsx
+// Dark mode + Hover
+<button className="text-gray-700 hover:text-blue-600 dark:text-gray-300 dark:hover:text-blue-400">
+  <PlusIcon />
+</button>
+
+// Dark mode + Focus
+<input className="text-content-primary focus:text-primary-custom-600 dark:text-dark-content-primary dark:focus:text-blue-400">
+  <MagnifyingGlassIcon />
+</input>
+
+// Dark mode + Responsive
+<div className="text-gray-900 md:text-blue-600 dark:text-white dark:md:text-blue-400">
+  <CheckIcon />
+</div>
+
+// Dark mode + Group hover
+<div className="group">
+  <button className="text-gray-700 dark:text-gray-300">
+    <ArrowRightIcon className="
+      text-gray-500
+      group-hover:text-blue-600
+      dark:text-gray-400
+      dark:group-hover:text-blue-400
+    " />
+  </button>
+</div>
+```
+
+### Orden de Modificadores
+
+Tailwind CSS recomienda un orden específico para los modificadores:
+
+**Formato**: `{responsive}:{dark}:{state}:{utility}`
+
+```tsx
+// ✅ CORRECTO - Orden: responsive → dark → state → utility
+<button className="
+  md:text-gray-700
+  md:dark:text-gray-300
+  md:dark:hover:text-blue-400
+">
+  <PlusIcon />
+</button>
+
+// ❌ INCORRECTO - Orden equivocado
+<button className="
+  dark:md:hover:text-blue-400
+">
+  <PlusIcon />
+</button>
+```
+
+### Tabla de Estados con Hover
+
+| Estado | Light Mode | Dark Mode | Descripción |
+|--------|------------|-----------|-------------|
+| **Default** | `text-content-primary` | `dark:text-dark-content-primary` | Color principal del icono |
+| **Hover** | `hover:text-primary-custom-600` | `dark:hover:text-blue-400` | Color al pasar el mouse |
+| **Focus** | `focus:text-primary-custom-600` | `dark:focus:text-blue-400` | Color al enfocar |
+| **Active** | `active:text-primary-custom-700` | `dark:active:text-blue-500` | Color al hacer clic |
+| **Disabled** | `text-content-tertiary` | `dark:text-dark-content-tertiary` | Color deshabilitado |
+| **Error** | `text-error-content` | `dark:text-red-400` | Color de error |
+| **Success** | `text-green-600` | `dark:text-green-400` | Color de éxito |
+
+### Implementación del Toggle Dark Mode
+
+#### Implementación Básica con JavaScript
+
+```typescript
+// utils/darkMode.ts
+export const toggleDarkMode = () => {
+  const isDark = document.documentElement.classList.contains('dark');
+
+  if (isDark) {
+    document.documentElement.classList.remove('dark');
+    localStorage.setItem('theme', 'light');
+  } else {
+    document.documentElement.classList.add('dark');
+    localStorage.setItem('theme', 'dark');
+  }
+};
+
+// Cargar el tema al iniciar la aplicación
+export const loadTheme = () => {
+  const savedTheme = localStorage.getItem('theme');
+  const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+
+  if (savedTheme === 'dark' || (!savedTheme && prefersDark)) {
+    document.documentElement.classList.add('dark');
+  } else {
+    document.documentElement.classList.remove('dark');
+  }
+};
+```
+
+#### Prevenir Flash de Contenido (FOUC)
+
+Añadir este script en el `<head>` del HTML antes de que React se cargue:
+
+```html
+<!-- index.html -->
+<head>
+  <script>
+    // Aplicar tema inmediatamente antes del render
+    (function() {
+      const theme = localStorage.getItem('theme');
+      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+
+      if (theme === 'dark' || (!theme && prefersDark)) {
+        document.documentElement.classList.add('dark');
+      }
+    })();
+  </script>
+</head>
+```
+
+### Ejemplos Completos
+
+#### Ejemplo 1: Toolbar de Iconos con Dark Mode
+
+```tsx
+import { Button } from '@/components/Button';
+import { PlusIcon, CheckIcon, XIcon } from '@/components/Button/icons';
+
+export const IconToolbar = () => {
+  return (
+    <div className="
+      flex gap-2 p-4
+      bg-white dark:bg-dark-bg-primary
+      border-b border-border-primary dark:border-dark-border-primary
+    ">
+      {/* Icono con hover adaptado */}
+      <Button
+        iconOnly
+        type="outline"
+        leftIcon={<PlusIcon />}
+        ariaLabel="Añadir"
+        className="
+          text-content-primary dark:text-dark-content-primary
+          hover:text-primary-custom-600 dark:hover:text-blue-400
+          hover:bg-gray-100 dark:hover:bg-gray-800
+        "
+      />
+
+      {/* Icono de éxito */}
+      <Button
+        iconOnly
+        type="outline"
+        leftIcon={<CheckIcon />}
+        ariaLabel="Guardar"
+        className="
+          text-green-600 dark:text-green-400
+          hover:text-green-700 dark:hover:text-green-300
+          hover:bg-green-50 dark:hover:bg-green-900/20
+        "
+      />
+
+      {/* Icono de error */}
+      <Button
+        iconOnly
+        type="outline"
+        leftIcon={<XIcon />}
+        ariaLabel="Cancelar"
+        className="
+          text-error-content dark:text-red-400
+          hover:text-red-700 dark:hover:text-red-300
+          hover:bg-red-50 dark:hover:bg-red-900/20
+        "
+      />
+    </div>
+  );
+};
+```
+
+#### Ejemplo 2: Formulario con Iconos Adaptativos
+
+```tsx
+import { Input } from '@/components/Input';
+import { UserIcon, LockClosedIcon, EnvelopeIcon } from '@/components/Input/icons';
+import { Button } from '@/components/Button';
+import { ArrowRightIcon, CheckIcon } from '@/components/Button/icons';
+
+export const AdaptiveForm = () => {
+  return (
+    <div className="
+      w-full max-w-md p-6
+      bg-white dark:bg-dark-bg-primary
+      border border-border-primary dark:border-dark-border-primary
+      rounded-2xl
+      shadow-base dark:shadow-lg
+    ">
+      <h2 className="
+        mb-6
+        text-content-primary dark:text-dark-content-primary
+        font-bold text-xl
+      ">
+        Iniciar Sesión
+      </h2>
+
+      <form className="space-y-4">
+        {/* Input de email con icono */}
+        <Input
+          label="Correo Electrónico"
+          type="email"
+          leftIcon={
+            <EnvelopeIcon className="
+              text-content-secondary dark:text-dark-content-secondary
+            " />
+          }
+          placeholder="tu@email.com"
+          className="
+            text-content-primary dark:text-dark-content-primary
+            bg-bg-primary dark:bg-dark-bg-secondary
+            border-border-primary dark:border-dark-border-primary
+            focus:border-primary-custom-600 dark:focus:border-blue-400
+          "
+        />
+
+        {/* Input de usuario con icono */}
+        <Input
+          label="Usuario"
+          leftIcon={
+            <UserIcon className="
+              text-content-secondary dark:text-dark-content-secondary
+            " />
+          }
+          placeholder="Tu usuario"
+          className="
+            text-content-primary dark:text-dark-content-primary
+            bg-bg-primary dark:bg-dark-bg-secondary
+          "
+        />
+
+        {/* Input de contraseña con icono */}
+        <Input
+          label="Contraseña"
+          type="password"
+          leftIcon={
+            <LockClosedIcon className="
+              text-content-secondary dark:text-dark-content-secondary
+            " />
+          }
+          placeholder="Tu contraseña"
+          className="
+            text-content-primary dark:text-dark-content-primary
+            bg-bg-primary dark:bg-dark-bg-secondary
+          "
+        />
+
+        {/* Botón de submit con icono */}
+        <Button
+          type="default"
+          fullWidth
+          rightIcon={<ArrowRightIcon />}
+          className="
+            bg-primary-custom-600 dark:bg-dark-bg-inverse
+            text-primary-inverse-content dark:text-dark-content-inverse
+            hover:bg-primary-custom-500 dark:hover:bg-dark-bg-inverse/90
+          "
+        >
+          Continuar
+        </Button>
+      </form>
+    </div>
+  );
+};
+```
+
+#### Ejemplo 3: Status Icons con Colores Adaptativos
+
+```tsx
+import { CheckIcon, ExclamationCircleIcon, XMarkIcon } from '@/components/Input/icons';
+
+export const StatusMessages = () => {
+  return (
+    <div className="space-y-3">
+      {/* Mensaje de éxito */}
+      <div className="
+        flex items-center gap-3 p-4
+        bg-green-50 dark:bg-green-900/20
+        border border-green-200 dark:border-green-800
+        rounded-lg
+      ">
+        <CheckIcon className="
+          w-5 h-5
+          text-green-600 dark:text-green-400
+        " />
+        <p className="
+          text-green-800 dark:text-green-300
+          font-medium
+        ">
+          Operación completada con éxito
+        </p>
+      </div>
+
+      {/* Mensaje de advertencia */}
+      <div className="
+        flex items-center gap-3 p-4
+        bg-yellow-50 dark:bg-yellow-900/20
+        border border-yellow-200 dark:border-yellow-800
+        rounded-lg
+      ">
+        <ExclamationCircleIcon className="
+          w-5 h-5
+          text-yellow-600 dark:text-yellow-400
+        " />
+        <p className="
+          text-yellow-800 dark:text-yellow-300
+          font-medium
+        ">
+          Advertencia: Revisa la información
+        </p>
+      </div>
+
+      {/* Mensaje de error */}
+      <div className="
+        flex items-center gap-3 p-4
+        bg-red-50 dark:bg-red-900/20
+        border border-red-200 dark:border-red-800
+        rounded-lg
+      ">
+        <XMarkIcon className="
+          w-5 h-5
+          text-error-content dark:text-red-400
+        " />
+        <p className="
+          text-red-800 dark:text-red-300
+          font-medium
+        ">
+          Error: No se pudo completar la operación
+        </p>
+      </div>
+    </div>
+  );
+};
+```
+
+#### Ejemplo 4: Icon Button con Group Hover
+
+```tsx
+import { ArrowRightIcon } from '@/components/Button/icons';
+
+export const NavigationCard = () => {
+  return (
+    <button className="
+      group
+      w-full p-6
+      bg-white dark:bg-dark-bg-primary
+      border border-border-primary dark:border-dark-border-primary
+      rounded-xl
+      hover:border-primary-custom-600 dark:hover:border-blue-400
+      hover:shadow-lg
+      transition-all
+      text-left
+    ">
+      <div className="flex items-center justify-between">
+        <div>
+          <h3 className="
+            mb-2
+            text-content-primary dark:text-dark-content-primary
+            font-bold text-lg
+            group-hover:text-primary-custom-600 dark:group-hover:text-blue-400
+          ">
+            Ir a la Configuración
+          </h3>
+          <p className="
+            text-content-secondary dark:text-dark-content-secondary
+            text-sm
+          ">
+            Administra las preferencias del sistema
+          </p>
+        </div>
+
+        {/* Icono que se anima y cambia de color en hover */}
+        <ArrowRightIcon className="
+          w-6 h-6
+          text-content-tertiary dark:text-dark-content-tertiary
+          group-hover:text-primary-custom-600 dark:group-hover:text-blue-400
+          group-hover:translate-x-1
+          transition-all
+        " />
+      </div>
+    </button>
+  );
+};
+```
+
+### Mejores Prácticas para Iconos en Dark Mode
+
+#### ✅ Hacer
+
+1. **Usar tokens semánticos que se adaptan automáticamente**
+   ```tsx
+   // ✅ CORRECTO - Los tokens ya incluyen dark mode
+   <UserIcon className="text-content-primary dark:text-dark-content-primary" />
+   ```
+
+2. **Aprovechar currentColor para heredar colores del padre**
+   ```tsx
+   // ✅ CORRECTO - El icono hereda el color
+   <div className="text-primary-custom-600 dark:text-blue-400">
+     <EnvelopeIcon />
+   </div>
+   ```
+
+3. **Usar colores más brillantes en dark mode**
+   ```tsx
+   // ✅ CORRECTO - Ajustar intensidad para dark mode
+   <CheckIcon className="text-green-600 dark:text-green-400" />
+   ```
+
+4. **Combinar con estados hover y focus**
+   ```tsx
+   // ✅ CORRECTO - Estados completos
+   <button className="
+     text-gray-700 dark:text-gray-300
+     hover:text-blue-600 dark:hover:text-blue-400
+   ">
+     <PlusIcon />
+   </button>
+   ```
+
+5. **Reducir opacidad de iconos secundarios en dark mode**
+   ```tsx
+   // ✅ CORRECTO - Jerarquía visual
+   <QuestionMarkCircleIcon className="
+     text-content-secondary/70 dark:text-dark-content-secondary/60
+   " />
+   ```
+
+#### ❌ Evitar
+
+1. **No usar el mismo color para light y dark mode**
+   ```tsx
+   // ❌ INCORRECTO - Sin dark variant
+   <UserIcon className="text-gray-900" />
+
+   // ✅ CORRECTO
+   <UserIcon className="text-gray-900 dark:text-gray-100" />
+   ```
+
+2. **No hardcodear colores sin considerar contraste**
+   ```tsx
+   // ❌ INCORRECTO - Pobre contraste en dark mode
+   <CheckIcon className="text-gray-300" />
+
+   // ✅ CORRECTO - Buen contraste en ambos modos
+   <CheckIcon className="text-green-600 dark:text-green-400" />
+   ```
+
+3. **No olvidar estados interactivos**
+   ```tsx
+   // ❌ INCORRECTO - Sin hover para dark mode
+   <button className="hover:text-blue-600">
+     <PlusIcon />
+   </button>
+
+   // ✅ CORRECTO
+   <button className="hover:text-blue-600 dark:hover:text-blue-400">
+     <PlusIcon />
+   </button>
+   ```
+
+4. **No usar colores muy oscuros en dark mode**
+   ```tsx
+   // ❌ INCORRECTO - Invisible en fondo oscuro
+   <XIcon className="text-gray-900 dark:text-gray-900" />
+
+   // ✅ CORRECTO - Visible en ambos modos
+   <XIcon className="text-gray-900 dark:text-gray-100" />
+   ```
+
+### Guía Rápida: Colores de Iconos por Contexto
+
+| Contexto | Light Mode | Dark Mode | Ejemplo |
+|----------|------------|-----------|---------|
+| **Icono Principal** | `text-content-primary` | `dark:text-dark-content-primary` | Iconos en botones principales |
+| **Icono Secundario** | `text-content-secondary` | `dark:text-dark-content-secondary` | Iconos decorativos |
+| **Icono Terciario** | `text-content-tertiary` | `dark:text-dark-content-tertiary` | Iconos de ayuda |
+| **Icono Interactivo** | `text-gray-700 hover:text-blue-600` | `dark:text-gray-300 dark:hover:text-blue-400` | Botones icon-only |
+| **Icono de Éxito** | `text-green-600` | `dark:text-green-400` | Check, confirmación |
+| **Icono de Error** | `text-error-content` | `dark:text-red-400` | X, advertencias |
+| **Icono de Info** | `text-blue-600` | `dark:text-blue-400` | Información, ayuda |
+| **Icono Deshabilitado** | `text-content-tertiary opacity-50` | `dark:text-dark-content-tertiary opacity-50` | Elementos inactivos |
+
+### Recursos Adicionales
+
+Para más información sobre el modo oscuro:
+- Ver `docs/dark-mode-guide.md` - Guía completa de Dark Mode en Tailwind CSS
+- Ver `docs/colors.md` - Sistema de colores completo con tokens dark mode
+- [Documentación oficial de Tailwind Dark Mode](https://tailwindcss.com/docs/dark-mode)
+
+---
+
+## Accesibilidad
+
+### Consideraciones de Accesibilidad
+
+#### 1. Iconos Decorativos
+
+Cuando el icono acompaña texto visible, es decorativo:
+
+```tsx
+// ✅ CORRECTO: El texto describe la acción
+<Button leftIcon={<PlusIcon />}>
+  Crear Usuario
+</Button>
+// No se necesita aria-label adicional
+```
+
+#### 2. Iconos Funcionales (Icon-Only)
+
+Cuando el icono es el único elemento visual:
+
+```tsx
+// ✅ CORRECTO: Usar aria-label
+<Button
+  iconOnly
+  leftIcon={<PlusIcon />}
+  ariaLabel="Añadir nuevo elemento"
+/>
+
+// ❌ INCORRECTO: Sin aria-label
+<Button iconOnly leftIcon={<PlusIcon />} />
+// Los lectores de pantalla no sabrán la función
+```
+
+#### 3. Iconos con Significado
+
+En contextos donde el icono comunica información:
+
+```tsx
+// ✅ CORRECTO: Añadir rol y aria-label
+<span role="img" aria-label="Estado: Exitoso">
+  <CheckIcon className="text-green-600" />
+</span>
+
+// ✅ CORRECTO: Con texto de soporte visible
+<div className="flex items-center gap-2">
+  <ExclamationCircleIcon className="text-error-content" />
+  <span>Error en la validación</span>
+</div>
+```
+
+#### 4. Tooltips para Contexto Adicional
+
+```tsx
+// ✅ MEJOR PRÁCTICA: Icono + Tooltip
+<button
+  className="p-2"
+  aria-label="Ayuda"
+  title="Obtener ayuda sobre este campo"
+>
+  <QuestionMarkCircleIcon />
+</button>
+```
+
+### Directrices WCAG 2.1
+
+- **Nivel A**: Todos los iconos funcionales deben tener texto alternativo
+- **Nivel AA**: Contraste mínimo 3:1 para iconos (se cumple con currentColor)
+- **Nivel AAA**: Proveer texto descriptivo adicional cuando sea posible
+
+---
+
+## Ejemplos de Código
+
+### Ejemplo 1: Toolbar de Acciones
+
+```tsx
+import { Button } from '@/components/Button';
+import { PlusIcon, CheckIcon, XIcon } from '@/components/Button/icons';
+
+export const ActionToolbar = () => {
+  return (
+    <div className="flex gap-2 p-4 bg-bg-primary border-b border-border-primary">
+      {/* Botones icon-only con tooltips */}
+      <Button
+        iconOnly
+        size="base"
+        type="default"
+        leftIcon={<PlusIcon />}
+        ariaLabel="Añadir nuevo registro"
+        title="Añadir nuevo registro"
+      />
+
+      <Button
+        iconOnly
+        size="base"
+        type="outline"
+        leftIcon={<CheckIcon />}
+        ariaLabel="Guardar cambios"
+        title="Guardar cambios"
+      />
+
+      <Button
+        iconOnly
+        size="base"
+        type="plain"
+        leftIcon={<XIcon />}
+        ariaLabel="Cancelar operación"
+        title="Cancelar operación"
+      />
+    </div>
+  );
+};
+```
+
+### Ejemplo 2: Formulario de Login
+
+```tsx
+import { Input } from '@/components/Input';
+import { Button } from '@/components/Button';
+import {
+  UserIcon,
+  LockClosedIcon,
+  EyeIcon,
+  EyeSlashIcon
+} from '@/components/Input/icons';
+import { ArrowRightIcon } from '@/components/Button/icons';
+import { useState } from 'react';
+
+export const LoginForm = () => {
+  const [showPassword, setShowPassword] = useState(false);
+
+  return (
+    <form className="space-y-4 w-full max-w-sm">
+      {/* Usuario */}
+      <Input
+        label="Usuario"
+        name="username"
+        leftIcon={<UserIcon />}
+        placeholder="Ingrese su usuario"
+        required
+      />
+
+      {/* Contraseña con toggle */}
+      <Input
+        label="Contraseña"
+        name="password"
+        type={showPassword ? 'text' : 'password'}
+        leftIcon={<LockClosedIcon />}
+        rightIcon={
+          <button
+            type="button"
+            onClick={() => setShowPassword(!showPassword)}
+            className="cursor-pointer"
+            aria-label={showPassword ? 'Ocultar contraseña' : 'Mostrar contraseña'}
+          >
+            {showPassword ? <EyeSlashIcon /> : <EyeIcon />}
+          </button>
+        }
+        placeholder="Ingrese su contraseña"
+        required
+      />
+
+      {/* Submit */}
+      <Button
+        type="default"
+        size="base"
+        fullWidth
+        rightIcon={<ArrowRightIcon />}
+        htmlType="submit"
+      >
+        Iniciar Sesión
+      </Button>
+    </form>
+  );
+};
+```
+
+### Ejemplo 3: Search Input con Estados
+
+```tsx
+import { Input } from '@/components/Input';
+import {
+  MagnifyingGlassIcon,
+  XMarkIcon,
+  CheckIcon,
+  ExclamationCircleIcon
+} from '@/components/Input/icons';
+import { useState } from 'react';
+
+export const SearchInput = () => {
+  const [query, setQuery] = useState('');
+  const [status, setStatus] = useState<'idle' | 'searching' | 'success' | 'error'>('idle');
+
+  const getStatusIcon = () => {
+    switch (status) {
+      case 'success':
+        return <CheckIcon className="text-green-600" />;
+      case 'error':
+        return <ExclamationCircleIcon className="text-error-content" />;
+      default:
+        return null;
+    }
+  };
+
+  return (
+    <div className="w-full max-w-md">
+      <Input
+        label="Búsqueda"
+        value={query}
+        onChange={(e) => setQuery(e.target.value)}
+        leftIcon={<MagnifyingGlassIcon />}
+        rightIcon={
+          query ? (
+            <button
+              type="button"
+              onClick={() => setQuery('')}
+              aria-label="Limpiar búsqueda"
+              className="cursor-pointer hover:text-primary-custom-600"
+            >
+              <XMarkIcon />
+            </button>
+          ) : (
+            getStatusIcon()
+          )
+        }
+        placeholder="Buscar..."
+        helperText={
+          status === 'error' ? 'No se encontraron resultados' : undefined
+        }
+        error={status === 'error'}
+      />
+    </div>
+  );
+};
+```
+
+---
+
+## Mejores Prácticas
+
+### ✅ Hacer
+
+1. **Usar iconos semánticamente apropiados**
+   ```tsx
+   // ✅ CORRECTO
+   <Button leftIcon={<PlusIcon />}>Añadir</Button>
+   <Button leftIcon={<CheckIcon />}>Guardar</Button>
+   ```
+
+2. **Mantener el tamaño de 16px en la mayoría de casos**
+   ```tsx
+   // ✅ CORRECTO - tamaño por defecto
+   <UserIcon className="w-4 h-4" />
+   ```
+
+3. **Usar currentColor para heredar el color del contexto**
+   ```tsx
+   // ✅ CORRECTO - el icono hereda el color
+   <div className="text-primary-custom-600">
+     <EnvelopeIcon />
+   </div>
+   ```
+
+4. **Proveer aria-label en botones icon-only**
+   ```tsx
+   // ✅ CORRECTO
+   <Button iconOnly leftIcon={<XIcon />} ariaLabel="Cerrar" />
+   ```
+
+5. **Agrupar iconos relacionados en el mismo archivo**
+   ```tsx
+   // ✅ CORRECTO - iconos de un componente juntos
+   // src/components/Button/icons.tsx
+   ```
+
+### ❌ Evitar
+
+1. **No mezclar diferentes estilos de iconos**
+   ```tsx
+   // ❌ INCORRECTO - mezclar Heroicons con otros
+   <PlusIcon /> {/* Heroicons Micro */}
+   <SomeOtherIcon /> {/* Otra librería */}
+   ```
+
+2. **No usar tamaños inconsistentes sin razón**
+   ```tsx
+   // ❌ INCORRECTO - tamaños arbitrarios
+   <UserIcon className="w-7 h-7" />
+   <EnvelopeIcon className="w-3 h-3" />
+   ```
+
+3. **No hardcodear colores directamente en el SVG**
+   ```tsx
+   // ❌ INCORRECTO - hardcodear fill
+   <svg fill="#0e79fd">...</svg>
+
+   // ✅ CORRECTO - usar currentColor
+   <svg fill="currentColor">...</svg>
+   ```
+
+4. **No omitir aria-label en iconos funcionales**
+   ```tsx
+   // ❌ INCORRECTO
+   <button><XIcon /></button>
+
+   // ✅ CORRECTO
+   <button aria-label="Cerrar"><XIcon /></button>
+   ```
+
+5. **No usar iconos como única forma de comunicación**
+   ```tsx
+   // ❌ INCORRECTO - solo icono sin contexto
+   <div><ExclamationCircleIcon /></div>
+
+   // ✅ CORRECTO - icono + texto
+   <div className="flex gap-2">
+     <ExclamationCircleIcon />
+     <span>Error: Campo requerido</span>
+   </div>
+   ```
+
+### Rendimiento
+
+- **✅ SVG Inline**: Mejor para iconos que se usan frecuentemente
+- **✅ Tree-shaking**: Importar solo los iconos necesarios
+- **✅ Evitar re-renders**: Los iconos son componentes puros
+- **✅ Memoización**: React.memo si se pasan como props frecuentemente
+
+```tsx
+// ✅ CORRECTO - memoizar icono si se pasa como prop
+const MemoizedIcon = React.memo(PlusIcon);
+
+// En componente padre
+<Button leftIcon={<MemoizedIcon />}>Añadir</Button>
+```
+
+---
+
+## Referencia Rápida
+
+### Cheat Sheet: Importaciones
+
+```typescript
+// Iconos de Button
+import {
+  PlusIcon,           // Añadir/Crear
+  ChevronDownIcon,    // Dropdown
+  ArrowRightIcon,     // Navegación
+  CheckIcon,          // Confirmar
+  XIcon              // Cerrar/Cancelar
+} from '@/components/Button/icons';
+
+// Iconos de Input
+import {
+  EnvelopeIcon,             // Email
+  QuestionMarkCircleIcon,   // Ayuda
+  UserIcon,                 // Usuario
+  LockClosedIcon,           // Seguridad
+  MagnifyingGlassIcon,      // Búsqueda
+  EyeIcon,                  // Ver password
+  EyeSlashIcon,             // Ocultar password
+  XMarkIcon,                // Limpiar
+  CheckIcon,                // Éxito
+  ExclamationCircleIcon     // Error
+} from '@/components/Input/icons';
+```
+
+### Cheat Sheet: Tamaños Comunes
+
+| Clase Tailwind | Tamaño | Uso |
+|----------------|--------|-----|
+| `w-4 h-4` | 16px | **Default** - Botones, inputs |
+| `w-5 h-5` | 20px | Iconos destacados |
+| `w-6 h-6` | 24px | Headers, títulos |
+| `w-8 h-8` | 32px | Iconos grandes, heros |
+
+### Cheat Sheet: Colores Comunes
+
+```tsx
+// Primary
+<Icon className="text-primary-custom-600" />
+
+// Éxito (Verde)
+<CheckIcon className="text-green-600" />
+
+// Error (Rojo)
+<ExclamationCircleIcon className="text-error-content" />
+
+// Secundario (Gris)
+<Icon className="text-content-secondary" />
+
+// Dark Mode (automático)
+<Icon className="text-content-primary dark:text-dark-content-primary" />
+```
+
+### Cheat Sheet: Patrones de Uso
+
+```tsx
+// 1. Icon-only Button
+<Button iconOnly leftIcon={<PlusIcon />} ariaLabel="Añadir" />
+
+// 2. Button con texto e icono
+<Button leftIcon={<CheckIcon />}>Guardar</Button>
+
+// 3. Input con icono
+<Input leftIcon={<UserIcon />} placeholder="Usuario" />
+
+// 4. Toggle icon
+{visible ? <EyeIcon /> : <EyeSlashIcon />}
+
+// 5. Status icon
+{status === 'success' ? <CheckIcon /> : <ExclamationCircleIcon />}
+```
+
+---
+
+## Añadir Nuevos Iconos
+
+### Proceso para Agregar un Icono
+
+1. **Obtener el SVG de Heroicons Micro**
+   - Visitar: https://heroicons.com
+   - Seleccionar versión "Micro" (16px)
+   - Copiar el código SVG
+
+2. **Crear el Componente React**
+   ```tsx
+   // En el archivo icons.tsx correspondiente
+   export const NewIcon: React.FC<IconProps> = ({ className = '' }) => (
+     <svg
+       xmlns="http://www.w3.org/2000/svg"
+       viewBox="0 0 16 16"
+       fill="currentColor"
+       className={className}
+     >
+       {/* Pegar path(s) del SVG */}
+       <path d="..." />
+     </svg>
+   );
+   ```
+
+3. **Documentar el Nuevo Icono**
+   - Añadir a la tabla de catálogo
+   - Incluir ejemplo de uso
+   - Especificar contexto apropiado
+
+4. **Testing**
+   - Verificar en modo claro y oscuro
+   - Probar diferentes tamaños
+   - Validar accesibilidad
+
+### Decisiones de Organización
+
+- **¿Dónde colocar el nuevo icono?**
+  - ¿Se usa en Button? → `src/components/Button/icons.tsx`
+  - ¿Se usa en Input? → `src/components/Input/icons.tsx`
+  - ¿Se usa en múltiples componentes? → Crear `src/shared/icons.tsx`
+
+---
+
+## Recursos Adicionales
+
+### Enlaces Útiles
+
+- **Heroicons**: https://heroicons.com
+- **Documentación Heroicons**: https://github.com/tailwindlabs/heroicons
+- **WCAG Guidelines**: https://www.w3.org/WAI/WCAG21/quickref/
+- **SVG Accessibility**: https://css-tricks.com/accessible-svgs/
+
+### Archivos Relacionados
+
+- `src/components/Button/icons.tsx` - Iconos de botones
+- `src/components/Input/icons.tsx` - Iconos de inputs
+- `src/components/Button/Button.tsx` - Implementación de iconos en Button
+- `docs/colors.md` - Sistema de colores (para colores de iconos)
+- `docs/typography.md` - Sistema tipográfico
+
+---
+
+**Última actualización**: 2025-11-11
+**Versión**: 1.0.0
+**Mantenedor**: Siesa UI Kit Team