@imansi/ui

Componentes React accesibles y sin estilos propios para el ecosistema Imansi. Construidos sobre @imansi/tailwind y Radix UI.

¿Qué es?

@imansi/ui es la librería de componentes React del ecosistema Imansi. Contiene más de 40 componentes accesibles y sin estilos propios: toda la apariencia viene de los design tokens de @imansi/tailwind.

Cambiar el tema o el modo (light/dark) es un solo atributo en <html>. Los componentes se adaptan automáticamente sin una sola línea condicional.

Construidos sobre Radix UI para máxima accesibilidad (foco, teclado, ARIA) y estilizados exclusivamente con Tailwind CSS v4.

Parte del ecosistema Imansi — infraestructura moderna para tus apps.

Instalación

bash

npm install @imansi/ui @imansi/tailwind

Requiere:

React 18+ o 19
Tailwind CSS v4
@imansi/tailwind como peer dependency

Instalá Tailwind v4 y el plugin de Vite (o PostCSS):

bash

npm install -D tailwindcss @tailwindcss/vite

Configuración

1. Configurar Vite

// vite.config.js
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'

export default defineConfig({
  plugins: [react(), tailwindcss()],
  optimizeDeps: {
    exclude: ['@imansi/ui'],
  },
})

El optimizeDeps.exclude evita que Vite pre-empaquete la librería, permitiendo que el HMR funcione correctamente durante el desarrollo.

2. Importar estilos

En tu src/index.css:

css

@import "tailwindcss";
@import "@imansi/tailwind/styles.css";

/* Escanear las clases usadas en tu app */
@source "./**/*.jsx";
@source "./**/*.js";

/* Escanear las clases dentro de @imansi/ui */
@source "../node_modules/@imansi/ui/src/**/*.jsx";

3. Configurar tema y modo

En el <html> de tu index.html:

html

<html data-theme="modern" data-mode="light">

O dinámicamente desde JavaScript:

document.documentElement.dataset.theme = 'modern';
document.documentElement.dataset.mode = 'dark';

Uso básico

jsx

import {
  Button,
  Input,
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
  Alert,
} from '@imansi/ui';

export function LoginForm() {
  return (
    <Card className="max-w-md">
      <CardHeader>
        <CardTitle>Iniciar sesión</CardTitle>
        <CardDescription>Ingresá tus credenciales</CardDescription>
      </CardHeader>

      <CardContent className="space-y-4">
        <Input label="Email" type="email" placeholder="correo@ejemplo.com" />
        <Input label="Contraseña" type="password" placeholder="••••••••" />
        <Alert variant="info" title="Tip">
          Usá una contraseña segura de al menos 8 caracteres.
        </Alert>
      </CardContent>

      <CardFooter className="justify-end gap-2">
        <Button variant="ghost">Cancelar</Button>
        <Button>Entrar</Button>
      </CardFooter>
    </Card>
  );
}

Componentes disponibles

Los 40+ componentes están organizados en 6 categorías funcionales.

1. Core

Los componentes esenciales para cualquier interfaz.

Componente	Descripción
`Button`	Botón con variantes (primary, outline, ghost, destructive)
`Input`	Campo de texto con label, hint y error
`Card`	Contenedor de superficies con header, content y footer
`Badge`	Etiqueta pequeña de estado
`Alert`	Mensaje destacado (info, success, warning, destructive)

2. Formularios

Campos y controles de entrada.

Componente	Descripción
`Label`	Etiqueta accesible para campos
`Textarea`	Campo de texto multilínea
`Checkbox`	Casilla de selección
`Switch`	Interruptor on/off
`RadioGroup`	Grupo de radios
`Slider`	Control deslizante
`Select`	Selector desplegable

3. Overlays

Elementos flotantes y modales.

Componente	Descripción
`Dialog`	Modal centrado
`AlertDialog`	Modal de confirmación
`Drawer`	Panel lateral deslizante
`Popover`	Contenido flotante anclado
`Tooltip`	Texto informativo al hover
`DropdownMenu`	Menú desplegable
`Toaster`	Notificaciones toast

4. Datos

Componentes para mostrar información.

Componente	Descripción
`Avatar`	Foto de usuario con fallback
`Progress`	Barra de progreso
`Skeleton`	Placeholder de carga
`Tabs`	Pestañas de contenido
`Accordion`	Secciones plegables
`Table`	Tabla de datos

5. Layout y Navegación

Componente	Descripción
`Breadcrumb`	Ruta de navegación
`Pagination`	Paginación
`Collapsible`	Sección plegable
`Separator`	Línea divisoria
`ScrollArea`	Área con scroll custom

6. Avanzados

Componentes especializados para casos específicos.

Componente	Descripción
`AspectRatio`	Contenedor con relación de aspecto
`Calendar`	Calendario de selección de fecha
`Command`	Paleta de comandos tipo ⌘K
`Combobox`	Selector con búsqueda
`ContextMenu`	Menú contextual (click derecho)
`HoverCard`	Card al hover
`InputOTP`	Campo de código OTP
`Menubar`	Barra de menú de aplicación
`NavigationMenu`	Menú de navegación complejo
`Resizable`	Paneles redimensionables
`Sheet`	Panel lateral tipo drawer
`Toggle`	Botón de estado on/off
`ToggleGroup`	Grupo de toggles

