@moni-labs/moni-ui 0.4.4 → 0.4.6

package/docs/components/carousel.md

@@ -0,0 +1,275 @@
+# Carousel
+
+Componente Material Design 3 Expressive Carousel.
+
+Los carruseles muestran una colección de elementos relacionados en una lista horizontal desplazable.
+Permiten a los usuarios navegar rápidamente a través de elementos como imágenes, tarjetas, o productos.
+
+**Referencia de la especificación M3:** `m3-docs/components/carousel/specs.md`
+
+**Variantes de diseño:**
+- `multi-browse` (por defecto) — Muestra una mezcla de elementos grandes, medianos y pequeños (asomando).
+  Mejor para explorar un gran número de elementos.
+- `hero` — Se enfoca en un elemento primario grande mientras muestra una fracción del
+  siguiente elemento. Mejor para destacar contenido importante.
+- `uncontained` — Diseño estándar donde todos los elementos tienen el mismo ancho y
+  se desbordan por los bordes del contenedor.
+
+**Animación y Gestos:**
+Este componente usa GSAP para animaciones suaves de arrastre, deslizamiento y ajuste,
+reflejando las especificaciones de movimiento de alta fidelidad de M3 Expressive. Maneja
+gestos táctiles para móviles y arrastre del ratón para escritorio.
+
+**Auto-tamaño (modo `auto`):**
+Cuando `auto=true` (por defecto), el carrusel mide su propio ancho y
+calcula dinámicamente los tamaños óptimos para los elementos grandes, medianos y pequeños
+basados en el `layout` activo para asegurar que encajen perfectamente sin huecos incómodos
+ni recortes en los bordes.
+
+- Tag: `moni-carousel`
+- Clase: `MoniCarousel`
+- Fuente: `src/components/moni-carousel.ts`
+
+## Cuándo usarlo
+
+Usa `moni-carousel` cuando la interfaz necesite el patrón que describe este componente. Antes de elegirlo, revisa sus estados, contenido permitido y comportamiento accesible; las capturas del final muestran el resultado real de cada variante.
+
+## Uso básico
+
+```html
+<!-- Uso declarativo a través de propiedades DOM (recomendado) -->
+<moni-carousel layout="hero"></moni-carousel>
+<script>
+  const carousel = document.querySelector('moni-carousel');
+  carousel.items = [
+    { title: 'Elemento 1', img: '/img1.jpg', href: '/link1' },
+    { title: 'Elemento 2', img: '/img2.jpg' }
+  ];
+</script>
+
+<!-- Uso basado en slots (para SSR o contenido estático simple) -->
+<moni-carousel layout="uncontained">
+  <div slot="item">
+    <img src="/img1.jpg" />
+    <h3>Elemento Estático</h3>
+  </div>
+</moni-carousel>
+```
+
+## Ejemplo práctico con Tailwind CSS v4
+
+Tailwind controla composición, ancho, espaciado y responsividad alrededor del Web Component. Moni UI conserva el aspecto interno mediante Shadow DOM y design tokens.
+
+```html
+<div class="mx-auto flex w-full max-w-md flex-col gap-4 p-6">
+  <moni-carousel></moni-carousel>
+</div>
+```
+
+No necesitas un plugin de Tailwind. En tu CSS v4 importa ambas capas una sola vez:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Las utilities aplicadas directamente al tag afectan su caja anfitriona. No uses selectores Tailwind para asumir acceso al DOM interno; personaliza únicamente con los CSS Parts y Custom Properties públicos enumerados más abajo.
+
+## Recomendaciones
+
+- Usa `moni-carousel` para su propósito semántico; no lo sustituyas por un `div` estilizado.
+- Aplica Tailwind al layout exterior. Para el interior del Shadow DOM usa las variables CSS y `::part()` documentados.
+- Prueba los estados claro, oscuro, foco por teclado, deshabilitado y viewport móvil antes de publicar.
+
+## Propiedades y atributos
+
+| Atributo | Propiedad | Tipo | Default | Descripción |
+|---|---|---|---|---|
+| `items` | `items` | `CarouselItem[]` | `[]` | Array de elementos a mostrar en el carrusel. Cada elemento requiere al menos `title` e `img`. El opcional `href` renderiza la tarjeta como un enlace. |
+| `layout` | `layout` | `'multi-browse' \| 'hero' \| 'uncontained'` | `'multi-browse'` | Variante de diseño visual. Determina cuántos elementos son visibles y cómo escalan. - `'multi-browse'` (por defecto) — Elementos grandes + medianos + pequeños (asomando). - `'hero'` — Uno o más elementos grandes + elemento pequeño asomando. - `'uncontained'` — Elementos de igual ancho que se desbordan por el borde. |
+| `auto` | `auto` | `boolean` | `true` | Cuando es `true`, el carrusel calcula los tamaños óptimos de los elementos automáticamente basado en el ancho del contenedor y la variante de `layout` activa. Cuando es `false`, usa los valores explícitos `largeWidth`, `mediumWidth`, `smallWidth`. |
+| `large-width` | `largeWidth` | `number` | `220` | Ancho en píxeles para el elemento grande (enfoque principal) del carrusel. Solo se usa cuando `auto=false`. |
+| `medium-width` | `mediumWidth` | `number` | `96` | Ancho en píxeles para el elemento de tamaño mediano (secundario) del carrusel. Solo se usa cuando `auto=false` y `layout='multi-browse'`. |
+| `small-width` | `smallWidth` | `number` | `48` | Ancho en píxeles para el elemento pequeño (asomando) del carrusel. Solo se usa cuando `auto=false`. |
+| `gap` | `gap` | `number` | `8` | Espacio en píxeles entre los elementos del carrusel. |
+| `padding` | `padding` | `number` | `16` | Relleno horizontal en píxeles aplicado al inicio de la pista del carrusel. |
+| `border-radius` | `borderRadius` | `number` | `28` | Radio del borde en píxeles aplicado a cada tarjeta. |
+| `show-all` | `showAll` | `boolean` | `false` | Cuando es `true`, renderiza un enlace "Mostrar todo" en el encabezado. |
+| `show-all-text` | `showAllText` | `string` | `'Show all'` | Texto de etiqueta para el enlace "Mostrar todo". |
+| `header-text` | `headerText` | `string` | `''` | Encabezado de sección opcional renderizado sobre la pista del carrusel. |
+| `hide-nav` | `hideNav` | `boolean` | `false` | Cuando es `true`, oculta los botones de flecha de navegación anterior/siguiente. |
+| `infinite` | `infinite` | `boolean` | `false` | Cuando es `true`, habilita el bucle infinito sin interrupciones clonando la lista de elementos a través de un búfer de desplazamiento virtual grande, luego reposicionando silenciosamente el desplazamiento cuando el usuario se acerca a cualquier borde. |
+| `autoplay` | `autoplay` | `boolean` | `false` | Cuando es `true`, avanza automáticamente el carrusel en el intervalo definido por `autoplayInterval`. La reproducción automática se detiene durante las interacciones de arrastre activas. |
+| `autoplay-interval` | `autoplayInterval` | `number` | `3000` | Milisegundos entre los avances automáticos de diapositivas cuando `autoplay=true`. |
+
+## Slots
+
+- `item`: Alternativa a la propiedad `items`. Inserta elementos HTML individuales
+       en lugar de pasar objetos de datos.
+
+## Eventos
+
+- `item-click`: evento compuesto y burbujeante emitido por el componente.
+- `show-all-click`: evento compuesto y burbujeante emitido por el componente.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `carousel`: El envoltorio exterior.
+- `track`: El elemento de la pista desplazable.
+- `item`: Contenedores de elementos del carrusel individuales.
+- `img`: Los elementos de imagen dentro de los elementos.
+- `title`: Los elementos de texto de título dentro de los elementos.
+
+## CSS Custom Properties consumidas
+
+- `--carousel-border-radius`
+- `--carousel-gap`
+- `--carousel-padding`
+- `--carousel-right-padding`
+- `--carousel-snap-width`
+- `--carousel-track-width`
+- `--elevate1`
+- `--elevate2`
+- `--font-icon`
+- `--font-title`
+- `--on-primary-container`
+- `--on-surface`
+- `--primary`
+- `--primary-container`
+- `--speed2`
+- `--surface-container-high`
+- `--surface-container-highest`
+
+## Referencia visual por variable
+
+Cada imagen se genera con el componente real: cambia solo la variable indicada y mantiene estable el resto del escenario. Úsala para comparar estados, no como sustituto de la API.
+
+### `items`
+
+Array de elementos a mostrar en el carrusel.
+Cada elemento requiere al menos `title` e `img`. El opcional `href` renderiza la tarjeta como un enlace.
+
+![moni-carousel — items=default](../assets/moni-carousel/items--default.png)
+
+### `layout`
+
+Variante de diseño visual. Determina cuántos elementos son visibles y cómo escalan.
+- `'multi-browse'` (por defecto) — Elementos grandes + medianos + pequeños (asomando).
+- `'hero'` — Uno o más elementos grandes + elemento pequeño asomando.
+- `'uncontained'` — Elementos de igual ancho que se desbordan por el borde.
+
+![moni-carousel — layout=multi-browse](../assets/moni-carousel/layout--multi-browse.png)
+
+![moni-carousel — layout=hero](../assets/moni-carousel/layout--hero.png)
+
+![moni-carousel — layout=uncontained](../assets/moni-carousel/layout--uncontained.png)
+
+### `auto`
+
+Cuando es `true`, el carrusel calcula los tamaños óptimos de los elementos automáticamente
+basado en el ancho del contenedor y la variante de `layout` activa.
+Cuando es `false`, usa los valores explícitos `largeWidth`, `mediumWidth`, `smallWidth`.
+
+![moni-carousel — auto=false](../assets/moni-carousel/auto--false.png)
+
+![moni-carousel — auto=true](../assets/moni-carousel/auto--true.png)
+
+### `large-width`
+
+Ancho en píxeles para el elemento grande (enfoque principal) del carrusel.
+Solo se usa cuando `auto=false`.
+
+![moni-carousel — large-width=default](../assets/moni-carousel/largeWidth--default.png)
+
+### `medium-width`
+
+Ancho en píxeles para el elemento de tamaño mediano (secundario) del carrusel.
+Solo se usa cuando `auto=false` y `layout='multi-browse'`.
+
+![moni-carousel — medium-width=default](../assets/moni-carousel/mediumWidth--default.png)
+
+### `small-width`
+
+Ancho en píxeles para el elemento pequeño (asomando) del carrusel.
+Solo se usa cuando `auto=false`.
+
+![moni-carousel — small-width=default](../assets/moni-carousel/smallWidth--default.png)
+
+### `gap`
+
+Espacio en píxeles entre los elementos del carrusel.
+
+![moni-carousel — gap=default](../assets/moni-carousel/gap--default.png)
+
+### `padding`
+
+Relleno horizontal en píxeles aplicado al inicio de la pista del carrusel.
+
+![moni-carousel — padding=default](../assets/moni-carousel/padding--default.png)
+
+### `border-radius`
+
+Radio del borde en píxeles aplicado a cada tarjeta.
+
+![moni-carousel — border-radius=default](../assets/moni-carousel/borderRadius--default.png)
+
+### `show-all`
+
+Cuando es `true`, renderiza un enlace "Mostrar todo" en el encabezado.
+
+![moni-carousel — show-all=false](../assets/moni-carousel/showAll--false.png)
+
+![moni-carousel — show-all=true](../assets/moni-carousel/showAll--true.png)
+
+### `show-all-text`
+
+Texto de etiqueta para el enlace "Mostrar todo".
+
+![moni-carousel — show-all-text=default](../assets/moni-carousel/showAllText--default.png)
+
+### `header-text`
+
+Encabezado de sección opcional renderizado sobre la pista del carrusel.
+
+![moni-carousel — header-text=default](../assets/moni-carousel/headerText--default.png)
+
+### `hide-nav`
+
+Cuando es `true`, oculta los botones de flecha de navegación anterior/siguiente.
+
+![moni-carousel — hide-nav=false](../assets/moni-carousel/hideNav--false.png)
+
+![moni-carousel — hide-nav=true](../assets/moni-carousel/hideNav--true.png)
+
+### `infinite`
+
+Cuando es `true`, habilita el bucle infinito sin interrupciones clonando la lista de elementos
+a través de un búfer de desplazamiento virtual grande, luego reposicionando silenciosamente
+el desplazamiento cuando el usuario se acerca a cualquier borde.
+
+![moni-carousel — infinite=false](../assets/moni-carousel/infinite--false.png)
+
+![moni-carousel — infinite=true](../assets/moni-carousel/infinite--true.png)
+
+### `autoplay`
+
+Cuando es `true`, avanza automáticamente el carrusel en el intervalo definido
+por `autoplayInterval`. La reproducción automática se detiene durante las interacciones de arrastre activas.
+
+![moni-carousel — autoplay=false](../assets/moni-carousel/autoplay--false.png)
+
+![moni-carousel — autoplay=true](../assets/moni-carousel/autoplay--true.png)
+
+### `autoplay-interval`
+
+Milisegundos entre los avances automáticos de diapositivas cuando `autoplay=true`.
+
+![moni-carousel — autoplay-interval=default](../assets/moni-carousel/autoplayInterval--default.png)

