siesa-ui-kit 1.0.5 → 1.0.7

package/docs/shadows.md

@@ -1,1377 +0,0 @@
-# Sistema de Sombras (Shadows) - Siesa UI Kit
-
-## 📋 Tabla de Contenidos
-
-1. [Introducción](#introducción)
-2. [Drop Shadows](#drop-shadows)
-3. [Inner Shadows](#inner-shadows)
-4. [Sombras Personalizadas](#sombras-personalizadas)
-5. [Guía de Uso](#guía-de-uso)
-6. [Componentes del Sistema](#componentes-del-sistema)
-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 sombras de Siesa UI Kit proporciona profundidad y jerarquía visual a los componentes de la interfaz. Las sombras ayudan a establecer la elevación de elementos y mejorar la experiencia del usuario al crear una interfaz más intuitiva y dimensional.
-
-### Objetivos del Sistema
-
-- **Jerarquía Visual**: Establecer niveles de elevación claros entre componentes
-- **Profundidad**: Crear sensación de tridimensionalidad en interfaces planas
-- **Consistencia**: Uso uniforme de sombras en todo el sistema
-- **Sutileza**: Sombras suaves que no distraigan del contenido
-- **Accesibilidad**: Sombras que mejoren la usabilidad sin depender solo de ellas
-
-### Principios de Diseño
-
-1. **Elevación Progresiva**: Las sombras más grandes indican mayor elevación
-2. **Sutileza**: Sombras suaves con opacidad controlada (5% a 25%)
-3. **Múltiples Capas**: Combinación de sombras para efectos más naturales
-4. **Adaptabilidad**: Funciona en modo claro y oscuro
-
----
-
-## Drop Shadows
-
-Las **drop shadows** (sombras externas) se usan para elevar elementos sobre el fondo, creando la ilusión de que flotan.
-
-### Escala de Drop Shadows
-
-| Clase Tailwind | Valor CSS | Elevación | Uso Principal |
-|----------------|-----------|-----------|---------------|
-| `shadow-sm` | `0px 1px 2px 0px rgba(0,0,0,0.05)` | Muy baja | Bordes sutiles, separadores ligeros |
-| `shadow-base` | `0px 1px 2px -1px rgba(0,0,0,0.1), 0px 1px 3px 0px rgba(0,0,0,0.1)` | Baja | **Cards planos, inputs** |
-| `shadow-md` | `0px 2px 4px -2px rgba(0,0,0,0.1), 0px 4px 6px -1px rgba(0,0,0,0.1)` | Media-baja | Cards elevados, dropdowns |
-| `shadow-lg` | `0px 4px 6px -4px rgba(0,0,0,0.1), 0px 10px 15px -3px rgba(0,0,0,0.1)` | Media | **Modales, popovers** |
-| `shadow-xl` | `0px 8px 10px -6px rgba(0,0,0,0.1), 0px 20px 25px -5px rgba(0,0,0,0.1)` | Alta | Modales grandes, overlays |
-| `shadow-2xl` | `0px 25px 50px -12px rgba(0,0,0,0.25)` | Muy alta | Elementos flotantes principales |
-
-### Características de las Sombras
-
-**Sombras de Capas Múltiples**: La mayoría incluyen 2 sombras para un efecto más natural:
-- **Sombra principal**: Mayor blur, más alejada, simula luz ambiental
-- **Sombra de contacto**: Menor blur, más cercana, define los bordes
-
-**Opacidades Controladas**:
-- `0.05` (5%) - Sombras muy sutiles
-- `0.1` (10%) - Sombras estándar (más común)
-- `0.25` (25%) - Sombras dramáticas
-
-### Valores Más Comunes
-
-En el 80% de los casos, usarás estos 3 valores:
-
-1. **`shadow-base`**: Cards y paneles estándar
-2. **`shadow-lg`**: Modales y popovers
-3. **`shadow-xl`**: Overlays importantes
-
----
-
-## Inner Shadows
-
-Las **inner shadows** (sombras internas) crean la ilusión de profundidad hacia adentro, como si el elemento estuviera hundido.
-
-### Escala de Inner Shadows
-
-| Clase Tailwind | Valor CSS | Uso Principal |
-|----------------|-----------|---------------|
-| `shadow-inner` | `inset 0 2px 4px 0 rgba(0,0,0,0.05)` | Inputs hundidos, áreas presionadas |
-
-### Sombra Inner Personalizada
-
-El sistema incluye una sombra inner especial para botones:
-
-| Nombre | Valor CSS | Uso |
-|--------|-----------|-----|
-| `shadow-button-inset` | `0px 2px 0px 0px inset rgba(255,255,255,0.15)` | **Botones default** - Efecto de brillo superior |
-
-**Nota**: Esta sombra usa **blanco** con 15% de opacidad para crear un efecto de luz desde arriba, dando dimensión a los botones.
-
----
-
-## Sombras Personalizadas
-
-Además de las sombras estándar de Tailwind, el sistema incluye sombras personalizadas para casos específicos.
-
-### Tabla de Sombras Personalizadas
-
-| Nombre | Clase | Valor CSS | Uso |
-|--------|-------|-----------|-----|
-| **Button Inset** | `shadow-button-inset` | `0px 2px 0px 0px inset rgba(255,255,255,0.15)` | Botones default |
-| **Menu** | `shadow-menu` | `0px 4px 4px -1px rgba(12,12,13,0.05), 0px 4px 4px -1px rgba(12,12,13,0.1)` | Menús desplegables, dropdowns |
-| **Base** | `shadow-base` | `0px 1px 2px -1px rgba(0,0,0,0.1), 0px 1px 3px 0px rgba(0,0,0,0.1)` | Cards estándar |
-
-### Configuración en Tailwind
-
-```javascript
-// tailwind.config.js
-boxShadow: {
-  // Personalizada para botones (inner shadow)
-  'button-inset': '0px 2px 0px 0px inset rgba(255,255,255,0.15)',
-
-  // Personalizada para menús
-  'menu': '0px 4px 4px -1px rgba(12, 12, 13, 0.05), 0px 4px 4px -1px rgba(12, 12, 13, 0.1)',
-}
-```
-
----
-
-## Guía de Uso
-
-### Por Tipo de Componente
-
-#### 1. Botones
-
-```tsx
-// Botón default con sombra interna
-<button className="rounded-md bg-primary-custom-600 text-white px-4 py-2 shadow-button-inset">
-  Guardar
-</button>
-
-// Botón elevado con sombra externa
-<button className="rounded-md bg-white border px-4 py-2 shadow-base hover:shadow-md transition-shadow">
-  Cancelar
-</button>
-```
-
-**Recomendación**:
-- Botones default (rellenos): `shadow-button-inset`
-- Botones outline (sin fondo): `shadow-base` en hover
-
-#### 2. Cards
-
-```tsx
-// Card plano - shadow-base
-<div className="rounded-2xl border bg-white p-6 shadow-base">
-  <h3>Card Estándar</h3>
-  <p>Contenido...</p>
-</div>
-
-// Card elevado - shadow-md
-<div className="rounded-2xl bg-white p-6 shadow-md">
-  <h3>Card Destacado</h3>
-  <p>Contenido importante...</p>
-</div>
-
-// Card flotante - shadow-lg
-<div className="rounded-2xl bg-white p-6 shadow-lg">
-  <h3>Card Flotante</h3>
-  <p>Elemento prominente...</p>
-</div>
-```
-
-**Recomendación**:
-- Cards de lista: `shadow-base`
-- Cards destacados: `shadow-md`
-- Cards sobre overlay: `shadow-lg` o `shadow-xl`
-
-#### 3. Modales y Overlays
-
-```tsx
-// Modal pequeño - shadow-lg
-<div className="rounded-3xl bg-white p-6 shadow-lg max-w-md">
-  <h2>Modal Pequeño</h2>
-  <p>Contenido...</p>
-</div>
-
-// Modal grande - shadow-xl
-<div className="rounded-3xl bg-white p-8 shadow-xl max-w-2xl">
-  <h2>Modal Grande</h2>
-  <p>Contenido extenso...</p>
-</div>
-
-// Drawer/Panel lateral - shadow-2xl
-<div className="fixed right-0 top-0 h-full bg-white p-6 shadow-2xl w-96">
-  <h2>Panel Lateral</h2>
-  <p>Contenido...</p>
-</div>
-```
-
-**Recomendación**:
-- Modales pequeños: `shadow-lg`
-- Modales grandes: `shadow-xl`
-- Drawers/Panels: `shadow-2xl`
-
-#### 4. Dropdowns y Menus
-
-```tsx
-// Dropdown simple - shadow-menu
-<div className="rounded-lg bg-white border shadow-menu">
-  <ul>
-    <li className="px-4 py-2 hover:bg-gray-100">Opción 1</li>
-    <li className="px-4 py-2 hover:bg-gray-100">Opción 2</li>
-  </ul>
-</div>
-
-// Menú contextual - shadow-md
-<div className="rounded-xl bg-white shadow-md">
-  <ul className="py-2">
-    <li className="px-4 py-2 hover:bg-gray-100">Editar</li>
-    <li className="px-4 py-2 hover:bg-gray-100">Eliminar</li>
-  </ul>
-</div>
-```
-
-**Recomendación**:
-- Dropdowns estándar: `shadow-menu`
-- Menús contextuales: `shadow-md`
-- Select expandido: `shadow-lg`
-
-#### 5. Inputs y Controles
-
-```tsx
-// Input enfocado - shadow-base
-<input
-  type="text"
-  className="rounded-md border px-4 py-2 focus:shadow-base transition-shadow"
-  placeholder="Email"
-/>
-
-// Input con error - shadow-base + borde rojo
-<input
-  type="text"
-  className="rounded-md border border-error-border px-4 py-2 shadow-base"
-  placeholder="Email"
-/>
-
-// Input hundido (inner shadow)
-<input
-  type="text"
-  className="rounded-md border bg-gray-50 px-4 py-2 shadow-inner"
-  placeholder="Búsqueda"
-  readOnly
-/>
-```
-
-**Recomendación**:
-- Input normal: sin sombra
-- Input focus: `shadow-base`
-- Input disabled/readonly: `shadow-inner`
-
-#### 6. Tooltips y Popovers
-
-```tsx
-// Tooltip - shadow-lg
-<div className="rounded-lg bg-gray-900 text-white px-3 py-2 text-sm shadow-lg">
-  Este es un tooltip
-</div>
-
-// Popover - shadow-xl
-<div className="rounded-xl bg-white border p-4 shadow-xl max-w-xs">
-  <h4 className="font-bold mb-2">Información</h4>
-  <p className="text-sm">Contenido del popover...</p>
-</div>
-```
-
-**Recomendación**:
-- Tooltips simples: `shadow-lg`
-- Popovers con contenido: `shadow-xl`
-
-### Por Elevación
-
-| Elevación | Shadow | Cuándo Usar |
-|-----------|--------|-------------|
-| **Nivel 0** | Sin sombra | Elementos integrados, fondos |
-| **Nivel 1** | `shadow-sm` | Separadores sutiles, bordes suaves |
-| **Nivel 2** | `shadow-base` | **Cards estándar, inputs focus** |
-| **Nivel 3** | `shadow-md` | Cards elevados, dropdowns |
-| **Nivel 4** | `shadow-lg` | **Modales pequeños, popovers** |
-| **Nivel 5** | `shadow-xl` | Modales grandes, overlays |
-| **Nivel 6** | `shadow-2xl` | Drawers, panels laterales |
-
-### Transiciones de Sombra
-
-Las sombras pueden animarse para crear interacciones fluidas:
-
-```tsx
-// Hover que eleva el card
-<div className="rounded-2xl bg-white p-6 shadow-base hover:shadow-lg transition-shadow duration-200">
-  Card Interactivo
-</div>
-
-// Botón que se hunde al hacer click
-<button className="rounded-md bg-primary-custom-600 px-4 py-2 shadow-md active:shadow-sm transition-shadow">
-  Click me
-</button>
-
-// Card que se expande
-<div className="rounded-2xl bg-white p-6 shadow-base hover:scale-105 hover:shadow-xl transition-all duration-300">
-  Card con efecto
-</div>
-```
-
----
-
-## Componentes del Sistema
-
-### Uso Actual en Componentes
-
-| Componente | Shadow Usada | Ubicación |
-|------------|--------------|-----------|
-| **Button (default)** | `shadow-button-inset` | Button.tsx:67 |
-| **Card** | `shadow-base` o `shadow-md` | (a implementar) |
-| **Modal** | `shadow-lg` o `shadow-xl` | (a implementar) |
-| **Dropdown** | `shadow-menu` o `shadow-md` | (a implementar) |
-| **Tooltip** | `shadow-lg` | (a implementar) |
-| **Input (focus)** | `shadow-base` | (a implementar) |
-
-### Configuración Completa
-
-```javascript
-// tailwind.config.js
-module.exports = {
-  theme: {
-    extend: {
-      boxShadow: {
-        // Sombras personalizadas
-        'button-inset': '0px 2px 0px 0px inset rgba(255,255,255,0.15)',
-        'menu': '0px 4px 4px -1px rgba(12, 12, 13, 0.05), 0px 4px 4px -1px rgba(12, 12, 13, 0.1)',
-
-        // Tailwind defaults (para referencia)
-        'sm': '0 1px 2px 0 rgba(0, 0, 0, 0.05)',
-        'DEFAULT': '0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px -1px rgba(0, 0, 0, 0.1)',
-        'md': '0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -2px rgba(0, 0, 0, 0.1)',
-        'lg': '0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -4px rgba(0, 0, 0, 0.1)',
-        'xl': '0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 8px 10px -6px rgba(0, 0, 0, 0.1)',
-        '2xl': '0 25px 50px -12px rgba(0, 0, 0, 0.25)',
-        'inner': 'inset 0 2px 4px 0 rgba(0, 0, 0, 0.05)',
-        'none': 'none',
-      }
-    }
-  }
-}
-```
-
----
-
-## Ejemplos de Código
-
-### Ejemplo 1: Sistema de Cards con Diferentes Elevaciones
-
-```tsx
-export const CardShowcase = () => {
-  return (
-    <div className="grid grid-cols-3 gap-6 p-8">
-      {/* Card Plano - Nivel 2 */}
-      <div className="rounded-2xl border border-border-primary bg-white p-6 shadow-base">
-        <h3 className="text-xl font-bold mb-2">Card Plano</h3>
-        <p className="text-sm text-content-secondary">
-          Sombra sutil para cards en lista o grids.
-        </p>
-        <span className="inline-block mt-4 text-xs font-bold text-content-tertiary">
-          shadow-base
-        </span>
-      </div>
-
-      {/* Card Elevado - Nivel 3 */}
-      <div className="rounded-2xl bg-white p-6 shadow-md">
-        <h3 className="text-xl font-bold mb-2">Card Elevado</h3>
-        <p className="text-sm text-content-secondary">
-          Mayor elevación para cards destacados.
-        </p>
-        <span className="inline-block mt-4 text-xs font-bold text-content-tertiary">
-          shadow-md
-        </span>
-      </div>
-
-      {/* Card Flotante - Nivel 4 */}
-      <div className="rounded-2xl bg-white p-6 shadow-lg">
-        <h3 className="text-xl font-bold mb-2">Card Flotante</h3>
-        <p className="text-sm text-content-secondary">
-          Máxima elevación para elementos importantes.
-        </p>
-        <span className="inline-block mt-4 text-xs font-bold text-content-tertiary">
-          shadow-lg
-        </span>
-      </div>
-    </div>
-  );
-};
-```
-
-### Ejemplo 2: Modal con Overlay
-
-```tsx
-export const Modal = ({ isOpen, onClose, children, size = 'small' }) => {
-  if (!isOpen) return null;
-
-  const sizeClasses = {
-    small: 'max-w-md shadow-lg',
-    medium: 'max-w-2xl shadow-xl',
-    large: 'max-w-4xl shadow-2xl',
-  };
-
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
-      {/* Overlay - Sin sombra */}
-      <div
-        className="absolute inset-0 bg-black/50 backdrop-blur-sm"
-        onClick={onClose}
-      />
-
-      {/* Modal - Sombra según tamaño */}
-      <div className={`rounded-3xl bg-white relative z-10 ${sizeClasses[size]}`}>
-        {/* Header */}
-        <div className="flex items-center justify-between p-6 border-b border-border-primary">
-          <h2 className="text-2xl font-bold">Modal Title</h2>
-          <button
-            onClick={onClose}
-            className="rounded-full hover:bg-gray-100 p-2 transition-colors"
-          >
-            <XIcon />
-          </button>
-        </div>
-
-        {/* Body */}
-        <div className="p-6">{children}</div>
-
-        {/* Footer */}
-        <div className="flex gap-3 justify-end p-6 border-t border-border-primary">
-          <button
-            onClick={onClose}
-            className="rounded-md border border-border-primary bg-white px-4 py-2 font-bold hover:bg-gray-50 transition-colors"
-          >
-            Cancelar
-          </button>
-          <button className="rounded-md bg-primary-custom-600 text-white px-4 py-2 font-bold shadow-button-inset hover:bg-primary-custom-500 transition-colors">
-            Confirmar
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-};
-
-// Uso
-<Modal isOpen={true} size="medium">
-  <p>Contenido del modal...</p>
-</Modal>
-```
-
-### Ejemplo 3: Dropdown Menu
-
-```tsx
-export const DropdownMenu = ({ trigger, items }) => {
-  const [isOpen, setIsOpen] = useState(false);
-
-  return (
-    <div className="relative">
-      {/* Trigger */}
-      <button
-        onClick={() => setIsOpen(!isOpen)}
-        className="rounded-md border border-border-primary bg-white px-4 py-2 font-bold hover:bg-gray-50 transition-colors"
-      >
-        {trigger}
-      </button>
-
-      {/* Menu - shadow-menu personalizada */}
-      {isOpen && (
-        <div className="absolute top-full mt-2 right-0 rounded-lg bg-white border shadow-menu min-w-[200px] z-10">
-          <ul className="py-2">
-            {items.map((item, index) => (
-              <li key={index}>
-                <button
-                  onClick={() => {
-                    item.onClick();
-                    setIsOpen(false);
-                  }}
-                  className="w-full text-left px-4 py-2 text-sm hover:bg-gray-100 transition-colors"
-                >
-                  {item.icon && (
-                    <span className="inline-flex mr-3">{item.icon}</span>
-                  )}
-                  {item.label}
-                </button>
-              </li>
-            ))}
-          </ul>
-        </div>
-      )}
-    </div>
-  );
-};
-
-// Uso
-<DropdownMenu
-  trigger="Acciones"
-  items={[
-    { label: 'Editar', onClick: () => console.log('Editar'), icon: <EditIcon /> },
-    { label: 'Duplicar', onClick: () => console.log('Duplicar'), icon: <CopyIcon /> },
-    { label: 'Eliminar', onClick: () => console.log('Eliminar'), icon: <DeleteIcon /> },
-  ]}
-/>
-```
-
-### Ejemplo 4: Card Interactivo con Hover
-
-```tsx
-export const ProductCard = ({ product }) => {
-  return (
-    <div className="rounded-2xl bg-white overflow-hidden shadow-base hover:shadow-lg transition-all duration-300 hover:-translate-y-1 cursor-pointer">
-      {/* Imagen */}
-      <div className="aspect-square bg-gray-100">
-        <img
-          src={product.image}
-          alt={product.name}
-          className="w-full h-full object-cover"
-        />
-      </div>
-
-      {/* Contenido */}
-      <div className="p-6">
-        <div className="flex items-start justify-between mb-2">
-          <h3 className="text-xl font-bold text-content-primary">
-            {product.name}
-          </h3>
-          {product.badge && (
-            <span className="rounded px-2 py-1 text-xs font-bold bg-primary-custom-100 text-primary-custom-600">
-              {product.badge}
-            </span>
-          )}
-        </div>
-
-        <p className="text-sm text-content-secondary mb-4">
-          {product.description}
-        </p>
-
-        <div className="flex items-center justify-between">
-          <span className="text-2xl font-bold text-primary-custom-600">
-            ${product.price}
-          </span>
-          <button className="rounded-md bg-primary-custom-600 text-white px-4 py-2 text-sm font-bold shadow-button-inset hover:bg-primary-custom-500 transition-colors">
-            Añadir al carrito
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-};
-```
-
-### Ejemplo 5: Input States con Sombras
-
-```tsx
-export const InputWithStates = () => {
-  const [value, setValue] = useState('');
-  const [isFocused, setIsFocused] = useState(false);
-  const [hasError, setHasError] = useState(false);
-
-  return (
-    <div className="space-y-6 max-w-md">
-      {/* Input Normal */}
-      <div>
-        <label className="text-sm font-bold mb-2 block">Input Normal</label>
-        <input
-          type="text"
-          className="rounded-md border border-border-primary px-4 py-2 w-full transition-shadow"
-          placeholder="Sin foco, sin sombra"
-        />
-      </div>
-
-      {/* Input Focused */}
-      <div>
-        <label className="text-sm font-bold mb-2 block">Input con Focus</label>
-        <input
-          type="text"
-          className="rounded-md border border-border-primary px-4 py-2 w-full focus:shadow-base focus:border-primary-custom-400 focus:ring-2 focus:ring-primary-custom-400 transition-all"
-          placeholder="Click para ver shadow-base"
-        />
-      </div>
-
-      {/* Input con Error */}
-      <div>
-        <label className="text-sm font-bold mb-2 block">Input con Error</label>
-        <input
-          type="text"
-          className="rounded-md border-2 border-error-border px-4 py-2 w-full shadow-base"
-          placeholder="Con error"
-        />
-        <p className="text-xs text-error-content mt-1">
-          Este campo es requerido
-        </p>
-      </div>
-
-      {/* Input Disabled */}
-      <div>
-        <label className="text-sm font-bold mb-2 block text-content-tertiary">
-          Input Disabled
-        </label>
-        <input
-          type="text"
-          className="rounded-md border border-border-primary bg-gray-50 px-4 py-2 w-full shadow-inner cursor-not-allowed"
-          placeholder="Deshabilitado"
-          disabled
-        />
-      </div>
-    </div>
-  );
-};
-```
-
----
-
-## Mejores Prácticas
-
-### ✅ Hacer
-
-1. **Usar elevación apropiada según importancia**
-   ```tsx
-   // ✅ CORRECTO - Jerarquía clara
-   <div className="shadow-base">Card normal</div>
-   <div className="shadow-lg">Modal importante</div>
-   ```
-
-2. **Combinar con transiciones para interacciones suaves**
-   ```tsx
-   // ✅ CORRECTO - Transición fluida
-   <div className="shadow-base hover:shadow-md transition-shadow duration-200">
-     Card interactivo
-   </div>
-   ```
-
-3. **Usar sombras en conjunto con border-radius**
-   ```tsx
-   // ✅ CORRECTO - Sombra + bordes redondeados
-   <div className="rounded-2xl shadow-base">
-     Card con bordes suaves
-   </div>
-   ```
-
-4. **Aplicar sombras internas para elementos hundidos**
-   ```tsx
-   // ✅ CORRECTO - Input con apariencia hundida
-   <input className="rounded-md border bg-gray-50 shadow-inner" readOnly />
-   ```
-
-5. **Usar sombras personalizadas para casos específicos**
-   ```tsx
-   // ✅ CORRECTO - Sombra personalizada de botón
-   <button className="rounded-md bg-primary-custom-600 shadow-button-inset">
-     Botón Default
-   </button>
-   ```
-
-### ❌ Evitar
-
-1. **No usar sombras muy oscuras o exageradas**
-   ```tsx
-   // ❌ INCORRECTO - Sombra demasiado dramática
-   <div style={{ boxShadow: '0 10px 50px rgba(0,0,0,0.8)' }}>
-     Sombra exagerada
-   </div>
-
-   // ✅ CORRECTO - Sombra sutil del sistema
-   <div className="shadow-lg">Sombra apropiada</div>
-   ```
-
-2. **No apilar múltiples elementos con sombras grandes**
-   ```tsx
-   // ❌ INCORRECTO - Demasiadas sombras compiten
-   <div className="shadow-2xl">
-     <div className="shadow-2xl">
-       <div className="shadow-2xl">Contenido</div>
-     </div>
-   </div>
-
-   // ✅ CORRECTO - Solo el contenedor tiene sombra
-   <div className="shadow-2xl">
-     <div>
-       <div>Contenido</div>
-     </div>
-   </div>
-   ```
-
-3. **No usar sombras en elementos muy pequeños**
-   ```tsx
-   // ❌ INCORRECTO - Badge pequeño con sombra grande
-   <span className="text-xs px-2 py-0.5 shadow-xl">Badge</span>
-
-   // ✅ CORRECTO - Sin sombra o sombra mínima
-   <span className="text-xs px-2 py-0.5 rounded bg-blue-100">Badge</span>
-   ```
-
-4. **No omitir transiciones en cambios de sombra**
-   ```tsx
-   // ❌ INCORRECTO - Cambio abrupto
-   <div className="shadow-base hover:shadow-xl">Card</div>
-
-   // ✅ CORRECTO - Con transición
-   <div className="shadow-base hover:shadow-xl transition-shadow">Card</div>
-   ```
-
-5. **No usar sombras como único indicador de interactividad**
-   ```tsx
-   // ❌ INCORRECTO - Solo sombra para hover
-   <button className="hover:shadow-lg">Click</button>
-
-   // ✅ CORRECTO - Múltiples indicadores
-   <button className="rounded-md bg-primary-custom-600 hover:bg-primary-custom-500 hover:shadow-lg transition-all">
-     Click
-   </button>
-   ```
-
-### Accesibilidad
-
-1. **No depender solo de sombras para comunicar estados**
-   - Combinar con colores, bordes, iconos
-   - Las sombras pueden no ser visibles en todos los contextos
-
-2. **Asegurar contraste suficiente**
-   - Las sombras no deben reducir el contraste del texto
-   - Verificar WCAG 2.1 AA (4.5:1 para texto normal)
-
-3. **Considerar usuarios con baja visión**
-   - Sombras muy sutiles pueden no ser percibidas
-   - Usar indicadores adicionales para estados importantes
-
-4. **Dark Mode**
-   - Las sombras negras funcionan bien en fondos claros y oscuros
-   - No necesitas sombras diferentes para dark mode en la mayoría de casos
-
-### Performance
-
-1. **Las sombras CSS son eficientes**
-   - ✅ No requieren imágenes adicionales
-   - ✅ Son hardware-accelerated en la mayoría de navegadores
-
-2. **Evitar blur excesivo**
-   - Valores de blur muy altos pueden impactar performance
-   - El sistema usa valores optimizados (1px a 50px)
-
-3. **Animar solo transform y opacity cuando sea posible**
-   ```tsx
-   // ✅ MEJOR PERFORMANCE - Animar transform
-   <div className="shadow-base hover:scale-105 transition-transform">
-     Card
-   </div>
-
-   // ⚠️ ACEPTABLE - Animar shadow
-   <div className="shadow-base hover:shadow-lg transition-shadow">
-     Card
-   </div>
-   ```
-
----
-
-## Dark Mode
-
-Las sombras en dark mode requieren consideraciones especiales para mantener la profundidad visual sin que las sombras negras se vuelvan invisibles sobre fondos oscuros.
-
-### 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.
-
-#### Principios para Sombras en Dark Mode
-
-```tsx
-// Patrón básico - Sombras funcionan bien en ambos modos
-<div className="rounded-2xl bg-white dark:bg-dark-bg-primary shadow-base p-6">
-  Card con sombra adaptable
-</div>
-
-// Las sombras negras (rgba(0,0,0,...)) funcionan bien en ambos modos
-// porque el contraste se mantiene sobre fondos oscuros
-```
-
-**Nota Importante**: Las sombras negras con opacidad baja (5%-10%) funcionan bien tanto en fondos claros como oscuros, por lo que **generalmente NO necesitas cambiar las sombras en dark mode**.
-
-### Cuándo Ajustar Sombras en Dark Mode
-
-Hay casos específicos donde puedes querer ajustar las sombras:
-
-#### 1. Aumentar Opacidad en Dark Mode
-
-Para elementos que necesitan destacarse más en dark mode:
-
-```tsx
-// Aumentar intensidad de sombra en dark mode
-<div className="
-  rounded-2xl
-  bg-white dark:bg-dark-bg-primary
-  shadow-base dark:shadow-lg
-  p-6
-">
-  Card con sombra más intensa en dark mode
-</div>
-
-// Modal que necesita más prominencia en dark mode
-<div className="
-  rounded-3xl
-  bg-white dark:bg-dark-bg-primary
-  shadow-xl dark:shadow-2xl
-  p-8
-">
-  Modal destacado en dark mode
-</div>
-```
-
-#### 2. Sombras de Color en Dark Mode
-
-Sombras de color (para efectos especiales) pueden necesitar ajuste:
-
-```tsx
-// Sombra de color ajustada para dark mode
-<button className="
-  rounded-md
-  bg-primary-custom-600 dark:bg-dark-bg-inverse
-  shadow-[0_4px_14px_0_rgba(14,121,253,0.4)]
-  dark:shadow-[0_4px_14px_0_rgba(147,209,253,0.3)]
-  px-4 py-2
-">
-  Botón con sombra de color
-</button>
-```
-
-### Combinando Sombras con Otros Estados
-
-El modificador `dark:` se puede combinar con hover, focus, y otros estados:
-
-```tsx
-// Dark mode + Hover
-<div className="
-  rounded-2xl
-  bg-white dark:bg-dark-bg-primary
-  shadow-base dark:shadow-md
-  hover:shadow-lg dark:hover:shadow-xl
-  transition-shadow
-  p-6
-">
-  Card con hover effect en ambos modos
-</div>
-
-// Dark mode + Focus en inputs
-<input className="
-  rounded-md
-  border border-border-primary dark:border-dark-border-primary
-  focus:shadow-lg dark:focus:shadow-xl
-  focus:ring-2 focus:ring-primary-custom-400/20 dark:focus:ring-dark-border-custom/20
-" />
-```
-
-### Orden de Modificadores
-
-Tailwind CSS recomienda un orden específico:
-
-**Formato**: `{responsive}:{dark}:{state}:{utility}`
-
-```tsx
-// ✅ CORRECTO - Orden: responsive → dark → state → utility
-<div className="
-  shadow-base
-  md:shadow-md
-  md:dark:shadow-lg
-  md:dark:hover:shadow-xl
-  transition-shadow
-">
-  Card con orden correcto
-</div>
-
-// ❌ INCORRECTO - Orden equivocado
-<div className="
-  dark:md:hover:shadow-xl
-  shadow-base
-">
-  Orden confuso
-</div>
-```
-
-### Tabla de Sombras por Modo
-
-| Componente | Light Mode | Dark Mode | Razón |
-|------------|------------|-----------|-------|
-| **Card estándar** | `shadow-base` | `shadow-base` | Mismo valor - funciona bien |
-| **Card elevado** | `shadow-md` | `shadow-md` o `shadow-lg` | Opcional: aumentar en dark |
-| **Modal pequeño** | `shadow-lg` | `shadow-lg` o `shadow-xl` | Opcional: aumentar en dark |
-| **Modal grande** | `shadow-xl` | `shadow-xl` o `shadow-2xl` | Opcional: aumentar en dark |
-| **Dropdown** | `shadow-menu` | `shadow-menu` o `shadow-lg` | Opcional: aumentar en dark |
-| **Button inset** | `shadow-button-inset` | `shadow-button-inset` | Mismo valor |
-
-### Ejemplos Completos
-
-#### Ejemplo 1: Cards con Sombras Adaptativas
-
-```tsx
-export const CardWithShadow = () => {
-  return (
-    <div className="
-      rounded-2xl
-      bg-white dark:bg-dark-bg-primary
-      border border-border-primary dark:border-dark-border-primary
-      shadow-base dark:shadow-md
-      p-6
-      hover:shadow-lg dark:hover:shadow-xl
-      transition-all
-    ">
-      <h3 className="
-        text-content-primary dark:text-dark-content-primary
-        font-bold text-xl mb-4
-      ">
-        Card Title
-      </h3>
-      <p className="
-        text-content-secondary dark:text-content-secondary
-        mb-4
-      ">
-        Card content con sombra que se adapta al modo oscuro
-      </p>
-      <button className="
-        rounded-md
-        bg-primary-custom-600 dark:bg-dark-bg-inverse
-        text-primary-inverse-content dark:text-dark-content-inverse
-        shadow-button-inset
-        px-4 py-2
-        font-bold
-      ">
-        Action
-      </button>
-    </div>
-  );
-};
-```
-
-#### Ejemplo 2: Modal con Sombras Intensas en Dark Mode
-
-```tsx
-export const AdaptiveModal = ({ isOpen, onClose }) => {
-  if (!isOpen) return null;
-
-  return (
-    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
-      {/* Overlay */}
-      <div
-        className="absolute inset-0 bg-black/50 dark:bg-black/70 backdrop-blur-sm"
-        onClick={onClose}
-      />
-
-      {/* Modal */}
-      <div className="
-        relative z-10
-        rounded-3xl
-        bg-white dark:bg-dark-bg-primary
-        border border-border-primary dark:border-dark-border-primary
-        shadow-xl dark:shadow-2xl
-        max-w-md w-full
-      ">
-        {/* Header */}
-        <div className="
-          flex items-center justify-between
-          p-6
-          border-b border-border-primary dark:border-dark-border-primary
-        ">
-          <h2 className="
-            text-content-primary dark:text-dark-content-primary
-            font-bold text-2xl
-          ">
-            Modal Title
-          </h2>
-          <button
-            onClick={onClose}
-            className="
-              rounded-full p-2
-              hover:bg-background-secondary dark:hover:bg-dark-bg-primary
-              transition-colors
-            "
-          >
-            <XIcon className="w-5 h-5" />
-          </button>
-        </div>
-
-        {/* Body */}
-        <div className="p-6">
-          <p className="
-            text-content-secondary dark:text-content-secondary
-          ">
-            Modal content adaptado para dark mode con sombras más intensas
-          </p>
-        </div>
-
-        {/* Footer */}
-        <div className="
-          flex gap-3 justify-end
-          p-6
-          border-t border-border-primary dark:border-dark-border-primary
-        ">
-          <button
-            onClick={onClose}
-            className="
-              rounded-md
-              border border-border-primary dark:border-dark-border-custom
-              px-4 py-2
-              font-bold
-              text-content-primary dark:text-dark-content-primary
-              hover:bg-background-secondary dark:hover:bg-dark-bg-primary
-            "
-          >
-            Cancel
-          </button>
-          <button className="
-            rounded-md
-            bg-primary-custom-600 dark:bg-dark-bg-inverse
-            text-primary-inverse-content dark:text-dark-content-inverse
-            shadow-button-inset
-            px-4 py-2
-            font-bold
-          ">
-            Confirm
-          </button>
-        </div>
-      </div>
-    </div>
-  );
-};
-```
-
-#### Ejemplo 3: Dropdown con Sombra Adaptativa
-
-```tsx
-export const DropdownMenu = ({ isOpen, items }) => {
-  if (!isOpen) return null;
-
-  return (
-    <div className="
-      absolute top-full right-0 mt-2
-      rounded-xl
-      bg-white dark:bg-dark-bg-primary
-      border border-border-primary dark:border-dark-border-primary
-      shadow-menu dark:shadow-lg
-      min-w-[200px]
-      py-2
-    ">
-      {items.map((item, index) => (
-        <button
-          key={index}
-          className="
-            w-full px-4 py-2
-            text-left
-            text-content-primary dark:text-dark-content-primary
-            hover:bg-background-secondary dark:hover:bg-dark-bg-primary
-            transition-colors
-          "
-        >
-          {item.label}
-        </button>
-      ))}
-    </div>
-  );
-};
-```
-
-#### Ejemplo 4: Grid de Cards con Hover
-
-```tsx
-export const CardGrid = ({ cards }) => {
-  return (
-    <div className="
-      min-h-screen
-      bg-bg-primary dark:bg-dark-bg-primary
-      p-8
-    ">
-      <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
-        {cards.map((card) => (
-          <div
-            key={card.id}
-            className="
-              rounded-2xl
-              bg-white dark:bg-dark-bg-primary
-              border border-border-primary dark:border-dark-border-primary
-              shadow-base dark:shadow-md
-              hover:shadow-lg dark:hover:shadow-xl
-              hover:scale-105
-              transition-all
-              p-6
-              cursor-pointer
-            "
-          >
-            <h3 className="
-              text-content-primary dark:text-dark-content-primary
-              font-bold text-lg mb-2
-            ">
-              {card.title}
-            </h3>
-            <p className="
-              text-content-secondary dark:text-content-secondary
-              text-sm
-            ">
-              {card.description}
-            </p>
-          </div>
-        ))}
-      </div>
-    </div>
-  );
-};
-```
-
-### Mejores Prácticas para Sombras en Dark Mode
-
-#### ✅ Hacer
-
-1. **Usar las sombras estándar en ambos modos (cuando sea suficiente)**
-   ```tsx
-   // ✅ CORRECTO - Las sombras negras funcionan bien
-   <div className="shadow-base">Card</div>
-   ```
-
-2. **Aumentar la sombra en dark mode solo si es necesario**
-   ```tsx
-   // ✅ CORRECTO - Más prominencia en dark mode
-   <div className="shadow-base dark:shadow-lg">Card destacado</div>
-   ```
-
-3. **Combinar sombras con colores adaptativos**
-   ```tsx
-   // ✅ CORRECTO - Todo se adapta
-   <div className="
-     bg-white dark:bg-dark-bg-primary
-     border border-border-primary dark:border-dark-border-primary
-     shadow-base dark:shadow-md
-   ">
-     Card completo
-   </div>
-   ```
-
-4. **Ajustar overlay opacities en dark mode**
-   ```tsx
-   // ✅ CORRECTO - Overlay más oscuro en dark mode
-   <div className="bg-black/50 dark:bg-black/70 backdrop-blur-sm">
-     Overlay
-   </div>
-   ```
-
-#### ❌ Evitar
-
-1. **No remover sombras en dark mode**
-   ```tsx
-   // ❌ INCORRECTO - Perder profundidad en dark
-   <div className="shadow-base dark:shadow-none">Card</div>
-
-   // ✅ CORRECTO - Mantener o aumentar
-   <div className="shadow-base dark:shadow-md">Card</div>
-   ```
-
-2. **No usar sombras blancas en dark mode**
-   ```tsx
-   // ❌ INCORRECTO - Sombras blancas no funcionan bien
-   <div className="dark:shadow-[0_4px_6px_rgba(255,255,255,0.3)]">
-     Card
-   </div>
-
-   // ✅ CORRECTO - Mantener sombras negras o aumentar intensidad
-   <div className="shadow-base dark:shadow-lg">Card</div>
-   ```
-
-3. **No olvidar combinar con colores de fondo y borde**
-   ```tsx
-   // ❌ INCORRECTO - Solo cambiar sombra
-   <div className="bg-white shadow-base dark:shadow-lg">
-     Fondo no se adapta
-   </div>
-
-   // ✅ CORRECTO - Adaptar todo
-   <div className="
-     bg-white dark:bg-dark-bg-primary
-     border border-border-primary dark:border-dark-border-primary
-     shadow-base dark:shadow-lg
-   ">
-     Todo adaptado
-   </div>
-   ```
-
-### Guía Rápida: Decisiones sobre Sombras en Dark Mode
-
-| Situación | Recomendación |
-|-----------|---------------|
-| **Card de lista** | Mantener `shadow-base` en ambos modos |
-| **Card destacado** | `shadow-base` → `dark:shadow-md` |
-| **Modal** | Aumentar un nivel: `shadow-lg` → `dark:shadow-xl` |
-| **Dropdown** | Aumentar: `shadow-menu` → `dark:shadow-lg` |
-| **Overlay** | Aumentar opacidad: `bg-black/50` → `dark:bg-black/70` |
-| **Button inset** | Mantener `shadow-button-inset` en ambos |
-
-### Recursos Adicionales sobre Dark Mode
-
-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
-- Ver `docs/border-radius.md` - Border radius con ejemplos de dark mode
-- Ver `docs/typography.md` - Sistema tipográfico adaptado a dark mode
-- [Documentación oficial de Tailwind Dark Mode](https://tailwindcss.com/docs/dark-mode)
-
----
-
-## Referencia Rápida
-
-### Cheat Sheet: Por Componente
-
-```tsx
-// ===== BOTONES =====
-<button className="shadow-button-inset">Button default</button>
-<button className="shadow-base hover:shadow-md">Button outline</button>
-
-// ===== CARDS =====
-<div className="shadow-base">Card estándar</div>
-<div className="shadow-md">Card elevado</div>
-<div className="shadow-lg">Card flotante</div>
-
-// ===== MODALES =====
-<div className="shadow-lg">Modal pequeño</div>
-<div className="shadow-xl">Modal grande</div>
-<div className="shadow-2xl">Drawer/Panel</div>
-
-// ===== DROPDOWNS =====
-<div className="shadow-menu">Dropdown simple</div>
-<div className="shadow-md">Menú contextual</div>
-
-// ===== INPUTS =====
-<input className="focus:shadow-base" />
-<input className="shadow-inner" disabled />
-
-// ===== TOOLTIPS =====
-<div className="shadow-lg">Tooltip</div>
-<div className="shadow-xl">Popover</div>
-```
-
-### Cheat Sheet: Por Elevación
-
-| Nivel | Clase | Uso |
-|-------|-------|-----|
-| 0 | Sin sombra | Fondos, elementos integrados |
-| 1 | `shadow-sm` | Separadores sutiles |
-| 2 | `shadow-base` | **Cards, inputs focus** |
-| 3 | `shadow-md` | Cards elevados, dropdowns |
-| 4 | `shadow-lg` | **Modales, popovers** |
-| 5 | `shadow-xl` | Modales grandes |
-| 6 | `shadow-2xl` | Drawers, panels |
-
-### Cheat Sheet: Valores CSS
-
-```css
-/* Drop Shadows */
-shadow-sm:    0px 1px 2px 0px rgba(0,0,0,0.05)
-shadow-base:  0px 1px 2px -1px rgba(0,0,0,0.1),
-              0px 1px 3px 0px rgba(0,0,0,0.1)
-shadow-md:    0px 2px 4px -2px rgba(0,0,0,0.1),
-              0px 4px 6px -1px rgba(0,0,0,0.1)
-shadow-lg:    0px 4px 6px -4px rgba(0,0,0,0.1),
-              0px 10px 15px -3px rgba(0,0,0,0.1)
-shadow-xl:    0px 8px 10px -6px rgba(0,0,0,0.1),
-              0px 20px 25px -5px rgba(0,0,0,0.1)
-shadow-2xl:   0px 25px 50px -12px rgba(0,0,0,0.25)
-
-/* Inner Shadow */
-shadow-inner: inset 0 2px 4px 0 rgba(0,0,0,0.05)
-
-/* Custom */
-shadow-button-inset: 0px 2px 0px 0px inset rgba(255,255,255,0.15)
-shadow-menu:  0px 4px 4px -1px rgba(12,12,13,0.05),
-              0px 4px 4px -1px rgba(12,12,13,0.1)
-```
-
-### Cheat Sheet: Transiciones
-
-```tsx
-// Transición básica
-<div className="shadow-base hover:shadow-md transition-shadow">...</div>
-
-// Transición con duración
-<div className="shadow-base hover:shadow-lg transition-shadow duration-300">...</div>
-
-// Transición con múltiples propiedades
-<div className="shadow-base hover:shadow-lg hover:scale-105 transition-all duration-200">...</div>
-
-// Transición solo en hover out
-<div className="shadow-lg hover:shadow-base transition-shadow ease-out">...</div>
-```
-
----
-
-## Recursos Adicionales
-
-### Enlaces Útiles
-
-- **Tailwind Box Shadow**: https://tailwindcss.com/docs/box-shadow
-- **CSS box-shadow**: https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow
-- **Shadow Generator**: https://shadows.brumm.af
-- **Material Design Elevation**: https://material.io/design/environment/elevation.html
-
-### Archivos Relacionados
-
-- `tailwind.config.js` - Configuración de boxShadow (líneas 114-118)
-- `src/components/Button/Button.tsx` - Uso de shadow-button-inset (línea 67)
-- `docs/colors.md` - Sistema de colores
-- `docs/border-radius.md` - Border radius (combina bien con sombras)
-- `docs/typography.md` - Sistema tipográfico
-
-### Herramientas de Testing
-
-```tsx
-// Componente para visualizar todas las sombras
-export const ShadowsDemo = () => {
-  const shadows = [
-    { name: 'shadow-sm', label: 'Small' },
-    { name: 'shadow-base', label: 'Base' },
-    { name: 'shadow-md', label: 'Medium' },
-    { name: 'shadow-lg', label: 'Large' },
-    { name: 'shadow-xl', label: 'Extra Large' },
-    { name: 'shadow-2xl', label: '2X Large' },
-    { name: 'shadow-inner', label: 'Inner' },
-    { name: 'shadow-button-inset', label: 'Button Inset' },
-    { name: 'shadow-menu', label: 'Menu' },
-  ];
-
-  return (
-    <div className="grid grid-cols-3 gap-8 p-8 bg-gray-50">
-      {shadows.map((shadow) => (
-        <div key={shadow.name} className="text-center">
-          <div
-            className={`${shadow.name} rounded-lg bg-white w-32 h-32 mx-auto mb-4 flex items-center justify-center`}
-          >
-            <span className="text-sm font-bold">{shadow.label}</span>
-          </div>
-          <p className="font-bold text-sm">{shadow.name}</p>
-        </div>
-      ))}
-    </div>
-  );
-};
-```
-
----
-
-**Última actualización**: 2025-11-11
-**Versión**: 1.0.0
-**Mantenedor**: Siesa UI Kit Team