@adamosuiteservices/ui 2.10.0 → 2.10.2

package/docs/components/ui/card.md

@@ -1,10 +1,12 @@
 # Card
 
-Contenedor versátil con bordes redondeados, padding y sombra para agrupar contenido relacionado. Incluye 6 variantes de color y un sistema de layout con grid automático para headers con acciones.
+Contenedor versátil con bordes redondeados, padding, sombra y borde configurables para agrupar contenido relacionado. Incluye 6 variantes de color, control de elevación y bordes, y un sistema de layout con grid automático para headers con acciones.
 
 ## Características Principales
 
 - **6 variantes de color**: Default, Primary, Muted, Success, Warning, Destructive
+- **2 variantes de sombra**: Default (con elevación) y None (diseño plano, por defecto)
+- **2 variantes de borde**: Default (visible) y Transparent (invisible pero mantiene espacio)
 - **Composición modular**: 6 subcomponentes (Card, CardHeader, CardTitle, CardDescription, CardAction, CardContent, CardFooter)
 - **Grid automático en header**: Detecta `CardAction` y ajusta layout automáticamente con `has-data-[slot=card-action]:grid-cols-[1fr_auto]`
 - **Container queries**: CardHeader usa `@container/card-header` para layouts responsive
@@ -104,11 +106,13 @@ Contenedor principal de la card.
 
 #### Props
 
-| Prop        | Tipo                                                                           | Default     | Descripción                |
-| ----------- | ------------------------------------------------------------------------------ | ----------- | -------------------------- |
-| `variant`   | `"default" \| "primary" \| "muted" \| "success" \| "warning" \| "destructive"` | `"default"` | Variante de color de fondo |
-| `className` | `string`                                                                       | -           | Clases CSS adicionales     |
-| `children`  | `ReactNode`                                                                    | -           | Contenido de la card       |
+| Prop        | Tipo                                                                           | Default     | Descripción                                                |
+| ----------- | ------------------------------------------------------------------------------ | ----------- | ---------------------------------------------------------- |
+| `variant`   | `"default" \| "primary" \| "muted" \| "success" \| "warning" \| "destructive"` | `"default"` | Variante de color de fondo                                 |
+| `shadow`    | `"default" \| "none"`                                                          | `"none"`    | Control de sombra (none=flat, default=elevación)           |
+| `border`    | `"default" \| "transparent"`                                                   | `"default"` | Control de borde (default=visible, transparent=invisible)  |
+| `className` | `string`                                                                       | -           | Clases CSS adicionales                                     |
+| `children`  | `ReactNode`                                                                    | -           | Contenido de la card                                       |
 
 ### CardHeader
 
@@ -335,7 +339,125 @@ Fondo gris claro para información secundaria.
 
 **Colores**: `bg-muted` con texto `text-muted/90`
 
-**Colores**: `bg-muted` con texto `text-muted/90`
+## Variantes de Sombra
+
+Controla la elevación de las cards con la prop `shadow`. Por defecto, las cards no tienen sombra (`shadow="none"`).
+
+### Sin Sombra (Default)
+
+Card plana sin elevación para diseños limpios y modernos.
+
+```tsx
+<Card className="w-[350px]">
+  <CardHeader>
+    <CardTitle>Flat Card</CardTitle>
+    <CardDescription>No elevation, flat design</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">
+      Default behavior - perfect for modern, clean layouts and dense grids.
+    </p>
+  </CardContent>
+</Card>
+```
+
+**Uso**: Default para todas las cards. Ideal para diseños modernos, layouts densos, o cuando las cards ya están visualmente separadas por otros elementos.
+
+### Con Sombra
+
+Card con sombra sutil para crear profundidad cuando se necesita énfasis.
+
+```tsx
+<Card shadow="default" className="w-[350px]">
+  <CardHeader>
+    <CardTitle>Card with Shadow</CardTitle>
+    <CardDescription>Subtle elevation effect</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">
+      Use shadow="default" when you need elevation to make cards stand out.
+    </p>
+  </CardContent>
+</Card>
+```
+
+**Uso**: Usa cuando necesites que cards individuales se destaquen o floten sobre el contenido de fondo.
+
+### Combinando con Variantes de Color
+
+La prop `shadow` funciona con todas las variantes de color.
+
+```tsx
+{/* Flat colored cards */}
+<Card variant="primary" shadow="none" className="w-[350px]">
+  <CardHeader>
+    <CardTitle>Flat Primary</CardTitle>
+    <CardDescription>Primary color without shadow</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">
+      Combines color variant with flat design for modern appearance.
+    </p>
+  </CardContent>
+</Card>
+
+{/* Elevated colored cards */}
+<Card variant="success" shadow="default" className="w-[350px]">
+  <CardHeader>
+    <CardTitle>Elevated Success</CardTitle>
+    <CardDescription>Success color with shadow</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">
+      Shadow adds depth to colored variants for emphasis.
+    </p>
+  </CardContent>
+</Card>
+```
+
+**Nota**: Experimenta con `shadow="none"` en grids de cards o layouts densos para un look más limpio.
+
+## Variantes de Borde
+
+El Card ofrece dos opciones de borde a través de la prop `border`:
+
+### Con Borde (Default)
+
+Por defecto, las cards tienen un borde visible que define claramente sus límites:
+
+```tsx
+<Card border="default" variant="primary">
+  <CardHeader>
+    <CardTitle>Card con Borde</CardTitle>
+    <CardDescription>Borde visible para definición clara</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">
+      El borde ayuda a separar la card del fondo y de otros elementos.
+    </p>
+  </CardContent>
+</Card>
+```
+
+### Sin Borde
+
+Usa `border="transparent"` para ocultar el borde mientras mantienes el espaciado:
+
+```tsx
+<Card border="transparent" variant="primary">
+  <CardHeader>
+    <CardTitle>Card sin Borde</CardTitle>
+    <CardDescription>Diseño más limpio y minimalista</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p className="text-sm">
+      Sin borde para un look más integrado con el fondo.
+    </p>
+  </CardContent>
+</Card>
+```
+
+**Nota**: `border="transparent"` mantiene el espacio del borde en el layout, a diferencia de removerlo completamente. Esto asegura consistencia en el espaciado.
 
 ## Patrones Avanzados
 