package/docs/components/checkbox.md

@@ -0,0 +1,196 @@
+# Checkbox
+
+Componente Material Design 3 Checkbox.
+
+Los checkboxes permiten a los usuarios seleccionar uno o más elementos de un conjunto, o alternar
+una sola opción binaria. Son envolturas solo visuales — el consumidor es
+responsable de conectar la lógica de envío y validación del formulario.
+
+**Arquitectura visual (Patrón BeerCSS):**
+El `<input type="checkbox">` nativo ocupa espacio real en el diseño (mínimo 16×16)
+pero está oculto visualmente con `opacity: 0`. Un hermano `<span>` renderizado después
+del input contiene dos pseudo-elementos:
+- `::before` — el icono visible del checkbox (ligadura de Material Symbols).
+- `::after`  — el anillo de onda (ripple) de la capa de estado hover/focus.
+
+El contenido de `::before` cambia entre:
+- `'check_box_outline_blank'` (desmarcado)
+- `'check_box'` (marcado)
+- `'indeterminate_check_box'` (estado nativo indeterminado)
+
+**Integración de formulario:**
+Establecer `name` y `value` los pasa al elemento `<input>` nativo,
+permitiendo la participación en envíos de formularios HTML.
+
+- Tag: `moni-checkbox`
+- Clase: `MoniCheckbox`
+- Fuente: `src/components/moni-checkbox.ts`
+
+## Cuándo usarlo
+
+Usa `moni-checkbox` cuando la interfaz necesite el patrón que describe este componente. Antes de elegirlo, revisa sus estados, contenido permitido y comportamiento accesible; las capturas del final muestran el resultado real de cada variante.
+
+## Uso básico
+
+```html
+<moni-checkbox label="Aceptar términos" name="terms" value="yes"></moni-checkbox>
+
+<script>
+  document.querySelector('moni-checkbox').addEventListener('moni-change', (e) => {
+    console.log('checked:', e.target.checked);
+  });
+</script>
+```
+
+## Ejemplo práctico con Tailwind CSS v4
+
+Tailwind controla composición, ancho, espaciado y responsividad alrededor del Web Component. Moni UI conserva el aspecto interno mediante Shadow DOM y design tokens.
+
+```html
+<div class="mx-auto flex w-full max-w-md flex-col gap-4 p-6">
+  <moni-checkbox label="Ejemplo"></moni-checkbox>
+</div>
+```
+
+No necesitas un plugin de Tailwind. En tu CSS v4 importa ambas capas una sola vez:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Las utilities aplicadas directamente al tag afectan su caja anfitriona. No uses selectores Tailwind para asumir acceso al DOM interno; personaliza únicamente con los CSS Parts y Custom Properties públicos enumerados más abajo.
+
+## Recomendaciones
+
+- Usa `moni-checkbox` para su propósito semántico; no lo sustituyas por un `div` estilizado.
+- Aplica Tailwind al layout exterior. Para el interior del Shadow DOM usa las variables CSS y `::part()` documentados.
+- Durante una operación asíncrona combina el estado `loading` —si existe— con `disabled` para evitar envíos duplicados.
+- En formularios controlados, sincroniza la propiedad `value` y escucha el evento documentado; no dependas solo del atributo inicial.
+- Prueba los estados claro, oscuro, foco por teclado, deshabilitado y viewport móvil antes de publicar.
+
+## Propiedades y atributos
+
+| Atributo | Propiedad | Tipo | Default | Descripción |
+|---|---|---|---|---|
+| `label` | `label` | `string` | `''` | Texto de la etiqueta mostrado a la derecha del icono del checkbox.  Cuando no está vacío, la etiqueta se renderiza como un nodo de texto dentro del `<span>`. Cuando está vacío, el slot por defecto se renderiza en su lugar, permitiendo HTML en el slot. |
+| `checked` | `checked` | `boolean` | `false` | Si el checkbox está actualmente marcado.  Reflejado como un atributo para que los selectores de atributos CSS y los lectores de estado externos puedan observar el estado marcado sin acceder a la propiedad JS. Sincronizado con el input nativo a través de `updated()`. |
+| `disabled` | `disabled` | `boolean` | `false` | Cuando es `true`, el input nativo se deshabilita: el checkbox no es interactivo y se renderiza con opacidad del 50%. |
+| `unchecked-icon` | `uncheckedIcon` | `string` | `''` | Material Symbol mostrado cuando el checkbox está desmarcado. |
+| `checked-icon` | `checkedIcon` | `string` | `''` | Material Symbol mostrado cuando el checkbox está marcado. |
+| `size` | `size` | `'small' \| 'medium' \| 'large' \| 'extra'` | `'medium'` | Tamaño visual del icono del checkbox.  Se mapea a la propiedad personalizada `--_size` que controla tanto el área de impacto del input invisible como el tamaño del icono visible `::before`.  \| Valor      \| `--_size` \| \|------------\|-----------\| \| `'small'`  \| 1rem      \| \| `'medium'` \| 1.5rem    \| \| `'large'`  \| 2rem      \| \| `'extra'`  \| 2.5rem    \| |
+| `name` | `name` | `string` | `''` | Reenviado al atributo `<input name>` nativo. Requerido para agrupar checkboxes dentro de un formulario. |
+| `value` | `value` | `string` | `''` | Reenviado al atributo `<input value>` nativo. El valor enviado en un formulario cuando este checkbox está marcado. |
+
+## Slots
+
+Este componente no declara slots públicos.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `checkbox`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_size`
+- `--font`
+- `--font-icon`
+- `--on-primary`
+- `--on-surface`
+- `--on-surface-variant`
+- `--primary`
+- `--speed1`
+
+## Referencia visual por variable
+
+Cada imagen se genera con el componente real: cambia solo la variable indicada y mantiene estable el resto del escenario. Úsala para comparar estados, no como sustituto de la API.
+
+### `label`
+
+Texto de la etiqueta mostrado a la derecha del icono del checkbox.
+
+Cuando no está vacío, la etiqueta se renderiza como un nodo de texto dentro del `<span>`.
+Cuando está vacío, el slot por defecto se renderiza en su lugar, permitiendo HTML en el slot.
+
+![moni-checkbox — label=default](../assets/moni-checkbox/label--default.png)
+
+### `checked`
+
+Si el checkbox está actualmente marcado.
+
+Reflejado como un atributo para que los selectores de atributos CSS y los lectores
+de estado externos puedan observar el estado marcado sin acceder a la propiedad JS.
+Sincronizado con el input nativo a través de `updated()`.
+
+![moni-checkbox — checked=false](../assets/moni-checkbox/checked--false.png)
+
+![moni-checkbox — checked=true](../assets/moni-checkbox/checked--true.png)
+
+### `disabled`
+
+Cuando es `true`, el input nativo se deshabilita: el checkbox no es interactivo
+y se renderiza con opacidad del 50%.
+
+![moni-checkbox — disabled=false](../assets/moni-checkbox/disabled--false.png)
+
+![moni-checkbox — disabled=true](../assets/moni-checkbox/disabled--true.png)
+
+### `unchecked-icon`
+
+Material Symbol mostrado cuando el checkbox está desmarcado.
+
+![moni-checkbox — unchecked-icon=default](../assets/moni-checkbox/uncheckedIcon--default.png)
+
+### `checked-icon`
+
+Material Symbol mostrado cuando el checkbox está marcado.
+
+![moni-checkbox — checked-icon=default](../assets/moni-checkbox/checkedIcon--default.png)
+
+### `size`
+
+Tamaño visual del icono del checkbox.
+
+Se mapea a la propiedad personalizada `--_size` que controla tanto el área de impacto
+del input invisible como el tamaño del icono visible `::before`.
+
+| Valor      | `--_size` |
+|------------|-----------|
+| `'small'`  | 1rem      |
+| `'medium'` | 1.5rem    |
+| `'large'`  | 2rem      |
+| `'extra'`  | 2.5rem    |
+
+![moni-checkbox — size=small](../assets/moni-checkbox/size--small.png)
+
+![moni-checkbox — size=medium](../assets/moni-checkbox/size--medium.png)
+
+![moni-checkbox — size=large](../assets/moni-checkbox/size--large.png)
+
+![moni-checkbox — size=extra](../assets/moni-checkbox/size--extra.png)
+
+### `name`
+
+Reenviado al atributo `<input name>` nativo.
+Requerido para agrupar checkboxes dentro de un formulario.
+
+![moni-checkbox — name=default](../assets/moni-checkbox/name--default.png)
+
+### `value`
+
+Reenviado al atributo `<input value>` nativo.
+El valor enviado en un formulario cuando este checkbox está marcado.
+
+![moni-checkbox — value=default](../assets/moni-checkbox/value--default.png)

package/docs/components/chip.md

@@ -0,0 +1,222 @@
+# Chip
+
+Componente Material Design 3 Chip.
+
+Los chips (fichas) son elementos compactos e interactivos que representan acciones, filtros,
+atributos o entradas de usuario. Son contenedores solo visuales — el consumidor
+es dueño de todo el manejo del estado (selección, eliminación, estado de filtro activo).
+
+**Referencia de la especificación M3:** `m3-docs/components/chips/specs.md`
+
+**Variantes:**
+- `assist` (por defecto) — Acciones inteligentes o sugeridas. Usa borde `var(--outline)`
+  para asegurar un contraste de 3:1 según la especificación de accesibilidad de M3. Alias: `outlined`.
+- `filter` — Filtros para una colección de contenido. Muestra una marca de verificación al principio cuando
+  está `selected`. Alias: `fill`.
+- `input` — Representa una entrada de usuario discreta (etiquetas, tokens). Añade un icono de
+  eliminación al final cuando es `removable`.
+- `suggestion` — Sugerencias generadas por el producto. Con contorno, sin iconos.
+
+**Medidas M3:**
+- Altura por defecto: 32dp (tamaño `small` = línea base de la especificación M3).
+- Radio de esquina: 8dp.
+- Tamaño de icono: 18dp.
+- Los tamaños `medium` y `large` son extensiones de Moni con áreas táctiles más grandes.
+
+**Accesibilidad:**
+Los chips `assist` y `suggestion` usan `var(--outline)` para su trazo para
+garantizar un contraste de 3:1 contra el fondo de la superficie en reposo.
+`filter` e `input` usan `outline-variant` en reposo pero logran contraste
+a través del relleno `secondary-container` cuando se seleccionan.
+
+- Tag: `moni-chip`
+- Clase: `MoniChip`
+- Fuente: `src/components/moni-chip.ts`
+
+## Cuándo usarlo
+
+Usa `moni-chip` cuando la interfaz necesite el patrón que describe este componente. Antes de elegirlo, revisa sus estados, contenido permitido y comportamiento accesible; las capturas del final muestran el resultado real de cada variante.
+
+## Uso básico
+
+```html
+<!-- Chip de filtro con estado seleccionado -->
+<moni-chip variant="filter" selected>Technology</moni-chip>
+
+<!-- Chip de entrada (etiqueta/token) -->
+<moni-chip variant="input" removable icon="label">TypeScript</moni-chip>
+
+<!-- Chip de asistencia con icono -->
+<moni-chip icon="directions_car">Get directions</moni-chip>
+```
+
+## Ejemplo práctico con Tailwind CSS v4
+
+Tailwind controla composición, ancho, espaciado y responsividad alrededor del Web Component. Moni UI conserva el aspecto interno mediante Shadow DOM y design tokens.
+
+```html
+<div class="mx-auto flex w-full max-w-md flex-col gap-4 p-6">
+  <moni-chip>Accesibilidad</moni-chip>
+</div>
+```
+
+No necesitas un plugin de Tailwind. En tu CSS v4 importa ambas capas una sola vez:
+
+```css
+@import "tailwindcss";
+@import "@moni-labs/moni-ui/styles";
+
+@theme {
+  --font-sans: Inter, ui-sans-serif, system-ui, sans-serif;
+}
+```
+
+Las utilities aplicadas directamente al tag afectan su caja anfitriona. No uses selectores Tailwind para asumir acceso al DOM interno; personaliza únicamente con los CSS Parts y Custom Properties públicos enumerados más abajo.
+
+## Recomendaciones
+
+- Usa `moni-chip` para su propósito semántico; no lo sustituyas por un `div` estilizado.
+- Aplica Tailwind al layout exterior. Para el interior del Shadow DOM usa las variables CSS y `::part()` documentados.
+- Durante una operación asíncrona combina el estado `loading` —si existe— con `disabled` para evitar envíos duplicados.
+- Cuando el control muestre únicamente un icono, añade siempre un `aria-label` descriptivo.
+- Prueba los estados claro, oscuro, foco por teclado, deshabilitado y viewport móvil antes de publicar.
+
+## Propiedades y atributos
+
+| Atributo | Propiedad | Tipo | Default | Descripción |
+|---|---|---|---|---|
+| `variant` | `variant` | `'assist' \| 'filter' \| 'input' \| 'suggestion' \| 'outlined' \| 'fill'` | `'assist'` | Variante visual del chip. |
+| `size` | `size` | `'small' \| 'medium' \| 'large'` | `'small'` | Define las dimensiones del chip. |
+| `shape` | `shape` | `'round' \| 'no-round' \| 'square' \| 'circle' \| 'left-round' \| 'right-round' \| 'top-round' \| 'bottom-round'` | `'round'` | Forma del radio del borde del chip. |
+| `selected` | `selected` | `boolean` | `false` | Si es true, marca el chip como seleccionado (útil para chips de filtro). |
+| `removable` | `removable` | `boolean` | `false` | Si es true, muestra un icono de cierre al final para permitir la eliminación. |
+| `disabled` | `disabled` | `boolean` | `false` | Deshabilita el chip. |
+| `loading` | `loading` | `boolean` | `false` | Si es true, muestra un indicador de carga dentro del chip. |
+| `icon` | `icon` | `string` | `''` | Nombre del icono inicial (Material Symbols). |
+
+## Slots
+
+- `default`: El texto de la etiqueta del chip.
+- `icon`: Anula el icono inicial (alternativa al atributo `icon`).
+
+## Eventos
+
+- `remove`: evento compuesto y burbujeante emitido por el componente.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `chip`: Parte interna personalizable.
+- `label`: Parte interna personalizable.
+- `icon`: Parte interna personalizable.
+- `loading`: Parte interna personalizable.
+- `remove`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_icon-size`
+- `--_padding`
+- `--_round`
+- `--_size`
+- `--font`
+- `--font-icon`
+- `--on-secondary-container`
+- `--on-surface`
+- `--on-surface-variant`
+- `--outline`
+- `--outline-variant`
+- `--primary`
+- `--secondary-container`
+- `--speed2`
+- `--speed3`
+
+## Referencia visual por variable
+
+Cada imagen se genera con el componente real: cambia solo la variable indicada y mantiene estable el resto del escenario. Úsala para comparar estados, no como sustituto de la API.
+
+### `variant`
+
+Variante visual del chip.
+
+![moni-chip — variant=assist](../assets/moni-chip/variant--assist.png)
+
+![moni-chip — variant=filter](../assets/moni-chip/variant--filter.png)
+
+![moni-chip — variant=input](../assets/moni-chip/variant--input.png)
+
+![moni-chip — variant=suggestion](../assets/moni-chip/variant--suggestion.png)
+
+![moni-chip — variant=outlined](../assets/moni-chip/variant--outlined.png)
+
+![moni-chip — variant=fill](../assets/moni-chip/variant--fill.png)
+
+### `size`
+
+Define las dimensiones del chip.
+
+![moni-chip — size=small](../assets/moni-chip/size--small.png)
+
+![moni-chip — size=medium](../assets/moni-chip/size--medium.png)
+
+![moni-chip — size=large](../assets/moni-chip/size--large.png)
+
+### `shape`
+
+Forma del radio del borde del chip.
+
+![moni-chip — shape=round](../assets/moni-chip/shape--round.png)
+
+![moni-chip — shape=no-round](../assets/moni-chip/shape--no-round.png)
+
+![moni-chip — shape=square](../assets/moni-chip/shape--square.png)
+
+![moni-chip — shape=circle](../assets/moni-chip/shape--circle.png)
+
+![moni-chip — shape=left-round](../assets/moni-chip/shape--left-round.png)
+
+![moni-chip — shape=right-round](../assets/moni-chip/shape--right-round.png)
+
+![moni-chip — shape=top-round](../assets/moni-chip/shape--top-round.png)
+
+![moni-chip — shape=bottom-round](../assets/moni-chip/shape--bottom-round.png)
+
+### `selected`
+
+Si es true, marca el chip como seleccionado (útil para chips de filtro).
+
+![moni-chip — selected=false](../assets/moni-chip/selected--false.png)
+
+![moni-chip — selected=true](../assets/moni-chip/selected--true.png)
+
+### `removable`
+
+Si es true, muestra un icono de cierre al final para permitir la eliminación.
+
+![moni-chip — removable=false](../assets/moni-chip/removable--false.png)
+
+![moni-chip — removable=true](../assets/moni-chip/removable--true.png)
+
+### `disabled`
+
+Deshabilita el chip.
+
+![moni-chip — disabled=false](../assets/moni-chip/disabled--false.png)
+
+![moni-chip — disabled=true](../assets/moni-chip/disabled--true.png)
+
+### `loading`
+
+Si es true, muestra un indicador de carga dentro del chip.
+
+![moni-chip — loading=false](../assets/moni-chip/loading--false.png)
+
+![moni-chip — loading=true](../assets/moni-chip/loading--true.png)
+
+### `icon`
+
+Nombre del icono inicial (Material Symbols).
+
+![moni-chip — icon=default](../assets/moni-chip/icon--default.png)