siesa-ui-kit 1.0.4 → 1.0.5

package/docs/colors.md

@@ -1,832 +1,832 @@
-# 🎨 Sistema de Colores - Siesa UI Kit
-
-## 📋 Tabla de Contenidos
-
-1. [Introducción](#introducción)
-2. [Arquitectura de Colores](#arquitectura-de-colores)
-3. [Colores Primitivos](#colores-primitivos)
-4. [Tokens Semánticos](#tokens-semánticos)
-5. [Modos de Color (Light/Dark)](#modos-de-color-lightdark)
-6. [Guía de Uso en Componentes](#guía-de-uso-en-componentes)
-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
-
-Este documento describe el sistema de colores del **Siesa UI Kit**, diseñado para garantizar consistencia visual, accesibilidad y mantenibilidad en todos los componentes de la interfaz.
-
-### 🎯 Objetivos del Sistema
-
-- **Consistencia**: Colores unificados en toda la aplicación
-- **Accesibilidad**: Ratios de contraste WCAG AA/AAA
-- **Mantenibilidad**: Tokens semánticos fáciles de actualizar
-- **Escalabilidad**: Sistema extensible para nuevos componentes
-- **Dark Mode**: Soporte completo para modo oscuro
-
----
-
-## Arquitectura de Colores
-
-El sistema de colores está estructurado en 3 capas:
-
-```
-┌─────────────────────────────────────┐
-│  CAPA 3: Componentes                │
-│  (Button, Alert, Badge, etc.)       │
-└─────────────────────────────────────┘
-              ▲
-              │ usa tokens
-              │
-┌─────────────────────────────────────┐
-│  CAPA 2: Tokens Semánticos          │
-│  (content-primary, bg-primary, etc) │
-└─────────────────────────────────────┘
-              ▲
-              │ mapea a
-              │
-┌─────────────────────────────────────┐
-│  CAPA 1: Colores Primitivos         │
-│  (primary-custom-600, gray-100, etc)│
-└─────────────────────────────────────┘
-```
-
-### Principios de Diseño
-
-1. **Primitivos = Valores Hex**: Colores base inmutables
-2. **Tokens = Intención de Uso**: Nombres semánticos que describen propósito
-3. **Componentes = Aplicación**: Uso consistente de tokens
-
----
-
-## Colores Primitivos
-
-Los colores primitivos son la base del sistema. Están organizados en escalas de 100-700 (actualmente) con planes de expandir a 50-950.
-
-### 📘 Primary Custom (Azul Principal)
-
-Color primario de marca Siesa. Usado en botones, enlaces y elementos interactivos principales.
-
-| Escala | Valor Hex | CSS Class | Uso Principal |
-|--------|-----------|-----------|---------------|
-| **100** | `#dbeefe` | `primary-custom-100` | Hover backgrounds (outline buttons) |
-| **300** | `#93d1fd` | `primary-custom-300` | Bordes (outline buttons, inputs) |
-| **400** | `#60b6fa` | `primary-custom-400` | Focus rings |
-| **500** | `#3c9bf6` | `primary-custom-500` | Hover state (default buttons) |
-| **600** | `#0e79fd` | `primary-custom-600` | **Color principal** (contenido, íconos) |
-| **700** | `#0c6ade` | `primary-custom-700` | Active/Pressed states |
-
-**Ejemplo de Aplicación**:
-```tsx
-// Botón primario
-<button className="bg-primary-custom-600 hover:bg-primary-custom-500 focus:ring-primary-custom-400">
-  Click me
-</button>
-```
-
----
-
-### 🎨 Colores Inverse (Para fondos oscuros)
-
-Colores optimizados para usar sobre fondos de color primario.
-
-| Token | Valor Hex | Uso |
-|-------|-----------|-----|
-| `primary-inverse-content` | `#eff8ff` | Texto sobre fondo primario |
-| `primary-inverse-background` | `#0e79fd` | Fondo de botones primarios |
-| `primary-inverse-border` | `#3c9bf6` | Bordes sobre fondo primario |
-
-**Ejemplo de Aplicación**:
-```tsx
-// Botón con fondo primario y texto claro
-<button className="bg-primary-inverse-background text-primary-inverse-content border-primary-inverse-border">
-  Botón Primario
-</button>
-```
-
----
-
-### 🌈 Colores del Sistema (Light Mode)
-
-Paleta neutral para textos, fondos y bordes en modo claro.
-
-#### Contenido (Texto)
-
-| Token | Valor Hex | Uso | Contraste |
-|-------|-----------|-----|-----------|
-| `content-primary` | `#18181b` | Texto principal | AAA (18:1) |
-| `content-secondary` | `#a1a1aa` | Descripciones, labels | AA (4.5:1) |
-| `content-tertiary` | `#71717a` | Placeholders, disabled text | AA (4.5:1) |
-
-#### Fondos
-
-| Token | Valor Hex | Uso |
-|-------|-----------|-----|
-| `bg-primary` | `#ffffff` | Fondo principal de la app |
-| `background-secondary` | `#f4f4f5` | Cards, fondos disabled |
-
-#### Bordes
-
-| Token | Valor Hex | Uso |
-|-------|-----------|-----|
-| `border-primary` | `#e4e4e7` | Bordes normales (inputs, cards) |
-| `border-secondary` | `#f4f4f5` | Dividers, bordes suaves |
-
-**Ejemplo de Aplicación**:
-```tsx
-// Card con sistema de colores semánticos
-<div className="bg-bg-primary border border-border-primary">
-  <h3 className="text-content-primary">Título Principal</h3>
-  <p className="text-content-secondary">Descripción secundaria</p>
-</div>
-```
-
----
-
-### 🔴 Colores de Error
-
-Paleta para estados de error y validación.
-
-| Token | Valor Hex | Base Color | Uso |
-|-------|-----------|------------|-----|
-| `error-bg` | `#fef2f2` | Red 50 | Fondo de alertas de error |
-| `error-border` | `#ef4444` | Red 500 | Bordes de inputs con error |
-| `error-content` | `#dc2626` | Red 600 | Texto de mensajes de error |
-
-**Ejemplo de Aplicación**:
-```tsx
-// Input con error
-<div className="border-2 border-error-border bg-error-bg">
-  <input type="text" />
-  <span className="text-error-content">Email inválido</span>
-</div>
-```
-
-> **⚠️ PENDIENTE**: Agregar colores para Success, Warning, Info con la misma estructura.
-
----
-
-## Tokens Semánticos
-
-Los tokens semánticos describen **dónde y cómo** usar los colores, no **qué color** son.
-
-### 📊 Estructura de Tokens
-
-```
-{categoria}-{proposito}-{variante}
-
-Ejemplos:
-- content-primary (Categoría: content, Propósito: primary)
-- bg-secondary (Categoría: bg, Propósito: secondary)
-- border-custom (Categoría: border, Propósito: custom)
-```
-
-### Categorías de Tokens
-
-| Categoría | Prefijo | Uso | Ejemplos |
-|-----------|---------|-----|----------|
-| **Content** | `content-` | Texto, íconos | `content-primary`, `content-secondary` |
-| **Background** | `bg-`, `background-` | Fondos | `bg-primary`, `background-secondary` |
-| **Border** | `border-` | Bordes, divisores | `border-primary`, `border-secondary` |
-| **Primary Custom** | `primary-custom-` | Color de marca | `primary-custom-600`, `primary-custom-300` |
-| **Error** | `error-` | Estados de error | `error-bg`, `error-border`, `error-content` |
-
----
-
-## Modos de Color (Light/Dark)
-
-### Configuración de Tailwind CSS
-
-Siesa UI Kit utiliza la estrategia **class-based** de Tailwind CSS para dark mode:
-
-```javascript
-// tailwind.config.js
-module.exports = {
-  darkMode: 'class', // ✅ Estrategia basada en clases
-  // ... resto de la configuración
-}
-```
-
-Con `darkMode: 'class'`, el modificador `dark:` se activa cuando un elemento ancestro (típicamente `<html>`) tiene la clase `dark`:
-
-### 🌞 Light Mode (Por Defecto)
-
-```html
-<html>
-  <!-- Sin clase 'dark' = Light Mode activo -->
-  <body>
-    <div class="bg-white text-content-primary">
-      Contenido en light mode
-    </div>
-  </body>
-</html>
-```
-
-### 🌙 Dark Mode
-
-```html
-<html class="dark">
-  <!-- Con clase 'dark' = Dark Mode activo -->
-  <body>
-    <div class="bg-white dark:bg-dark-bg-primary text-content-primary dark:text-dark-content-primary">
-      Contenido adaptado a dark mode
-    </div>
-  </body>
-</html>
-```
-
-### Modificador dark: en Tailwind
-
-El modificador `dark:` funciona como prefijo para cualquier utilidad de Tailwind:
-
-```tsx
-// Sintaxis básica
-dark:{utility}
-
-// Ejemplos
-dark:bg-dark-bg-primary    // Background en dark mode
-dark:text-white            // Texto en dark mode
-dark:border-gray-700       // Borde en dark mode
-dark:hover:bg-blue-600     // Hover en dark mode
-```
-
-### Colores para Dark Mode
-
-| Token (Dark) | Valor Hex | Descripción |
-|--------------|-----------|-------------|
-| `dark-bg-primary` | `#000000` | Fondo principal oscuro |
-| `dark-content-primary` | `#ffffff` | Texto principal claro (blanco) |
-| `dark-border-primary` | `#71717a` | Bordes en dark mode |
-| `dark-border-custom` | `#0f6ae3` | Bordes de componentes interactivos |
-| `dark-bg-inverse` | `#bfe2fe` | Fondos inversos (botones) |
-| `dark-content-inverse` | `#0e79fd` | Texto inverso |
-
-### Combinación con Otros Modificadores
-
-El modificador `dark:` se puede combinar con cualquier otro modificador de Tailwind:
-
-```tsx
-// dark: + hover:
-<button className="
-  bg-primary-custom-600
-  hover:bg-primary-custom-500
-  dark:bg-dark-bg-inverse
-  dark:hover:bg-dark-bg-inverse/90
-">
-  Button con hover en ambos modos
-</button>
-
-// dark: + focus:
-<input className="
-  border-border-primary
-  focus:border-primary-custom-400
-  dark:border-dark-border-primary
-  dark:focus:border-dark-border-custom
-" />
-
-// dark: + responsive (orden correcto: responsive → dark → state)
-<div className="
-  bg-white
-  md:bg-gray-50
-  dark:bg-dark-bg-primary
-  dark:md:bg-gray-900
-">
-  Responsive + dark mode
-</div>
-
-// dark: + group-hover:
-<div className="group">
-  <p className="
-    text-content-secondary
-    group-hover:text-content-primary
-    dark:text-gray-400
-    dark:group-hover:text-white
-  ">
-    Text con group hover
-  </p>
-</div>
-```
-
-### Orden de Modificadores
-
-Cuando combines múltiples modificadores, sigue este orden:
-
-**Formato**: `{responsive}:{dark}:{state}:{utility}`
-
-```tsx
-// ✅ CORRECTO - Orden consistente
-<button className="
-  md:bg-blue-500
-  md:dark:bg-blue-700
-  md:dark:hover:bg-blue-800
-">
-
-// ❌ INCORRECTO - Orden inconsistente
-<button className="
-  dark:md:hover:bg-blue-800
-">
-```
-
-Ejemplos correctos:
-```tsx
-sm:dark:hover:bg-blue-500          // responsive → dark → state
-lg:dark:focus:text-white           // responsive → dark → state
-md:dark:group-hover:opacity-100    // responsive → dark → state
-```
-
-### Estados Hover con Dark Mode
-
-| Token | Light Mode | Dark Mode | Uso |
-|-------|------------|-----------|-----|
-| Hover Overlay | `rgba(0, 0, 0, 0.1)` | `rgba(255, 255, 255, 0.2)` | Botones ghost |
-| Hover Primary | `-primary-custom-500` | `dark-bg-inverse/90` | Botones primarios |
-| Hover Border | `-primary-custom-300` | `dark-border-custom` | Cards interactivas |
-
-```tsx
-// Hover overlay para botones ghost
-<button className="
-  bg-transparent
-  hover:bg-hover-overlay
-  dark:hover:bg-hover-overlay-dark
-">
-  Ghost Button
-</button>
-
-// Hover para botones primarios
-<button className="
-  bg-primary-custom-600
-  hover:bg-primary-custom-500
-  dark:bg-dark-bg-inverse
-  dark:hover:bg-dark-bg-inverse/90
-">
-  Primary Button
-</button>
-
-// Hover para cards interactivas
-<div className="
-  border-border-primary
-  hover:border-primary-custom-300
-  dark:border-dark-border-primary
-  dark:hover:border-dark-border-custom
-">
-  Interactive Card
-</div>
-```
-
-### Implementación con JavaScript
-
-Para alternar entre modos, agrega/quita la clase `dark` del elemento `<html>`:
-
-```tsx
-// Toggle básico
-const toggleDarkMode = () => {
-  document.documentElement.classList.toggle('dark');
-};
-
-// Con persistencia en localStorage
-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');
-  }
-};
-
-// Aplicar tema guardado al cargar
-const savedTheme = localStorage.getItem('theme');
-if (savedTheme === 'dark') {
-  document.documentElement.classList.add('dark');
-}
-```
-
-**Ver**: `docs/dark-mode-guide.md` para implementación completa con React hooks y Context API.
-
-### Ejemplo Completo de Componente
-
-```tsx
-// Card que adapta todos sus colores a dark mode
-export const AdaptiveCard = () => {
-  return (
-    <div className="
-      p-6
-      bg-white dark:bg-dark-bg-primary
-      border border-border-primary dark:border-dark-border-primary
-      rounded-2xl
-      shadow-base
-      hover:shadow-lg
-      transition-shadow
-    ">
-      {/* Header */}
-      <div className="mb-4 flex items-center justify-between">
-        <h3 className="
-          text-content-primary dark:text-dark-content-primary
-          font-bold
-          text-lg
-        ">
-          Card Title
-        </h3>
-        <span className="
-          text-content-secondary dark:text-content-secondary
-          text-sm
-        ">
-          Just now
-        </span>
-      </div>
-
-      {/* Content */}
-      <p className="
-        mb-4
-        text-content-secondary dark:text-content-secondary
-      ">
-        Card content que se adapta automáticamente según el modo activo.
-        Todos los colores usan el modificador dark: correctamente.
-      </p>
-
-      {/* Actions */}
-      <div className="flex gap-3">
-        <button className="
-          px-4 py-2
-          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
-          rounded-md
-          font-bold
-          transition-colors
-        ">
-          Primary
-        </button>
-
-        <button className="
-          px-4 py-2
-          border border-border-primary dark:border-dark-border-custom
-          text-content-primary dark:text-dark-content-primary
-          hover:bg-background-secondary dark:hover:bg-dark-bg-primary
-          rounded-md
-          font-bold
-          transition-colors
-        ">
-          Secondary
-        </button>
-      </div>
-    </div>
-  );
-};
-```
-
----
-
-## Guía de Uso en Componentes
-
-### ✅ Buenas Prácticas
-
-#### 1. **Usar Tokens Semánticos, NO Primitivos**
-
-```tsx
-// ✅ CORRECTO - Usa tokens semánticos
-<p className="text-content-primary">Texto principal</p>
-
-// ❌ INCORRECTO - Usa primitivos directamente
-<p className="text-primary-custom-600">Texto</p>
-```
-
-**Razón**: Los tokens permiten cambiar el sistema de colores sin tocar componentes.
-
----
-
-#### 2. **Especificar Dark Mode Explícitamente**
-
-```tsx
-// ✅ CORRECTO - Dark mode explícito
-<div className="bg-white dark:bg-dark-bg-primary">
-  Contenido
-</div>
-
-// ⚠️ EVITAR - Confiar en defaults
-<div className="bg-white">
-  Contenido
-</div>
-```
-
----
-
-#### 3. **Agrupar Colores Relacionados**
-
-```tsx
-// ✅ CORRECTO - Colores agrupados por propósito
-<button className="
-  bg-primary-inverse-background
-  text-primary-inverse-content
-  border-primary-inverse-border
-">
-  Botón
-</button>
-```
-
----
-
-#### 4. **Usar Hover Overlay para Interacciones Sutiles**
-
-```tsx
-// ✅ CORRECTO - Hover overlay ligero
-<button className="
-  bg-transparent
-  hover:bg-hover-overlay
-  dark:hover:bg-hover-overlay-dark
-">
-  Plain Button
-</button>
-```
-
----
-
-### ❌ Anti-Patrones a Evitar
-
-#### 1. **NO mezclar capas**
-
-```tsx
-// ❌ INCORRECTO - Mezcla tokens y primitivos
-<div className="text-content-primary bg-primary-custom-600">
-  Contenido
-</div>
-```
-
-#### 2. **NO hardcodear valores hex**
-
-```tsx
-// ❌ INCORRECTO - Valor hex hardcodeado
-<div style={{ backgroundColor: '#0e79fd' }}>
-  Contenido
-</div>
-```
-
-#### 3. **NO usar colores Tailwind nativos en componentes core**
-
-```tsx
-// ❌ INCORRECTO - Tailwind nativo (inconsistente)
-<div className="bg-blue-500 text-white">
-  Contenido
-</div>
-
-// ✅ CORRECTO - Tokens del sistema
-<div className="bg-primary-inverse-background text-primary-inverse-content">
-  Contenido
-</div>
-```
-
----
-
-## Ejemplos de Código
-
-### Ejemplo 1: Botón Primario
-
-```tsx
-import React from 'react';
-
-export const PrimaryButton = ({ children, onClick }) => {
-  return (
-    <button
-      onClick={onClick}
-      className="
-        bg-primary-inverse-background
-        text-primary-inverse-content
-        border border-primary-inverse-border
-        hover:bg-primary-custom-500
-        focus:ring-2 focus:ring-primary-custom-400 focus:ring-offset-2
-        active:scale-95
-        disabled:opacity-50 disabled:cursor-not-allowed
-        px-4 py-2 rounded-md font-bold
-        transition-all duration-150
-        dark:bg-primary-inverse-background
-        dark:text-primary-inverse-content
-        dark:hover:bg-primary-custom-500
-      "
-    >
-      {children}
-    </button>
-  );
-};
-```
-
----
-
-### Ejemplo 2: Card con Dark Mode
-
-```tsx
-import React from 'react';
-
-export const Card = ({ title, description }) => {
-  return (
-    <div className="
-      bg-white dark:bg-dark-bg-primary
-      border border-border-primary dark:border-dark-border-primary
-      rounded-lg p-6
-      shadow-sm
-    ">
-      <h3 className="
-        text-content-primary dark:text-dark-content-primary
-        text-xl font-bold mb-2
-      ">
-        {title}
-      </h3>
-      <p className="
-        text-content-secondary dark:text-dark-content-primary
-        opacity-80
-      ">
-        {description}
-      </p>
-    </div>
-  );
-};
-```
-
----
-
-### Ejemplo 3: Input con Validación
-
-```tsx
-import React from 'react';
-
-export const Input = ({ label, error, ...props }) => {
-  return (
-    <div className="space-y-1">
-      <label className="text-content-primary dark:text-dark-content-primary text-sm font-medium">
-        {label}
-      </label>
-      <input
-        {...props}
-        className={`
-          w-full px-3 py-2 rounded-md
-          bg-white dark:bg-dark-bg-primary
-          text-content-primary dark:text-dark-content-primary
-          border-2
-          ${error
-            ? 'border-error-border bg-error-bg focus:ring-error-border'
-            : 'border-border-primary dark:border-dark-border-primary focus:ring-primary-custom-400'
-          }
-          focus:outline-none focus:ring-2 focus:ring-offset-1
-          disabled:opacity-50 disabled:cursor-not-allowed
-        `}
-      />
-      {error && (
-        <p className="text-error-content text-sm">
-          {error}
-        </p>
-      )}
-    </div>
-  );
-};
-```
-
----
-
-## Mejores Prácticas
-
-### 🎯 Principios de Uso
-
-1. **Jerarquía de Texto**
-   - `content-primary`: Títulos y contenido principal
-   - `content-secondary`: Descripciones y labels
-   - `content-tertiary`: Placeholders y texto deshabilitado
-
-2. **Contraste y Accesibilidad**
-   - Verificar ratios de contraste (WCAG AA mínimo: 4.5:1)
-   - Usar herramientas como [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
-   - Contenido principal debe tener AAA (7:1)
-
-3. **Estados Interactivos**
-   - **Default**: Color base del token
-   - **Hover**: Tono más claro/oscuro (+100 en escala)
-   - **Active**: Tono más oscuro (-100 en escala)
-   - **Focus**: Ring con `primary-custom-400`
-   - **Disabled**: Reducir opacity a 50%
-
-4. **Consistencia en Componentes**
-   - Todos los botones primarios usan los mismos colores
-   - Todos los inputs usan los mismos bordes
-   - Todos los errores usan la misma paleta
-
----
-
-### 🔧 Flujo de Trabajo Recomendado
-
-```
-1. Diseño en Figma
-   ↓
-2. Identificar colores usados
-   ↓
-3. Mapear a tokens existentes
-   ↓
-4. Si no existe token → Crear nuevo en tailwind.config.js
-   ↓
-5. Implementar en componente
-   ↓
-6. Probar en Light y Dark mode
-   ↓
-7. Verificar accesibilidad (contraste)
-```
-
----
-
-## Referencia Rápida
-
-### Cheat Sheet: Colores por Caso de Uso
-
-| Caso de Uso | Light Mode | Dark Mode |
-|-------------|------------|-----------|
-| **Fondo principal** | `bg-white` | `dark:bg-dark-bg-primary` |
-| **Fondo secundario** | `background-secondary` | `dark:bg-dark-bg-primary` |
-| **Texto principal** | `text-content-primary` | `dark:text-dark-content-primary` |
-| **Texto secundario** | `text-content-secondary` | `dark:text-dark-content-primary opacity-80` |
-| **Bordes normales** | `border-border-primary` | `dark:border-dark-border-primary` |
-| **Botón primario BG** | `bg-primary-inverse-background` | `dark:bg-primary-inverse-background` |
-| **Botón primario texto** | `text-primary-inverse-content` | `dark:text-primary-inverse-content` |
-| **Focus ring** | `focus:ring-primary-custom-400` | `focus:ring-primary-custom-400` |
-| **Error BG** | `bg-error-bg` | `bg-error-bg` |
-| **Error texto** | `text-error-content` | `text-error-content` |
-| **Hover overlay** | `hover:bg-hover-overlay` | `dark:hover:bg-hover-overlay-dark` |
-
----
-
-### Configuración en `tailwind.config.js`
-
-```javascript
-// Archivo: tailwind.config.js
-module.exports = {
-  darkMode: 'class',
-  theme: {
-    extend: {
-      colors: {
-        // Primary Custom Colors
-        'primary-custom': {
-          100: '#dbeefe',
-          300: '#93d1fd',
-          400: '#60b6fa',
-          500: '#3c9bf6',
-          600: '#0e79fd',
-          700: '#0c6ade',
-        },
-
-        // Primary Inverse
-        'primary-inverse-content': '#eff8ff',
-        'primary-inverse-background': '#0e79fd',
-        'primary-inverse-border': '#3c9bf6',
-
-        // System Colors (Light)
-        'content-primary': '#18181b',
-        'content-secondary': '#a1a1aa',
-        'content-tertiary': '#71717a',
-        'bg-primary': '#ffffff',
-        'background-secondary': '#f4f4f5',
-        'border-primary': '#e4e4e7',
-        'border-secondary': '#f4f4f5',
-
-        // Error Colors
-        'error-border': '#ef4444',
-        'error-content': '#dc2626',
-        'error-bg': '#fef2f2',
-
-        // Dark Mode Colors
-        'dark-bg-primary': '#18181b', // zinc-900 - gris muy oscuro
-        'dark-content-primary': '#ffffff',
-        'dark-border-primary': '#71717a',
-        'dark-border-custom': '#0f6ae3',
-        'dark-bg-inverse': '#bfe2fe',
-        'dark-content-inverse': '#0e79fd',
-      },
-
-      backgroundColor: {
-        'hover-overlay': 'rgba(0, 0, 0, 0.1)',
-        'hover-overlay-dark': 'rgba(255, 255, 255, 0.2)',
-      },
-    },
-  },
-};
-```
-
----
-
-## 📚 Referencias
-
-- **Figma**: [Color Primitives](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=16-4560&m=dev)
-- **Figma**: [Color Tokens](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4001-1314&m=dev)
-- **Código**: `tailwind.config.js` (líneas 15-73)
-- **WCAG**: [Web Content Accessibility Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
-
----
-
-## 🔄 Historial de Cambios
-
-| Versión | Fecha | Cambios |
-|---------|-------|---------|
-| 1.0.0 | 2025-11-11 | Documentación inicial del sistema de colores |
-
----
-
-**Última actualización**: 2025-11-11
-**Mantenido por**: Equipo de Siesa UI Kit
+# 🎨 Sistema de Colores - Siesa UI Kit
+
+## 📋 Tabla de Contenidos
+
+1. [Introducción](#introducción)
+2. [Arquitectura de Colores](#arquitectura-de-colores)
+3. [Colores Primitivos](#colores-primitivos)
+4. [Tokens Semánticos](#tokens-semánticos)
+5. [Modos de Color (Light/Dark)](#modos-de-color-lightdark)
+6. [Guía de Uso en Componentes](#guía-de-uso-en-componentes)
+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
+
+Este documento describe el sistema de colores del **Siesa UI Kit**, diseñado para garantizar consistencia visual, accesibilidad y mantenibilidad en todos los componentes de la interfaz.
+
+### 🎯 Objetivos del Sistema
+
+- **Consistencia**: Colores unificados en toda la aplicación
+- **Accesibilidad**: Ratios de contraste WCAG AA/AAA
+- **Mantenibilidad**: Tokens semánticos fáciles de actualizar
+- **Escalabilidad**: Sistema extensible para nuevos componentes
+- **Dark Mode**: Soporte completo para modo oscuro
+
+---
+
+## Arquitectura de Colores
+
+El sistema de colores está estructurado en 3 capas:
+
+```
+┌─────────────────────────────────────┐
+│  CAPA 3: Componentes                │
+│  (Button, Alert, Badge, etc.)       │
+└─────────────────────────────────────┘
+              ▲
+              │ usa tokens
+              │
+┌─────────────────────────────────────┐
+│  CAPA 2: Tokens Semánticos          │
+│  (content-primary, bg-primary, etc) │
+└─────────────────────────────────────┘
+              ▲
+              │ mapea a
+              │
+┌─────────────────────────────────────┐
+│  CAPA 1: Colores Primitivos         │
+│  (primary-custom-600, gray-100, etc)│
+└─────────────────────────────────────┘
+```
+
+### Principios de Diseño
+
+1. **Primitivos = Valores Hex**: Colores base inmutables
+2. **Tokens = Intención de Uso**: Nombres semánticos que describen propósito
+3. **Componentes = Aplicación**: Uso consistente de tokens
+
+---
+
+## Colores Primitivos
+
+Los colores primitivos son la base del sistema. Están organizados en escalas de 100-700 (actualmente) con planes de expandir a 50-950.
+
+### 📘 Primary Custom (Azul Principal)
+
+Color primario de marca Siesa. Usado en botones, enlaces y elementos interactivos principales.
+
+| Escala | Valor Hex | CSS Class | Uso Principal |
+|--------|-----------|-----------|---------------|
+| **100** | `#dbeefe` | `primary-custom-100` | Hover backgrounds (outline buttons) |
+| **300** | `#93d1fd` | `primary-custom-300` | Bordes (outline buttons, inputs) |
+| **400** | `#60b6fa` | `primary-custom-400` | Focus rings |
+| **500** | `#3c9bf6` | `primary-custom-500` | Hover state (default buttons) |
+| **600** | `#0e79fd` | `primary-custom-600` | **Color principal** (contenido, íconos) |
+| **700** | `#0c6ade` | `primary-custom-700` | Active/Pressed states |
+
+**Ejemplo de Aplicación**:
+```tsx
+// Botón primario
+<button className="bg-primary-custom-600 hover:bg-primary-custom-500 focus:ring-primary-custom-400">
+  Click me
+</button>
+```
+
+---
+
+### 🎨 Colores Inverse (Para fondos oscuros)
+
+Colores optimizados para usar sobre fondos de color primario.
+
+| Token | Valor Hex | Uso |
+|-------|-----------|-----|
+| `primary-inverse-content` | `#eff8ff` | Texto sobre fondo primario |
+| `primary-inverse-background` | `#0e79fd` | Fondo de botones primarios |
+| `primary-inverse-border` | `#3c9bf6` | Bordes sobre fondo primario |
+
+**Ejemplo de Aplicación**:
+```tsx
+// Botón con fondo primario y texto claro
+<button className="bg-primary-inverse-background text-primary-inverse-content border-primary-inverse-border">
+  Botón Primario
+</button>
+```
+
+---
+
+### 🌈 Colores del Sistema (Light Mode)
+
+Paleta neutral para textos, fondos y bordes en modo claro.
+
+#### Contenido (Texto)
+
+| Token | Valor Hex | Uso | Contraste |
+|-------|-----------|-----|-----------|
+| `content-primary` | `#18181b` | Texto principal | AAA (18:1) |
+| `content-secondary` | `#a1a1aa` | Descripciones, labels | AA (4.5:1) |
+| `content-tertiary` | `#71717a` | Placeholders, disabled text | AA (4.5:1) |
+
+#### Fondos
+
+| Token | Valor Hex | Uso |
+|-------|-----------|-----|
+| `bg-primary` | `#ffffff` | Fondo principal de la app |
+| `background-secondary` | `#f4f4f5` | Cards, fondos disabled |
+
+#### Bordes
+
+| Token | Valor Hex | Uso |
+|-------|-----------|-----|
+| `border-primary` | `#e4e4e7` | Bordes normales (inputs, cards) |
+| `border-secondary` | `#f4f4f5` | Dividers, bordes suaves |
+
+**Ejemplo de Aplicación**:
+```tsx
+// Card con sistema de colores semánticos
+<div className="bg-bg-primary border border-border-primary">
+  <h3 className="text-content-primary">Título Principal</h3>
+  <p className="text-content-secondary">Descripción secundaria</p>
+</div>
+```
+
+---
+
+### 🔴 Colores de Error
+
+Paleta para estados de error y validación.
+
+| Token | Valor Hex | Base Color | Uso |
+|-------|-----------|------------|-----|
+| `error-bg` | `#fef2f2` | Red 50 | Fondo de alertas de error |
+| `error-border` | `#ef4444` | Red 500 | Bordes de inputs con error |
+| `error-content` | `#dc2626` | Red 600 | Texto de mensajes de error |
+
+**Ejemplo de Aplicación**:
+```tsx
+// Input con error
+<div className="border-2 border-error-border bg-error-bg">
+  <input type="text" />
+  <span className="text-error-content">Email inválido</span>
+</div>
+```
+
+> **⚠️ PENDIENTE**: Agregar colores para Success, Warning, Info con la misma estructura.
+
+---
+
+## Tokens Semánticos
+
+Los tokens semánticos describen **dónde y cómo** usar los colores, no **qué color** son.
+
+### 📊 Estructura de Tokens
+
+```
+{categoria}-{proposito}-{variante}
+
+Ejemplos:
+- content-primary (Categoría: content, Propósito: primary)
+- bg-secondary (Categoría: bg, Propósito: secondary)
+- border-custom (Categoría: border, Propósito: custom)
+```
+
+### Categorías de Tokens
+
+| Categoría | Prefijo | Uso | Ejemplos |
+|-----------|---------|-----|----------|
+| **Content** | `content-` | Texto, íconos | `content-primary`, `content-secondary` |
+| **Background** | `bg-`, `background-` | Fondos | `bg-primary`, `background-secondary` |
+| **Border** | `border-` | Bordes, divisores | `border-primary`, `border-secondary` |
+| **Primary Custom** | `primary-custom-` | Color de marca | `primary-custom-600`, `primary-custom-300` |
+| **Error** | `error-` | Estados de error | `error-bg`, `error-border`, `error-content` |
+
+---
+
+## Modos de Color (Light/Dark)
+
+### Configuración de Tailwind CSS
+
+Siesa UI Kit utiliza la estrategia **class-based** de Tailwind CSS para dark mode:
+
+```javascript
+// tailwind.config.js
+module.exports = {
+  darkMode: 'class', // ✅ Estrategia basada en clases
+  // ... resto de la configuración
+}
+```
+
+Con `darkMode: 'class'`, el modificador `dark:` se activa cuando un elemento ancestro (típicamente `<html>`) tiene la clase `dark`:
+
+### 🌞 Light Mode (Por Defecto)
+
+```html
+<html>
+  <!-- Sin clase 'dark' = Light Mode activo -->
+  <body>
+    <div class="bg-white text-content-primary">
+      Contenido en light mode
+    </div>
+  </body>
+</html>
+```
+
+### 🌙 Dark Mode
+
+```html
+<html class="dark">
+  <!-- Con clase 'dark' = Dark Mode activo -->
+  <body>
+    <div class="bg-white dark:bg-dark-bg-primary text-content-primary dark:text-dark-content-primary">
+      Contenido adaptado a dark mode
+    </div>
+  </body>
+</html>
+```
+
+### Modificador dark: en Tailwind
+
+El modificador `dark:` funciona como prefijo para cualquier utilidad de Tailwind:
+
+```tsx
+// Sintaxis básica
+dark:{utility}
+
+// Ejemplos
+dark:bg-dark-bg-primary    // Background en dark mode
+dark:text-white            // Texto en dark mode
+dark:border-gray-700       // Borde en dark mode
+dark:hover:bg-blue-600     // Hover en dark mode
+```
+
+### Colores para Dark Mode
+
+| Token (Dark) | Valor Hex | Descripción |
+|--------------|-----------|-------------|
+| `dark-bg-primary` | `#000000` | Fondo principal oscuro |
+| `dark-content-primary` | `#ffffff` | Texto principal claro (blanco) |
+| `dark-border-primary` | `#71717a` | Bordes en dark mode |
+| `dark-border-custom` | `#0f6ae3` | Bordes de componentes interactivos |
+| `dark-bg-inverse` | `#bfe2fe` | Fondos inversos (botones) |
+| `dark-content-inverse` | `#0e79fd` | Texto inverso |
+
+### Combinación con Otros Modificadores
+
+El modificador `dark:` se puede combinar con cualquier otro modificador de Tailwind:
+
+```tsx
+// dark: + hover:
+<button className="
+  bg-primary-custom-600
+  hover:bg-primary-custom-500
+  dark:bg-dark-bg-inverse
+  dark:hover:bg-dark-bg-inverse/90
+">
+  Button con hover en ambos modos
+</button>
+
+// dark: + focus:
+<input className="
+  border-border-primary
+  focus:border-primary-custom-400
+  dark:border-dark-border-primary
+  dark:focus:border-dark-border-custom
+" />
+
+// dark: + responsive (orden correcto: responsive → dark → state)
+<div className="
+  bg-white
+  md:bg-gray-50
+  dark:bg-dark-bg-primary
+  dark:md:bg-gray-900
+">
+  Responsive + dark mode
+</div>
+
+// dark: + group-hover:
+<div className="group">
+  <p className="
+    text-content-secondary
+    group-hover:text-content-primary
+    dark:text-gray-400
+    dark:group-hover:text-white
+  ">
+    Text con group hover
+  </p>
+</div>
+```
+
+### Orden de Modificadores
+
+Cuando combines múltiples modificadores, sigue este orden:
+
+**Formato**: `{responsive}:{dark}:{state}:{utility}`
+
+```tsx
+// ✅ CORRECTO - Orden consistente
+<button className="
+  md:bg-blue-500
+  md:dark:bg-blue-700
+  md:dark:hover:bg-blue-800
+">
+
+// ❌ INCORRECTO - Orden inconsistente
+<button className="
+  dark:md:hover:bg-blue-800
+">
+```
+
+Ejemplos correctos:
+```tsx
+sm:dark:hover:bg-blue-500          // responsive → dark → state
+lg:dark:focus:text-white           // responsive → dark → state
+md:dark:group-hover:opacity-100    // responsive → dark → state
+```
+
+### Estados Hover con Dark Mode
+
+| Token | Light Mode | Dark Mode | Uso |
+|-------|------------|-----------|-----|
+| Hover Overlay | `rgba(0, 0, 0, 0.1)` | `rgba(255, 255, 255, 0.2)` | Botones ghost |
+| Hover Primary | `-primary-custom-500` | `dark-bg-inverse/90` | Botones primarios |
+| Hover Border | `-primary-custom-300` | `dark-border-custom` | Cards interactivas |
+
+```tsx
+// Hover overlay para botones ghost
+<button className="
+  bg-transparent
+  hover:bg-hover-overlay
+  dark:hover:bg-hover-overlay-dark
+">
+  Ghost Button
+</button>
+
+// Hover para botones primarios
+<button className="
+  bg-primary-custom-600
+  hover:bg-primary-custom-500
+  dark:bg-dark-bg-inverse
+  dark:hover:bg-dark-bg-inverse/90
+">
+  Primary Button
+</button>
+
+// Hover para cards interactivas
+<div className="
+  border-border-primary
+  hover:border-primary-custom-300
+  dark:border-dark-border-primary
+  dark:hover:border-dark-border-custom
+">
+  Interactive Card
+</div>
+```
+
+### Implementación con JavaScript
+
+Para alternar entre modos, agrega/quita la clase `dark` del elemento `<html>`:
+
+```tsx
+// Toggle básico
+const toggleDarkMode = () => {
+  document.documentElement.classList.toggle('dark');
+};
+
+// Con persistencia en localStorage
+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');
+  }
+};
+
+// Aplicar tema guardado al cargar
+const savedTheme = localStorage.getItem('theme');
+if (savedTheme === 'dark') {
+  document.documentElement.classList.add('dark');
+}
+```
+
+**Ver**: `docs/dark-mode-guide.md` para implementación completa con React hooks y Context API.
+
+### Ejemplo Completo de Componente
+
+```tsx
+// Card que adapta todos sus colores a dark mode
+export const AdaptiveCard = () => {
+  return (
+    <div className="
+      p-6
+      bg-white dark:bg-dark-bg-primary
+      border border-border-primary dark:border-dark-border-primary
+      rounded-2xl
+      shadow-base
+      hover:shadow-lg
+      transition-shadow
+    ">
+      {/* Header */}
+      <div className="mb-4 flex items-center justify-between">
+        <h3 className="
+          text-content-primary dark:text-dark-content-primary
+          font-bold
+          text-lg
+        ">
+          Card Title
+        </h3>
+        <span className="
+          text-content-secondary dark:text-content-secondary
+          text-sm
+        ">
+          Just now
+        </span>
+      </div>
+
+      {/* Content */}
+      <p className="
+        mb-4
+        text-content-secondary dark:text-content-secondary
+      ">
+        Card content que se adapta automáticamente según el modo activo.
+        Todos los colores usan el modificador dark: correctamente.
+      </p>
+
+      {/* Actions */}
+      <div className="flex gap-3">
+        <button className="
+          px-4 py-2
+          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
+          rounded-md
+          font-bold
+          transition-colors
+        ">
+          Primary
+        </button>
+
+        <button className="
+          px-4 py-2
+          border border-border-primary dark:border-dark-border-custom
+          text-content-primary dark:text-dark-content-primary
+          hover:bg-background-secondary dark:hover:bg-dark-bg-primary
+          rounded-md
+          font-bold
+          transition-colors
+        ">
+          Secondary
+        </button>
+      </div>
+    </div>
+  );
+};
+```
+
+---
+
+## Guía de Uso en Componentes
+
+### ✅ Buenas Prácticas
+
+#### 1. **Usar Tokens Semánticos, NO Primitivos**
+
+```tsx
+// ✅ CORRECTO - Usa tokens semánticos
+<p className="text-content-primary">Texto principal</p>
+
+// ❌ INCORRECTO - Usa primitivos directamente
+<p className="text-primary-custom-600">Texto</p>
+```
+
+**Razón**: Los tokens permiten cambiar el sistema de colores sin tocar componentes.
+
+---
+
+#### 2. **Especificar Dark Mode Explícitamente**
+
+```tsx
+// ✅ CORRECTO - Dark mode explícito
+<div className="bg-white dark:bg-dark-bg-primary">
+  Contenido
+</div>
+
+// ⚠️ EVITAR - Confiar en defaults
+<div className="bg-white">
+  Contenido
+</div>
+```
+
+---
+
+#### 3. **Agrupar Colores Relacionados**
+
+```tsx
+// ✅ CORRECTO - Colores agrupados por propósito
+<button className="
+  bg-primary-inverse-background
+  text-primary-inverse-content
+  border-primary-inverse-border
+">
+  Botón
+</button>
+```
+
+---
+
+#### 4. **Usar Hover Overlay para Interacciones Sutiles**
+
+```tsx
+// ✅ CORRECTO - Hover overlay ligero
+<button className="
+  bg-transparent
+  hover:bg-hover-overlay
+  dark:hover:bg-hover-overlay-dark
+">
+  Plain Button
+</button>
+```
+
+---
+
+### ❌ Anti-Patrones a Evitar
+
+#### 1. **NO mezclar capas**
+
+```tsx
+// ❌ INCORRECTO - Mezcla tokens y primitivos
+<div className="text-content-primary bg-primary-custom-600">
+  Contenido
+</div>
+```
+
+#### 2. **NO hardcodear valores hex**
+
+```tsx
+// ❌ INCORRECTO - Valor hex hardcodeado
+<div style={{ backgroundColor: '#0e79fd' }}>
+  Contenido
+</div>
+```
+
+#### 3. **NO usar colores Tailwind nativos en componentes core**
+
+```tsx
+// ❌ INCORRECTO - Tailwind nativo (inconsistente)
+<div className="bg-blue-500 text-white">
+  Contenido
+</div>
+
+// ✅ CORRECTO - Tokens del sistema
+<div className="bg-primary-inverse-background text-primary-inverse-content">
+  Contenido
+</div>
+```
+
+---
+
+## Ejemplos de Código
+
+### Ejemplo 1: Botón Primario
+
+```tsx
+import React from 'react';
+
+export const PrimaryButton = ({ children, onClick }) => {
+  return (
+    <button
+      onClick={onClick}
+      className="
+        bg-primary-inverse-background
+        text-primary-inverse-content
+        border border-primary-inverse-border
+        hover:bg-primary-custom-500
+        focus:ring-2 focus:ring-primary-custom-400 focus:ring-offset-2
+        active:scale-95
+        disabled:opacity-50 disabled:cursor-not-allowed
+        px-4 py-2 rounded-md font-bold
+        transition-all duration-150
+        dark:bg-primary-inverse-background
+        dark:text-primary-inverse-content
+        dark:hover:bg-primary-custom-500
+      "
+    >
+      {children}
+    </button>
+  );
+};
+```
+
+---
+
+### Ejemplo 2: Card con Dark Mode
+
+```tsx
+import React from 'react';
+
+export const Card = ({ title, description }) => {
+  return (
+    <div className="
+      bg-white dark:bg-dark-bg-primary
+      border border-border-primary dark:border-dark-border-primary
+      rounded-lg p-6
+      shadow-sm
+    ">
+      <h3 className="
+        text-content-primary dark:text-dark-content-primary
+        text-xl font-bold mb-2
+      ">
+        {title}
+      </h3>
+      <p className="
+        text-content-secondary dark:text-dark-content-primary
+        opacity-80
+      ">
+        {description}
+      </p>
+    </div>
+  );
+};
+```
+
+---
+
+### Ejemplo 3: Input con Validación
+
+```tsx
+import React from 'react';
+
+export const Input = ({ label, error, ...props }) => {
+  return (
+    <div className="space-y-1">
+      <label className="text-content-primary dark:text-dark-content-primary text-sm font-medium">
+        {label}
+      </label>
+      <input
+        {...props}
+        className={`
+          w-full px-3 py-2 rounded-md
+          bg-white dark:bg-dark-bg-primary
+          text-content-primary dark:text-dark-content-primary
+          border-2
+          ${error
+            ? 'border-error-border bg-error-bg focus:ring-error-border'
+            : 'border-border-primary dark:border-dark-border-primary focus:ring-primary-custom-400'
+          }
+          focus:outline-none focus:ring-2 focus:ring-offset-1
+          disabled:opacity-50 disabled:cursor-not-allowed
+        `}
+      />
+      {error && (
+        <p className="text-error-content text-sm">
+          {error}
+        </p>
+      )}
+    </div>
+  );
+};
+```
+
+---
+
+## Mejores Prácticas
+
+### 🎯 Principios de Uso
+
+1. **Jerarquía de Texto**
+   - `content-primary`: Títulos y contenido principal
+   - `content-secondary`: Descripciones y labels
+   - `content-tertiary`: Placeholders y texto deshabilitado
+
+2. **Contraste y Accesibilidad**
+   - Verificar ratios de contraste (WCAG AA mínimo: 4.5:1)
+   - Usar herramientas como [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+   - Contenido principal debe tener AAA (7:1)
+
+3. **Estados Interactivos**
+   - **Default**: Color base del token
+   - **Hover**: Tono más claro/oscuro (+100 en escala)
+   - **Active**: Tono más oscuro (-100 en escala)
+   - **Focus**: Ring con `primary-custom-400`
+   - **Disabled**: Reducir opacity a 50%
+
+4. **Consistencia en Componentes**
+   - Todos los botones primarios usan los mismos colores
+   - Todos los inputs usan los mismos bordes
+   - Todos los errores usan la misma paleta
+
+---
+
+### 🔧 Flujo de Trabajo Recomendado
+
+```
+1. Diseño en Figma
+   ↓
+2. Identificar colores usados
+   ↓
+3. Mapear a tokens existentes
+   ↓
+4. Si no existe token → Crear nuevo en tailwind.config.js
+   ↓
+5. Implementar en componente
+   ↓
+6. Probar en Light y Dark mode
+   ↓
+7. Verificar accesibilidad (contraste)
+```
+
+---
+
+## Referencia Rápida
+
+### Cheat Sheet: Colores por Caso de Uso
+
+| Caso de Uso | Light Mode | Dark Mode |
+|-------------|------------|-----------|
+| **Fondo principal** | `bg-white` | `dark:bg-dark-bg-primary` |
+| **Fondo secundario** | `background-secondary` | `dark:bg-dark-bg-primary` |
+| **Texto principal** | `text-content-primary` | `dark:text-dark-content-primary` |
+| **Texto secundario** | `text-content-secondary` | `dark:text-dark-content-primary opacity-80` |
+| **Bordes normales** | `border-border-primary` | `dark:border-dark-border-primary` |
+| **Botón primario BG** | `bg-primary-inverse-background` | `dark:bg-primary-inverse-background` |
+| **Botón primario texto** | `text-primary-inverse-content` | `dark:text-primary-inverse-content` |
+| **Focus ring** | `focus:ring-primary-custom-400` | `focus:ring-primary-custom-400` |
+| **Error BG** | `bg-error-bg` | `bg-error-bg` |
+| **Error texto** | `text-error-content` | `text-error-content` |
+| **Hover overlay** | `hover:bg-hover-overlay` | `dark:hover:bg-hover-overlay-dark` |
+
+---
+
+### Configuración en `tailwind.config.js`
+
+```javascript
+// Archivo: tailwind.config.js
+module.exports = {
+  darkMode: 'class',
+  theme: {
+    extend: {
+      colors: {
+        // Primary Custom Colors
+        'primary-custom': {
+          100: '#dbeefe',
+          300: '#93d1fd',
+          400: '#60b6fa',
+          500: '#3c9bf6',
+          600: '#0e79fd',
+          700: '#0c6ade',
+        },
+
+        // Primary Inverse
+        'primary-inverse-content': '#eff8ff',
+        'primary-inverse-background': '#0e79fd',
+        'primary-inverse-border': '#3c9bf6',
+
+        // System Colors (Light)
+        'content-primary': '#18181b',
+        'content-secondary': '#a1a1aa',
+        'content-tertiary': '#71717a',
+        'bg-primary': '#ffffff',
+        'background-secondary': '#f4f4f5',
+        'border-primary': '#e4e4e7',
+        'border-secondary': '#f4f4f5',
+
+        // Error Colors
+        'error-border': '#ef4444',
+        'error-content': '#dc2626',
+        'error-bg': '#fef2f2',
+
+        // Dark Mode Colors
+        'dark-bg-primary': '#18181b', // zinc-900 - gris muy oscuro
+        'dark-content-primary': '#ffffff',
+        'dark-border-primary': '#71717a',
+        'dark-border-custom': '#0f6ae3',
+        'dark-bg-inverse': '#bfe2fe',
+        'dark-content-inverse': '#0e79fd',
+      },
+
+      backgroundColor: {
+        'hover-overlay': 'rgba(0, 0, 0, 0.1)',
+        'hover-overlay-dark': 'rgba(255, 255, 255, 0.2)',
+      },
+    },
+  },
+};
+```
+
+---
+
+## 📚 Referencias
+
+- **Figma**: [Color Primitives](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=16-4560&m=dev)
+- **Figma**: [Color Tokens](https://www.figma.com/design/5XNqf2YTxvwemxwo1LMQ6j/Siesa-UI-Kit?node-id=4001-1314&m=dev)
+- **Código**: `tailwind.config.js` (líneas 15-73)
+- **WCAG**: [Web Content Accessibility Guidelines](https://www.w3.org/WAI/WCAG21/quickref/)
+
+---
+
+## 🔄 Historial de Cambios
+
+| Versión | Fecha | Cambios |
+|---------|-------|---------|
+| 1.0.0 | 2025-11-11 | Documentación inicial del sistema de colores |
+
+---
+
+**Última actualización**: 2025-11-11
+**Mantenido por**: Equipo de Siesa UI Kit