@adamosuiteservices/ui 1.7.13 → 1.8.13

package/docs/components/ui/alert.md

@@ -1,671 +1,671 @@
-# Alert Component
-
-## Descripción
-
-Componente versátil para mostrar **mensajes importantes** que requieren la atención del usuario. Usa un sistema de grid inteligente para iconos opcionales, soporta 4 variantes de color, y permite contenido rico con botones, listas, progress bars y más.
-
-## Características
-
-- ✅ 4 variantes visuales (default, destructive, success, warning)
-- ✅ Grid automático para iconos opcionales
-- ✅ Soporta título solo, descripción solo, o ambos
-- ✅ Contenido rico: botones, progress, checkboxes, badges
-- ✅ Rol ARIA "alert" para accesibilidad
-- ✅ Iconos auto-dimensionados (size-4)
-- ✅ Line clamp en títulos largos
-- ✅ Sistema de slots para composición
-
-## Importación
-
-```typescript
-import {
-  Alert,
-  AlertTitle,
-  AlertDescription,
-} from "@adamosuiteservices/ui/alert";
-```
-
-## Uso Básico
-
-### Alert Completo (Icono + Título + Descripción)
-
-```tsx
-import { InfoIcon } from "lucide-react";
-
-<Alert>
-  <InfoIcon />
-  <AlertTitle>Heads up!</AlertTitle>
-  <AlertDescription>
-    You can add components and dependencies to your app using the cli.
-  </AlertDescription>
-</Alert>;
-```
-
-### Solo Título con Icono
-
-```tsx
-import { CheckCircle2Icon } from "lucide-react";
-
-<Alert variant="success">
-  <CheckCircle2Icon />
-  <AlertTitle>Your order has been processed!</AlertTitle>
-</Alert>;
-```
-
-### Solo Descripción con Icono
-
-```tsx
-import { InfoIcon } from "lucide-react";
-
-<Alert>
-  <InfoIcon />
-  <AlertDescription>
-    This is an alert with only a description. Sometimes you don't need a title.
-  </AlertDescription>
-</Alert>;
-```
-
-### Sin Icono
-
-```tsx
-<Alert>
-  <AlertTitle>Update available</AlertTitle>
-  <AlertDescription>
-    A new software update is available. You can now update your app.
-  </AlertDescription>
-</Alert>
-```
-
-## Variantes
-
-### Default (Información General)
-
-Para mensajes informativos neutrales:
-
-```tsx
-import { InfoIcon } from "lucide-react";
-
-<Alert variant="default">
-  <InfoIcon />
-  <AlertTitle>Default variant</AlertTitle>
-  <AlertDescription>
-    This is the default alert variant for general information.
-  </AlertDescription>
-</Alert>;
-```
-
-**Estilos aplicados**:
-
-- Fondo: `bg-card` (blanco/gris claro según tema)
-- Texto: `text-card-foreground`
-- Uso: Información general, tips, avisos neutrales
-
-### Success (Operaciones Exitosas)
-
-Para confirmaciones y feedback positivo:
-
-```tsx
-import { CheckCircle2Icon } from "lucide-react";
-
-<Alert variant="success">
-  <CheckCircle2Icon />
-  <AlertTitle>Success</AlertTitle>
-  <AlertDescription>
-    Your changes have been saved successfully.
-  </AlertDescription>
-</Alert>;
-```
-
-**Estilos aplicados**:
-
-- Fondo: `bg-success-50` (verde claro)
-- Texto título/icono: `text-success` (verde)
-- Texto descripción: `text-success/90` (verde 90% opacidad)
-- Uso: Confirmaciones, operaciones completadas, validaciones exitosas
-
-### Warning (Advertencias)
-
-Para mensajes de precaución que requieren atención:
-
-```tsx
-import { AlertTriangleIcon } from "lucide-react";
-
-<Alert variant="warning">
-  <AlertTriangleIcon />
-  <AlertTitle>Warning</AlertTitle>
-  <AlertDescription>
-    Your storage is running low. Consider upgrading your plan.
-  </AlertDescription>
-</Alert>;
-```
-
-**Estilos aplicados**:
-
-- Fondo: `bg-warning-50` (naranja/amarillo claro)
-- Texto título/icono: `text-warning` (naranja/amarillo)
-- Texto descripción: `text-warning/90`
-- Uso: Advertencias, límites cercanos, acciones recomendadas
-
-### Destructive (Errores Críticos)
-
-Para errores, fallos y mensajes críticos:
-
-```tsx
-import { XCircleIcon } from "lucide-react";
-
-<Alert variant="destructive">
-  <XCircleIcon />
-  <AlertTitle>Error</AlertTitle>
-  <AlertDescription>
-    Your session has expired. Please log in again.
-  </AlertDescription>
-</Alert>;
-```
-
-**Estilos aplicados**:
-
-- Fondo: `bg-destructive-50` (rojo claro)
-- Texto título/icono: `text-destructive` (rojo)
-- Texto descripción: `text-destructive/90`
-- Uso: Errores, fallos de validación, acciones bloqueadas
-
-## Props
-
-### Alert (Root)
-
-Contenedor principal del alert con rol ARIA.
-
-| Prop      | Tipo                                                   | Default     | Descripción                            |
-| --------- | ------------------------------------------------------ | ----------- | -------------------------------------- |
-| variant   | `"default" \| "destructive" \| "success" \| "warning"` | `"default"` | Variante visual del alert              |
-| className | `string`                                               | -           | Clases CSS adicionales                 |
-| children  | `ReactNode`                                            | -           | Contenido (icono, título, descripción) |
-| ...props  | `HTMLAttributes<HTMLDivElement>`                       | -           | Props nativas de div                   |
-
-**Atributos aplicados automáticamente**:
-
-- `data-slot="alert"`: Para identificación interna
-- `role="alert"`: Accesibilidad ARIA
-
-### AlertTitle
-
-Título del alert con line clamp automático.
-
-| Prop      | Tipo                             | Descripción                  |
-| --------- | -------------------------------- | ---------------------------- |
-| className | `string`                         | Clases CSS adicionales       |
-| children  | `ReactNode`                      | Texto o contenido del título |
-| ...props  | `HTMLAttributes<HTMLDivElement>` | Props nativas de div         |
-
-**Características**:
-
-- `line-clamp-1`: Trunca automáticamente textos largos
-- `font-medium`: Peso de fuente medium
-- `tracking-tight`: Letter spacing ajustado
-- `min-h-4`: Altura mínima de 1rem
-- `col-start-2`: Inicia en segunda columna del grid (después del icono)
-
-### AlertDescription
-
-Contenedor de la descripción con soporte para contenido rico.
-
-| Prop      | Tipo                             | Descripción                              |
-| --------- | -------------------------------- | ---------------------------------------- |
-| className | `string`                         | Clases CSS adicionales                   |
-| children  | `ReactNode`                      | Contenido (texto, listas, botones, etc.) |
-| ...props  | `HTMLAttributes<HTMLDivElement>` | Props nativas de div                     |
-
-**Características**:
-
-- `text-muted-foreground`: Color de texto secundario (sobrescrito por variantes)
-- `grid`: Contenedor grid interno
-- `justify-items-start`: Alinea items a la izquierda
-- `gap-1`: Espaciado de 0.25rem entre elementos
-- `[&_p]:leading-relaxed`: Line height relajado para párrafos
-- `col-start-2`: Inicia en segunda columna del grid
-
-## Sistema de Grid Inteligente
-
-El Alert usa CSS Grid con **detección automática de iconos**:
-
-### Sin Icono
-
-```css
-grid-cols-[0_1fr]
-```
-
-- Columna 1: 0px (oculta)
-- Columna 2: Todo el espacio disponible
-
-### Con Icono
-
-```css
-grid-cols-[calc(var(--adm-spacing)*4)_1fr]
-has-[>svg]:gap-x-3
-```
-
-- Columna 1: 1rem (16px) para icono
-- Columna 2: Todo el espacio restante
-- Gap horizontal: 0.75rem (12px)
-
-**Selector automático**: `has-[>svg]` detecta si hay un elemento SVG directo
-
-### Estilos de Iconos
-
-```css
-[&>svg]:size-4          /* 16x16px */
-[&>svg]:translate-y-0.5 /* Alineación vertical */
-[&>svg]:text-current    /* Hereda color de la variante */
-```
-
-## Ejemplos Avanzados
-
-### Alert de Seguridad con Botones
-
-```tsx
-import { ShieldCheckIcon } from "lucide-react";
-import { Button } from "@adamosuiteservices/ui/button";
-
-<Alert variant="destructive">
-  <ShieldCheckIcon />
-  <AlertTitle>Security Notice: Suspicious Login Attempt</AlertTitle>
-  <AlertDescription>
-    <p>We detected a login attempt from an unrecognized device:</p>
-    <div className="mt-3 space-y-2 text-sm">
-      <div className="grid grid-cols-2 gap-2">
-        <span className="font-medium">Location:</span>
-        <span>San Francisco, CA</span>
-        <span className="font-medium">Device:</span>
-        <span>Chrome on Windows</span>
-        <span className="font-medium">Time:</span>
-        <span>2 minutes ago</span>
-      </div>
-    </div>
-    <div className="mt-4 flex gap-2">
-      <Button size="sm" variant="destructive">
-        Secure Account
-      </Button>
-      <Button size="sm" variant="outline">
-        This was me
-      </Button>
-    </div>
-  </AlertDescription>
-</Alert>;
-```
-
-### Estado del Sistema con Progress
-
-```tsx
-import { WifiOffIcon } from "lucide-react";
-import { Progress } from "@adamosuiteservices/ui/progress";
-
-<Alert variant="destructive">
-  <WifiOffIcon />
-  <AlertTitle>Service outage detected</AlertTitle>
-  <AlertDescription>
-    <p>We're experiencing connectivity issues with our primary data center.</p>
-    <div className="mt-3">
-      <div className="flex gap-2 items-center justify-between mb-2">
-        <span className="text-sm">Recovery Progress</span>
-        <span className="text-sm">75%</span>
-      </div>
-      <Progress value={75} variant="destructive" className="h-2" />
-    </div>
-    <p className="mt-2 text-sm">Estimated resolution: 15 minutes</p>
-  </AlertDescription>
-</Alert>;
-```
-
-### Notificación con Iconos Secundarios
-
-```tsx
-import { CalendarIcon, ClockIcon, MapPinIcon, UsersIcon } from "lucide-react";
-
-<Alert>
-  <CalendarIcon />
-  <AlertTitle>Meeting reminder</AlertTitle>
-  <AlertDescription>
-    <p>Your meeting with the design team starts in 15 minutes.</p>
-    <div className="mt-3 space-y-1 text-sm">
-      <div className="flex items-center gap-2">
-        <ClockIcon className="h-3 w-3" />
-        <span>3:00 PM - 4:00 PM</span>
-      </div>
-      <div className="flex items-center gap-2">
-        <MapPinIcon className="h-3 w-3" />
-        <span>Conference Room B</span>
-      </div>
-      <div className="flex items-center gap-2">
-        <UsersIcon className="h-3 w-3" />
-        <span>5 attendees</span>
-      </div>
-    </div>
-  </AlertDescription>
-</Alert>;
-```
-
-### Alert de Performance con Métricas
-
-```tsx
-import { ZapIcon } from "lucide-react";
-
-<Alert variant="success">
-  <ZapIcon />
-  <AlertTitle>Performance optimized</AlertTitle>
-  <AlertDescription>
-    <p>Your application performance has been automatically optimized.</p>
-    <div className="mt-3 grid grid-cols-2 gap-2 text-sm">
-      <div className="flex gap-4 justify-between">
-        <span>Load time:</span>
-        <span className="text-green-600">-45%</span>
-      </div>
-      <div className="flex gap-4 justify-between">
-        <span>Memory usage:</span>
-        <span className="text-green-600">-23%</span>
-      </div>
-      <div className="flex gap-4 justify-between">
-        <span>CPU usage:</span>
-        <span className="text-green-600">-31%</span>
-      </div>
-      <div className="flex gap-4 justify-between">
-        <span>Battery life:</span>
-        <span className="text-green-600">+18%</span>
-      </div>
-    </div>
-  </AlertDescription>
-</Alert>;
-```
-
-### Almacenamiento con Progreso y Acciones
-
-```tsx
-import { AlertTriangleIcon } from "lucide-react";
-import { Progress } from "@adamosuiteservices/ui/progress";
-import { Button } from "@adamosuiteservices/ui/button";
-
-<Alert variant="warning">
-  <AlertTriangleIcon />
-  <AlertTitle>Storage almost full</AlertTitle>
-  <AlertDescription>
-    <p>
-      Your storage is 89% full. Consider cleaning up files or upgrading your
-      plan.
-    </p>
-    <div className="mt-3 space-y-2 text-sm">
-      <div className="flex justify-between">
-        <span>Used space:</span>
-        <span>89.2 GB of 100 GB</span>
-      </div>
-      <Progress value={89} variant="warning" className="h-2" />
-      <div className="grid grid-cols-2 gap-4 mt-3">
-        <div>
-          <p className="font-medium">Largest folders:</p>
-          <ul className="mt-1 space-y-1">
-            <li>Photos: 45.2 GB</li>
-            <li>Videos: 23.8 GB</li>
-            <li>Documents: 12.1 GB</li>
-          </ul>
-        </div>
-        <div className="space-y-2">
-          <Button size="sm" className="w-full">
-            Upgrade Storage
-          </Button>
-          <Button size="sm" variant="outline" className="w-full">
-            Clean Up Files
-          </Button>
-        </div>
-      </div>
-    </div>
-  </AlertDescription>
-</Alert>;
-```
-
-### E-commerce: Orden Enviada
-
-```tsx
-import { TruckIcon } from "lucide-react";
-import { Button } from "@adamosuiteservices/ui/button";
-
-<Alert variant="success">
-  <TruckIcon />
-  <AlertTitle>Order shipped!</AlertTitle>
-  <AlertDescription>
-    <p>Your order #12345 has been shipped and is on its way to you.</p>
-    <div className="mt-3 space-y-1 text-sm">
-      <div className="flex gap-4 justify-between">
-        <span>Tracking number:</span>
-        <span className="font-mono">1Z999AA1234567890</span>
-      </div>
-      <div className="flex gap-4 justify-between">
-        <span>Estimated delivery:</span>
-        <span>Tomorrow, Oct 26</span>
-      </div>
-      <div className="flex gap-4 justify-between">
-        <span>Carrier:</span>
-        <span>UPS</span>
-      </div>
-    </div>
-    <Button size="sm" className="mt-3">
-      Track Package
-    </Button>
-  </AlertDescription>
-</Alert>;
-```
-
-### Alert Interactivo con Checkboxes
-
-```tsx
-import { ShieldCheckIcon } from "lucide-react";
-import { Badge } from "@adamosuiteservices/ui/badge";
-import { Checkbox } from "@adamosuiteservices/ui/checkbox";
-import { Button } from "@adamosuiteservices/ui/button";
-
-<Alert>
-  <ShieldCheckIcon />
-  <AlertTitle>Cookie preferences</AlertTitle>
-  <AlertDescription>
-    <p>We use cookies to improve your experience and analyze site usage.</p>
-    <div className="mt-3 space-y-3">
-      <div className="space-y-2">
-        <div className="flex items-center justify-between">
-          <span className="text-sm">Essential cookies</span>
-          <Badge variant="secondary">Required</Badge>
-        </div>
-        <div className="flex items-center justify-between">
-          <span className="text-sm">Analytics cookies</span>
-          <Checkbox defaultChecked className="rounded" />
-        </div>
-        <div className="flex items-center justify-between">
-          <span className="text-sm">Marketing cookies</span>
-          <Checkbox className="rounded" />
-        </div>
-      </div>
-      <div className="flex gap-2">
-        <Button size="sm">Accept All</Button>
-        <Button size="sm" variant="outline">
-          Save Preferences
-        </Button>
-        <Button size="sm" variant="ghost">
-          Reject All
-        </Button>
-      </div>
-    </div>
-  </AlertDescription>
-</Alert>;
-```
-
-### Update con Lista y Botones
-
-```tsx
-import { DownloadIcon } from "lucide-react";
-import { Button } from "@adamosuiteservices/ui/button";
-
-<Alert>
-  <DownloadIcon />
-  <AlertTitle>App update available</AlertTitle>
-  <AlertDescription>
-    <p>
-      Version 2.1.0 is now available with bug fixes and performance
-      improvements.
-    </p>
-    <div className="mt-3 space-y-2">
-      <div className="text-sm">
-        <p className="font-medium">What's new:</p>
-        <ul className="list-disc list-inside mt-1 space-y-1">
-          <li>Improved loading times</li>
-          <li>Fixed dark mode issues</li>
-          <li>Enhanced security</li>
-        </ul>
-      </div>
-      <div className="flex gap-2">
-        <Button size="sm">Update Now</Button>
-        <Button size="sm" variant="outline">
-          Remind Me Later
-        </Button>
-        <Button size="sm" variant="ghost">
-          Skip This Version
-        </Button>
-      </div>
-    </div>
-  </AlertDescription>
-</Alert>;
-```
-
-## Casos de Uso Comunes
-
-### Validación de Formularios
-
-```tsx
-<Alert variant="destructive">
-  <XCircleIcon />
-  <AlertTitle>Form validation failed</AlertTitle>
-  <AlertDescription>
-    Please correct the following errors before submitting.
-  </AlertDescription>
-</Alert>
-```
-
-### Confirmación de Acción
-
-```tsx
-<Alert variant="success">
-  <CheckCircle2Icon />
-  <AlertTitle>Profile updated</AlertTitle>
-  <AlertDescription>
-    Your changes have been saved successfully.
-  </AlertDescription>
-</Alert>
-```
-
-### Mantenimiento Programado
-
-```tsx
-<Alert variant="warning">
-  <AlertTriangleIcon />
-  <AlertTitle>Planned maintenance scheduled</AlertTitle>
-  <AlertDescription>
-    System maintenance tonight from 2:00 AM to 4:00 AM PST.
-  </AlertDescription>
-</Alert>
-```
-
-### Sistema Operativo
-
-```tsx
-<Alert variant="success">
-  <ServerIcon />
-  <AlertTitle>All systems operational</AlertTitle>
-  <AlertDescription>
-    All services running normally. No issues detected.
-  </AlertDescription>
-</Alert>
-```
-
-### Información de Backup
-
-```tsx
-<Alert>
-  <ArchiveIcon />
-  <AlertTitle>Backup completed</AlertTitle>
-  <AlertDescription>
-    Daily backup completed. 1,247 files backed up to cloud storage.
-  </AlertDescription>
-</Alert>
-```
-
-## Mejores Prácticas
-
-### Iconos Recomendados (lucide-react)
-
-- **Default**: `InfoIcon`, `BellIcon`, `MailIcon`
-- **Success**: `CheckCircle2Icon`, `CheckIcon`, `ShieldCheckIcon`
-- **Warning**: `AlertTriangleIcon`, `AlertCircleIcon`
-- **Destructive**: `XCircleIcon`, `AlertTriangleIcon`, `ShieldAlertIcon`
-
-### Estructura de Contenido
-
-```tsx
-<Alert variant="...">
-  {/* 1. Icono (opcional, directo como hijo) */}
-  <IconComponent />
-
-  {/* 2. Título (opcional, breve y descriptivo) */}
-  <AlertTitle>Short descriptive title</AlertTitle>
-
-  {/* 3. Descripción (puede incluir contenido rico) */}
-  <AlertDescription>
-    <p>Main message goes here.</p>
-    {/* Contenido adicional: listas, botones, progress, etc. */}
-  </AlertDescription>
-</Alert>
-```
-
-### Cuándo Usar Cada Variante
-
-- **default**: Información general, notificaciones neutras
-- **success**: Confirmaciones, operaciones completadas con éxito
-- **warning**: Advertencias, límites próximos, acciones recomendadas
-- **destructive**: Errores críticos, fallos de validación, acciones bloqueadas
-
-### Acciones en Alerts
-
-Para alerts con botones de acción:
-
-```tsx
-<AlertDescription>
-  <p>Message text</p>
-  <div className="mt-3 flex gap-2">
-    <Button size="sm">Primary Action</Button>
-    <Button size="sm" variant="outline">
-      Secondary
-    </Button>
-  </div>
-</AlertDescription>
-```
-
-## Notas de Implementación
-
-- Basado en CVA (class-variance-authority) para variantes
-- Grid con selector CSS `has-[>svg]` para detección automática de iconos
-- Usa sistema de slots con `data-slot` para composición
-- Colores de variantes usan tokens CSS personalizados
-- El icono debe ser hijo directo (no dentro de AlertTitle/AlertDescription)
-- Padding horizontal: 1rem (px-4)
-- Padding vertical: 0.75rem (py-3)
-- Border radius: 0.5rem (rounded-lg)
-
-## Accesibilidad
-
-- ✅ Rol ARIA `role="alert"` aplicado automáticamente
-- ✅ Screen readers anunciarán el contenido como alerta importante
-- ✅ Contraste de colores cumple WCAG AA en todas las variantes
-- ✅ Texto descriptivo en lugar de solo iconos
-- ✅ Botones dentro de alerts mantienen navegación por teclado
-- ⚠️ Para alerts dinámicos (que aparecen después de carga), considera usar `role="status"` o `aria-live="polite"` si no son urgentes
-
-## Referencias
-
-- Radix UI primitives: https://www.radix-ui.com/
-- shadcn/ui Alert: https://ui.shadcn.com/docs/components/alert
-- ARIA alert role: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role
-- Lucide Icons: https://lucide.dev/
+# Alert Component
+
+## Descripción
+
+Componente versátil para mostrar **mensajes importantes** que requieren la atención del usuario. Usa un sistema de grid inteligente para iconos opcionales, soporta 4 variantes de color, y permite contenido rico con botones, listas, progress bars y más.
+
+## Características
+
+- ✅ 4 variantes visuales (default, destructive, success, warning)
+- ✅ Grid automático para iconos opcionales
+- ✅ Soporta título solo, descripción solo, o ambos
+- ✅ Contenido rico: botones, progress, checkboxes, badges
+- ✅ Rol ARIA "alert" para accesibilidad
+- ✅ Iconos auto-dimensionados (size-4)
+- ✅ Line clamp en títulos largos
+- ✅ Sistema de slots para composición
+
+## Importación
+
+```typescript
+import {
+  Alert,
+  AlertTitle,
+  AlertDescription,
+} from "@adamosuiteservices/ui/alert";
+```
+
+## Uso Básico
+
+### Alert Completo (Icono + Título + Descripción)
+
+```tsx
+import { InfoIcon } from "lucide-react";
+
+<Alert>
+  <InfoIcon />
+  <AlertTitle>Heads up!</AlertTitle>
+  <AlertDescription>
+    You can add components and dependencies to your app using the cli.
+  </AlertDescription>
+</Alert>;
+```
+
+### Solo Título con Icono
+
+```tsx
+import { CheckCircle2Icon } from "lucide-react";
+
+<Alert variant="success">
+  <CheckCircle2Icon />
+  <AlertTitle>Your order has been processed!</AlertTitle>
+</Alert>;
+```
+
+### Solo Descripción con Icono
+
+```tsx
+import { InfoIcon } from "lucide-react";
+
+<Alert>
+  <InfoIcon />
+  <AlertDescription>
+    This is an alert with only a description. Sometimes you don't need a title.
+  </AlertDescription>
+</Alert>;
+```
+
+### Sin Icono
+
+```tsx
+<Alert>
+  <AlertTitle>Update available</AlertTitle>
+  <AlertDescription>
+    A new software update is available. You can now update your app.
+  </AlertDescription>
+</Alert>
+```
+
+## Variantes
+
+### Default (Información General)
+
+Para mensajes informativos neutrales:
+
+```tsx
+import { InfoIcon } from "lucide-react";
+
+<Alert variant="default">
+  <InfoIcon />
+  <AlertTitle>Default variant</AlertTitle>
+  <AlertDescription>
+    This is the default alert variant for general information.
+  </AlertDescription>
+</Alert>;
+```
+
+**Estilos aplicados**:
+
+- Fondo: `bg-card` (blanco/gris claro según tema)
+- Texto: `text-card-foreground`
+- Uso: Información general, tips, avisos neutrales
+
+### Success (Operaciones Exitosas)
+
+Para confirmaciones y feedback positivo:
+
+```tsx
+import { CheckCircle2Icon } from "lucide-react";
+
+<Alert variant="success">
+  <CheckCircle2Icon />
+  <AlertTitle>Success</AlertTitle>
+  <AlertDescription>
+    Your changes have been saved successfully.
+  </AlertDescription>
+</Alert>;
+```
+
+**Estilos aplicados**:
+
+- Fondo: `bg-success-50` (verde claro)
+- Texto título/icono: `text-success` (verde)
+- Texto descripción: `text-success/90` (verde 90% opacidad)
+- Uso: Confirmaciones, operaciones completadas, validaciones exitosas
+
+### Warning (Advertencias)
+
+Para mensajes de precaución que requieren atención:
+
+```tsx
+import { AlertTriangleIcon } from "lucide-react";
+
+<Alert variant="warning">
+  <AlertTriangleIcon />
+  <AlertTitle>Warning</AlertTitle>
+  <AlertDescription>
+    Your storage is running low. Consider upgrading your plan.
+  </AlertDescription>
+</Alert>;
+```
+
+**Estilos aplicados**:
+
+- Fondo: `bg-warning-50` (naranja/amarillo claro)
+- Texto título/icono: `text-warning` (naranja/amarillo)
+- Texto descripción: `text-warning/90`
+- Uso: Advertencias, límites cercanos, acciones recomendadas
+
+### Destructive (Errores Críticos)
+
+Para errores, fallos y mensajes críticos:
+
+```tsx
+import { XCircleIcon } from "lucide-react";
+
+<Alert variant="destructive">
+  <XCircleIcon />
+  <AlertTitle>Error</AlertTitle>
+  <AlertDescription>
+    Your session has expired. Please log in again.
+  </AlertDescription>
+</Alert>;
+```
+
+**Estilos aplicados**:
+
+- Fondo: `bg-destructive-50` (rojo claro)
+- Texto título/icono: `text-destructive` (rojo)
+- Texto descripción: `text-destructive/90`
+- Uso: Errores, fallos de validación, acciones bloqueadas
+
+## Props
+
+### Alert (Root)
+
+Contenedor principal del alert con rol ARIA.
+
+| Prop      | Tipo                                                   | Default     | Descripción                            |
+| --------- | ------------------------------------------------------ | ----------- | -------------------------------------- |
+| variant   | `"default" \| "destructive" \| "success" \| "warning"` | `"default"` | Variante visual del alert              |
+| className | `string`                                               | -           | Clases CSS adicionales                 |
+| children  | `ReactNode`                                            | -           | Contenido (icono, título, descripción) |
+| ...props  | `HTMLAttributes<HTMLDivElement>`                       | -           | Props nativas de div                   |
+
+**Atributos aplicados automáticamente**:
+
+- `data-slot="alert"`: Para identificación interna
+- `role="alert"`: Accesibilidad ARIA
+
+### AlertTitle
+
+Título del alert con line clamp automático.
+
+| Prop      | Tipo                             | Descripción                  |
+| --------- | -------------------------------- | ---------------------------- |
+| className | `string`                         | Clases CSS adicionales       |
+| children  | `ReactNode`                      | Texto o contenido del título |
+| ...props  | `HTMLAttributes<HTMLDivElement>` | Props nativas de div         |
+
+**Características**:
+
+- `line-clamp-1`: Trunca automáticamente textos largos
+- `font-medium`: Peso de fuente medium
+- `tracking-tight`: Letter spacing ajustado
+- `min-h-4`: Altura mínima de 1rem
+- `col-start-2`: Inicia en segunda columna del grid (después del icono)
+
+### AlertDescription
+
+Contenedor de la descripción con soporte para contenido rico.
+
+| Prop      | Tipo                             | Descripción                              |
+| --------- | -------------------------------- | ---------------------------------------- |
+| className | `string`                         | Clases CSS adicionales                   |
+| children  | `ReactNode`                      | Contenido (texto, listas, botones, etc.) |
+| ...props  | `HTMLAttributes<HTMLDivElement>` | Props nativas de div                     |
+
+**Características**:
+
+- `text-muted-foreground`: Color de texto secundario (sobrescrito por variantes)
+- `grid`: Contenedor grid interno
+- `justify-items-start`: Alinea items a la izquierda
+- `gap-1`: Espaciado de 0.25rem entre elementos
+- `[&_p]:leading-relaxed`: Line height relajado para párrafos
+- `col-start-2`: Inicia en segunda columna del grid
+
+## Sistema de Grid Inteligente
+
+El Alert usa CSS Grid con **detección automática de iconos**:
+
+### Sin Icono
+
+```css
+grid-cols-[0_1fr]
+```
+
+- Columna 1: 0px (oculta)
+- Columna 2: Todo el espacio disponible
+
+### Con Icono
+
+```css
+grid-cols-[calc(var(--adm-spacing)*4)_1fr]
+has-[>svg]:gap-x-3
+```
+
+- Columna 1: 1rem (16px) para icono
+- Columna 2: Todo el espacio restante
+- Gap horizontal: 0.75rem (12px)
+
+**Selector automático**: `has-[>svg]` detecta si hay un elemento SVG directo
+
+### Estilos de Iconos
+
+```css
+[&>svg]:size-4          /* 16x16px */
+[&>svg]:translate-y-0.5 /* Alineación vertical */
+[&>svg]:text-current    /* Hereda color de la variante */
+```
+
+## Ejemplos Avanzados
+
+### Alert de Seguridad con Botones
+
+```tsx
+import { ShieldCheckIcon } from "lucide-react";
+import { Button } from "@adamosuiteservices/ui/button";
+
+<Alert variant="destructive">
+  <ShieldCheckIcon />
+  <AlertTitle>Security Notice: Suspicious Login Attempt</AlertTitle>
+  <AlertDescription>
+    <p>We detected a login attempt from an unrecognized device:</p>
+    <div className="mt-3 space-y-2 text-sm">
+      <div className="grid grid-cols-2 gap-2">
+        <span className="font-medium">Location:</span>
+        <span>San Francisco, CA</span>
+        <span className="font-medium">Device:</span>
+        <span>Chrome on Windows</span>
+        <span className="font-medium">Time:</span>
+        <span>2 minutes ago</span>
+      </div>
+    </div>
+    <div className="mt-4 flex gap-2">
+      <Button size="sm" variant="destructive">
+        Secure Account
+      </Button>
+      <Button size="sm" variant="outline">
+        This was me
+      </Button>
+    </div>
+  </AlertDescription>
+</Alert>;
+```
+
+### Estado del Sistema con Progress
+
+```tsx
+import { WifiOffIcon } from "lucide-react";
+import { Progress } from "@adamosuiteservices/ui/progress";
+
+<Alert variant="destructive">
+  <WifiOffIcon />
+  <AlertTitle>Service outage detected</AlertTitle>
+  <AlertDescription>
+    <p>We're experiencing connectivity issues with our primary data center.</p>
+    <div className="mt-3">
+      <div className="flex gap-2 items-center justify-between mb-2">
+        <span className="text-sm">Recovery Progress</span>
+        <span className="text-sm">75%</span>
+      </div>
+      <Progress value={75} variant="destructive" className="h-2" />
+    </div>
+    <p className="mt-2 text-sm">Estimated resolution: 15 minutes</p>
+  </AlertDescription>
+</Alert>;
+```
+
+### Notificación con Iconos Secundarios
+
+```tsx
+import { CalendarIcon, ClockIcon, MapPinIcon, UsersIcon } from "lucide-react";
+
+<Alert>
+  <CalendarIcon />
+  <AlertTitle>Meeting reminder</AlertTitle>
+  <AlertDescription>
+    <p>Your meeting with the design team starts in 15 minutes.</p>
+    <div className="mt-3 space-y-1 text-sm">
+      <div className="flex items-center gap-2">
+        <ClockIcon className="h-3 w-3" />
+        <span>3:00 PM - 4:00 PM</span>
+      </div>
+      <div className="flex items-center gap-2">
+        <MapPinIcon className="h-3 w-3" />
+        <span>Conference Room B</span>
+      </div>
+      <div className="flex items-center gap-2">
+        <UsersIcon className="h-3 w-3" />
+        <span>5 attendees</span>
+      </div>
+    </div>
+  </AlertDescription>
+</Alert>;
+```
+
+### Alert de Performance con Métricas
+
+```tsx
+import { ZapIcon } from "lucide-react";
+
+<Alert variant="success">
+  <ZapIcon />
+  <AlertTitle>Performance optimized</AlertTitle>
+  <AlertDescription>
+    <p>Your application performance has been automatically optimized.</p>
+    <div className="mt-3 grid grid-cols-2 gap-2 text-sm">
+      <div className="flex gap-4 justify-between">
+        <span>Load time:</span>
+        <span className="text-green-600">-45%</span>
+      </div>
+      <div className="flex gap-4 justify-between">
+        <span>Memory usage:</span>
+        <span className="text-green-600">-23%</span>
+      </div>
+      <div className="flex gap-4 justify-between">
+        <span>CPU usage:</span>
+        <span className="text-green-600">-31%</span>
+      </div>
+      <div className="flex gap-4 justify-between">
+        <span>Battery life:</span>
+        <span className="text-green-600">+18%</span>
+      </div>
+    </div>
+  </AlertDescription>
+</Alert>;
+```
+
+### Almacenamiento con Progreso y Acciones
+
+```tsx
+import { AlertTriangleIcon } from "lucide-react";
+import { Progress } from "@adamosuiteservices/ui/progress";
+import { Button } from "@adamosuiteservices/ui/button";
+
+<Alert variant="warning">
+  <AlertTriangleIcon />
+  <AlertTitle>Storage almost full</AlertTitle>
+  <AlertDescription>
+    <p>
+      Your storage is 89% full. Consider cleaning up files or upgrading your
+      plan.
+    </p>
+    <div className="mt-3 space-y-2 text-sm">
+      <div className="flex justify-between">
+        <span>Used space:</span>
+        <span>89.2 GB of 100 GB</span>
+      </div>
+      <Progress value={89} variant="warning" className="h-2" />
+      <div className="grid grid-cols-2 gap-4 mt-3">
+        <div>
+          <p className="font-medium">Largest folders:</p>
+          <ul className="mt-1 space-y-1">
+            <li>Photos: 45.2 GB</li>
+            <li>Videos: 23.8 GB</li>
+            <li>Documents: 12.1 GB</li>
+          </ul>
+        </div>
+        <div className="space-y-2">
+          <Button size="sm" className="w-full">
+            Upgrade Storage
+          </Button>
+          <Button size="sm" variant="outline" className="w-full">
+            Clean Up Files
+          </Button>
+        </div>
+      </div>
+    </div>
+  </AlertDescription>
+</Alert>;
+```
+
+### E-commerce: Orden Enviada
+
+```tsx
+import { TruckIcon } from "lucide-react";
+import { Button } from "@adamosuiteservices/ui/button";
+
+<Alert variant="success">
+  <TruckIcon />
+  <AlertTitle>Order shipped!</AlertTitle>
+  <AlertDescription>
+    <p>Your order #12345 has been shipped and is on its way to you.</p>
+    <div className="mt-3 space-y-1 text-sm">
+      <div className="flex gap-4 justify-between">
+        <span>Tracking number:</span>
+        <span className="font-mono">1Z999AA1234567890</span>
+      </div>
+      <div className="flex gap-4 justify-between">
+        <span>Estimated delivery:</span>
+        <span>Tomorrow, Oct 26</span>
+      </div>
+      <div className="flex gap-4 justify-between">
+        <span>Carrier:</span>
+        <span>UPS</span>
+      </div>
+    </div>
+    <Button size="sm" className="mt-3">
+      Track Package
+    </Button>
+  </AlertDescription>
+</Alert>;
+```
+
+### Alert Interactivo con Checkboxes
+
+```tsx
+import { ShieldCheckIcon } from "lucide-react";
+import { Badge } from "@adamosuiteservices/ui/badge";
+import { Checkbox } from "@adamosuiteservices/ui/checkbox";
+import { Button } from "@adamosuiteservices/ui/button";
+
+<Alert>
+  <ShieldCheckIcon />
+  <AlertTitle>Cookie preferences</AlertTitle>
+  <AlertDescription>
+    <p>We use cookies to improve your experience and analyze site usage.</p>
+    <div className="mt-3 space-y-3">
+      <div className="space-y-2">
+        <div className="flex items-center justify-between">
+          <span className="text-sm">Essential cookies</span>
+          <Badge variant="secondary">Required</Badge>
+        </div>
+        <div className="flex items-center justify-between">
+          <span className="text-sm">Analytics cookies</span>
+          <Checkbox defaultChecked className="rounded" />
+        </div>
+        <div className="flex items-center justify-between">
+          <span className="text-sm">Marketing cookies</span>
+          <Checkbox className="rounded" />
+        </div>
+      </div>
+      <div className="flex gap-2">
+        <Button size="sm">Accept All</Button>
+        <Button size="sm" variant="outline">
+          Save Preferences
+        </Button>
+        <Button size="sm" variant="ghost">
+          Reject All
+        </Button>
+      </div>
+    </div>
+  </AlertDescription>
+</Alert>;
+```
+
+### Update con Lista y Botones
+
+```tsx
+import { DownloadIcon } from "lucide-react";
+import { Button } from "@adamosuiteservices/ui/button";
+
+<Alert>
+  <DownloadIcon />
+  <AlertTitle>App update available</AlertTitle>
+  <AlertDescription>
+    <p>
+      Version 2.1.0 is now available with bug fixes and performance
+      improvements.
+    </p>
+    <div className="mt-3 space-y-2">
+      <div className="text-sm">
+        <p className="font-medium">What's new:</p>
+        <ul className="list-disc list-inside mt-1 space-y-1">
+          <li>Improved loading times</li>
+          <li>Fixed dark mode issues</li>
+          <li>Enhanced security</li>
+        </ul>
+      </div>
+      <div className="flex gap-2">
+        <Button size="sm">Update Now</Button>
+        <Button size="sm" variant="outline">
+          Remind Me Later
+        </Button>
+        <Button size="sm" variant="ghost">
+          Skip This Version
+        </Button>
+      </div>
+    </div>
+  </AlertDescription>
+</Alert>;
+```
+
+## Casos de Uso Comunes
+
+### Validación de Formularios
+
+```tsx
+<Alert variant="destructive">
+  <XCircleIcon />
+  <AlertTitle>Form validation failed</AlertTitle>
+  <AlertDescription>
+    Please correct the following errors before submitting.
+  </AlertDescription>
+</Alert>
+```
+
+### Confirmación de Acción
+
+```tsx
+<Alert variant="success">
+  <CheckCircle2Icon />
+  <AlertTitle>Profile updated</AlertTitle>
+  <AlertDescription>
+    Your changes have been saved successfully.
+  </AlertDescription>
+</Alert>
+```
+
+### Mantenimiento Programado
+
+```tsx
+<Alert variant="warning">
+  <AlertTriangleIcon />
+  <AlertTitle>Planned maintenance scheduled</AlertTitle>
+  <AlertDescription>
+    System maintenance tonight from 2:00 AM to 4:00 AM PST.
+  </AlertDescription>
+</Alert>
+```
+
+### Sistema Operativo
+
+```tsx
+<Alert variant="success">
+  <ServerIcon />
+  <AlertTitle>All systems operational</AlertTitle>
+  <AlertDescription>
+    All services running normally. No issues detected.
+  </AlertDescription>
+</Alert>
+```
+
+### Información de Backup
+
+```tsx
+<Alert>
+  <ArchiveIcon />
+  <AlertTitle>Backup completed</AlertTitle>
+  <AlertDescription>
+    Daily backup completed. 1,247 files backed up to cloud storage.
+  </AlertDescription>
+</Alert>
+```
+
+## Mejores Prácticas
+
+### Iconos Recomendados (lucide-react)
+
+- **Default**: `InfoIcon`, `BellIcon`, `MailIcon`
+- **Success**: `CheckCircle2Icon`, `CheckIcon`, `ShieldCheckIcon`
+- **Warning**: `AlertTriangleIcon`, `AlertCircleIcon`
+- **Destructive**: `XCircleIcon`, `AlertTriangleIcon`, `ShieldAlertIcon`
+
+### Estructura de Contenido
+
+```tsx
+<Alert variant="...">
+  {/* 1. Icono (opcional, directo como hijo) */}
+  <IconComponent />
+
+  {/* 2. Título (opcional, breve y descriptivo) */}
+  <AlertTitle>Short descriptive title</AlertTitle>
+
+  {/* 3. Descripción (puede incluir contenido rico) */}
+  <AlertDescription>
+    <p>Main message goes here.</p>
+    {/* Contenido adicional: listas, botones, progress, etc. */}
+  </AlertDescription>
+</Alert>
+```
+
+### Cuándo Usar Cada Variante
+
+- **default**: Información general, notificaciones neutras
+- **success**: Confirmaciones, operaciones completadas con éxito
+- **warning**: Advertencias, límites próximos, acciones recomendadas
+- **destructive**: Errores críticos, fallos de validación, acciones bloqueadas
+
+### Acciones en Alerts
+
+Para alerts con botones de acción:
+
+```tsx
+<AlertDescription>
+  <p>Message text</p>
+  <div className="mt-3 flex gap-2">
+    <Button size="sm">Primary Action</Button>
+    <Button size="sm" variant="outline">
+      Secondary
+    </Button>
+  </div>
+</AlertDescription>
+```
+
+## Notas de Implementación
+
+- Basado en CVA (class-variance-authority) para variantes
+- Grid con selector CSS `has-[>svg]` para detección automática de iconos
+- Usa sistema de slots con `data-slot` para composición
+- Colores de variantes usan tokens CSS personalizados
+- El icono debe ser hijo directo (no dentro de AlertTitle/AlertDescription)
+- Padding horizontal: 1rem (px-4)
+- Padding vertical: 0.75rem (py-3)
+- Border radius: 0.5rem (rounded-lg)
+
+## Accesibilidad
+
+- ✅ Rol ARIA `role="alert"` aplicado automáticamente
+- ✅ Screen readers anunciarán el contenido como alerta importante
+- ✅ Contraste de colores cumple WCAG AA en todas las variantes
+- ✅ Texto descriptivo en lugar de solo iconos
+- ✅ Botones dentro de alerts mantienen navegación por teclado
+- ⚠️ Para alerts dinámicos (que aparecen después de carga), considera usar `role="status"` o `aria-live="polite"` si no son urgentes
+
+## Referencias
+
+- Radix UI primitives: https://www.radix-ui.com/
+- shadcn/ui Alert: https://ui.shadcn.com/docs/components/alert
+- ARIA alert role: https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/alert_role
+- Lucide Icons: https://lucide.dev/