@@ -892,6 +1014,37 @@ Diferentes arreglos de botones.
 </Card>
 ```
 
+### Uso de Sombras y Bordes
+
+```tsx
+{/* ✅ Correcto - Default sin sombra para diseño plano */}
+<Card>
+  <CardContent>Clean, flat design</CardContent>
+</Card>
+
+{/* ✅ Correcto - Shadow para cards flotantes o destacadas */}
+<Card shadow="default">
+  <CardContent>Elevated card with depth</CardContent>
+</Card>
+
+{/* ✅ Correcto - Border transparent para integración con fondo */}
+<Card border="transparent" variant="muted">
+  <CardContent>Blends with background</CardContent>
+</Card>
+
+{/* ⚠️ Evitar - Shadow sin propósito específico */}
+<Card shadow="default">
+  <CardContent>Unnecessary elevation</CardContent>
+</Card>
+```
+
+**Recomendaciones**:
+
+- Usa `shadow="none"` (default) para layouts densos y diseños modernos
+- Aplica `shadow="default"` para destacar cards importantes o flotantes
+- Usa `border="transparent"` en cards sobre fondos de color similar
+- Mantén `border="default"` para máxima claridad y separación
+
 ### Estructura de Header Completa
 
 ```tsx
@@ -1023,17 +1176,60 @@ Diferentes arreglos de botones.
 </CardHeader>;
 ```
 
+### Uso de Shadow
+
+```tsx
+{/* ✅ Correcto - Shadow para cards individuales o destacadas */}
+<Card shadow="default" className="w-[350px]">
+  <CardContent>
+    Stands out with subtle elevation
+  </CardContent>
+</Card>
+
+{/* ✅ Correcto - Sin shadow para grids densos */}
+<div className="grid gap-4 md:grid-cols-3">
+  <Card shadow="none">
+    <CardContent>Flat design in dense layout</CardContent>
+  </Card>
+  <Card shadow="none">
+    <CardContent>Flat design in dense layout</CardContent>
+  </Card>
+  <Card shadow="none">
+    <CardContent>Flat design in dense layout</CardContent>
+  </Card>
+</div>
+
+{/* ✅ Correcto - Sin shadow cuando ya hay separación visual */}
+<div className="space-y-4">
+  <Card shadow="none">
+    <CardContent>Spacing provides separation</CardContent>
+  </Card>
+  <Card shadow="none">
+    <CardContent>No shadow needed here</CardContent>
+  </Card>
+</div>
+
+{/* ⚠️ Considerar - Mucha sombra en layouts densos */}
+<div className="grid gap-2 md:grid-cols-4">
+  <Card shadow="default">...</Card>  {/* Puede verse pesado */}
+  <Card shadow="default">...</Card>
+  <Card shadow="default">...</Card>
+  <Card shadow="default">...</Card>
+</div>
+```
+
 ## Notas de Implementación
 
-- **Basado en CVA**: Usa `class-variance-authority` para variantes de color
+- **Basado en CVA**: Usa `class-variance-authority` para variantes de color, sombra y borde
 - **Data Slots**: Cada componente tiene `data-slot` para CSS targeting específico (`data-slot="card"`, `data-slot="card-header"`, etc.)
 - **Grid Automático**: CardHeader usa `has-data-[slot=card-action]:grid-cols-[1fr_auto]` para detectar CardAction y ajustar layout
 - **Container Queries**: CardHeader tiene `@container/card-header` para responsive interno (requiere Tailwind CSS container queries)
 - **Spacing Consistente**: `gap-6` entre secciones (header, content, footer), `px-6` horizontal en todas las secciones
 - **Padding Condicional**: `.border-b` y `.border-t` triggers automáticos para `pb-6` y `pt-6` respectivamente
 - **Variantes de Color**: Cada variante ajusta `bg-*-50` y `text-*-foreground`, con ajustes para iconos SVG (`[&>svg]:text-current`)
-- **Rounded Corners**: `rounded-xl` por defecto (12px)
-- **Shadow**: `shadow-sm` para elevación sutil
+- **Variantes de Sombra**: Dos opciones (`default` con `shadow-xs`, `none` sin sombra por defecto) para control de elevación
+- **Variantes de Borde**: Dos opciones (`default` con borde visible, `transparent` con borde invisible pero mantiene espaciado)
+- **Rounded Corners**: `rounded-3xl` por defecto para esquinas suaves
 - **Flex Column**: Card root usa `flex flex-col gap-6` para layout vertical automático
 
 ## Accesibilidad

package/docs/components/ui/icon.md

@@ -8,11 +8,13 @@ Componente para mostrar **iconos Material Symbols Outlined** con configuración
 
 - ✅ Material Symbols Outlined con fuente local para mejor rendimiento
 - ✅ Tamaños controlados por clases Tailwind: `text-lg`, `text-2xl`, `text-4xl`, `text-5xl`
+- ✅ Tamaño por defecto: `text-2xl` (~24px) para uso general
 - ✅ 7 pesos tipográficos: 100-700 (default: 300)
 - ✅ Fill modes: outlined (0) y filled (1)
 - ✅ 3 grados ópticos: -25, 0 (default), 200
 - ✅ 4 tamaños ópticos: 20, 24 (default), 40, 48
 - ✅ Configuración via CSS font-variation-settings
+- ✅ Data slot `data-slot="icon"` para CSS targeting específico
 - ✅ Tipos exportados: IconProps para extensibilidad
 - ✅ Extensión de ComponentProps<"span"> para máxima flexibilidad
 - ✅ Soporte completo para className y style customizados
@@ -479,12 +481,12 @@ La fuente se carga localmente desde `assets/icons/`:
 
 ```css
 .material-symbols-outlined {
-  font-variation-settings: "FILL" 0, "wght" 200, "GRAD" 0, "opsz" 24;
+  font-variation-settings: "FILL" 0, "wght" 300, "GRAD" 0, "opsz" 24;
   /* ... otros estilos de optimización */
 }
 ```
 
-**Nota**: Tanto el CSS como el componente React usan 200 como peso por defecto.
+**Nota**: Tanto el CSS como el componente React usan 300 como peso por defecto para un aspecto ligero y moderno.
 
 ### TypeScript Interface
 
@@ -500,6 +502,24 @@ export type IconProps = ComponentProps<"span"> & {
 
 **Tipos Exportados**: Usa `IconProps` para crear componentes custom. Los tamaños ahora se controlan via `className` con clases Tailwind.
 
+### Component Structure
+
+El componente renderiza un `<span>` con las siguientes características:
+
+```tsx
+<span
+  data-slot="icon"
+  className="material-symbols-outlined adm:inline-block adm:text-2xl"
+  style={{ fontVariationSettings: '...' }}
+>
+  {symbol}
+</span>
+```
+
+- **data-slot="icon"**: Permite targeting CSS específico, útil para estilos contextuales (ej: `[&>[data-slot=icon]]:text-current`)
+- **className base**: `material-symbols-outlined adm:inline-block adm:text-2xl` (puede ser extendido via prop `className`)
+- **style**: Genera `font-variation-settings` dinámicamente según props
+
 ## Recursos
 
 ### Material Symbols

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adamosuiteservices/ui",
-  "version": "2.10.0",
+  "version": "2.10.2",
   "private": false,
   "type": "module",
   "main": "./dist/index.js",