# Referencia Completa — Tailwind CSS v4

## Tokens de Color Completos

```css
@theme {
  /* Sistema de colores semántico */
  --color-fondo: #ffffff;
  --color-superficie: #f8fafc;
  --color-borde: #e2e8f0;
  --color-texto: #0f172a;
  --color-texto-muted: #64748b;

  /* Paleta de marca */
  --color-marca-50:  oklch(97% 0.01 250);
  --color-marca-100: oklch(93% 0.03 250);
  --color-marca-200: oklch(86% 0.06 250);
  --color-marca-300: oklch(77% 0.10 250);
  --color-marca-400: oklch(67% 0.15 250);
  --color-marca-500: oklch(56% 0.20 250);
  --color-marca-600: oklch(46% 0.20 250);
  --color-marca-700: oklch(38% 0.18 250);
  --color-marca-800: oklch(30% 0.14 250);
  --color-marca-900: oklch(22% 0.10 250);

  /* Estados */
  --color-exito:    oklch(65% 0.20 145);
  --color-error:    oklch(58% 0.24  27);
  --color-advertencia: oklch(78% 0.18  80);
  --color-info:     oklch(62% 0.20 250);
}
```

## Tipografía y Escalas Fluidas

```css
@theme {
  /* Escala tipográfica fluida */
  --text-xs:   clamp(0.70rem, 0.5vw + 0.5rem, 0.75rem);
  --text-sm:   clamp(0.85rem, 0.8vw + 0.5rem, 0.875rem);
  --text-base: clamp(1rem,    1vw  + 0.5rem, 1rem);
  --text-lg:   clamp(1.1rem,  1.5vw + 0.5rem, 1.125rem);
  --text-xl:   clamp(1.2rem,  2vw  + 0.5rem, 1.25rem);
  --text-2xl:  clamp(1.4rem,  3vw  + 0.5rem, 1.5rem);
  --text-4xl:  clamp(2rem,    5vw  + 0.5rem, 2.25rem);

  /* Line heights */
  --leading-tight:   1.25;
  --leading-snug:    1.375;
  --leading-normal:  1.5;
  --leading-relaxed: 1.625;
}
```

---

## Patrón: Composición de Layouts

```tsx
// Layout de dos columnas con sidebar
function DashboardLayout({ children }: { children: React.ReactNode }) {
  return (
    <div className="flex min-h-screen bg-fondo">
      <aside className="w-64 shrink-0 border-r border-borde bg-superficie">
        <NavSidebar />
      </aside>
      <main className="flex-1 overflow-auto p-6">
        {children}
      </main>
    </div>
  );
}
```

## Patrón: Tarjeta con Variantes

```tsx
const cardVariants = cva('rounded-lg border bg-superficie', {
  variants: {
    elevacion: {
      none: 'shadow-none',
      sm:   'shadow-sm',
      md:   'shadow-md',
      lg:   'shadow-lg ring-1 ring-black/5',
    },
    padding: {
      none: 'p-0',
      sm:   'p-4',
      md:   'p-6',
      lg:   'p-8',
    },
  },
  defaultVariants: { elevacion: 'sm', padding: 'md' },
});
```

---

## Plugin Custom Completo

```typescript
// plugins/animation-plugin.ts
import plugin from 'tailwindcss/plugin';

export const animacionesPlugin = plugin(
  ({ addUtilities, addComponents, theme }) => {
    // Utilidades de animación custom
    addUtilities({
      '.animate-fade-in': {
        animation: 'fadeIn 0.3s ease-in-out',
      },
      '.animate-slide-up': {
        animation: 'slideUp 0.4s ease-out',
      },
    });

    // Componente de badge
    addComponents({
      '.badge': {
        display: 'inline-flex',
        alignItems: 'center',
        padding: `${theme('spacing.1')} ${theme('spacing.2')}`,
        borderRadius: theme('borderRadius.full'),
        fontSize: theme('fontSize.xs'),
        fontWeight: '500',
      },
    });
  },
  {
    // Keyframes del plugin
    theme: {
      extend: {
        keyframes: {
          fadeIn: {
            from: { opacity: '0' },
            to: { opacity: '1' },
          },
          slideUp: {
            from: { transform: 'translateY(10px)', opacity: '0' },
            to: { transform: 'translateY(0)', opacity: '1' },
          },
        },
      },
    },
  }
);
```

---

## Compilación JIT y Purging

Tailwind v4 usa JIT por defecto. Solo genera las clases que realmente usas:

```css
/* globals.css */
@import "tailwindcss";

/* Tailwind escanea automáticamente archivos .tsx, .ts, .jsx, .js, .html */
/* Para archivos especiales, agregar fuentes adicionales: */
@source "../node_modules/mi-libreria-ui/dist/**/*.js";
```

### Valores arbitrarios (escape hatch)

```html
<!-- Valor exacto que no está en el sistema -->
<div class="top-[117px] w-[calc(100%-2rem)] bg-[#1da1f2]">

<!-- Variable CSS arbitraria -->
<div class="text-(--color-personalizado)">
```

---

## Anti-patrón: Olvidar el Orden de Variantes

```html
<!-- MAL: dark: debe aplicarse DESPUÉS del estado base en la misma propiedad -->
<div class="dark:bg-gray-900 bg-white hover:dark:bg-gray-800 hover:bg-gray-50">

<!-- BIEN: agrupar por propiedad, modificadores al final -->
<div class="bg-white dark:bg-gray-900 hover:bg-gray-50 dark:hover:bg-gray-800">
```
