npm package: @nrivera-iimp/ui-kit-iimp
Description: Sistema de diseño premium para las verticales de **ProExplo**, **WMC** y **Gess**. Basado en shadcn/ui y Tailwind CSS.
Latest version: 0.1.15

# @nrivera-iimp/ui-kit-iimp 🚀

Sistema de diseño premium para las verticales de **ProExplo**, **WMC** y **Gess**. Basado en shadcn/ui y Tailwind CSS.

Este paquete proporciona una base sólida, accesible y altamente personalizable para todas las aplicaciones web del IIMP, con un motor de theming dinámico integrado.

---

## 🛠️ Instalación

Abre tu terminal en la carpeta del proyecto y ejecuta:

```bash
npm install @nrivera-iimp/ui-kit-iimp lucide-react clsx tailwind-merge next-themes
```

### Requisitos Previos
- **Node.js**: 18.0 o superior
- **Next.js**: 13.0+ (App Router recomendado)
- **Tailwind CSS**: Configurado en el proyecto

---

## ⚙️ Configuración Paso a Paso

### 1. Agregar el Preset de Tailwind
Modifica tu archivo `tailwind.config.ts` (o `.js`) para importar nuestro preset. Esto incluirá automáticamente todos los colores corporativos y animaciones.

```tsx
// tailwind.config.ts
import { iimpPreset } from "@nrivera-iimp/ui-kit-iimp/preset";

export default {
  // El preset añade las variables HSL y la configuración de shadcn/ui
  presets: [iimpPreset],
  content: [
    "./{src/,}app/**/*.{ts,tsx,js,jsx}",
    "./node_modules/@nrivera-iimp/ui-kit-iimp/dist/**/*.{js,mjs}"
  ],
  // ... resto de tu configuración
}
```

### 2. Importar Estilos Globales
En tu archivo `app/globals.css`, añade la importación de nuestros estilos. 

**Si usas Tailwind v4**, es crucial añadir el `@source` para que Tailwind escanee los componentes dentro de `node_modules`.

```css
@import "tailwindcss";
@import "@nrivera-iimp/ui-kit-iimp/styles.css";

/* ⚡️ CRUCIAL PARA TAILWIND v4 ⚡️ */
/* Esto permite que Tailwind encuentre las clases CSS dentro del paquete */
@source "../node_modules/@nrivera-iimp/ui-kit-iimp/dist";
```

### 3. Script Anti-Flash (Crucial)
Para evitar el parpadeo blanco y asegurar que los colores de la vertical carguen instantáneamente, añade este script en el `<head>` de tu `app/layout.tsx`.

```tsx
// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="es" suppressHydrationWarning>
      <head>
        <script
          dangerouslySetInnerHTML={{
            __html: `
              (function() {
                try {
                  const saved = localStorage.getItem('iimp-vertical');
                  const urlParams = new URLSearchParams(window.location.search);
                  const themeParam = urlParams.get('theme');
                  
                  // Vertical por defecto: 'proexplo', 'wmc' o 'gess'
                  const vertical = themeParam || saved || 'proexplo'; 
                  
                  // Aplicar clase y atributo para el motor de HSL
                  document.documentElement.classList.add('vert-' + vertical);
                  document.documentElement.setAttribute('data-vertical', vertical);
                } catch (e) {}
              })();
            `,
          }}
        />
      </head>
      <body>{children}</body>
    </html>
  );
}
```

### 4. Configurar el VerticalProvider
Envuelve tu aplicación con el provider en el layout raíz para gestionar el estado de las verticales y el modo oscuro.

```tsx
import { VerticalProvider } from "@nrivera-iimp/ui-kit-iimp";
import { ThemeProvider } from "next-themes";

export default function RootLayout({ children }) {
  return (
    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
      <VerticalProvider defaultVertical="proexplo">
        {children}
      </VerticalProvider>
    </ThemeProvider>
  );
}
```

---

## 🎨 Theming y Verticales

El sistema utiliza un **HSL Engine** que inyecta variables dinámicamente. 

### Verticales Disponibles:
- `proexplo`: Naranja IIMP (Enfoque en eventos y minería).
- `wmc`: Azul Corporativo (World Mining Congress).
- `gess`: Verde Sostenibilidad (Gestión Social).

### URL Theming (Dinámico)
Puedes forzar el cambio de tema para un cliente específico enviando un parámetro en la URL. El sistema lo detectará, lo guardará en `localStorage` y limpiará la URL automáticamente.

**Ejemplo:** `www.tu-sitio.com?theme=wmc`

---

## 🌓 Dark Mode
El kit tiene soporte nativo para modo oscuro utilizando la clase `.dark` en el HTML. 
- Utiliza los prefijos `dark:` de Tailwind para estilos específicos.
- El `VerticalProvider` ya maneja las variables de contraste optimizadas para fondos oscuros.

---

## 📦 Uso de Componentes

```tsx
import { Button, Card, CardHeader, CardTitle } from "@nrivera-iimp/ui-kit-iimp";

export default function MiPagina() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Hola IIMP</CardTitle>
      </CardHeader>
      <Button variant="default">Click aquí</Button>
    </Card>
  );
}
```

---
© 2026 Instituto de Ingenieros de Minas del Perú. Excelencia en Minería.