siesa-ui-kit 1.0.3 → 1.0.5

package/docs/border-radius.md

@@ -0,0 +1,1261 @@
+# Sistema de Border Radius - Siesa UI Kit
+
+## 📋 Tabla de Contenidos
+
+1. [Introducción](#introducción)
+2. [Escala de Border Radius](#escala-de-border-radius)
+3. [Guía de Uso](#guía-de-uso)
+4. [Componentes del Sistema](#componentes-del-sistema)
+5. [Ejemplos de Código](#ejemplos-de-código)
+6. [Mejores Prácticas](#mejores-prácticas)
+7. [Dark Mode](#dark-mode)
+8. [Referencia Rápida](#referencia-rápida)
+
+---
+
+## Introducción
+
+El sistema de border radius de Siesa UI Kit proporciona una escala consistente de bordes redondeados que ayuda a crear una jerarquía visual clara y mantener la coherencia en toda la interfaz.
+
+### Objetivos del Sistema
+
+- **Consistencia Visual**: Escalas bien definidas para todos los elementos de UI
+- **Jerarquía Clara**: Diferentes niveles de redondeo según la importancia del componente
+- **Flexibilidad**: Escalas adaptables desde bordes rectos hasta completamente circulares
+- **Armonía**: Progresión coherente entre valores
+
+### Principios de Diseño
+
+1. **Progresión Geométrica**: Incrementos lógicos entre escalas (2px → 4px → 6px → 8px → 12px → 16px → 24px)
+2. **Propósito Semántico**: Cada escala tiene casos de uso específicos
+3. **Adaptabilidad**: Compatible con diferentes tamaños de componentes
+4. **Accesibilidad**: Bordes redondeados que no comprometen la usabilidad
+
+---
+
+## Escala de Border Radius
+
+El sistema incluye **9 escalas** que van desde bordes completamente rectos hasta completamente circulares.
+
+### Tabla Completa de Escalas
+
+| Clase Tailwind | Valor | CSS | Uso Principal | Componentes |
+|----------------|-------|-----|---------------|-------------|
+| `rounded-none` | 0px | `border-radius: 0px` | Sin redondeo | Dividers, líneas |
+| `rounded-sm` | 2px | `border-radius: 2px` | Redondeo mínimo | Badges pequeños, tags |
+| `rounded` | 4px | `border-radius: 4px` | Redondeo sutil | Pequeños elementos |
+| `rounded-md` | 6px | `border-radius: 6px` | **Botones, inputs** | Button, Input, Select |
+| `rounded-lg` | 8px | `border-radius: 8px` | Cards pequeños | Card, Dropdown items |
+| `rounded-xl` | 12px | `border-radius: 12px` | Cards medianos | Card, Modal pequeño |
+| `rounded-2xl` | 16px | `border-radius: 16px` | **Cards grandes** | Card principal, Panel |
+| `rounded-3xl` | 24px | `border-radius: 24px` | Containers grandes | Hero cards, Modal grande |
+| `rounded-full` | 9999px | `border-radius: 9999px` | **Círculos perfectos** | Avatar, Badge circular |
+
+### Valores Más Comunes
+
+En el 80% de los casos, usarás estos 3 valores:
+
+1. **`rounded-md` (6px)**: Botones, inputs, dropdowns
+2. **`rounded-2xl` (16px)**: Cards, paneles, modales
+3. **`rounded-full` (9999px)**: Avatares, badges circulares, botones circulares
+
+---
+
+## Guía de Uso
+
+### Por Tipo de Componente
+
+#### 1. Botones y Controles (6px - `rounded-md`)
+
+```tsx
+// Botones
+<Button className="rounded-md">Guardar</Button>
+
+// Inputs
+<input className="rounded-md border px-3 py-2" />
+
+// Select
+<select className="rounded-md border px-3 py-2">
+  <option>Seleccionar</option>
+</select>
+
+// Checkbox personalizado (pequeño)
+<div className="rounded border w-5 h-5" />
+```
+
+**Razón**: 6px proporciona el equilibrio perfecto entre suavidad y nitidez para controles interactivos.
+
+#### 2. Cards y Contenedores (16px - `rounded-2xl`)
+
+```tsx
+// Card estándar
+<div className="rounded-2xl border bg-white p-6">
+  <h3>Título del Card</h3>
+  <p>Contenido...</p>
+</div>
+
+// Panel
+<div className="rounded-2xl border bg-bg-primary p-8">
+  {/* Contenido del panel */}
+</div>
+
+// Modal
+<div className="rounded-2xl bg-white shadow-lg p-6 max-w-md">
+  {/* Contenido del modal */}
+</div>
+```
+
+**Razón**: 16px crea una apariencia amigable y moderna para contenedores grandes.
+
+#### 3. Avatares y Elementos Circulares (9999px - `rounded-full`)
+
+```tsx
+// Avatar
+<img
+  src="/avatar.jpg"
+  alt="Usuario"
+  className="rounded-full w-12 h-12"
+/>
+
+// Badge circular
+<span className="rounded-full bg-red-500 text-white w-6 h-6 flex items-center justify-center text-xs">
+  3
+</span>
+
+// Botón circular icon-only
+<button className="rounded-full bg-primary-custom-600 p-3">
+  <PlusIcon />
+</button>
+
+// Indicador de estado
+<div className="rounded-full bg-green-500 w-3 h-3" />
+```
+
+**Razón**: `rounded-full` garantiza círculos perfectos independientemente del tamaño.
+
+#### 4. Badges y Tags (2-8px)
+
+```tsx
+// Badge pequeño - rounded-sm (2px)
+<span className="rounded-sm bg-blue-100 text-blue-800 px-2 py-0.5 text-xs font-bold">
+  NUEVO
+</span>
+
+// Badge mediano - rounded (4px)
+<span className="rounded bg-green-100 text-green-800 px-2 py-1 text-sm font-bold">
+  ACTIVO
+</span>
+
+// Badge grande - rounded-lg (8px)
+<span className="rounded-lg bg-purple-100 text-purple-800 px-3 py-1.5 text-sm font-bold">
+  PREMIUM
+</span>
+```
+
+**Razón**: Los badges más pequeños necesitan menos redondeo para mantener proporciones visuales correctas.
+
+#### 5. Tooltips y Popovers (8-12px)
+
+```tsx
+// Tooltip - rounded-lg (8px)
+<div className="rounded-lg bg-gray-900 text-white px-3 py-2 text-sm">
+  Este es un tooltip
+</div>
+
+// Popover - rounded-xl (12px)
+<div className="rounded-xl bg-white border shadow-lg p-4">
+  <h4 className="font-bold mb-2">Información</h4>
+  <p className="text-sm">Contenido del popover...</p>
+</div>
+```
+
+**Razón**: Redondeo suave que no compite visualmente con los elementos principales.
+
+### Por Tamaño de Elemento
+
+| Tamaño del Elemento | Border Radius Recomendado |
+|---------------------|---------------------------|
+| **Muy pequeño** (< 32px) | `rounded-sm` (2px) o `rounded` (4px) |
+| **Pequeño** (32-48px) | `rounded-md` (6px) |
+| **Mediano** (48-96px) | `rounded-lg` (8px) o `rounded-xl` (12px) |
+| **Grande** (96-200px) | `rounded-2xl` (16px) |
+| **Muy grande** (> 200px) | `rounded-3xl` (24px) |
+| **Circular** (cualquier tamaño) | `rounded-full` (9999px) |
+
+---
+
+## Componentes del Sistema
+
+### Configuración Actual
+
+Según el tailwind.config.js y las especificaciones de Figma:
+
+```javascript
+// tailwind.config.js
+borderRadius: {
+  'none': '0px',      // Tailwind default
+  'sm': '2px',        // Tailwind default
+  'DEFAULT': '4px',   // Tailwind default (rounded)
+  'md': '6px',        // ⚠️ PERSONALIZADO - Botones e inputs
+  'lg': '8px',        // Tailwind default
+  'xl': '12px',       // Tailwind default
+  '2xl': '16px',      // ⚠️ PERSONALIZADO - Cards
+  '3xl': '24px',      // ⚠️ PERSONALIZADO - Containers grandes
+  'full': '9999px',   // Tailwind default
+}
+```
+
+### Valores Personalizados del Sistema
+
+**Importante**: Siesa UI Kit sobrescribe 3 valores de Tailwind por defecto:
+
+| Clase | Tailwind Default | Siesa UI Kit | Razón |
+|-------|------------------|--------------|-------|
+| `rounded-md` | 6px (0.375rem) | **6px** | ✅ Igual - Diseñado para botones |
+| `rounded-2xl` | 24px (1.5rem) | **16px** | ⚠️ Diferente - Ajustado para cards |
+| `rounded-3xl` | 32px (2rem) | **24px** | ⚠️ Diferente - Ajustado para containers |
+
+**Nota**: Si migras código de otros proyectos Tailwind, ten en cuenta estas diferencias.
+
+### Uso en Componentes Actuales
+
+| Componente | Border Radius | Ubicación |
+|------------|---------------|-----------|
+| **Button** | `rounded-md` (6px) | Button.tsx:108 |
+| **Input** | `rounded-md` (6px) | (a implementar) |
+| **Card** | `rounded-2xl` (16px) | (a implementar) |
+| **Badge** | `rounded` (4px) o `rounded-full` | (a implementar) |
+| **Avatar** | `rounded-full` (9999px) | (a implementar) |
+| **Modal** | `rounded-2xl` (16px) o `rounded-3xl` (24px) | (a implementar) |
+
+---
+
+## Ejemplos de Código
+
+### Ejemplo 1: Dashboard con Cards
+
+```tsx
+export const Dashboard = () => {
+  return (
+    <div className="p-8 space-y-6">
+      {/* Título sin border radius */}
+      <h1 className="text-4xl font-bold">Dashboard</h1>
+
+      {/* Grid de Cards con rounded-2xl */}
+      <div className="grid grid-cols-3 gap-6">
+        <div className="rounded-2xl border border-border-primary bg-white p-6">
+          <div className="flex items-center gap-4 mb-4">
+            {/* Avatar circular */}
+            <img
+              src="/avatar.jpg"
+              alt="Usuario"
+              className="rounded-full w-12 h-12"
+            />
+            <div>
+              <h3 className="text-xl font-bold">Ventas</h3>
+              {/* Badge con rounded-sm */}
+              <span className="rounded-sm bg-green-100 text-green-800 px-2 py-0.5 text-xs font-bold">
+                +12.5%
+              </span>
+            </div>
+          </div>
+          <p className="text-3xl font-bold">$125,430</p>
+        </div>
+
+        <div className="rounded-2xl border border-border-primary bg-white p-6">
+          <h3 className="text-xl font-bold mb-4">Clientes</h3>
+          <p className="text-3xl font-bold">1,234</p>
+        </div>
+
+        <div className="rounded-2xl border border-border-primary bg-white p-6">
+          <h3 className="text-xl font-bold mb-4">Pedidos</h3>
+          <p className="text-3xl font-bold">456</p>
+        </div>
+      </div>
+
+      {/* Card grande con rounded-3xl */}
+      <div className="rounded-3xl border border-border-primary bg-white p-8">
+        <h2 className="text-2xl font-bold mb-6">Actividad Reciente</h2>
+        {/* Contenido */}
+      </div>
+    </div>
+  );
+};
+```
+
+### Ejemplo 2: Formulario Completo
+
+```tsx
+export const ProfileForm = () => {
+  return (
+    <form className="max-w-2xl mx-auto p-6">
+      {/* Container del formulario - rounded-2xl */}
+      <div className="rounded-2xl border border-border-primary bg-white p-8 space-y-6">
+        <h2 className="text-3xl font-bold">Editar Perfil</h2>
+
+        {/* Avatar upload */}
+        <div className="flex items-center gap-6">
+          <img
+            src="/avatar.jpg"
+            alt="Avatar"
+            className="rounded-full w-24 h-24"
+          />
+          <button className="rounded-md bg-primary-custom-600 text-white px-4 py-2 font-bold hover:bg-primary-custom-500">
+            Cambiar Foto
+          </button>
+        </div>
+
+        {/* Inputs con rounded-md */}
+        <div className="space-y-4">
+          <div>
+            <label className="text-sm font-bold mb-2 block">Nombre</label>
+            <input
+              type="text"
+              className="rounded-md border border-border-primary px-4 py-2 w-full focus:ring-2 focus:ring-primary-custom-400"
+              placeholder="Juan Pérez"
+            />
+          </div>
+
+          <div>
+            <label className="text-sm font-bold mb-2 block">Email</label>
+            <input
+              type="email"
+              className="rounded-md border border-border-primary px-4 py-2 w-full focus:ring-2 focus:ring-primary-custom-400"
+              placeholder="juan@ejemplo.com"
+            />
+          </div>
+
+          <div>
+            <label className="text-sm font-bold mb-2 block">Rol</label>
+            <select className="rounded-md border border-border-primary px-4 py-2 w-full focus:ring-2 focus:ring-primary-custom-400">
+              <option>Administrador</option>
+              <option>Usuario</option>
+            </select>
+          </div>
+        </div>
+
+        {/* Botones */}
+        <div className="flex gap-4">
+          <button
+            type="submit"
+            className="rounded-md bg-primary-custom-600 text-white px-6 py-2 font-bold hover:bg-primary-custom-500"
+          >
+            Guardar Cambios
+          </button>
+          <button
+            type="button"
+            className="rounded-md border border-border-primary bg-white px-6 py-2 font-bold hover:bg-gray-50"
+          >
+            Cancelar
+          </button>
+        </div>
+      </div>
+    </form>
+  );
+};
+```
+
+### Ejemplo 3: Lista con Avatares y Badges
+
+```tsx
+export const UserList = ({ users }) => {
+  return (
+    <div className="rounded-2xl border border-border-primary bg-white">
+      <div className="p-6 border-b border-border-primary">
+        <h2 className="text-2xl font-bold">Equipo</h2>
+      </div>
+
+      <ul className="divide-y divide-border-primary">
+        {users.map((user) => (
+          <li key={user.id} className="p-6 hover:bg-gray-50 transition-colors">
+            <div className="flex items-center justify-between">
+              <div className="flex items-center gap-4">
+                {/* Avatar */}
+                <div className="relative">
+                  <img
+                    src={user.avatar}
+                    alt={user.name}
+                    className="rounded-full w-12 h-12"
+                  />
+                  {/* Indicador de estado online */}
+                  {user.online && (
+                    <div className="rounded-full bg-green-500 w-3 h-3 absolute bottom-0 right-0 border-2 border-white" />
+                  )}
+                </div>
+
+                <div>
+                  <h3 className="font-bold text-base">{user.name}</h3>
+                  <p className="text-sm text-content-secondary">{user.email}</p>
+                </div>
+              </div>
+
+              <div className="flex items-center gap-3">
+                {/* Badge de rol */}
+                <span className={`rounded px-3 py-1 text-sm font-bold ${
+                  user.role === 'admin'
+                    ? 'bg-purple-100 text-purple-800'
+                    : 'bg-gray-100 text-gray-800'
+                }`}>
+                  {user.role}
+                </span>
+
+                {/* Badge circular de notificaciones */}
+                {user.notifications > 0 && (
+                  <span className="rounded-full bg-red-500 text-white w-6 h-6 flex items-center justify-center text-xs font-bold">
+                    {user.notifications}
+                  </span>
+                )}
+
+                {/* Botón de acción circular */}
+                <button className="rounded-full hover:bg-gray-100 p-2">
+                  <MoreIcon />
+                </button>
+              </div>
+            </div>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+};
+```
+
+### Ejemplo 4: Modal y Overlay
+
+```tsx
+export const Modal = ({ isOpen, onClose, children }) => {
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+      {/* Overlay sin border radius */}
+      <div
+        className="absolute inset-0 bg-black/50"
+        onClick={onClose}
+      />
+
+      {/* Modal con rounded-3xl */}
+      <div className="rounded-3xl bg-white shadow-2xl max-w-lg w-full relative z-10">
+        {/* Header */}
+        <div className="flex items-center justify-between p-6 border-b border-border-primary">
+          <h2 className="text-2xl font-bold">Confirmar Acción</h2>
+          <button
+            onClick={onClose}
+            className="rounded-full hover:bg-gray-100 p-2"
+          >
+            <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"
+          >
+            Cancelar
+          </button>
+          <button className="rounded-md bg-primary-custom-600 text-white px-4 py-2 font-bold hover:bg-primary-custom-500">
+            Confirmar
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+};
+```
+
+### Ejemplo 5: Navegación con Pills
+
+```tsx
+export const Navigation = () => {
+  const [activeTab, setActiveTab] = useState('dashboard');
+
+  return (
+    <nav className="rounded-2xl border border-border-primary bg-white p-2">
+      <ul className="flex gap-2">
+        <li>
+          <button
+            onClick={() => setActiveTab('dashboard')}
+            className={`rounded-lg px-4 py-2 font-bold transition-all ${
+              activeTab === 'dashboard'
+                ? 'bg-primary-custom-600 text-white'
+                : 'text-content-primary hover:bg-gray-100'
+            }`}
+          >
+            Dashboard
+          </button>
+        </li>
+        <li>
+          <button
+            onClick={() => setActiveTab('analytics')}
+            className={`rounded-lg px-4 py-2 font-bold transition-all ${
+              activeTab === 'analytics'
+                ? 'bg-primary-custom-600 text-white'
+                : 'text-content-primary hover:bg-gray-100'
+            }`}
+          >
+            Analíticas
+          </button>
+        </li>
+        <li>
+          <button
+            onClick={() => setActiveTab('settings')}
+            className={`rounded-lg px-4 py-2 font-bold transition-all ${
+              activeTab === 'settings'
+                ? 'bg-primary-custom-600 text-white'
+                : 'text-content-primary hover:bg-gray-100'
+            }`}
+          >
+            Configuración
+          </button>
+        </li>
+      </ul>
+    </nav>
+  );
+};
+```
+
+---
+
+## Mejores Prácticas
+
+### ✅ Hacer
+
+1. **Usar valores consistentes del sistema**
+   ```tsx
+   // ✅ CORRECTO - Usar las escalas definidas
+   <div className="rounded-md">Botón</div>
+   <div className="rounded-2xl">Card</div>
+   ```
+
+2. **Mantener jerarquía visual**
+   ```tsx
+   // ✅ CORRECTO - Elementos hijos menos redondeados que padres
+   <div className="rounded-2xl p-6">
+     <button className="rounded-md">Acción</button>
+   </div>
+   ```
+
+3. **Usar rounded-full para círculos perfectos**
+   ```tsx
+   // ✅ CORRECTO - Garantiza círculo perfecto
+   <div className="rounded-full w-12 h-12">Avatar</div>
+   ```
+
+4. **Adaptar el radio al tamaño del componente**
+   ```tsx
+   // ✅ CORRECTO - Radio proporcional
+   <span className="rounded-sm px-2 py-0.5 text-xs">Badge pequeño</span>
+   <div className="rounded-3xl p-12 text-2xl">Container grande</div>
+   ```
+
+5. **Agrupar elementos relacionados con el mismo radio**
+   ```tsx
+   // ✅ CORRECTO - Consistencia en el grupo
+   <div className="flex gap-2">
+     <button className="rounded-md">Guardar</button>
+     <button className="rounded-md">Cancelar</button>
+     <button className="rounded-md">Eliminar</button>
+   </div>
+   ```
+
+### ❌ Evitar
+
+1. **No usar valores arbitrarios**
+   ```tsx
+   // ❌ INCORRECTO - Valor personalizado
+   <div className="rounded-[10px]">Card</div>
+
+   // ✅ CORRECTO - Usar escala del sistema
+   <div className="rounded-xl">Card</div>
+   ```
+
+2. **No mezclar diferentes radios sin propósito**
+   ```tsx
+   // ❌ INCORRECTO - Inconsistencia visual
+   <div className="flex gap-2">
+     <button className="rounded-sm">Acción 1</button>
+     <button className="rounded-xl">Acción 2</button>
+     <button className="rounded-full">Acción 3</button>
+   </div>
+
+   // ✅ CORRECTO - Consistencia
+   <div className="flex gap-2">
+     <button className="rounded-md">Acción 1</button>
+     <button className="rounded-md">Acción 2</button>
+     <button className="rounded-md">Acción 3</button>
+   </div>
+   ```
+
+3. **No usar radios grandes en elementos pequeños**
+   ```tsx
+   // ❌ INCORRECTO - Radio desproporcionado
+   <span className="rounded-3xl px-2 py-0.5 text-xs">Badge</span>
+
+   // ✅ CORRECTO - Radio proporcional
+   <span className="rounded px-2 py-0.5 text-xs">Badge</span>
+   ```
+
+4. **No usar rounded-full en elementos no cuadrados**
+   ```tsx
+   // ❌ INCORRECTO - No será un círculo perfecto
+   <div className="rounded-full w-20 h-8">Rectángulo</div>
+
+   // ✅ CORRECTO - Para rectángulos usar radio fijo
+   <div className="rounded-full w-8 h-8">Círculo</div>
+   ```
+
+5. **No omitir border radius en componentes interactivos**
+   ```tsx
+   // ❌ INCORRECTO - Botón sin redondeo se ve rígido
+   <button className="bg-primary-custom-600 text-white px-4 py-2">
+     Guardar
+   </button>
+
+   // ✅ CORRECTO - rounded-md para botones
+   <button className="rounded-md bg-primary-custom-600 text-white px-4 py-2">
+     Guardar
+   </button>
+   ```
+
+### Accesibilidad
+
+1. **Los bordes redondeados no deben afectar el área clickeable**
+   ```tsx
+   // ✅ CORRECTO - El padding compensa el redondeo
+   <button className="rounded-md px-4 py-2">
+     Texto del botón
+   </button>
+   ```
+
+2. **Mantener contraste suficiente en los bordes**
+   ```tsx
+   // ✅ CORRECTO - Borde visible
+   <input className="rounded-md border-2 border-border-primary" />
+   ```
+
+3. **Considerar usuarios con baja visión**
+   - Radios muy grandes pueden hacer difícil distinguir los límites
+   - Radios muy pequeños pueden parecer demasiado rígidos
+
+### Performance
+
+- ✅ Las propiedades `border-radius` son muy eficientes
+- ✅ No requieren cálculos complejos del navegador
+- ✅ Se pueden animar suavemente si es necesario
+
+```tsx
+// ✅ Transición suave de border radius
+<button className="rounded-md hover:rounded-lg transition-all">
+  Hover me
+</button>
+```
+
+---
+
+## Dark Mode
+
+El border radius se mantiene consistente entre light y dark mode, pero es importante ajustar los colores de fondo y borde para que los componentes redondeados se vean correctamente en ambos modos.
+
+### 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 para border radius + colores
+<div className="
+  rounded-2xl
+  bg-white dark:bg-dark-bg-primary
+  border border-border-primary dark:border-dark-border-primary
+  p-6
+">
+  Card adaptable
+</div>
+
+// El border-radius NO cambia, pero los colores SÍ:
+// - bg-white en modo claro → bg-dark-bg-primary en modo oscuro
+// - border-border-primary en claro → border-dark-border-primary en oscuro
+```
+
+### Principios de Dark Mode con Border Radius
+
+**Regla de Oro**: Los valores de `border-radius` no cambian entre modos, pero la combinación con colores sí:
+
+```tsx
+// ✅ CORRECTO - Border radius consistente, colores adaptativos
+<div className="rounded-2xl bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary p-6">
+  Card con esquinas redondeadas que se adapta al modo
+</div>
+
+// ❌ INCORRECTO - Cambiar border radius en dark mode
+<div className="rounded-2xl dark:rounded-md">
+  NO hacer esto - mantener border radius consistente
+</div>
+```
+
+### Combinando con Estados Interactivos
+
+El modificador `dark:` se puede combinar con hover, focus, y otros estados:
+
+```tsx
+// Dark mode + Hover en border
+<div className="
+  rounded-2xl
+  border border-border-primary dark:border-dark-border-primary
+  hover:border-primary-custom-300 dark:hover:border-dark-border-custom
+  transition-colors
+  p-6
+">
+  Card interactiva
+</div>
+
+// Dark mode + Hover en background
+<button className="
+  rounded-md
+  bg-background-secondary dark:bg-dark-bg-primary
+  hover:bg-primary-custom-100 dark:hover:bg-dark-border-custom
+  px-4 py-2
+">
+  Botón con hover
+</button>
+
+// Dark mode + Focus en inputs
+<input className="
+  rounded-md
+  border border-border-primary dark:border-dark-border-primary
+  focus:border-primary-custom-400 dark:focus:border-dark-border-custom
+  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 para los modificadores:
+
+**Formato**: `{responsive}:{dark}:{state}:{utility}`
+
+```tsx
+// ✅ CORRECTO - Orden: responsive → dark → state → utility
+<div className="
+  rounded-2xl
+  md:rounded-3xl
+  border
+  border-border-primary
+  md:dark:border-dark-border-custom
+  md:dark:hover:border-blue-400
+  p-6
+">
+  Card con orden correcto
+</div>
+
+// ❌ INCORRECTO - Orden equivocado
+<div className="
+  dark:md:hover:border-blue-400
+  rounded-2xl
+">
+  Orden confuso
+</div>
+```
+
+### Tabla de Estados con Border Radius
+
+| Estado | Light Mode | Dark Mode | Descripción |
+|--------|------------|-----------|-------------|
+| **Default Border** | `border-border-primary` | `dark:border-dark-border-primary` | Borde estándar |
+| **Default BG** | `bg-white` | `dark:bg-dark-bg-primary` | Fondo estándar |
+| **Hover Border** | `hover:border-primary-custom-300` | `dark:hover:border-dark-border-custom` | Borde al hover |
+| **Hover BG** | `hover:bg-background-secondary` | `dark:hover:bg-dark-bg-primary` | Fondo al hover |
+| **Focus Border** | `focus:border-primary-custom-400` | `dark:focus:border-dark-border-custom` | Borde al focus (inputs) |
+| **Focus Ring** | `focus:ring-primary-custom-400/20` | `dark:focus:ring-dark-border-custom/20` | Ring de focus |
+| **Active BG** | `active:bg-primary-custom-700` | `dark:active:bg-dark-bg-inverse/90` | Fondo al hacer clic |
+
+### Ejemplos de Componentes en Dark Mode
+
+#### 1. Cards con Border Radius
+
+```tsx
+// Card estándar adaptable
+<div className="rounded-2xl bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary p-6 shadow-base">
+  <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">
+    Card content que funciona en ambos modos
+  </p>
+</div>
+
+// Card con hover effect
+<div className="rounded-2xl bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary p-6 hover:border-primary-custom-300 dark:hover:border-dark-border-custom transition-colors">
+  Card interactiva
+</div>
+```
+
+#### 2. Botones Redondeados
+
+```tsx
+// Botón primary
+<button className="rounded-md bg-primary-custom-600 dark:bg-dark-bg-inverse text-primary-inverse-content dark:text-dark-content-inverse px-4 py-2 font-bold">
+  Primary Button
+</button>
+
+// Botón outline
+<button className="rounded-md border border-border-primary dark:border-dark-border-custom text-content-primary dark:text-dark-content-primary px-4 py-2 font-bold hover:bg-background-secondary dark:hover:bg-dark-bg-primary">
+  Outline Button
+</button>
+
+// Botón circular (iconos)
+<button className="rounded-full w-10 h-10 flex items-center justify-center bg-background-secondary dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary hover:bg-primary-custom-100 dark:hover:bg-dark-border-custom">
+  <Icon />
+</button>
+```
+
+#### 3. Inputs con Border Radius
+
+```tsx
+// Input estándar
+<input
+  type="text"
+  className="rounded-md w-full px-3 py-2 border border-border-primary dark:border-dark-border-primary bg-white dark:bg-dark-bg-primary text-content-primary dark:text-dark-content-primary focus:border-primary-custom-400 dark:focus:border-dark-border-custom"
+  placeholder="Escribe aquí..."
+/>
+
+// Input con error
+<input
+  type="email"
+  className="rounded-md w-full px-3 py-2 border border-error-border bg-error-bg dark:bg-dark-bg-primary text-content-primary dark:text-dark-content-primary"
+/>
+```
+
+#### 4. Modales con Border Radius
+
+```tsx
+export const ModalDarkMode = ({ isOpen, onClose }) => {
+  if (!isOpen) return null;
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center p-4">
+      <div
+        className="absolute inset-0 bg-black/50 backdrop-blur-lg"
+        onClick={onClose}
+      />
+
+      <div className="relative z-10 rounded-3xl bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary 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"
+          >
+            <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
+          </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"
+          >
+            Cancel
+          </button>
+          <button className="rounded-md bg-primary-custom-600 dark:bg-dark-bg-inverse text-primary-inverse-content dark:text-dark-content-inverse px-4 py-2 font-bold">
+            Confirm
+          </button>
+        </div>
+      </div>
+    </div>
+  );
+};
+```
+
+#### 5. Badges y Tags
+
+```tsx
+// Badge pill (rounded-full)
+<span className="rounded-full bg-primary-custom-100 dark:bg-dark-border-custom text-primary-custom-600 dark:text-dark-content-primary px-3 py-1 text-xs font-bold">
+  New
+</span>
+
+// Badge redondeado (rounded-md)
+<span className="rounded-md bg-background-secondary dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary px-2 py-1 text-xs font-bold text-content-primary dark:text-dark-content-primary">
+  Tag
+</span>
+```
+
+### Mejores Prácticas para Dark Mode
+
+#### 1. Mantener Consistencia de Border Radius
+
+```tsx
+// ✅ CORRECTO - Mismo border radius en ambos modos
+<div className="rounded-2xl bg-white dark:bg-dark-bg-primary">
+  Consistente
+</div>
+
+// ❌ INCORRECTO - Cambiar border radius en dark mode
+<div className="rounded-2xl dark:rounded-md">
+  Inconsistente
+</div>
+```
+
+#### 2. Combinar Border Radius con Colores Adaptativos
+
+```tsx
+// ✅ CORRECTO - Todos los colores se adaptan
+<div className="rounded-2xl bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary shadow-base">
+  <h3 className="text-content-primary dark:text-dark-content-primary">Title</h3>
+  <p className="text-content-secondary dark:text-content-secondary">Content</p>
+</div>
+
+// ❌ INCORRECTO - Fondo no se adapta
+<div className="rounded-2xl bg-white border border-border-primary dark:border-dark-border-primary">
+  <p className="text-content-primary dark:text-dark-content-primary">Content</p>
+</div>
+```
+
+#### 3. Hover States en Dark Mode
+
+```tsx
+// ✅ CORRECTO - Hover states para ambos modos
+<button className="rounded-md bg-background-secondary dark:bg-dark-bg-primary hover:bg-primary-custom-100 dark:hover:bg-dark-border-custom px-4 py-2">
+  Button
+</button>
+
+// Con border en hover
+<div className="rounded-2xl border border-border-primary dark:border-dark-border-primary hover:border-primary-custom-300 dark:hover:border-dark-border-custom transition-colors p-6">
+  Interactive card
+</div>
+```
+
+#### 4. Focus States en Inputs
+
+```tsx
+// ✅ CORRECTO - Focus ring adaptado
+<input
+  type="text"
+  className="rounded-md border border-border-primary dark:border-dark-border-primary focus:border-primary-custom-400 focus:ring-2 focus:ring-primary-custom-400/20 dark:focus:border-dark-border-custom dark:focus:ring-dark-border-custom/20"
+/>
+```
+
+### Ejemplo Completo: Card System con Dark Mode
+
+```tsx
+export const CardSystemDarkMode = () => {
+  return (
+    <div className="min-h-screen bg-bg-primary dark:bg-dark-bg-primary p-8">
+      <div className="max-w-4xl mx-auto space-y-6">
+        {/* Card con rounded-2xl */}
+        <div className="rounded-2xl bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary p-6 shadow-base">
+          <h2 className="text-content-primary dark:text-dark-content-primary font-bold text-xl mb-4">
+            Standard Card (rounded-2xl)
+          </h2>
+          <p className="text-content-secondary dark:text-content-secondary mb-4">
+            Esta card usa rounded-2xl (16px) y se adapta perfectamente a dark mode.
+          </p>
+          <div className="flex gap-3">
+            <button className="rounded-md bg-primary-custom-600 dark:bg-dark-bg-inverse text-primary-inverse-content dark:text-dark-content-inverse px-4 py-2 font-bold">
+              Primary Action
+            </button>
+            <button className="rounded-md border border-border-primary dark:border-dark-border-custom text-content-primary dark:text-dark-content-primary px-4 py-2 font-bold">
+              Secondary
+            </button>
+          </div>
+        </div>
+
+        {/* Card con rounded-3xl */}
+        <div className="rounded-3xl bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary p-8 shadow-lg">
+          <div className="flex items-center gap-4 mb-4">
+            <div className="rounded-full w-16 h-16 bg-primary-custom-100 dark:bg-dark-border-custom flex items-center justify-center">
+              <span className="text-2xl">🎨</span>
+            </div>
+            <div>
+              <h2 className="text-content-primary dark:text-dark-content-primary font-bold text-2xl">
+                Premium Card (rounded-3xl)
+              </h2>
+              <p className="text-content-secondary dark:text-content-secondary">
+                Con más padding y border radius
+              </p>
+            </div>
+          </div>
+          <p className="text-content-secondary dark:text-content-secondary mb-6">
+            Esta card premium usa rounded-3xl (24px) para un look más suave y moderno.
+          </p>
+          <div className="flex gap-2">
+            <span className="rounded-full bg-primary-custom-100 dark:bg-dark-border-custom text-primary-custom-600 dark:text-dark-content-primary px-3 py-1 text-xs font-bold">
+              Premium
+            </span>
+            <span className="rounded-md bg-background-secondary dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary px-2 py-1 text-xs font-bold">
+              Featured
+            </span>
+          </div>
+        </div>
+
+        {/* Grid de cards pequeñas */}
+        <div className="grid grid-cols-3 gap-4">
+          {['Design', 'Development', 'Marketing'].map((title) => (
+            <div
+              key={title}
+              className="rounded-xl bg-white dark:bg-dark-bg-primary border border-border-primary dark:border-dark-border-primary p-4 hover:border-primary-custom-300 dark:hover:border-dark-border-custom transition-colors"
+            >
+              <h3 className="text-content-primary dark:text-dark-content-primary font-bold mb-2">
+                {title}
+              </h3>
+              <p className="text-content-secondary dark:text-content-secondary text-sm">
+                Descripción breve
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </div>
+  );
+};
+```
+
+### Tokens de Color para Border Radius + Dark Mode
+
+Referencia rápida para combinar border radius con colores en dark mode:
+
+| Elemento | Light Mode | Dark Mode |
+|----------|------------|-----------|
+| **Background** | `bg-white` | `dark:bg-dark-bg-primary` |
+| **Border** | `border-border-primary` | `dark:border-dark-border-primary` |
+| **Border (custom)** | `border-primary-custom-300` | `dark:border-dark-border-custom` |
+| **Hover BG** | `hover:bg-background-secondary` | `dark:hover:bg-dark-bg-primary` |
+| **Hover Border** | `hover:border-primary-custom-300` | `dark:hover:border-dark-border-custom` |
+| **Button Primary BG** | `bg-primary-custom-600` | `dark:bg-dark-bg-inverse` |
+| **Button Primary Text** | `text-primary-inverse-content` | `dark:text-dark-content-inverse` |
+
+### 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/icons.md` - Sistema de iconos 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 Y CONTROLES (6px) =====
+<button className="rounded-md">Button</button>
+<input className="rounded-md" />
+<select className="rounded-md">...</select>
+
+// ===== CARDS Y CONTAINERS (16px) =====
+<div className="rounded-2xl">Card</div>
+<div className="rounded-2xl">Panel</div>
+<div className="rounded-2xl">Modal pequeño</div>
+
+// ===== CONTAINERS GRANDES (24px) =====
+<div className="rounded-3xl">Hero Card</div>
+<div className="rounded-3xl">Modal grande</div>
+
+// ===== BADGES (2-8px) =====
+<span className="rounded-sm">Badge pequeño</span>
+<span className="rounded">Badge mediano</span>
+<span className="rounded-lg">Badge grande</span>
+
+// ===== ELEMENTOS CIRCULARES (9999px) =====
+<img className="rounded-full" />
+<div className="rounded-full">Avatar</div>
+<button className="rounded-full">Icon button</button>
+<span className="rounded-full">Badge circular</span>
+```
+
+### Cheat Sheet: Todas las Escalas
+
+| Clase | Valor | Uso Común |
+|-------|-------|-----------|
+| `rounded-none` | 0px | Dividers, líneas horizontales |
+| `rounded-sm` | 2px | Badges muy pequeños |
+| `rounded` | 4px | Tags, badges pequeños |
+| `rounded-md` | 6px | **Botones, inputs, selects** ⭐ |
+| `rounded-lg` | 8px | Cards pequeños, tabs |
+| `rounded-xl` | 12px | Cards medianos, tooltips |
+| `rounded-2xl` | 16px | **Cards, paneles, modales** ⭐ |
+| `rounded-3xl` | 24px | Containers muy grandes |
+| `rounded-full` | 9999px | **Avatares, badges circulares** ⭐ |
+
+### Cheat Sheet: Por Tamaño
+
+```tsx
+// XS (< 32px) - rounded-sm o rounded
+<span className="rounded-sm w-4 h-4" />
+
+// SM (32-48px) - rounded-md
+<button className="rounded-md h-8" />
+
+// MD (48-96px) - rounded-lg o rounded-xl
+<div className="rounded-xl w-20 h-20" />
+
+// LG (96-200px) - rounded-2xl
+<div className="rounded-2xl w-40 h-40" />
+
+// XL (> 200px) - rounded-3xl
+<div className="rounded-3xl w-80" />
+
+// Circular - rounded-full
+<div className="rounded-full w-12 h-12" />
+```
+
+### Cheat Sheet: Configuración Tailwind
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  theme: {
+    extend: {
+      borderRadius: {
+        'md': '6px',   // Personalizado (default Tailwind: 6px ✅)
+        '2xl': '16px', // Personalizado (default Tailwind: 24px ⚠️)
+        '3xl': '24px', // Personalizado (default Tailwind: 32px ⚠️)
+      }
+    }
+  }
+}
+```
+
+### Cheat Sheet: Variantes Direccionales
+
+Tailwind permite aplicar border radius a esquinas específicas:
+
+```tsx
+// Top
+<div className="rounded-t-2xl">Solo arriba</div>
+
+// Bottom
+<div className="rounded-b-2xl">Solo abajo</div>
+
+// Left
+<div className="rounded-l-2xl">Solo izquierda</div>
+
+// Right
+<div className="rounded-r-2xl">Solo derecha</div>
+
+// Esquinas individuales
+<div className="rounded-tl-2xl">Top-left</div>
+<div className="rounded-tr-2xl">Top-right</div>
+<div className="rounded-br-2xl">Bottom-right</div>
+<div className="rounded-bl-2xl">Bottom-left</div>
+```
+
+**Ejemplo práctico**: Modal con esquinas redondeadas solo arriba
+
+```tsx
+<div className="fixed inset-0 flex items-end">
+  <div className="rounded-t-3xl bg-white w-full p-6">
+    {/* Modal que sube desde abajo */}
+  </div>
+</div>
+```
+
+---
+
+## Recursos Adicionales
+
+### Enlaces Útiles
+
+- **Tailwind Border Radius**: https://tailwindcss.com/docs/border-radius
+- **CSS border-radius**: https://developer.mozilla.org/en-US/docs/Web/CSS/border-radius
+- **Border Radius Generator**: https://border-radius.com
+
+### Archivos Relacionados
+
+- `tailwind.config.js` - Configuración de borderRadius (líneas 96-101)
+- `src/components/Button/Button.tsx` - Ejemplo de uso (línea 108)
+- `docs/colors.md` - Sistema de colores
+- `docs/typography.md` - Sistema tipográfico
+- `docs/icons.md` - Sistema de iconos
+
+### Herramientas de Testing
+
+```tsx
+// Componente para visualizar todas las escalas
+export const BorderRadiusDemo = () => {
+  const scales = [
+    { name: 'rounded-none', value: '0px' },
+    { name: 'rounded-sm', value: '2px' },
+    { name: 'rounded', value: '4px' },
+    { name: 'rounded-md', value: '6px' },
+    { name: 'rounded-lg', value: '8px' },
+    { name: 'rounded-xl', value: '12px' },
+    { name: 'rounded-2xl', value: '16px' },
+    { name: 'rounded-3xl', value: '24px' },
+    { name: 'rounded-full', value: '9999px' },
+  ];
+
+  return (
+    <div className="grid grid-cols-3 gap-6 p-8">
+      {scales.map((scale) => (
+        <div key={scale.name} className="text-center">
+          <div
+            className={`${scale.name} bg-primary-custom-600 w-24 h-24 mx-auto mb-4`}
+          />
+          <p className="font-bold">{scale.name}</p>
+          <p className="text-sm text-content-secondary">{scale.value}</p>
+        </div>
+      ))}
+    </div>
+  );
+};
+```
+
+---
+
+**Última actualización**: 2025-11-11
+**Versión**: 1.0.0
+**Mantenedor**: Siesa UI Kit Team