Temas y modos

@imansi/ui funciona con los 6 temas de @imansi/tailwind:

Tema	Personalidad
minimal	Monocromo editorial, sin color de marca
modern	Índigo vibrante, radios generosos
compact	Verde esmeralda, denso, ideal para dashboards
warm	Serif + paleta cálida (crema, terracota, ámbar)
red	Rojo intenso, bold, energético
yellow	Ámbar brillante, soleado

Y los 2 modos:

light — Colores claros
dark — Colores oscuros

Cambiar de tema o modo es instantáneo y no requiere recargar. Los componentes se adaptan automáticamente porque todos usan tokens semánticos (bg-primary, text-muted-foreground).

Convenciones de la API

Todos los componentes de @imansi/ui siguen las mismas convenciones:

1. Props en español

Los nombres de las props usan español cuando tiene sentido:

jsx

<Input label="Email" hint="Usá tu correo principal" error={error} />
<Alert variant="info" title="Tip">...</Alert>

2. Variantes con `variant`

Los componentes con múltiples estilos aceptan la prop variant:

jsx

<Button variant="primary">Primario</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="destructive">Eliminar</Button>

Valores comunes: primary, secondary, outline, ghost, link, destructive.

3. Tamaños con `size`

jsx

<Button size="sm">Pequeño</Button>
<Button size="md">Mediano</Button>
<Button size="lg">Grande</Button>
<Button size="icon">🔔</Button>

4. `className` para estilos propios

Todos los componentes aceptan className y se mergea con tailwind-merge:

jsx

<Button className="w-full mt-4">Ancho completo</Button>

5. Accesibilidad por defecto

aria-label cuando no hay texto visible
role correcto en cada elemento
Navegación por teclado completa
Focus visible consistente

Composición

Los componentes están diseñados para componerse entre sí. Por ejemplo, Card tiene subcomponentes:

jsx

import {
  Card,
  CardHeader,
  CardTitle,
  CardDescription,
  CardContent,
  CardFooter,
} from '@imansi/ui';

<Card>
  <CardHeader>
    <CardTitle>Título</CardTitle>
    <CardDescription>Descripción corta</CardDescription>
  </CardHeader>
  <CardContent>Contenido principal</CardContent>
  <CardFooter>Acciones al pie</CardFooter>
</Card>

Lo mismo pasa con:

Alert + AlertTitle + AlertDescription
Select + SelectTrigger + SelectContent + SelectItem
Tabs + TabsList + TabsTrigger + TabsContent
Accordion + AccordionItem + AccordionTrigger + AccordionContent
Table + TableHeader + TableBody + TableRow + TableCell
Breadcrumb + BreadcrumbList + BreadcrumbItem + BreadcrumbLink

Personalización avanzada

Cambiar colores de un componente puntual

jsx

<Button className="bg-green-600 hover:bg-green-700">
  Botón verde custom
</Button>

Cambiar colores globalmente

Editá los tokens de @imansi/tailwind:

css

:root {
  --color-primary: oklch(0.55 0.24 155);
}

O en modo oscuro:

css

.dark {
  --color-primary: oklch(0.70 0.22 155);
}

Extender un componente

jsx

import { Button } from '@imansi/ui';

export function BotonPeligroso({ children, ...props }) {
  return (
    <Button variant="destructive" {...props}>
      ⚠️ {children}
    </Button>
  );
}

Arquitectura

@imansi/ui es la segunda capa del ecosistema Imansi. Consume @imansi/tailwind sin modificarlo.

@imansi/tailwind              ← Tokens + 6 temas + base
      ↓
@imansi/ui                    ← Este paquete (componentes)
      ↓
@imansi/templates             ← Páginas completas
      ↓
create-imansi-app             ← CLI de scaffolding

Reglas arquitectónicas:

@imansi/ui no define colores propios. Todo sale de @imansi/tailwind.
Nunca usa colores crudos (bg-blue-500). Solo tokens semánticos (bg-primary).
Sin estilos propios: cada componente es un wrapper de Radix UI con clases Tailwind semánticas.
La accesibilidad viene de Radix: foco, teclado, ARIA, roles, estados — todo incluido.

Próximos pasos

Button — Empezá por el componente más usado
@imansi/tailwind — El sistema de diseño
create-imansi-app — El CLI oficial

@imansi/ui ​

¿Qué es? ​

Instalación ​

Configuración ​

1. Configurar Vite ​

2. Importar estilos ​

3. Configurar tema y modo ​

Uso básico ​

Componentes disponibles ​

1. Core ​

2. Formularios ​

3. Overlays ​

4. Datos ​

5. Layout y Navegación ​

6. Avanzados ​

Temas y modos ​

Convenciones de la API ​

1. Props en español ​

2. Variantes con variant ​

3. Tamaños con size ​

4. className para estilos propios ​

5. Accesibilidad por defecto ​

Composición ​

Personalización avanzada ​

Cambiar colores de un componente puntual ​

Cambiar colores globalmente ​

Extender un componente ​

Arquitectura ​

Próximos pasos ​