siesa-ui-kit 1.0.4 → 1.0.5

package/docs/typography.md

@@ -1,1268 +1,1268 @@
-# Sistema de Tipografía - Siesa UI Kit
-
-## 📋 Tabla de Contenidos
-
-1. [Introducción](#introducción)
-2. [Familia Tipográfica](#familia-tipográfica)
-3. [Escala Tipográfica](#escala-tipográfica)
-4. [Display](#display)
-5. [Heading](#heading)
-6. [Label](#label)
-7. [Paragraph](#paragraph)
-8. [Guía de Uso](#guía-de-uso)
-9. [Pesos Tipográficos](#pesos-tipográficos)
-10. [Ejemplos de Código](#ejemplos-de-código)
-11. [Mejores Prácticas](#mejores-prácticas)
-12. [Dark Mode](#dark-mode)
-13. [Referencia Rápida](#referencia-rápida)
-
----
-
-## Introducción
-
-El sistema tipográfico de Siesa UI Kit está diseñado para proporcionar una jerarquía visual clara y consistente en todas las interfaces. Utilizamos la familia tipográfica personalizada **SiesaBT** con un sistema de escalas bien definido que abarca desde títulos grandes hasta textos pequeños.
-
-### Objetivos del Sistema Tipográfico
-
-- **Jerarquía Clara**: Escalas bien definidas para organizar la información
-- **Legibilidad**: Tamaños y alturas de línea optimizados para lectura
-- **Consistencia**: Uso uniforme de pesos y estilos en todo el sistema
-- **Flexibilidad**: Escalas adaptables para diferentes contextos
-- **Accesibilidad**: Cumplimiento de estándares WCAG para contraste y tamaño
-
-### Principios de Diseño
-
-1. **Escalas Semánticas**: Cada escala tiene un propósito claro (Display, Heading, Label, Paragraph)
-2. **Proporciones Armónicas**: Progresión coherente entre tamaños
-3. **Espaciado Vertical**: Line-height optimizado para cada tamaño
-4. **Peso Apropiado**: Bold para títulos y labels, Regular para párrafos
-
----
-
-## Familia Tipográfica
-
-### SiesaBT
-
-**SiesaBT** es la familia tipográfica corporativa de Siesa, diseñada específicamente para reflejar la identidad de marca.
-
-#### Pesos Disponibles
-
-| Peso | Font-Weight | Archivo | Uso Principal |
-|------|-------------|---------|---------------|
-| **Light** | 300 | SiesaBT-Light.otf | Textos decorativos, énfasis suave |
-| **Regular** | 400 | SiesaBT-Regular.otf | **Párrafos, contenido principal** |
-| **Bold** | 700 | SiesaBT-Bold.otf | **Títulos, labels, botones** |
-
-#### Configuración
-
-```css
-/* src/index.css */
-@font-face {
-  font-family: 'SiesaBT';
-  src: url('./assets/fonts/SiesaBT/SiesaBT-Regular.otf') format('opentype');
-  font-weight: 400;
-  font-style: normal;
-  font-display: swap;
-}
-
-@font-face {
-  font-family: 'SiesaBT';
-  src: url('./assets/fonts/SiesaBT/SiesaBT-Light.otf') format('opentype');
-  font-weight: 300;
-  font-style: normal;
-  font-display: swap;
-}
-
-@font-face {
-  font-family: 'SiesaBT';
-  src: url('./assets/fonts/SiesaBT/SiesaBT-Bold.otf') format('opentype');
-  font-weight: 700;
-  font-style: normal;
-  font-display: swap;
-}
-```
-
-```javascript
-// tailwind.config.js
-fontFamily: {
-  sans: ['SiesaBT', 'Inter', 'sans-serif'],
-}
-```
-
-#### Fallbacks
-
-- **Primario**: SiesaBT
-- **Secundario**: Inter (sans-serif moderna)
-- **Terciario**: sans-serif (sistema)
-
----
-
-## Escala Tipográfica
-
-El sistema tipográfico se organiza en **4 categorías semánticas** con **17 escalas totales**:
-
-| Categoría | Escalas | Peso | Letter Spacing | Uso |
-|-----------|---------|------|----------------|-----|
-| **Display** | 5 tamaños | Bold (700) | -2.5% | Heros, títulos muy grandes |
-| **Heading** | 4 tamaños | Bold (700) | -2.5% | Títulos de secciones |
-| **Label** | 4 tamaños | Bold (700) | 0% | Labels, botones, badges |
-| **Paragraph** | 4 tamaños | Regular (400) | 0% | Contenido, textos largos |
-
----
-
-## Display
-
-**Uso**: Títulos hero, landing pages, banners principales, presentaciones impactantes.
-
-**Características**:
-- Font-weight: 700 (Bold)
-- Letter-spacing: -2.5% (tracking más cerrado)
-- Line-height: Igual al font-size (leading compacto)
-
-### Escalas Display
-
-| Nombre | Tailwind Class | Font Size | Line Height | Tracking | Uso |
-|--------|---------------|-----------|-------------|----------|-----|
-| **Extra Large** | `text-9xl` | 128px (8rem) | 128px (8rem) | -2.5% | Máximo impacto |
-| **Large** | `text-8xl` | 96px (6rem) | 96px (6rem) | -2.5% | Hero sections |
-| **Medium** | `text-7xl` | 72px (4.5rem) | 72px (4.5rem) | -2.5% | Títulos grandes |
-| **Small** | `text-6xl` | 60px (3.75rem) | 60px (3.75rem) | -2.5% | Sub-heros |
-| **Tiny** | `text-5xl` | 48px (3rem) | 48px (3rem) | -2.5% | Títulos medianos |
-
-### Código Display
-
-```tsx
-// Extra Large Display
-<h1 className="text-9xl font-bold tracking-tighter">
-  Bienvenido a Siesa
-</h1>
-
-// Large Display
-<h1 className="text-8xl font-bold tracking-tighter">
-  Soluciones Empresariales
-</h1>
-
-// Medium Display
-<h2 className="text-7xl font-bold tracking-tighter">
-  Innovación Digital
-</h2>
-
-// Small Display
-<h2 className="text-6xl font-bold tracking-tighter">
-  Transformación
-</h2>
-
-// Tiny Display
-<h3 className="text-5xl font-bold tracking-tighter">
-  Nuevas Funcionalidades
-</h3>
-```
-
----
-
-## Heading
-
-**Uso**: Títulos de secciones, encabezados de páginas, títulos de cards, subtítulos importantes.
-
-**Características**:
-- Font-weight: 700 (Bold)
-- Letter-spacing: -2.5% (tracking más cerrado)
-- Line-height: Mayor que font-size (mejor legibilidad)
-
-### Escalas Heading
-
-| Nombre | Tailwind Class | Font Size | Line Height | Tracking | Uso |
-|--------|---------------|-----------|-------------|----------|-----|
-| **Large** | `text-4xl` | 36px (2.25rem) | 40px (2.5rem) | -2.5% | Títulos principales |
-| **Medium** | `text-3xl` | 30px (1.875rem) | 36px (2.25rem) | -2.5% | Títulos secundarios |
-| **Small** | `text-2xl` | 24px (1.5rem) | 32px (2rem) | -2.5% | Subtítulos |
-| **Tiny** | `text-xl` | 20px (1.25rem) | 28px (1.75rem) | -2.5% | Títulos pequeños |
-
-### Código Heading
-
-```tsx
-// Large Heading - Título de página
-<h1 className="text-4xl font-bold tracking-tighter">
-  Panel de Control
-</h1>
-
-// Medium Heading - Título de sección
-<h2 className="text-3xl font-bold tracking-tighter">
-  Estadísticas del Mes
-</h2>
-
-// Small Heading - Título de card
-<h3 className="text-2xl font-bold tracking-tighter">
-  Ventas Totales
-</h3>
-
-// Tiny Heading - Subtítulo
-<h4 className="text-xl font-bold tracking-tighter">
-  Resumen Semanal
-</h4>
-```
-
----
-
-## Label
-
-**Uso**: Labels de formularios, texto de botones, badges, tabs, tooltips, texto enfatizado.
-
-**Características**:
-- Font-weight: 700 (Bold)
-- Letter-spacing: 0% (tracking normal)
-- Line-height: Proporcionado para buena legibilidad
-
-### Escalas Label
-
-| Nombre | Tailwind Class | Font Size | Line Height | Tracking | Uso |
-|--------|---------------|-----------|-------------|----------|-----|
-| **Large** | `text-lg font-bold` | 18px (1.125rem) | 28px (1.75rem) | 0% | Labels grandes |
-| **Base** | `text-base font-bold` | 16px (1rem) | 24px (1.5rem) | 0% | Labels estándar |
-| **Small** | `text-sm font-bold` | 14px (0.875rem) | 20px (1.25rem) | 0% | **Labels comunes, botones** |
-| **Tiny** | `text-xs font-bold` | 12px (0.75rem) | 16px (1rem) | 0% | Badges, tags |
-
-### Código Label
-
-```tsx
-// Large Label
-<label className="text-lg font-bold text-content-primary">
-  Nombre del Proyecto
-</label>
-
-// Base Label
-<label className="text-base font-bold text-content-primary">
-  Correo Electrónico
-</label>
-
-// Small Label - MÁS COMÚN en formularios y botones
-<label className="text-sm font-bold text-content-primary">
-  Usuario
-</label>
-
-// Tiny Label - Badges
-<span className="text-xs font-bold text-primary-custom-600">
-  NUEVO
-</span>
-```
-
----
-
-## Paragraph
-
-**Uso**: Contenido principal, textos descriptivos, párrafos largos, ayudas contextuales.
-
-**Características**:
-- Font-weight: 400 (Regular)
-- Letter-spacing: 0% (tracking normal)
-- Line-height: Generoso para facilitar lectura
-
-### Escalas Paragraph
-
-| Nombre | Tailwind Class | Font Size | Line Height | Tracking | Uso |
-|--------|---------------|-----------|-------------|----------|-----|
-| **Large** | `text-lg` | 18px (1.125rem) | 28px (1.75rem) | 0% | Contenido destacado |
-| **Base** | `text-base` | 16px (1rem) | 24px (1.5rem) | 0% | **Párrafos estándar** |
-| **Small** | `text-sm` | 14px (0.875rem) | 20px (1.25rem) | 0% | Textos secundarios |
-| **Tiny** | `text-xs` | 12px (0.75rem) | 16px (1rem) | 0% | Notas, disclaimers |
-
-### Código Paragraph
-
-```tsx
-// Large Paragraph - Intro destacada
-<p className="text-lg text-content-primary">
-  Bienvenido al sistema de gestión empresarial.
-  Esta plataforma te permite administrar todos los aspectos de tu negocio.
-</p>
-
-// Base Paragraph - Contenido estándar
-<p className="text-base text-content-primary">
-  El panel de control muestra un resumen de las métricas más importantes
-  de tu organización en tiempo real.
-</p>
-
-// Small Paragraph - Descripción secundaria
-<p className="text-sm text-content-secondary">
-  Última actualización: hace 5 minutos
-</p>
-
-// Tiny Paragraph - Nota al pie
-<p className="text-xs text-content-tertiary">
-  * Los datos se actualizan cada 15 minutos
-</p>
-```
-
----
-
-## Guía de Uso
-
-### Cuándo Usar Cada Categoría
-
-#### Display
-- ✅ Landing pages principales
-- ✅ Páginas de marketing
-- ✅ Secciones hero
-- ✅ Presentaciones impactantes
-- ❌ Interfaces de aplicación (demasiado grande)
-- ❌ Dashboards (poco práctico)
-
-#### Heading
-- ✅ Títulos de páginas (text-4xl)
-- ✅ Títulos de secciones (text-3xl)
-- ✅ Títulos de cards (text-2xl)
-- ✅ Subtítulos (text-xl)
-- ✅ **Uso más común en aplicaciones**
-
-#### Label
-- ✅ Labels de formularios (text-sm o text-base)
-- ✅ Texto de botones (text-sm)
-- ✅ Tabs y navegación
-- ✅ Badges y tags (text-xs)
-- ✅ Tooltips (text-xs o text-sm)
-- ✅ **Siempre usar font-bold**
-
-#### Paragraph
-- ✅ Contenido principal (text-base)
-- ✅ Descripciones largas
-- ✅ Textos de ayuda (text-sm)
-- ✅ Notas al pie (text-xs)
-- ✅ **Siempre usar font-normal (Regular)**
-
-### Jerarquía Visual Recomendada
-
-```tsx
-// Página de Dashboard
-<div className="space-y-6">
-  {/* Título Principal - Heading Large */}
-  <h1 className="text-4xl font-bold tracking-tighter">
-    Dashboard Ejecutivo
-  </h1>
-
-  {/* Sección */}
-  <section className="space-y-4">
-    {/* Título de Sección - Heading Medium */}
-    <h2 className="text-3xl font-bold tracking-tighter">
-      Métricas de Ventas
-    </h2>
-
-    {/* Párrafo Descriptivo - Paragraph Base */}
-    <p className="text-base text-content-secondary">
-      Resumen de las ventas del último mes comparado con el período anterior.
-    </p>
-
-    {/* Card */}
-    <div className="border rounded-lg p-4">
-      {/* Título de Card - Heading Small */}
-      <h3 className="text-2xl font-bold tracking-tighter mb-2">
-        Total de Ventas
-      </h3>
-
-      {/* Contenido - Paragraph Small */}
-      <p className="text-sm text-content-tertiary">
-        Comparado con el mes anterior
-      </p>
-    </div>
-  </section>
-</div>
-```
-
----
-
-## Pesos Tipográficos
-
-### Mapa de Clases de Peso
-
-```tsx
-// Light (300) - Uso limitado
-<p className="font-light">Texto decorativo</p>
-
-// Regular (400) - Default para párrafos
-<p className="font-normal">Contenido principal</p>
-
-// Bold (700) - Títulos y labels
-<h1 className="font-bold">Título Principal</h1>
-```
-
-### Uso Semántico de Pesos
-
-| Peso | Clase | Cuándo Usar | Ejemplos |
-|------|-------|-------------|----------|
-| **300** | `font-light` | Decorativo, énfasis suave | Citas, texto hero decorativo |
-| **400** | `font-normal` | **Párrafos, contenido** | Todo el contenido de lectura |
-| **700** | `font-bold` | **Títulos, labels, botones** | H1-H6, labels, botones, badges |
-
-### Reglas de Oro
-
-1. **Párrafos**: Siempre `font-normal` (Regular 400)
-2. **Títulos**: Siempre `font-bold` (Bold 700)
-3. **Labels**: Siempre `font-bold` (Bold 700)
-4. **Botones**: Siempre `font-bold` (Bold 700)
-5. **Badges/Tags**: Siempre `font-bold` (Bold 700)
-
----
-
-## Ejemplos de Código
-
-### Ejemplo 1: Formulario Completo
-
-```tsx
-import { Input } from '@/components/Input';
-import { Button } from '@/components/Button';
-
-export const RegistrationForm = () => {
-  return (
-    <form className="space-y-6 max-w-md">
-      {/* Título - Heading Large */}
-      <h1 className="text-4xl font-bold tracking-tighter text-content-primary">
-        Crear Cuenta
-      </h1>
-
-      {/* Descripción - Paragraph Base */}
-      <p className="text-base text-content-secondary">
-        Completa el formulario para registrarte en la plataforma.
-      </p>
-
-      {/* Campo con Label Small */}
-      <div className="space-y-2">
-        <label className="text-sm font-bold text-content-primary">
-          Nombre Completo
-        </label>
-        <Input placeholder="Juan Pérez" />
-        <p className="text-xs text-content-tertiary">
-          Ingresa tu nombre como aparece en tu documento
-        </p>
-      </div>
-
-      {/* Campo con Label Base */}
-      <div className="space-y-2">
-        <label className="text-base font-bold text-content-primary">
-          Correo Electrónico
-        </label>
-        <Input type="email" placeholder="correo@ejemplo.com" />
-      </div>
-
-      {/* Botón - Label Small (interno) */}
-      <Button type="default" size="base" fullWidth>
-        Registrarse
-      </Button>
-
-      {/* Nota al pie - Paragraph Tiny */}
-      <p className="text-xs text-content-tertiary">
-        Al registrarte, aceptas nuestros términos y condiciones.
-      </p>
-    </form>
-  );
-};
-```
-
-### Ejemplo 2: Card de Estadística
-
-```tsx
-export const StatCard = ({ title, value, description, trend }) => {
-  return (
-    <div className="border border-border-primary rounded-lg p-6 space-y-3">
-      {/* Título - Heading Small */}
-      <h3 className="text-2xl font-bold tracking-tighter text-content-primary">
-        {title}
-      </h3>
-
-      {/* Valor Principal - Display Tiny */}
-      <p className="text-5xl font-bold tracking-tighter text-primary-custom-600">
-        {value}
-      </p>
-
-      {/* Descripción - Paragraph Small */}
-      <p className="text-sm text-content-secondary">
-        {description}
-      </p>
-
-      {/* Badge - Label Tiny */}
-      <span className="inline-flex items-center px-2 py-1 rounded text-xs font-bold bg-green-100 text-green-800">
-        {trend}
-      </span>
-    </div>
-  );
-};
-
-// Uso
-<StatCard
-  title="Ventas Totales"
-  value="$125,430"
-  description="Este mes"
-  trend="+12.5%"
-/>
-```
-
-### Ejemplo 3: Hero Section
-
-```tsx
-export const HeroSection = () => {
-  return (
-    <section className="py-20 px-6 text-center space-y-6">
-      {/* Título Hero - Display Large */}
-      <h1 className="text-8xl font-bold tracking-tighter text-content-primary">
-        Siesa Cloud
-      </h1>
-
-      {/* Subtítulo - Heading Large */}
-      <h2 className="text-4xl font-bold tracking-tighter text-content-secondary">
-        Gestión Empresarial Inteligente
-      </h2>
-
-      {/* Descripción - Paragraph Large */}
-      <p className="text-lg text-content-tertiary max-w-2xl mx-auto">
-        La plataforma todo-en-uno para administrar tu empresa de manera
-        eficiente, con herramientas diseñadas para impulsar tu crecimiento.
-      </p>
-
-      {/* CTAs */}
-      <div className="flex gap-4 justify-center">
-        <Button type="default" size="l">
-          Comenzar Ahora
-        </Button>
-        <Button type="outline" size="l">
-          Ver Demo
-        </Button>
-      </div>
-
-      {/* Nota - Paragraph Tiny */}
-      <p className="text-xs text-content-tertiary">
-        Prueba gratuita de 30 días • No requiere tarjeta de crédito
-      </p>
-    </section>
-  );
-};
-```
-
-### Ejemplo 4: Lista de Artículos
-
-```tsx
-export const ArticleList = ({ articles }) => {
-  return (
-    <div className="space-y-8">
-      {/* Título de Sección - Heading Large */}
-      <h2 className="text-4xl font-bold tracking-tighter text-content-primary">
-        Últimas Noticias
-      </h2>
-
-      {articles.map((article) => (
-        <article key={article.id} className="border-b pb-6 space-y-3">
-          {/* Título del Artículo - Heading Medium */}
-          <h3 className="text-3xl font-bold tracking-tighter text-content-primary">
-            {article.title}
-          </h3>
-
-          {/* Meta información - Label Tiny */}
-          <div className="flex gap-4 text-xs font-bold text-content-tertiary">
-            <span>{article.author}</span>
-            <span>•</span>
-            <span>{article.date}</span>
-            <span>•</span>
-            <span>{article.readTime} min lectura</span>
-          </div>
-
-          {/* Extracto - Paragraph Base */}
-          <p className="text-base text-content-secondary">
-            {article.excerpt}
-          </p>
-
-          {/* Categoría - Label Small */}
-          <span className="inline-block px-3 py-1 text-sm font-bold text-primary-custom-600 bg-primary-custom-100 rounded">
-            {article.category}
-          </span>
-        </article>
-      ))}
-    </div>
-  );
-};
-```
-
----
-
-## Mejores Prácticas
-
-### ✅ Hacer
-
-1. **Usar la escala apropiada para cada contexto**
-   ```tsx
-   // ✅ CORRECTO - Título de página
-   <h1 className="text-4xl font-bold tracking-tighter">Dashboard</h1>
-
-   // ✅ CORRECTO - Contenido
-   <p className="text-base text-content-primary">Contenido...</p>
-   ```
-
-2. **Mantener jerarquía visual clara**
-   ```tsx
-   // ✅ CORRECTO - Jerarquía clara
-   <h1 className="text-4xl">Título Principal</h1>
-   <h2 className="text-3xl">Subtítulo</h2>
-   <p className="text-base">Contenido</p>
-   ```
-
-3. **Usar tracking apropiado**
-   ```tsx
-   // ✅ CORRECTO - Display/Heading con tracking-tighter
-   <h1 className="text-5xl font-bold tracking-tighter">Hero</h1>
-
-   // ✅ CORRECTO - Label/Paragraph sin tracking
-   <p className="text-base">Contenido normal</p>
-   ```
-
-4. **Combinar con pesos semánticos**
-   ```tsx
-   // ✅ CORRECTO - Bold para títulos
-   <h2 className="text-3xl font-bold">Título</h2>
-
-   // ✅ CORRECTO - Regular para párrafos
-   <p className="text-base font-normal">Párrafo</p>
-   ```
-
-5. **Usar colores apropiados**
-   ```tsx
-   // ✅ CORRECTO - Jerarquía de colores
-   <h1 className="text-4xl font-bold text-content-primary">Principal</h1>
-   <p className="text-base text-content-secondary">Secundario</p>
-   <span className="text-sm text-content-tertiary">Terciario</span>
-   ```
-
-### ❌ Evitar
-
-1. **No mezclar categorías sin propósito**
-   ```tsx
-   // ❌ INCORRECTO - Display para contenido normal
-   <p className="text-7xl">Texto normal</p>
-
-   // ✅ CORRECTO
-   <p className="text-base">Texto normal</p>
-   ```
-
-2. **No omitir font-bold en títulos**
-   ```tsx
-   // ❌ INCORRECTO - Título sin bold
-   <h1 className="text-4xl">Título</h1>
-
-   // ✅ CORRECTO
-   <h1 className="text-4xl font-bold">Título</h1>
-   ```
-
-3. **No usar bold en párrafos largos**
-   ```tsx
-   // ❌ INCORRECTO - Párrafo en bold
-   <p className="text-base font-bold">
-     Este es un párrafo muy largo que se vuelve
-     difícil de leer cuando está en negrita...
-   </p>
-
-   // ✅ CORRECTO
-   <p className="text-base">Contenido legible...</p>
-   ```
-
-4. **No saltar demasiados niveles de jerarquía**
-   ```tsx
-   // ❌ INCORRECTO - Salto abrupto
-   <h1 className="text-8xl">Hero</h1>
-   <p className="text-xs">Texto diminuto</p>
-
-   // ✅ CORRECTO - Transición gradual
-   <h1 className="text-8xl">Hero</h1>
-   <h2 className="text-4xl">Subtítulo</h2>
-   <p className="text-base">Contenido</p>
-   ```
-
-5. **No usar Display en UI de aplicación**
-   ```tsx
-   // ❌ INCORRECTO - Display en dashboard
-   <h1 className="text-9xl">Dashboard</h1>
-
-   // ✅ CORRECTO - Heading en dashboard
-   <h1 className="text-4xl font-bold tracking-tighter">Dashboard</h1>
-   ```
-
-### Accesibilidad
-
-1. **Tamaño mínimo para contenido**: text-sm (14px) o mayor
-2. **Contraste**: Usar colores con contraste WCAG AA mínimo (4.5:1)
-3. **Jerarquía HTML**: Usar etiquetas semánticas (h1-h6, p, etc.)
-4. **Responsive**: Ajustar tamaños en móviles
-
-```tsx
-// ✅ CORRECTO - Responsive
-<h1 className="text-3xl md:text-4xl lg:text-5xl font-bold">
-  Título Adaptable
-</h1>
-
-// ✅ CORRECTO - Contraste
-<p className="text-base text-content-primary"> {/* #18181b - buen contraste */}
-  Contenido legible
-</p>
-```
-
-### Performance
-
-1. **Font-display: swap**: Ya configurado en @font-face
-2. **Preload fonts**: Considerar para fonts críticos
-3. **Subset fonts**: Solo caracteres necesarios (español)
-
-```html
-<!-- Preload font crítico -->
-<link
-  rel="preload"
-  href="/src/assets/fonts/SiesaBT/SiesaBT-Bold.otf"
-  as="font"
-  type="font/otf"
-  crossorigin
-/>
-```
-
----
-
-## Dark Mode
-
-La tipografía en dark mode mantiene las mismas escalas y pesos, pero es importante ajustar el contraste visual para garantizar la legibilidad en 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 (típicamente `<html>`).
-
-#### Sintaxis Básica
-
-```tsx
-// Patrón básico para texto
-<h1 className="text-content-primary dark:text-dark-content-primary">
-  Título adaptable
-</h1>
-
-// El título usa:
-// - text-content-primary (#18181b - casi negro) en modo claro
-// - text-dark-content-primary (#ffffff - blanco) en modo oscuro
-```
-
-### Colores de Texto en Dark Mode
-
-```tsx
-// Texto principal en dark mode
-<p className="text-content-primary dark:text-dark-content-primary">
-  Texto que se adapta automáticamente
-</p>
-
-// Usando colores personalizados para dark mode
-<h1 className="text-content-primary dark:text-dark-content-primary">
-  #18181b en light → #93d1fd en dark
-</h1>
-
-// Texto secundario
-<p className="text-content-secondary dark:text-content-secondary">
-  Texto secundario adaptable (#a1a1aa en ambos modos)
-</p>
-
-// Texto terciario
-<span className="text-content-tertiary dark:text-content-tertiary">
-  Placeholders y hints (#71717a en ambos modos)
-</span>
-```
-
-### Combinando con Otros Modificadores
-
-El modificador `dark:` se puede combinar con hover, focus, y responsive:
-
-```tsx
-// Dark mode + Hover
-<a className="
-  text-primary-custom-600 hover:text-primary-custom-500
-  dark:text-blue-400 dark:hover:text-blue-300
-">
-  Enlace con hover
-</a>
-
-// Dark mode + Focus
-<button className="
-  text-content-primary focus:text-primary-custom-600
-  dark:text-dark-content-primary dark:focus:text-blue-400
-">
-  Botón con focus
-</button>
-
-// Dark mode + Responsive
-<h1 className="
-  text-3xl md:text-4xl lg:text-5xl
-  text-content-primary
-  dark:text-dark-content-primary
-">
-  Título responsive y adaptable
-</h1>
-
-// Dark mode + Group hover
-<div className="group">
-  <h3 className="
-    text-content-primary
-    group-hover:text-primary-custom-600
-    dark:text-dark-content-primary
-    dark:group-hover:text-blue-400
-  ">
-    Título que cambia al hover del grupo
-  </h3>
-</div>
-```
-
-### Orden de Modificadores
-
-Tailwind CSS recomienda un orden específico para los modificadores:
-
-**Formato**: `{responsive}:{dark}:{state}:{utility}`
-
-```tsx
-// ✅ CORRECTO - Orden: responsive → dark → state → utility
-<h1 className="
-  text-3xl
-  md:text-4xl
-  md:dark:text-dark-content-primary
-  md:dark:hover:text-blue-400
-">
-  Título con orden correcto
-</h1>
-
-// ❌ INCORRECTO - Orden equivocado
-<h1 className="
-  dark:md:hover:text-blue-400
-">
-  Orden confuso
-</h1>
-```
-
-### Tabla de Colores de Texto por Estado
-
-| Estado | Light Mode | Dark Mode | Descripción |
-|--------|------------|-----------|-------------|
-| **Texto Principal** | `text-content-primary` (#18181b) | `dark:text-dark-content-primary` (#ffffff) | Títulos y contenido principal |
-| **Texto Secundario** | `text-content-secondary` (#a1a1aa) | `dark:text-content-secondary` (#a1a1aa) | Descripciones, metadata |
-| **Texto Terciario** | `text-content-tertiary` (#71717a) | `dark:text-content-tertiary` (#71717a) | Placeholders, hints |
-| **Enlaces** | `text-primary-custom-600` (#0e79fd) | `dark:text-blue-400` | Enlaces y CTAs |
-| **Enlaces Hover** | `hover:text-primary-custom-500` | `dark:hover:text-blue-300` | Estado hover de enlaces |
-| **Texto Deshabilitado** | `text-content-tertiary opacity-50` | `dark:text-dark-content-tertiary opacity-50` | Elementos inactivos |
-
-### Implementación del Toggle Dark Mode
-
-#### Script de Inicialización (Prevenir FOUC)
-
-```html
-<!-- index.html - En el <head> antes de cargar React -->
-<head>
-  <script>
-    // Aplicar tema inmediatamente antes del render
-    (function() {
-      const theme = localStorage.getItem('theme');
-      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
-
-      if (theme === 'dark' || (!theme && prefersDark)) {
-        document.documentElement.classList.add('dark');
-      }
-    })();
-  </script>
-</head>
-```
-
-#### Toggle Component
-
-```tsx
-import { useState, useEffect } from 'react';
-
-export const DarkModeToggle = () => {
-  const [darkMode, setDarkMode] = useState(false);
-
-  useEffect(() => {
-    // Leer preferencia del usuario
-    const isDark = localStorage.getItem('theme') === 'dark';
-    setDarkMode(isDark);
-
-    if (isDark) {
-      document.documentElement.classList.add('dark');
-    }
-  }, []);
-
-  const toggleDarkMode = () => {
-    const newDarkMode = !darkMode;
-    setDarkMode(newDarkMode);
-
-    // Guardar preferencia
-    localStorage.setItem('theme', newDarkMode ? 'dark' : 'light');
-
-    // Aplicar clase
-    if (newDarkMode) {
-      document.documentElement.classList.add('dark');
-    } else {
-      document.documentElement.classList.remove('dark');
-    }
-  };
-
-  return (
-    <button
-      onClick={toggleDarkMode}
-      className="
-        p-2 rounded-md
-        border border-border-primary dark:border-dark-border-primary
-        hover:bg-background-secondary dark:hover:bg-dark-bg-primary
-        text-sm font-bold
-      "
-      aria-label="Toggle dark mode"
-    >
-      {darkMode ? '☀️ Light' : '🌙 Dark'}
-    </button>
-  );
-};
-```
-
-### Mejores Prácticas para Dark Mode
-
-#### 1. Contraste Adecuado
-
-```tsx
-// ✅ CORRECTO - Buen contraste en ambos modos
-<div className="bg-white dark:bg-dark-bg-primary">
-  <h1 className="text-content-primary dark:text-dark-content-primary font-bold text-4xl">
-    Título legible
-  </h1>
-  <p className="text-content-secondary dark:text-content-secondary">
-    Contenido secundario con buen contraste
-  </p>
-</div>
-
-// ❌ INCORRECTO - Mismo color en ambos modos
-<h1 className="text-gray-900 font-bold">
-  Difícil de leer en dark mode
-</h1>
-```
-
-#### 2. Uso de Tokens de Color
-
-```tsx
-// ✅ CORRECTO - Usar tokens del sistema que se adaptan
-<article>
-  <h2 className="text-content-primary dark:text-dark-content-primary font-bold text-2xl mb-4">
-    Título del Artículo
-  </h2>
-  <p className="text-content-primary dark:text-dark-content-primary mb-4">
-    Contenido principal que se adapta automáticamente al modo oscuro.
-  </p>
-  <p className="text-content-secondary dark:text-content-secondary text-sm">
-    Metadata o texto secundario
-  </p>
-</article>
-
-// ❌ INCORRECTO - Colores hardcodeados
-<article>
-  <h2 className="text-black font-bold text-2xl">Título</h2>
-  <p className="text-gray-900">Contenido</p>
-</article>
-```
-
-#### 3. Fondos con Texto
-
-```tsx
-// ✅ CORRECTO - Fondo y texto se adaptan
-<div className="bg-bg-primary dark:bg-dark-bg-primary p-6 rounded-2xl">
-  <h3 className="text-content-primary dark:text-dark-content-primary font-bold">
-    Card Title
-  </h3>
-  <p className="text-content-secondary dark:text-content-secondary">
-    Card description
-  </p>
-</div>
-
-// Para botones primarios con fondo custom
-<button className="bg-primary-custom-600 dark:bg-dark-bg-inverse text-primary-inverse-content dark:text-dark-content-inverse px-4 py-2 rounded-md font-bold text-sm">
-  Primary Button
-</button>
-```
-
-#### 4. Consistencia en Componentes
-
-```tsx
-// ✅ CORRECTO - Componente que funciona en ambos modos
-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-2xl p-6">
-      <h3 className="text-content-primary dark:text-dark-content-primary font-bold text-xl mb-2">
-        {title}
-      </h3>
-      <p className="text-content-secondary dark:text-content-secondary">
-        {description}
-      </p>
-    </div>
-  );
-};
-```
-
-### Ejemplo Completo: Hero Section con Dark Mode
-
-```tsx
-export const HeroWithDarkMode = () => {
-  return (
-    <section className="bg-bg-primary dark:bg-dark-bg-primary px-6 py-16 md:py-24">
-      <div className="max-w-4xl mx-auto text-center">
-        {/* Hero title */}
-        <h1 className="text-content-primary dark:text-dark-content-primary font-bold text-5xl md:text-7xl tracking-tighter mb-6">
-          Bienvenido a Siesa UI Kit
-        </h1>
-
-        {/* Hero description */}
-        <p className="text-content-secondary dark:text-content-secondary text-lg md:text-xl mb-8 max-w-2xl mx-auto">
-          Un sistema de diseño moderno y completo con soporte nativo para
-          dark mode. Crea interfaces hermosas que funcionan en cualquier modo.
-        </p>
-
-        {/* CTA buttons */}
-        <div className="flex gap-4 justify-center">
-          <button className="bg-primary-custom-600 dark:bg-dark-bg-inverse text-primary-inverse-content dark:text-dark-content-inverse px-6 py-3 rounded-md font-bold">
-            Comenzar
-          </button>
-          <button className="border border-border-primary dark:border-dark-border-custom text-content-primary dark:text-dark-content-primary px-6 py-3 rounded-md font-bold hover:bg-background-secondary dark:hover:bg-dark-bg-primary">
-            Documentación
-          </button>
-        </div>
-
-        {/* Feature list */}
-        <div className="mt-16 grid grid-cols-1 md:grid-cols-3 gap-6">
-          {[
-            { title: 'Tipografía Escalable', desc: '17 escalas de texto' },
-            { title: 'Dark Mode Nativo', desc: 'Soporte completo' },
-            { title: 'Accessible', desc: 'WCAG 2.1 AAA' },
-          ].map((feature) => (
-            <div key={feature.title} className="p-6 border border-border-primary dark:border-dark-border-primary rounded-2xl bg-white dark:bg-dark-bg-primary">
-              <h3 className="text-content-primary dark:text-dark-content-primary font-bold text-lg mb-2">
-                {feature.title}
-              </h3>
-              <p className="text-content-secondary dark:text-content-secondary text-sm">
-                {feature.desc}
-              </p>
-            </div>
-          ))}
-        </div>
-      </div>
-    </section>
-  );
-};
-```
-
-### Toggle de Dark Mode
-
-```tsx
-import { useState, useEffect } from 'react';
-
-export const DarkModeToggle = () => {
-  const [darkMode, setDarkMode] = useState(false);
-
-  useEffect(() => {
-    // Leer preferencia del usuario
-    const isDark = localStorage.getItem('darkMode') === 'true';
-    setDarkMode(isDark);
-
-    if (isDark) {
-      document.documentElement.classList.add('dark');
-    }
-  }, []);
-
-  const toggleDarkMode = () => {
-    const newDarkMode = !darkMode;
-    setDarkMode(newDarkMode);
-
-    // Guardar preferencia
-    localStorage.setItem('darkMode', String(newDarkMode));
-
-    // Aplicar clase
-    if (newDarkMode) {
-      document.documentElement.classList.add('dark');
-    } else {
-      document.documentElement.classList.remove('dark');
-    }
-  };
-
-  return (
-    <button
-      onClick={toggleDarkMode}
-      className="p-2 rounded-md border border-border-primary dark:border-dark-border-primary hover:bg-background-secondary dark:hover:bg-dark-bg-primary"
-      aria-label="Toggle dark mode"
-    >
-      {darkMode ? '☀️' : '🌙'}
-    </button>
-  );
-};
-```
-
-### Tokens de Color para Tipografía
-
-Referencia rápida de colores de texto para dark mode:
-
-| Token Light | Hex Light | Token Dark | Hex Dark | Uso |
-|-------------|-----------|------------|----------|-----|
-| `text-content-primary` | `#18181b` | `dark:text-dark-content-primary` | `#93d1fd` | Texto principal |
-| `text-content-secondary` | `#a1a1aa` | `dark:text-content-secondary` | `#a1a1aa` | Texto secundario |
-| `text-content-tertiary` | `#71717a` | `dark:text-content-tertiary` | `#71717a` | Placeholders, hints |
-| `text-primary-custom-600` | `#0e79fd` | `dark:text-dark-content-primary` | `#93d1fd` | Enlaces, CTA text |
-
-### 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
-- [Documentación oficial de Tailwind Dark Mode](https://tailwindcss.com/docs/dark-mode)
-
----
-
-## Referencia Rápida
-
-### Cheat Sheet: Escalas por Contexto
-
-| Contexto | Clase Recomendada | Font-Weight |
-|----------|-------------------|-------------|
-| **Hero principal** | `text-8xl font-bold tracking-tighter` | 700 |
-| **Título de página** | `text-4xl font-bold tracking-tighter` | 700 |
-| **Título de sección** | `text-3xl font-bold tracking-tighter` | 700 |
-| **Título de card** | `text-2xl font-bold tracking-tighter` | 700 |
-| **Subtítulo** | `text-xl font-bold tracking-tighter` | 700 |
-| **Label de formulario** | `text-sm font-bold` o `text-base font-bold` | 700 |
-| **Texto de botón** | `text-sm font-bold` | 700 |
-| **Badge/Tag** | `text-xs font-bold` | 700 |
-| **Contenido principal** | `text-base` | 400 |
-| **Contenido destacado** | `text-lg` | 400 |
-| **Texto secundario** | `text-sm text-content-secondary` | 400 |
-| **Nota al pie** | `text-xs text-content-tertiary` | 400 |
-
-### Cheat Sheet: Todas las Escalas
-
-```tsx
-// ===== DISPLAY (Bold + tracking-tighter) =====
-<h1 className="text-9xl font-bold tracking-tighter">128px</h1>
-<h1 className="text-8xl font-bold tracking-tighter">96px</h1>
-<h1 className="text-7xl font-bold tracking-tighter">72px</h1>
-<h1 className="text-6xl font-bold tracking-tighter">60px</h1>
-<h1 className="text-5xl font-bold tracking-tighter">48px</h1>
-
-// ===== HEADING (Bold + tracking-tighter) =====
-<h1 className="text-4xl font-bold tracking-tighter">36px</h1>
-<h2 className="text-3xl font-bold tracking-tighter">30px</h2>
-<h3 className="text-2xl font-bold tracking-tighter">24px</h3>
-<h4 className="text-xl font-bold tracking-tighter">20px</h4>
-
-// ===== LABEL (Bold) =====
-<label className="text-lg font-bold">18px</label>
-<label className="text-base font-bold">16px</label>
-<label className="text-sm font-bold">14px</label> {/* MÁS COMÚN */}
-<span className="text-xs font-bold">12px</span>
-
-// ===== PARAGRAPH (Regular) =====
-<p className="text-lg">18px</p>
-<p className="text-base">16px</p> {/* MÁS COMÚN */}
-<p className="text-sm">14px</p>
-<p className="text-xs">12px</p>
-```
-
-### Cheat Sheet: Configuración Tailwind
-
-```javascript
-// tailwind.config.js - fontSize
-fontSize: {
-  // Display
-  '9xl': ['8rem', { lineHeight: '8rem', letterSpacing: '-0.025em', fontWeight: '700' }],
-  '8xl': ['6rem', { lineHeight: '6rem', letterSpacing: '-0.025em', fontWeight: '700' }],
-  '7xl': ['4.5rem', { lineHeight: '4.5rem', letterSpacing: '-0.025em', fontWeight: '700' }],
-  '6xl': ['3.75rem', { lineHeight: '3.75rem', letterSpacing: '-0.025em', fontWeight: '700' }],
-  '5xl': ['3rem', { lineHeight: '3rem', letterSpacing: '-0.025em', fontWeight: '700' }],
-
-  // Heading
-  '4xl': ['2.25rem', { lineHeight: '2.5rem', letterSpacing: '-0.025em', fontWeight: '700' }],
-  '3xl': ['1.875rem', { lineHeight: '2.25rem', letterSpacing: '-0.025em', fontWeight: '700' }],
-  '2xl': ['1.5rem', { lineHeight: '2rem', letterSpacing: '-0.025em', fontWeight: '700' }],
-  'xl': ['1.25rem', { lineHeight: '1.75rem', letterSpacing: '-0.025em', fontWeight: '700' }],
-
-  // Label & Paragraph
-  'lg': ['1.125rem', { lineHeight: '1.75rem' }],
-  'base': ['1rem', { lineHeight: '1.5rem' }],
-  'sm': ['0.875rem', { lineHeight: '1.25rem' }],
-  'xs': ['0.75rem', { lineHeight: '1rem' }],
-},
-
-letterSpacing: {
-  'tighter': '-0.025em', // -2.5%
-},
-```
-
-### Cheat Sheet: Componentes del Sistema
-
-| Componente | Tipografía Usada | Ubicación |
-|------------|------------------|-----------|
-| **Button** | Label Small (14px Bold) | Button.tsx:52-58 |
-| **Input Label** | Label Small/Base (14-16px Bold) | - |
-| **Input Placeholder** | Paragraph Small (14px Regular) | - |
-| **Card Title** | Heading Small (24px Bold) | - |
-| **Badge** | Label Tiny (12px Bold) | - |
-| **Tooltip** | Paragraph Tiny (12px Regular) | - |
-
----
-
-## Recursos Adicionales
-
-### Enlaces Útiles
-
-- **Tailwind Typography**: https://tailwindcss.com/docs/font-size
-- **WCAG Guidelines**: https://www.w3.org/WAI/WCAG21/quickref/#text-spacing
-- **Type Scale Calculator**: https://type-scale.com
-- **Modular Scale**: https://www.modularscale.com
-
-### Archivos Relacionados
-
-- `src/index.css` - Declaraciones @font-face (líneas 1-24)
-- `tailwind.config.js` - Configuración de fontSize (líneas 74-94)
-- `src/components/Button/Button.tsx` - Ejemplo de uso de Label Small
-- `docs/colors.md` - Sistema de colores para tipografía
-- `docs/icons.md` - Sistema de iconos
-
-### Herramientas de Testing
-
-```bash
-# Verificar que las fuentes estén cargando correctamente
-# En DevTools > Network > Filter: Font
-
-# Verificar contraste de texto
-# https://webaim.org/resources/contrastchecker/
-
-# Verificar legibilidad
-# https://www.webfx.com/tools/read-able/
-```
-
----
-
-**Última actualización**: 2025-11-11
-**Versión**: 1.0.0
-**Mantenedor**: Siesa UI Kit Team
+# Sistema de Tipografía - Siesa UI Kit
+
+## 📋 Tabla de Contenidos
+
+1. [Introducción](#introducción)
+2. [Familia Tipográfica](#familia-tipográfica)
+3. [Escala Tipográfica](#escala-tipográfica)
+4. [Display](#display)
+5. [Heading](#heading)
+6. [Label](#label)
+7. [Paragraph](#paragraph)
+8. [Guía de Uso](#guía-de-uso)
+9. [Pesos Tipográficos](#pesos-tipográficos)
+10. [Ejemplos de Código](#ejemplos-de-código)
+11. [Mejores Prácticas](#mejores-prácticas)
+12. [Dark Mode](#dark-mode)
+13. [Referencia Rápida](#referencia-rápida)
+
+---
+
+## Introducción
+
+El sistema tipográfico de Siesa UI Kit está diseñado para proporcionar una jerarquía visual clara y consistente en todas las interfaces. Utilizamos la familia tipográfica personalizada **SiesaBT** con un sistema de escalas bien definido que abarca desde títulos grandes hasta textos pequeños.
+
+### Objetivos del Sistema Tipográfico
+
+- **Jerarquía Clara**: Escalas bien definidas para organizar la información
+- **Legibilidad**: Tamaños y alturas de línea optimizados para lectura
+- **Consistencia**: Uso uniforme de pesos y estilos en todo el sistema
+- **Flexibilidad**: Escalas adaptables para diferentes contextos
+- **Accesibilidad**: Cumplimiento de estándares WCAG para contraste y tamaño
+
+### Principios de Diseño
+
+1. **Escalas Semánticas**: Cada escala tiene un propósito claro (Display, Heading, Label, Paragraph)
+2. **Proporciones Armónicas**: Progresión coherente entre tamaños
+3. **Espaciado Vertical**: Line-height optimizado para cada tamaño
+4. **Peso Apropiado**: Bold para títulos y labels, Regular para párrafos
+
+---
+
+## Familia Tipográfica
+
+### SiesaBT
+
+**SiesaBT** es la familia tipográfica corporativa de Siesa, diseñada específicamente para reflejar la identidad de marca.
+
+#### Pesos Disponibles
+
+| Peso | Font-Weight | Archivo | Uso Principal |
+|------|-------------|---------|---------------|
+| **Light** | 300 | SiesaBT-Light.otf | Textos decorativos, énfasis suave |
+| **Regular** | 400 | SiesaBT-Regular.otf | **Párrafos, contenido principal** |
+| **Bold** | 700 | SiesaBT-Bold.otf | **Títulos, labels, botones** |
+
+#### Configuración
+
+```css
+/* src/index.css */
+@font-face {
+  font-family: 'SiesaBT';
+  src: url('./assets/fonts/SiesaBT/SiesaBT-Regular.otf') format('opentype');
+  font-weight: 400;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'SiesaBT';
+  src: url('./assets/fonts/SiesaBT/SiesaBT-Light.otf') format('opentype');
+  font-weight: 300;
+  font-style: normal;
+  font-display: swap;
+}
+
+@font-face {
+  font-family: 'SiesaBT';
+  src: url('./assets/fonts/SiesaBT/SiesaBT-Bold.otf') format('opentype');
+  font-weight: 700;
+  font-style: normal;
+  font-display: swap;
+}
+```
+
+```javascript
+// tailwind.config.js
+fontFamily: {
+  sans: ['SiesaBT', 'Inter', 'sans-serif'],
+}
+```
+
+#### Fallbacks
+
+- **Primario**: SiesaBT
+- **Secundario**: Inter (sans-serif moderna)
+- **Terciario**: sans-serif (sistema)
+
+---
+
+## Escala Tipográfica
+
+El sistema tipográfico se organiza en **4 categorías semánticas** con **17 escalas totales**:
+
+| Categoría | Escalas | Peso | Letter Spacing | Uso |
+|-----------|---------|------|----------------|-----|
+| **Display** | 5 tamaños | Bold (700) | -2.5% | Heros, títulos muy grandes |
+| **Heading** | 4 tamaños | Bold (700) | -2.5% | Títulos de secciones |
+| **Label** | 4 tamaños | Bold (700) | 0% | Labels, botones, badges |
+| **Paragraph** | 4 tamaños | Regular (400) | 0% | Contenido, textos largos |
+
+---
+
+## Display
+
+**Uso**: Títulos hero, landing pages, banners principales, presentaciones impactantes.
+
+**Características**:
+- Font-weight: 700 (Bold)
+- Letter-spacing: -2.5% (tracking más cerrado)
+- Line-height: Igual al font-size (leading compacto)
+
+### Escalas Display
+
+| Nombre | Tailwind Class | Font Size | Line Height | Tracking | Uso |
+|--------|---------------|-----------|-------------|----------|-----|
+| **Extra Large** | `text-9xl` | 128px (8rem) | 128px (8rem) | -2.5% | Máximo impacto |
+| **Large** | `text-8xl` | 96px (6rem) | 96px (6rem) | -2.5% | Hero sections |
+| **Medium** | `text-7xl` | 72px (4.5rem) | 72px (4.5rem) | -2.5% | Títulos grandes |
+| **Small** | `text-6xl` | 60px (3.75rem) | 60px (3.75rem) | -2.5% | Sub-heros |
+| **Tiny** | `text-5xl` | 48px (3rem) | 48px (3rem) | -2.5% | Títulos medianos |
+
+### Código Display
+
+```tsx
+// Extra Large Display
+<h1 className="text-9xl font-bold tracking-tighter">
+  Bienvenido a Siesa
+</h1>
+
+// Large Display
+<h1 className="text-8xl font-bold tracking-tighter">
+  Soluciones Empresariales
+</h1>
+
+// Medium Display
+<h2 className="text-7xl font-bold tracking-tighter">
+  Innovación Digital
+</h2>
+
+// Small Display
+<h2 className="text-6xl font-bold tracking-tighter">
+  Transformación
+</h2>
+
+// Tiny Display
+<h3 className="text-5xl font-bold tracking-tighter">
+  Nuevas Funcionalidades
+</h3>
+```
+
+---
+
+## Heading
+
+**Uso**: Títulos de secciones, encabezados de páginas, títulos de cards, subtítulos importantes.
+
+**Características**:
+- Font-weight: 700 (Bold)
+- Letter-spacing: -2.5% (tracking más cerrado)
+- Line-height: Mayor que font-size (mejor legibilidad)
+
+### Escalas Heading
+
+| Nombre | Tailwind Class | Font Size | Line Height | Tracking | Uso |
+|--------|---------------|-----------|-------------|----------|-----|
+| **Large** | `text-4xl` | 36px (2.25rem) | 40px (2.5rem) | -2.5% | Títulos principales |
+| **Medium** | `text-3xl` | 30px (1.875rem) | 36px (2.25rem) | -2.5% | Títulos secundarios |
+| **Small** | `text-2xl` | 24px (1.5rem) | 32px (2rem) | -2.5% | Subtítulos |
+| **Tiny** | `text-xl` | 20px (1.25rem) | 28px (1.75rem) | -2.5% | Títulos pequeños |
+
+### Código Heading
+
+```tsx
+// Large Heading - Título de página
+<h1 className="text-4xl font-bold tracking-tighter">
+  Panel de Control
+</h1>
+
+// Medium Heading - Título de sección
+<h2 className="text-3xl font-bold tracking-tighter">
+  Estadísticas del Mes
+</h2>
+
+// Small Heading - Título de card
+<h3 className="text-2xl font-bold tracking-tighter">
+  Ventas Totales
+</h3>
+
+// Tiny Heading - Subtítulo
+<h4 className="text-xl font-bold tracking-tighter">
+  Resumen Semanal
+</h4>
+```
+
+---
+
+## Label
+
+**Uso**: Labels de formularios, texto de botones, badges, tabs, tooltips, texto enfatizado.
+
+**Características**:
+- Font-weight: 700 (Bold)
+- Letter-spacing: 0% (tracking normal)
+- Line-height: Proporcionado para buena legibilidad
+
+### Escalas Label
+
+| Nombre | Tailwind Class | Font Size | Line Height | Tracking | Uso |
+|--------|---------------|-----------|-------------|----------|-----|
+| **Large** | `text-lg font-bold` | 18px (1.125rem) | 28px (1.75rem) | 0% | Labels grandes |
+| **Base** | `text-base font-bold` | 16px (1rem) | 24px (1.5rem) | 0% | Labels estándar |
+| **Small** | `text-sm font-bold` | 14px (0.875rem) | 20px (1.25rem) | 0% | **Labels comunes, botones** |
+| **Tiny** | `text-xs font-bold` | 12px (0.75rem) | 16px (1rem) | 0% | Badges, tags |
+
+### Código Label
+
+```tsx
+// Large Label
+<label className="text-lg font-bold text-content-primary">
+  Nombre del Proyecto
+</label>
+
+// Base Label
+<label className="text-base font-bold text-content-primary">
+  Correo Electrónico
+</label>
+
+// Small Label - MÁS COMÚN en formularios y botones
+<label className="text-sm font-bold text-content-primary">
+  Usuario
+</label>
+
+// Tiny Label - Badges
+<span className="text-xs font-bold text-primary-custom-600">
+  NUEVO
+</span>
+```
+
+---
+
+## Paragraph
+
+**Uso**: Contenido principal, textos descriptivos, párrafos largos, ayudas contextuales.
+
+**Características**:
+- Font-weight: 400 (Regular)
+- Letter-spacing: 0% (tracking normal)
+- Line-height: Generoso para facilitar lectura
+
+### Escalas Paragraph
+
+| Nombre | Tailwind Class | Font Size | Line Height | Tracking | Uso |
+|--------|---------------|-----------|-------------|----------|-----|
+| **Large** | `text-lg` | 18px (1.125rem) | 28px (1.75rem) | 0% | Contenido destacado |
+| **Base** | `text-base` | 16px (1rem) | 24px (1.5rem) | 0% | **Párrafos estándar** |
+| **Small** | `text-sm` | 14px (0.875rem) | 20px (1.25rem) | 0% | Textos secundarios |
+| **Tiny** | `text-xs` | 12px (0.75rem) | 16px (1rem) | 0% | Notas, disclaimers |
+
+### Código Paragraph
+
+```tsx
+// Large Paragraph - Intro destacada
+<p className="text-lg text-content-primary">
+  Bienvenido al sistema de gestión empresarial.
+  Esta plataforma te permite administrar todos los aspectos de tu negocio.
+</p>
+
+// Base Paragraph - Contenido estándar
+<p className="text-base text-content-primary">
+  El panel de control muestra un resumen de las métricas más importantes
+  de tu organización en tiempo real.
+</p>
+
+// Small Paragraph - Descripción secundaria
+<p className="text-sm text-content-secondary">
+  Última actualización: hace 5 minutos
+</p>
+
+// Tiny Paragraph - Nota al pie
+<p className="text-xs text-content-tertiary">
+  * Los datos se actualizan cada 15 minutos
+</p>
+```
+
+---
+
+## Guía de Uso
+
+### Cuándo Usar Cada Categoría
+
+#### Display
+- ✅ Landing pages principales
+- ✅ Páginas de marketing
+- ✅ Secciones hero
+- ✅ Presentaciones impactantes
+- ❌ Interfaces de aplicación (demasiado grande)
+- ❌ Dashboards (poco práctico)
+
+#### Heading
+- ✅ Títulos de páginas (text-4xl)
+- ✅ Títulos de secciones (text-3xl)
+- ✅ Títulos de cards (text-2xl)
+- ✅ Subtítulos (text-xl)
+- ✅ **Uso más común en aplicaciones**
+
+#### Label
+- ✅ Labels de formularios (text-sm o text-base)
+- ✅ Texto de botones (text-sm)
+- ✅ Tabs y navegación
+- ✅ Badges y tags (text-xs)
+- ✅ Tooltips (text-xs o text-sm)
+- ✅ **Siempre usar font-bold**
+
+#### Paragraph
+- ✅ Contenido principal (text-base)
+- ✅ Descripciones largas
+- ✅ Textos de ayuda (text-sm)
+- ✅ Notas al pie (text-xs)
+- ✅ **Siempre usar font-normal (Regular)**
+
+### Jerarquía Visual Recomendada
+
+```tsx
+// Página de Dashboard
+<div className="space-y-6">
+  {/* Título Principal - Heading Large */}
+  <h1 className="text-4xl font-bold tracking-tighter">
+    Dashboard Ejecutivo
+  </h1>
+
+  {/* Sección */}
+  <section className="space-y-4">
+    {/* Título de Sección - Heading Medium */}
+    <h2 className="text-3xl font-bold tracking-tighter">
+      Métricas de Ventas
+    </h2>
+
+    {/* Párrafo Descriptivo - Paragraph Base */}
+    <p className="text-base text-content-secondary">
+      Resumen de las ventas del último mes comparado con el período anterior.
+    </p>
+
+    {/* Card */}
+    <div className="border rounded-lg p-4">
+      {/* Título de Card - Heading Small */}
+      <h3 className="text-2xl font-bold tracking-tighter mb-2">
+        Total de Ventas
+      </h3>
+
+      {/* Contenido - Paragraph Small */}
+      <p className="text-sm text-content-tertiary">
+        Comparado con el mes anterior
+      </p>
+    </div>
+  </section>
+</div>
+```
+
+---
+
+## Pesos Tipográficos
+
+### Mapa de Clases de Peso
+
+```tsx
+// Light (300) - Uso limitado
+<p className="font-light">Texto decorativo</p>
+
+// Regular (400) - Default para párrafos
+<p className="font-normal">Contenido principal</p>
+
+// Bold (700) - Títulos y labels
+<h1 className="font-bold">Título Principal</h1>
+```
+
+### Uso Semántico de Pesos
+
+| Peso | Clase | Cuándo Usar | Ejemplos |
+|------|-------|-------------|----------|
+| **300** | `font-light` | Decorativo, énfasis suave | Citas, texto hero decorativo |
+| **400** | `font-normal` | **Párrafos, contenido** | Todo el contenido de lectura |
+| **700** | `font-bold` | **Títulos, labels, botones** | H1-H6, labels, botones, badges |
+
+### Reglas de Oro
+
+1. **Párrafos**: Siempre `font-normal` (Regular 400)
+2. **Títulos**: Siempre `font-bold` (Bold 700)
+3. **Labels**: Siempre `font-bold` (Bold 700)
+4. **Botones**: Siempre `font-bold` (Bold 700)
+5. **Badges/Tags**: Siempre `font-bold` (Bold 700)
+
+---
+
+## Ejemplos de Código
+
+### Ejemplo 1: Formulario Completo
+
+```tsx
+import { Input } from '@/components/Input';
+import { Button } from '@/components/Button';
+
+export const RegistrationForm = () => {
+  return (
+    <form className="space-y-6 max-w-md">
+      {/* Título - Heading Large */}
+      <h1 className="text-4xl font-bold tracking-tighter text-content-primary">
+        Crear Cuenta
+      </h1>
+
+      {/* Descripción - Paragraph Base */}
+      <p className="text-base text-content-secondary">
+        Completa el formulario para registrarte en la plataforma.
+      </p>
+
+      {/* Campo con Label Small */}
+      <div className="space-y-2">
+        <label className="text-sm font-bold text-content-primary">
+          Nombre Completo
+        </label>
+        <Input placeholder="Juan Pérez" />
+        <p className="text-xs text-content-tertiary">
+          Ingresa tu nombre como aparece en tu documento
+        </p>
+      </div>
+
+      {/* Campo con Label Base */}
+      <div className="space-y-2">
+        <label className="text-base font-bold text-content-primary">
+          Correo Electrónico
+        </label>
+        <Input type="email" placeholder="correo@ejemplo.com" />
+      </div>
+
+      {/* Botón - Label Small (interno) */}
+      <Button type="default" size="base" fullWidth>
+        Registrarse
+      </Button>
+
+      {/* Nota al pie - Paragraph Tiny */}
+      <p className="text-xs text-content-tertiary">
+        Al registrarte, aceptas nuestros términos y condiciones.
+      </p>
+    </form>
+  );
+};
+```
+
+### Ejemplo 2: Card de Estadística
+
+```tsx
+export const StatCard = ({ title, value, description, trend }) => {
+  return (
+    <div className="border border-border-primary rounded-lg p-6 space-y-3">
+      {/* Título - Heading Small */}
+      <h3 className="text-2xl font-bold tracking-tighter text-content-primary">
+        {title}
+      </h3>
+
+      {/* Valor Principal - Display Tiny */}
+      <p className="text-5xl font-bold tracking-tighter text-primary-custom-600">
+        {value}
+      </p>
+
+      {/* Descripción - Paragraph Small */}
+      <p className="text-sm text-content-secondary">
+        {description}
+      </p>
+
+      {/* Badge - Label Tiny */}
+      <span className="inline-flex items-center px-2 py-1 rounded text-xs font-bold bg-green-100 text-green-800">
+        {trend}
+      </span>
+    </div>
+  );
+};
+
+// Uso
+<StatCard
+  title="Ventas Totales"
+  value="$125,430"
+  description="Este mes"
+  trend="+12.5%"
+/>
+```
+
+### Ejemplo 3: Hero Section
+
+```tsx
+export const HeroSection = () => {
+  return (
+    <section className="py-20 px-6 text-center space-y-6">
+      {/* Título Hero - Display Large */}
+      <h1 className="text-8xl font-bold tracking-tighter text-content-primary">
+        Siesa Cloud
+      </h1>
+
+      {/* Subtítulo - Heading Large */}
+      <h2 className="text-4xl font-bold tracking-tighter text-content-secondary">
+        Gestión Empresarial Inteligente
+      </h2>
+
+      {/* Descripción - Paragraph Large */}
+      <p className="text-lg text-content-tertiary max-w-2xl mx-auto">
+        La plataforma todo-en-uno para administrar tu empresa de manera
+        eficiente, con herramientas diseñadas para impulsar tu crecimiento.
+      </p>
+
+      {/* CTAs */}
+      <div className="flex gap-4 justify-center">
+        <Button type="default" size="l">
+          Comenzar Ahora
+        </Button>
+        <Button type="outline" size="l">
+          Ver Demo
+        </Button>
+      </div>
+
+      {/* Nota - Paragraph Tiny */}
+      <p className="text-xs text-content-tertiary">
+        Prueba gratuita de 30 días • No requiere tarjeta de crédito
+      </p>
+    </section>
+  );
+};
+```
+
+### Ejemplo 4: Lista de Artículos
+
+```tsx
+export const ArticleList = ({ articles }) => {
+  return (
+    <div className="space-y-8">
+      {/* Título de Sección - Heading Large */}
+      <h2 className="text-4xl font-bold tracking-tighter text-content-primary">
+        Últimas Noticias
+      </h2>
+
+      {articles.map((article) => (
+        <article key={article.id} className="border-b pb-6 space-y-3">
+          {/* Título del Artículo - Heading Medium */}
+          <h3 className="text-3xl font-bold tracking-tighter text-content-primary">
+            {article.title}
+          </h3>
+
+          {/* Meta información - Label Tiny */}
+          <div className="flex gap-4 text-xs font-bold text-content-tertiary">
+            <span>{article.author}</span>
+            <span>•</span>
+            <span>{article.date}</span>
+            <span>•</span>
+            <span>{article.readTime} min lectura</span>
+          </div>
+
+          {/* Extracto - Paragraph Base */}
+          <p className="text-base text-content-secondary">
+            {article.excerpt}
+          </p>
+
+          {/* Categoría - Label Small */}
+          <span className="inline-block px-3 py-1 text-sm font-bold text-primary-custom-600 bg-primary-custom-100 rounded">
+            {article.category}
+          </span>
+        </article>
+      ))}
+    </div>
+  );
+};
+```
+
+---
+
+## Mejores Prácticas
+
+### ✅ Hacer
+
+1. **Usar la escala apropiada para cada contexto**
+   ```tsx
+   // ✅ CORRECTO - Título de página
+   <h1 className="text-4xl font-bold tracking-tighter">Dashboard</h1>
+
+   // ✅ CORRECTO - Contenido
+   <p className="text-base text-content-primary">Contenido...</p>
+   ```
+
+2. **Mantener jerarquía visual clara**
+   ```tsx
+   // ✅ CORRECTO - Jerarquía clara
+   <h1 className="text-4xl">Título Principal</h1>
+   <h2 className="text-3xl">Subtítulo</h2>
+   <p className="text-base">Contenido</p>
+   ```
+
+3. **Usar tracking apropiado**
+   ```tsx
+   // ✅ CORRECTO - Display/Heading con tracking-tighter
+   <h1 className="text-5xl font-bold tracking-tighter">Hero</h1>
+
+   // ✅ CORRECTO - Label/Paragraph sin tracking
+   <p className="text-base">Contenido normal</p>
+   ```
+
+4. **Combinar con pesos semánticos**
+   ```tsx
+   // ✅ CORRECTO - Bold para títulos
+   <h2 className="text-3xl font-bold">Título</h2>
+
+   // ✅ CORRECTO - Regular para párrafos
+   <p className="text-base font-normal">Párrafo</p>
+   ```
+
+5. **Usar colores apropiados**
+   ```tsx
+   // ✅ CORRECTO - Jerarquía de colores
+   <h1 className="text-4xl font-bold text-content-primary">Principal</h1>
+   <p className="text-base text-content-secondary">Secundario</p>
+   <span className="text-sm text-content-tertiary">Terciario</span>
+   ```
+
+### ❌ Evitar
+
+1. **No mezclar categorías sin propósito**
+   ```tsx
+   // ❌ INCORRECTO - Display para contenido normal
+   <p className="text-7xl">Texto normal</p>
+
+   // ✅ CORRECTO
+   <p className="text-base">Texto normal</p>
+   ```
+
+2. **No omitir font-bold en títulos**
+   ```tsx
+   // ❌ INCORRECTO - Título sin bold
+   <h1 className="text-4xl">Título</h1>
+
+   // ✅ CORRECTO
+   <h1 className="text-4xl font-bold">Título</h1>
+   ```
+
+3. **No usar bold en párrafos largos**
+   ```tsx
+   // ❌ INCORRECTO - Párrafo en bold
+   <p className="text-base font-bold">
+     Este es un párrafo muy largo que se vuelve
+     difícil de leer cuando está en negrita...
+   </p>
+
+   // ✅ CORRECTO
+   <p className="text-base">Contenido legible...</p>
+   ```
+
+4. **No saltar demasiados niveles de jerarquía**
+   ```tsx
+   // ❌ INCORRECTO - Salto abrupto
+   <h1 className="text-8xl">Hero</h1>
+   <p className="text-xs">Texto diminuto</p>
+
+   // ✅ CORRECTO - Transición gradual
+   <h1 className="text-8xl">Hero</h1>
+   <h2 className="text-4xl">Subtítulo</h2>
+   <p className="text-base">Contenido</p>
+   ```
+
+5. **No usar Display en UI de aplicación**
+   ```tsx
+   // ❌ INCORRECTO - Display en dashboard
+   <h1 className="text-9xl">Dashboard</h1>
+
+   // ✅ CORRECTO - Heading en dashboard
+   <h1 className="text-4xl font-bold tracking-tighter">Dashboard</h1>
+   ```
+
+### Accesibilidad
+
+1. **Tamaño mínimo para contenido**: text-sm (14px) o mayor
+2. **Contraste**: Usar colores con contraste WCAG AA mínimo (4.5:1)
+3. **Jerarquía HTML**: Usar etiquetas semánticas (h1-h6, p, etc.)
+4. **Responsive**: Ajustar tamaños en móviles
+
+```tsx
+// ✅ CORRECTO - Responsive
+<h1 className="text-3xl md:text-4xl lg:text-5xl font-bold">
+  Título Adaptable
+</h1>
+
+// ✅ CORRECTO - Contraste
+<p className="text-base text-content-primary"> {/* #18181b - buen contraste */}
+  Contenido legible
+</p>
+```
+
+### Performance
+
+1. **Font-display: swap**: Ya configurado en @font-face
+2. **Preload fonts**: Considerar para fonts críticos
+3. **Subset fonts**: Solo caracteres necesarios (español)
+
+```html
+<!-- Preload font crítico -->
+<link
+  rel="preload"
+  href="/src/assets/fonts/SiesaBT/SiesaBT-Bold.otf"
+  as="font"
+  type="font/otf"
+  crossorigin
+/>
+```
+
+---
+
+## Dark Mode
+
+La tipografía en dark mode mantiene las mismas escalas y pesos, pero es importante ajustar el contraste visual para garantizar la legibilidad en 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 (típicamente `<html>`).
+
+#### Sintaxis Básica
+
+```tsx
+// Patrón básico para texto
+<h1 className="text-content-primary dark:text-dark-content-primary">
+  Título adaptable
+</h1>
+
+// El título usa:
+// - text-content-primary (#18181b - casi negro) en modo claro
+// - text-dark-content-primary (#ffffff - blanco) en modo oscuro
+```
+
+### Colores de Texto en Dark Mode
+
+```tsx
+// Texto principal en dark mode
+<p className="text-content-primary dark:text-dark-content-primary">
+  Texto que se adapta automáticamente
+</p>
+
+// Usando colores personalizados para dark mode
+<h1 className="text-content-primary dark:text-dark-content-primary">
+  #18181b en light → #93d1fd en dark
+</h1>
+
+// Texto secundario
+<p className="text-content-secondary dark:text-content-secondary">
+  Texto secundario adaptable (#a1a1aa en ambos modos)
+</p>
+
+// Texto terciario
+<span className="text-content-tertiary dark:text-content-tertiary">
+  Placeholders y hints (#71717a en ambos modos)
+</span>
+```
+
+### Combinando con Otros Modificadores
+
+El modificador `dark:` se puede combinar con hover, focus, y responsive:
+
+```tsx
+// Dark mode + Hover
+<a className="
+  text-primary-custom-600 hover:text-primary-custom-500
+  dark:text-blue-400 dark:hover:text-blue-300
+">
+  Enlace con hover
+</a>
+
+// Dark mode + Focus
+<button className="
+  text-content-primary focus:text-primary-custom-600
+  dark:text-dark-content-primary dark:focus:text-blue-400
+">
+  Botón con focus
+</button>
+
+// Dark mode + Responsive
+<h1 className="
+  text-3xl md:text-4xl lg:text-5xl
+  text-content-primary
+  dark:text-dark-content-primary
+">
+  Título responsive y adaptable
+</h1>
+
+// Dark mode + Group hover
+<div className="group">
+  <h3 className="
+    text-content-primary
+    group-hover:text-primary-custom-600
+    dark:text-dark-content-primary
+    dark:group-hover:text-blue-400
+  ">
+    Título que cambia al hover del grupo
+  </h3>
+</div>
+```
+
+### Orden de Modificadores
+
+Tailwind CSS recomienda un orden específico para los modificadores:
+
+**Formato**: `{responsive}:{dark}:{state}:{utility}`
+
+```tsx
+// ✅ CORRECTO - Orden: responsive → dark → state → utility
+<h1 className="
+  text-3xl
+  md:text-4xl
+  md:dark:text-dark-content-primary
+  md:dark:hover:text-blue-400
+">
+  Título con orden correcto
+</h1>
+
+// ❌ INCORRECTO - Orden equivocado
+<h1 className="
+  dark:md:hover:text-blue-400
+">
+  Orden confuso
+</h1>
+```
+
+### Tabla de Colores de Texto por Estado
+
+| Estado | Light Mode | Dark Mode | Descripción |
+|--------|------------|-----------|-------------|
+| **Texto Principal** | `text-content-primary` (#18181b) | `dark:text-dark-content-primary` (#ffffff) | Títulos y contenido principal |
+| **Texto Secundario** | `text-content-secondary` (#a1a1aa) | `dark:text-content-secondary` (#a1a1aa) | Descripciones, metadata |
+| **Texto Terciario** | `text-content-tertiary` (#71717a) | `dark:text-content-tertiary` (#71717a) | Placeholders, hints |
+| **Enlaces** | `text-primary-custom-600` (#0e79fd) | `dark:text-blue-400` | Enlaces y CTAs |
+| **Enlaces Hover** | `hover:text-primary-custom-500` | `dark:hover:text-blue-300` | Estado hover de enlaces |
+| **Texto Deshabilitado** | `text-content-tertiary opacity-50` | `dark:text-dark-content-tertiary opacity-50` | Elementos inactivos |
+
+### Implementación del Toggle Dark Mode
+
+#### Script de Inicialización (Prevenir FOUC)
+
+```html
+<!-- index.html - En el <head> antes de cargar React -->
+<head>
+  <script>
+    // Aplicar tema inmediatamente antes del render
+    (function() {
+      const theme = localStorage.getItem('theme');
+      const prefersDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
+
+      if (theme === 'dark' || (!theme && prefersDark)) {
+        document.documentElement.classList.add('dark');
+      }
+    })();
+  </script>
+</head>
+```
+
+#### Toggle Component
+
+```tsx
+import { useState, useEffect } from 'react';
+
+export const DarkModeToggle = () => {
+  const [darkMode, setDarkMode] = useState(false);
+
+  useEffect(() => {
+    // Leer preferencia del usuario
+    const isDark = localStorage.getItem('theme') === 'dark';
+    setDarkMode(isDark);
+
+    if (isDark) {
+      document.documentElement.classList.add('dark');
+    }
+  }, []);
+
+  const toggleDarkMode = () => {
+    const newDarkMode = !darkMode;
+    setDarkMode(newDarkMode);
+
+    // Guardar preferencia
+    localStorage.setItem('theme', newDarkMode ? 'dark' : 'light');
+
+    // Aplicar clase
+    if (newDarkMode) {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  };
+
+  return (
+    <button
+      onClick={toggleDarkMode}
+      className="
+        p-2 rounded-md
+        border border-border-primary dark:border-dark-border-primary
+        hover:bg-background-secondary dark:hover:bg-dark-bg-primary
+        text-sm font-bold
+      "
+      aria-label="Toggle dark mode"
+    >
+      {darkMode ? '☀️ Light' : '🌙 Dark'}
+    </button>
+  );
+};
+```
+
+### Mejores Prácticas para Dark Mode
+
+#### 1. Contraste Adecuado
+
+```tsx
+// ✅ CORRECTO - Buen contraste en ambos modos
+<div className="bg-white dark:bg-dark-bg-primary">
+  <h1 className="text-content-primary dark:text-dark-content-primary font-bold text-4xl">
+    Título legible
+  </h1>
+  <p className="text-content-secondary dark:text-content-secondary">
+    Contenido secundario con buen contraste
+  </p>
+</div>
+
+// ❌ INCORRECTO - Mismo color en ambos modos
+<h1 className="text-gray-900 font-bold">
+  Difícil de leer en dark mode
+</h1>
+```
+
+#### 2. Uso de Tokens de Color
+
+```tsx
+// ✅ CORRECTO - Usar tokens del sistema que se adaptan
+<article>
+  <h2 className="text-content-primary dark:text-dark-content-primary font-bold text-2xl mb-4">
+    Título del Artículo
+  </h2>
+  <p className="text-content-primary dark:text-dark-content-primary mb-4">
+    Contenido principal que se adapta automáticamente al modo oscuro.
+  </p>
+  <p className="text-content-secondary dark:text-content-secondary text-sm">
+    Metadata o texto secundario
+  </p>
+</article>
+
+// ❌ INCORRECTO - Colores hardcodeados
+<article>
+  <h2 className="text-black font-bold text-2xl">Título</h2>
+  <p className="text-gray-900">Contenido</p>
+</article>
+```
+
+#### 3. Fondos con Texto
+
+```tsx
+// ✅ CORRECTO - Fondo y texto se adaptan
+<div className="bg-bg-primary dark:bg-dark-bg-primary p-6 rounded-2xl">
+  <h3 className="text-content-primary dark:text-dark-content-primary font-bold">
+    Card Title
+  </h3>
+  <p className="text-content-secondary dark:text-content-secondary">
+    Card description
+  </p>
+</div>
+
+// Para botones primarios con fondo custom
+<button className="bg-primary-custom-600 dark:bg-dark-bg-inverse text-primary-inverse-content dark:text-dark-content-inverse px-4 py-2 rounded-md font-bold text-sm">
+  Primary Button
+</button>
+```
+
+#### 4. Consistencia en Componentes
+
+```tsx
+// ✅ CORRECTO - Componente que funciona en ambos modos
+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-2xl p-6">
+      <h3 className="text-content-primary dark:text-dark-content-primary font-bold text-xl mb-2">
+        {title}
+      </h3>
+      <p className="text-content-secondary dark:text-content-secondary">
+        {description}
+      </p>
+    </div>
+  );
+};
+```
+
+### Ejemplo Completo: Hero Section con Dark Mode
+
+```tsx
+export const HeroWithDarkMode = () => {
+  return (
+    <section className="bg-bg-primary dark:bg-dark-bg-primary px-6 py-16 md:py-24">
+      <div className="max-w-4xl mx-auto text-center">
+        {/* Hero title */}
+        <h1 className="text-content-primary dark:text-dark-content-primary font-bold text-5xl md:text-7xl tracking-tighter mb-6">
+          Bienvenido a Siesa UI Kit
+        </h1>
+
+        {/* Hero description */}
+        <p className="text-content-secondary dark:text-content-secondary text-lg md:text-xl mb-8 max-w-2xl mx-auto">
+          Un sistema de diseño moderno y completo con soporte nativo para
+          dark mode. Crea interfaces hermosas que funcionan en cualquier modo.
+        </p>
+
+        {/* CTA buttons */}
+        <div className="flex gap-4 justify-center">
+          <button className="bg-primary-custom-600 dark:bg-dark-bg-inverse text-primary-inverse-content dark:text-dark-content-inverse px-6 py-3 rounded-md font-bold">
+            Comenzar
+          </button>
+          <button className="border border-border-primary dark:border-dark-border-custom text-content-primary dark:text-dark-content-primary px-6 py-3 rounded-md font-bold hover:bg-background-secondary dark:hover:bg-dark-bg-primary">
+            Documentación
+          </button>
+        </div>
+
+        {/* Feature list */}
+        <div className="mt-16 grid grid-cols-1 md:grid-cols-3 gap-6">
+          {[
+            { title: 'Tipografía Escalable', desc: '17 escalas de texto' },
+            { title: 'Dark Mode Nativo', desc: 'Soporte completo' },
+            { title: 'Accessible', desc: 'WCAG 2.1 AAA' },
+          ].map((feature) => (
+            <div key={feature.title} className="p-6 border border-border-primary dark:border-dark-border-primary rounded-2xl bg-white dark:bg-dark-bg-primary">
+              <h3 className="text-content-primary dark:text-dark-content-primary font-bold text-lg mb-2">
+                {feature.title}
+              </h3>
+              <p className="text-content-secondary dark:text-content-secondary text-sm">
+                {feature.desc}
+              </p>
+            </div>
+          ))}
+        </div>
+      </div>
+    </section>
+  );
+};
+```
+
+### Toggle de Dark Mode
+
+```tsx
+import { useState, useEffect } from 'react';
+
+export const DarkModeToggle = () => {
+  const [darkMode, setDarkMode] = useState(false);
+
+  useEffect(() => {
+    // Leer preferencia del usuario
+    const isDark = localStorage.getItem('darkMode') === 'true';
+    setDarkMode(isDark);
+
+    if (isDark) {
+      document.documentElement.classList.add('dark');
+    }
+  }, []);
+
+  const toggleDarkMode = () => {
+    const newDarkMode = !darkMode;
+    setDarkMode(newDarkMode);
+
+    // Guardar preferencia
+    localStorage.setItem('darkMode', String(newDarkMode));
+
+    // Aplicar clase
+    if (newDarkMode) {
+      document.documentElement.classList.add('dark');
+    } else {
+      document.documentElement.classList.remove('dark');
+    }
+  };
+
+  return (
+    <button
+      onClick={toggleDarkMode}
+      className="p-2 rounded-md border border-border-primary dark:border-dark-border-primary hover:bg-background-secondary dark:hover:bg-dark-bg-primary"
+      aria-label="Toggle dark mode"
+    >
+      {darkMode ? '☀️' : '🌙'}
+    </button>
+  );
+};
+```
+
+### Tokens de Color para Tipografía
+
+Referencia rápida de colores de texto para dark mode:
+
+| Token Light | Hex Light | Token Dark | Hex Dark | Uso |
+|-------------|-----------|------------|----------|-----|
+| `text-content-primary` | `#18181b` | `dark:text-dark-content-primary` | `#93d1fd` | Texto principal |
+| `text-content-secondary` | `#a1a1aa` | `dark:text-content-secondary` | `#a1a1aa` | Texto secundario |
+| `text-content-tertiary` | `#71717a` | `dark:text-content-tertiary` | `#71717a` | Placeholders, hints |
+| `text-primary-custom-600` | `#0e79fd` | `dark:text-dark-content-primary` | `#93d1fd` | Enlaces, CTA text |
+
+### 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
+- [Documentación oficial de Tailwind Dark Mode](https://tailwindcss.com/docs/dark-mode)
+
+---
+
+## Referencia Rápida
+
+### Cheat Sheet: Escalas por Contexto
+
+| Contexto | Clase Recomendada | Font-Weight |
+|----------|-------------------|-------------|
+| **Hero principal** | `text-8xl font-bold tracking-tighter` | 700 |
+| **Título de página** | `text-4xl font-bold tracking-tighter` | 700 |
+| **Título de sección** | `text-3xl font-bold tracking-tighter` | 700 |
+| **Título de card** | `text-2xl font-bold tracking-tighter` | 700 |
+| **Subtítulo** | `text-xl font-bold tracking-tighter` | 700 |
+| **Label de formulario** | `text-sm font-bold` o `text-base font-bold` | 700 |
+| **Texto de botón** | `text-sm font-bold` | 700 |
+| **Badge/Tag** | `text-xs font-bold` | 700 |
+| **Contenido principal** | `text-base` | 400 |
+| **Contenido destacado** | `text-lg` | 400 |
+| **Texto secundario** | `text-sm text-content-secondary` | 400 |
+| **Nota al pie** | `text-xs text-content-tertiary` | 400 |
+
+### Cheat Sheet: Todas las Escalas
+
+```tsx
+// ===== DISPLAY (Bold + tracking-tighter) =====
+<h1 className="text-9xl font-bold tracking-tighter">128px</h1>
+<h1 className="text-8xl font-bold tracking-tighter">96px</h1>
+<h1 className="text-7xl font-bold tracking-tighter">72px</h1>
+<h1 className="text-6xl font-bold tracking-tighter">60px</h1>
+<h1 className="text-5xl font-bold tracking-tighter">48px</h1>
+
+// ===== HEADING (Bold + tracking-tighter) =====
+<h1 className="text-4xl font-bold tracking-tighter">36px</h1>
+<h2 className="text-3xl font-bold tracking-tighter">30px</h2>
+<h3 className="text-2xl font-bold tracking-tighter">24px</h3>
+<h4 className="text-xl font-bold tracking-tighter">20px</h4>
+
+// ===== LABEL (Bold) =====
+<label className="text-lg font-bold">18px</label>
+<label className="text-base font-bold">16px</label>
+<label className="text-sm font-bold">14px</label> {/* MÁS COMÚN */}
+<span className="text-xs font-bold">12px</span>
+
+// ===== PARAGRAPH (Regular) =====
+<p className="text-lg">18px</p>
+<p className="text-base">16px</p> {/* MÁS COMÚN */}
+<p className="text-sm">14px</p>
+<p className="text-xs">12px</p>
+```
+
+### Cheat Sheet: Configuración Tailwind
+
+```javascript
+// tailwind.config.js - fontSize
+fontSize: {
+  // Display
+  '9xl': ['8rem', { lineHeight: '8rem', letterSpacing: '-0.025em', fontWeight: '700' }],
+  '8xl': ['6rem', { lineHeight: '6rem', letterSpacing: '-0.025em', fontWeight: '700' }],
+  '7xl': ['4.5rem', { lineHeight: '4.5rem', letterSpacing: '-0.025em', fontWeight: '700' }],
+  '6xl': ['3.75rem', { lineHeight: '3.75rem', letterSpacing: '-0.025em', fontWeight: '700' }],
+  '5xl': ['3rem', { lineHeight: '3rem', letterSpacing: '-0.025em', fontWeight: '700' }],
+
+  // Heading
+  '4xl': ['2.25rem', { lineHeight: '2.5rem', letterSpacing: '-0.025em', fontWeight: '700' }],
+  '3xl': ['1.875rem', { lineHeight: '2.25rem', letterSpacing: '-0.025em', fontWeight: '700' }],
+  '2xl': ['1.5rem', { lineHeight: '2rem', letterSpacing: '-0.025em', fontWeight: '700' }],
+  'xl': ['1.25rem', { lineHeight: '1.75rem', letterSpacing: '-0.025em', fontWeight: '700' }],
+
+  // Label & Paragraph
+  'lg': ['1.125rem', { lineHeight: '1.75rem' }],
+  'base': ['1rem', { lineHeight: '1.5rem' }],
+  'sm': ['0.875rem', { lineHeight: '1.25rem' }],
+  'xs': ['0.75rem', { lineHeight: '1rem' }],
+},
+
+letterSpacing: {
+  'tighter': '-0.025em', // -2.5%
+},
+```
+
+### Cheat Sheet: Componentes del Sistema
+
+| Componente | Tipografía Usada | Ubicación |
+|------------|------------------|-----------|
+| **Button** | Label Small (14px Bold) | Button.tsx:52-58 |
+| **Input Label** | Label Small/Base (14-16px Bold) | - |
+| **Input Placeholder** | Paragraph Small (14px Regular) | - |
+| **Card Title** | Heading Small (24px Bold) | - |
+| **Badge** | Label Tiny (12px Bold) | - |
+| **Tooltip** | Paragraph Tiny (12px Regular) | - |
+
+---
+
+## Recursos Adicionales
+
+### Enlaces Útiles
+
+- **Tailwind Typography**: https://tailwindcss.com/docs/font-size
+- **WCAG Guidelines**: https://www.w3.org/WAI/WCAG21/quickref/#text-spacing
+- **Type Scale Calculator**: https://type-scale.com
+- **Modular Scale**: https://www.modularscale.com
+
+### Archivos Relacionados
+
+- `src/index.css` - Declaraciones @font-face (líneas 1-24)
+- `tailwind.config.js` - Configuración de fontSize (líneas 74-94)
+- `src/components/Button/Button.tsx` - Ejemplo de uso de Label Small
+- `docs/colors.md` - Sistema de colores para tipografía
+- `docs/icons.md` - Sistema de iconos
+
+### Herramientas de Testing
+
+```bash
+# Verificar que las fuentes estén cargando correctamente
+# En DevTools > Network > Filter: Font
+
+# Verificar contraste de texto
+# https://webaim.org/resources/contrastchecker/
+
+# Verificar legibilidad
+# https://www.webfx.com/tools/read-able/
+```
+
+---
+
+**Última actualización**: 2025-11-11
+**Versión**: 1.0.0
+**Mantenedor**: Siesa UI Kit Team