@moni-labs/moni-ui 0.4.4 → 0.4.6

package/docs/components/morph-modal.md

@@ -0,0 +1,183 @@
+# Morph Modal
+
+Componente moni-morph-modal de Moni UI.
+
+- Tag: `moni-morph-modal`
+- Clase: `MoniMorphModal`
+- Fuente: `src/components/moni-morph-modal.ts`
+
+## Cuándo usarlo
+
+Usa `moni-morph-modal` 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-morph-modal></moni-morph-modal>
+```
+
+## 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-morph-modal></moni-morph-modal>
+</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-morph-modal` 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.
+- Mantén el estado de apertura en una única fuente de verdad y devuelve el foco al disparador al cerrar.
+- 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 |
+|---|---|---|---|---|
+| `target` | `target` | `string` | `''` | Selector del elemento disparador desde el cual transformarse (ej. '#fab' o '.my-button'). Si se omite, el modal aún puede activarse programáticamente estableciendo `open = true`. |
+| `open` | `open` | `boolean` | `false` | Controla el estado abierto/cerrado del modal. Puede establecerse directamente, o se gestiona internamente cuando se hace clic en el elemento `target`. |
+| `modal` | `modal` | `boolean` | `true` | Si es true, renderiza un fondo y atrapa el foco, actuando como un verdadero diálogo modal. |
+| `placement` | `placement` | `Placement` | `'center'` | Posición preferida del modal en relación con la ventana gráfica. |
+| `expanded-width` | `expandedWidth` | `string` | `'22rem'` | El ancho del modal cuando está completamente expandido. |
+| `expanded-height` | `expandedHeight` | `string` | `'18rem'` | La altura del modal cuando está completamente expandido. |
+| `close-on-click-outside` | `closeOnClickOutside` | `boolean` | `true` | Si es true, hacer clic fuera del modal lo cerrará. |
+| `close-on-esc` | `closeOnEsc` | `boolean` | `true` | Si es true, presionar la tecla Escape cerrará el modal. |
+| `show-close-button` | `showCloseButton` | `boolean` | `false` | Si es true, muestra un botón de icono de cierre por defecto en el encabezado. |
+| `morph-label` | `morphLabel` | `boolean` | `false` | Si es true, intenta fundir/transformar una etiqueta del disparador hacia el encabezado del modal. |
+| `morph-label-selector` | `morphLabelSelector` | `string` | `''` | Un selector CSS personalizado utilizado para encontrar el elemento de etiqueta específico dentro del target a transformar. |
+| `has-backdrop` | `hasBackdrop` | `boolean` | `true` | Si es true, renderiza un fondo atenuado detrás del modal. |
+| `hide-target` | `hideTarget` | `boolean` | `false` | Si es true, oculta el elemento disparador (target) mientras el modal está abierto. |
+| `cover-target` | `coverTarget` | `boolean` | `false` | Si es true, fuerza al modal a cubrir visualmente la ubicación original del target antes de expandirse. |
+| `auto-size` | `autoSize` | `boolean` | `false` | Si es true, el modal calcula automáticamente su tamaño final basándose en el contenido interno (ignora expandedWidth y expandedHeight). |
+| `blur-content` | `blurContent` | `boolean` | `false` | Si es true, aplica un efecto de desenfoque (blur) al contenido durante la animación de entrada y salida. |
+| `debug` | `debug` | `boolean` | `false` | Muestra en consola el origen, geometría y estrategia usada por cada morph. |
+
+## Slots
+
+Este componente no declara slots públicos.
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+- `show(): void` — Dispara la apertura del modal y coordina la animación de FLIP (First, Last, Invert, Play) / Morphing.
+1. Oculta visualmente el target original.
+2. Posiciona el modal colapsado exactamente sobre el target original (mismas dimensiones, color, y radios).
+3. Expande fluidamente el modal a sus dimensiones finales mediante transformaciones CSS.
+- `showFrom(target: HTMLElement): void` — Abre el modal realizando el morph desde un elemento proporcionado directamente.
+Útil cuando el trigger vive dentro de un Shadow DOM y no puede resolverse con `target`.
+- `resizeTo(width: string, height: string, anchor: 'center' | 'top-left' = 'center'): void` — Redimensiona y reposiciona suavemente un modal que ya está abierto.
+- `hide(): void` — Método público hide.
+- `toggle(): void` — Método público toggle.
+
+## CSS Parts
+
+- `backdrop`: Parte interna personalizable.
+- `body`: Parte interna personalizable.
+- `footer`: Parte interna personalizable.
+- `header`: Parte interna personalizable.
+- `icon`: Parte interna personalizable.
+- `icon-trailing`: Parte interna personalizable.
+- `label`: Parte interna personalizable.
+- `panel`: Parte interna personalizable.
+- `panel-inner`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_backdrop-duration`
+- `--_backdrop-ease`
+- `--_panel-height`
+- `--_panel-width`
+- `--_z-index`
+- `--active`
+- `--elevate2`
+- `--font-icon`
+- `--moni-morph-body-overflow-x`
+- `--moni-morph-body-overflow-y`
+- `--moni-morph-body-padding`
+- `--moni-morph-body-scrollbar-gutter`
+- `--moni-morph-panel-radius`
+- `--on-surface`
+- `--on-surface-variant`
+- `--outline-variant`
+- `--scrim`
+- `--surface-container-high`
+
+## 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.
+
+### `open`
+
+Controla el estado abierto/cerrado del modal.
+Puede establecerse directamente, o se gestiona internamente cuando se hace clic en el elemento `target`.
+
+![moni-morph-modal — open=true](../assets/moni-morph-modal/open--true.png)
+
+### `modal`
+
+Si es true, renderiza un fondo y atrapa el foco, actuando como un verdadero diálogo modal.
+
+![moni-morph-modal — modal=false](../assets/moni-morph-modal/modal--false.png)
+
+![moni-morph-modal — modal=true](../assets/moni-morph-modal/modal--true.png)
+
+### `placement`
+
+Posición preferida del modal en relación con la ventana gráfica.
+
+![moni-morph-modal — placement=default](../assets/moni-morph-modal/placement--default.png)
+
+### `expanded-width`
+
+El ancho del modal cuando está completamente expandido.
+
+![moni-morph-modal — expanded-width=default](../assets/moni-morph-modal/expandedWidth--default.png)
+
+### `expanded-height`
+
+La altura del modal cuando está completamente expandido.
+
+![moni-morph-modal — expanded-height=default](../assets/moni-morph-modal/expandedHeight--default.png)
+
+### `show-close-button`
+
+Si es true, muestra un botón de icono de cierre por defecto en el encabezado.
+
+![moni-morph-modal — show-close-button=false](../assets/moni-morph-modal/showCloseButton--false.png)
+
+![moni-morph-modal — show-close-button=true](../assets/moni-morph-modal/showCloseButton--true.png)
+
+### `has-backdrop`
+
+Si es true, renderiza un fondo atenuado detrás del modal.
+
+![moni-morph-modal — has-backdrop=false](../assets/moni-morph-modal/hasBackdrop--false.png)
+
+![moni-morph-modal — has-backdrop=true](../assets/moni-morph-modal/hasBackdrop--true.png)
+
+### `auto-size`
+
+Si es true, el modal calcula automáticamente su tamaño final basándose en el contenido interno (ignora expandedWidth y expandedHeight).
+
+![moni-morph-modal — auto-size=false](../assets/moni-morph-modal/autoSize--false.png)
+
+![moni-morph-modal — auto-size=true](../assets/moni-morph-modal/autoSize--true.png)

package/docs/components/nav-item.md

@@ -0,0 +1,169 @@
+# Nav Item
+
+Componente Material Design 3 Navigation Item (Elemento de Navegación).
+
+Un elemento de destino individual dentro de un contenedor `<moni-nav>`. Se renderiza como un
+elemento `<a>` accesible con un icono, etiqueta y capa de estado M3.
+
+**Referencias a la especificación M3:**
+- Elemento de barra de navegación: `m3-docs/components/navigation-bar/specs.md`
+- Elemento de riel de navegación: `m3-docs/components/navigation-rail/specs.md`
+- Elemento de cajón de navegación: `m3-docs/components/navigation-drawer/specs.md`
+
+**Adaptación de diseño:**
+Las propiedades `placement`, `variant` y `layout` son retransmitidas desde
+el padre `<moni-nav>` (típicamente a través de vinculación de atributos en el
+método render del padre). El elemento de navegación las usa para renderizar condicionalmente:
+- Icono + etiqueta abajo (barra de navegación).
+- Solo icono + etiqueta horizontal (riel).
+- Icono + etiqueta completa (cajón).
+
+**Comportamiento responsivo:**
+Usa `window.matchMedia('(min-width: 601px)')` para detectar pantallas medianas
+y almacena el resultado en `_isMediumScreen`. Esto impulsa el cambio de diseño
+automático entre estilos de barra y riel.
+
+**Estado activo:**
+El atributo `active` aplica el indicador activo M3: un fondo `secondary-container`
+en forma de píldora detrás del icono y un color de etiqueta más oscuro.
+
+- Tag: `moni-nav-item`
+- Clase: `MoniNavItem`
+- Fuente: `src/components/moni-nav-item.ts`
+
+## Cuándo usarlo
+
+Usa `moni-nav-item` 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-nav placement="bottom">
+  <moni-nav-item href="/" icon="home" label="Inicio" active></moni-nav-item>
+  <moni-nav-item href="/search" icon="search" label="Buscar"></moni-nav-item>
+  <moni-nav-item href="/profile" icon="person" label="Perfil">
+    <moni-badge value="3"></moni-badge>  <!-- insignia de notificación -->
+  </moni-nav-item>
+</moni-nav>
+```
+
+## 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-nav-item label="Ejemplo"></moni-nav-item>
+</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-nav-item` 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.
+- Cuando el control muestre únicamente un icono, añade siempre un `aria-label` descriptivo.
+- Mantén el estado de apertura en una única fuente de verdad y devuelve el foco al disparador al cerrar.
+- 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 |
+|---|---|---|---|---|
+| `href` | `href` | `string` | `'#'` | Define `href`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `target` | `target` | `string` | `''` | Define `target`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `icon` | `icon` | `string` | `''` | Nombre de Material Symbol mostrado por el componente. |
+| `label` | `label` | `string` | `''` | Etiqueta visible y accesible del control. |
+| `active` | `active` | `boolean` | `false` | Indica si el elemento está activo. |
+| `placement` | `placement` | `string` | `'top'` | Define `placement`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+| `variant` | `variant` | `string` | `'rail'` | Selecciona la variante visual y su nivel de énfasis. |
+| `layout` | `layout` | `string` | `'auto'` | Define `layout`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena. |
+
+## Slots
+
+- `default`: Contenido adicional colocado después del icono (ej. `<moni-badge>`).
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `item`: Parte interna personalizable.
+- `icon`: Parte interna personalizable.
+- `label`: Parte interna personalizable.
+- `indicator`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--font`
+- `--on-secondary-container`
+- `--on-surface-variant`
+- `--secondary`
+- `--secondary-container`
+- `--speed2`
+- `--surface-container-high`
+
+## 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.
+
+### `href`
+
+Define `href`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-nav-item — href=default](../assets/moni-nav-item/href--default.png)
+
+### `icon`
+
+Nombre de Material Symbol mostrado por el componente.
+
+![moni-nav-item — icon=default](../assets/moni-nav-item/icon--default.png)
+
+### `label`
+
+Etiqueta visible y accesible del control.
+
+![moni-nav-item — label=default](../assets/moni-nav-item/label--default.png)
+
+### `active`
+
+Indica si el elemento está activo.
+
+![moni-nav-item — active=false](../assets/moni-nav-item/active--false.png)
+
+![moni-nav-item — active=true](../assets/moni-nav-item/active--true.png)
+
+### `placement`
+
+Define `placement`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-nav-item — placement=default](../assets/moni-nav-item/placement--default.png)
+
+### `variant`
+
+Selecciona la variante visual y su nivel de énfasis.
+
+![moni-nav-item — variant=default](../assets/moni-nav-item/variant--default.png)
+
+### `layout`
+
+Define `layout`. Conserva el tipo indicado y usa la propiedad JavaScript cuando el valor no sea una cadena.
+
+![moni-nav-item — layout=default](../assets/moni-nav-item/layout--default.png)

package/docs/components/nav.md

@@ -0,0 +1,172 @@
+# Nav
+
+Componente contenedor de Navegación Material Design 3.
+
+`<moni-nav>` es el contenedor que envuelve los elementos `<moni-nav-item>` y
+controla el patrón de navegación M3: barra de navegación, riel de navegación o
+cajón de navegación.
+
+**Referencias a la especificación M3:**
+- Barra de navegación: `m3-docs/components/navigation-bar/specs.md`
+- Riel de navegación: `m3-docs/components/navigation-rail/specs.md`
+- Cajón de navegación: `m3-docs/components/navigation-drawer/specs.md`
+
+**Patrones de navegación:**
+- **Barra de navegación** (`placement="bottom"`) — Barra horizontal de elementos de icono+etiqueta
+  en la parte inferior de la pantalla. Ideal para 3–5 destinos de nivel superior.
+- **Riel de navegación** (`variant="rail"`) — Riel vertical de elementos de icono+etiqueta
+  en el lateral de la pantalla. Ideal para puntos de interrupción medianos/expandidos.
+- **Cajón estándar** (`variant="drawer"`) — Panel vertical siempre visible
+  con etiquetas de texto completo. Sin atenuación (scrim). Ideal para pantallas grandes.
+- **Cajón modal** (`variant="drawer" modal`) — Cajón superpuesto con atenuación (scrim).
+  Se abre/cierra a través de la propiedad `open`. Atrapa el foco del teclado mientras está abierto.
+  Se cierra al presionar la tecla `Escape`.
+
+**Manejo del teclado:**
+Cuando `modal=true`, el componente añade un listener global de `keydown` en
+`connectedCallback` que cierra el cajón con `Escape`. El listener se
+elimina en `disconnectedCallback`.
+
+- Tag: `moni-nav`
+- Clase: `MoniNav`
+- Fuente: `src/components/moni-nav.ts`
+
+## Cuándo usarlo
+
+Usa `moni-nav` 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
+<!-- Barra de navegación inferior -->
+<moni-nav placement="bottom">
+  <moni-nav-item icon="home" label="Inicio" active></moni-nav-item>
+  <moni-nav-item icon="search" label="Buscar"></moni-nav-item>
+  <moni-nav-item icon="person" label="Perfil"></moni-nav-item>
+</moni-nav>
+
+<!-- Cajón de navegación modal -->
+<moni-nav variant="drawer" modal open placement="left">
+  <h3 slot="header">Mi App</h3>
+  <moni-nav-item icon="home" label="Inicio" active></moni-nav-item>
+  <moni-nav-item icon="settings" label="Ajustes"></moni-nav-item>
+</moni-nav>
+```
+
+## 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-nav></moni-nav>
+</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-nav` 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.
+- Mantén el estado de apertura en una única fuente de verdad y devuelve el foco al disparador al cerrar.
+- 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 |
+|---|---|---|---|---|
+| `placement` | `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Selecciona el valor de `placement` entre las opciones documentadas. |
+| `variant` | `variant` | `'rail' \| 'drawer'` | `'rail'` | Selecciona la variante visual y su nivel de énfasis. |
+| `modal` | `modal` | `boolean` | `false` | Activa o desactiva el comportamiento `modal`. En HTML, la presencia del atributo significa `true`; omítelo para `false`. |
+| `open` | `open` | `boolean` | `true` | Controla si la superficie superpuesta está abierta. |
+| `layout` | `layout` | `'vertical' \| 'horizontal' \| 'auto'` | `'auto'` | Selecciona el valor de `layout` entre las opciones documentadas. |
+
+## Slots
+
+- `default`: Hijos `<moni-nav-item>`.
+- `header`: Contenido encima de los elementos de navegación (solo variante drawer).
+- `footer`: Contenido debajo de los elementos de navegación (solo variante drawer).
+
+## Eventos
+
+No declara eventos propios.
+
+## Métodos públicos
+
+No expone métodos públicos adicionales.
+
+## CSS Parts
+
+- `nav`: Parte interna personalizable.
+- `scrim`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--font`
+- `--on-surface`
+- `--scrim`
+- `--speed2`
+- `--speed3`
+- `--surface-container`
+
+## 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.
+
+### `placement`
+
+Selecciona el valor de `placement` entre las opciones documentadas.
+
+![moni-nav — placement=top](../assets/moni-nav/placement--top.png)
+
+![moni-nav — placement=bottom](../assets/moni-nav/placement--bottom.png)
+
+![moni-nav — placement=left](../assets/moni-nav/placement--left.png)
+
+![moni-nav — placement=right](../assets/moni-nav/placement--right.png)
+
+### `variant`
+
+Selecciona la variante visual y su nivel de énfasis.
+
+![moni-nav — variant=rail](../assets/moni-nav/variant--rail.png)
+
+![moni-nav — variant=drawer](../assets/moni-nav/variant--drawer.png)
+
+### `modal`
+
+Activa o desactiva el comportamiento `modal`. En HTML, la presencia del atributo significa `true`; omítelo para `false`.
+
+![moni-nav — modal=false](../assets/moni-nav/modal--false.png)
+
+![moni-nav — modal=true](../assets/moni-nav/modal--true.png)
+
+### `open`
+
+Controla si la superficie superpuesta está abierta.
+
+![moni-nav — open=false](../assets/moni-nav/open--false.png)
+
+![moni-nav — open=true](../assets/moni-nav/open--true.png)
+
+### `layout`
+
+Selecciona el valor de `layout` entre las opciones documentadas.
+
+![moni-nav — layout=vertical](../assets/moni-nav/layout--vertical.png)
+
+![moni-nav — layout=horizontal](../assets/moni-nav/layout--horizontal.png)
+
+![moni-nav — layout=auto](../assets/moni-nav/layout--auto.png)

package/docs/components/progress.md

@@ -0,0 +1,172 @@
+# Progress
+
+Material 3 Expressive progress indicator.
+
+- Tag: `moni-progress`
+- Clase: `MoniProgress`
+- Fuente: `src/components/moni-progress.ts`
+
+## Cuándo usarlo
+
+Usa `moni-progress` 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-progress></moni-progress>
+```
+
+## 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-progress label="Ejemplo"></moni-progress>
+</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-progress` 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.
+- 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 |
+|---|---|---|---|---|
+| `value` | `value` | `number` | `0` | Current progress value. |
+| `max` | `max` | `number` | `100` | Maximum progress value. |
+| `variant` | `variant` | `MoniProgressVariant` | `'linear'` | Visual indicator family. |
+| `size` | `size` | `MoniProgressSize` | `'medium'` | Current M3 size token. |
+| `indeterminate` | `indeterminate` | `boolean` | `false` | Shows the animated state used when progress cannot be measured. |
+| `mode` | `mode` | `MoniProgressMode` | `'determinate'` | Linear progress behavior. Buffer adds loaded and pending regions. |
+| `buffer-value` | `bufferValue` | `number` | `0` | Buffered progress value used when mode is buffer. |
+| `stop-indicator` | `stopIndicator` | `boolean` | `false` | Shows the optional 4px M3 stop indicator at the end of a linear track. |
+| `wave-transition` | `waveTransition` | `boolean` | `false` | Smoothly morphs wavy indicators to flat and back without changing progress. |
+| `aria-label` | `label` | `string` | `'Progress'` | Accessible name announced by assistive technology. |
+
+## 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
+
+- `buffer`: Parte interna personalizable.
+- `indicator`: Parte interna personalizable.
+- `progress`: Parte interna personalizable.
+- `stop-indicator`: Parte interna personalizable.
+- `svg`: Parte interna personalizable.
+- `track`: Parte interna personalizable.
+
+## CSS Custom Properties consumidas
+
+- `--_active-color`
+- `--_active-end`
+- `--_buffer-end`
+- `--_buffer-gap-start`
+- `--_buffer-start`
+- `--_circular-size`
+- `--_gap`
+- `--_linear-height`
+- `--_stop`
+- `--_thickness`
+- `--_track-color`
+- `--active`
+- `--moni-progress-active`
+- `--moni-progress-track`
+- `--primary`
+- `--secondary-container`
+
+## 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.
+
+### `value`
+
+Current progress value.
+
+![moni-progress — value=default](../assets/moni-progress/value--default.png)
+
+### `max`
+
+Maximum progress value.
+
+![moni-progress — max=default](../assets/moni-progress/max--default.png)
+
+### `variant`
+
+Visual indicator family.
+
+![moni-progress — variant=default](../assets/moni-progress/variant--default.png)
+
+### `size`
+
+Current M3 size token.
+
+![moni-progress — size=default](../assets/moni-progress/size--default.png)
+
+### `indeterminate`
+
+Shows the animated state used when progress cannot be measured.
+
+![moni-progress — indeterminate=false](../assets/moni-progress/indeterminate--false.png)
+
+![moni-progress — indeterminate=true](../assets/moni-progress/indeterminate--true.png)
+
+### `mode`
+
+Linear progress behavior. Buffer adds loaded and pending regions.
+
+![moni-progress — mode=default](../assets/moni-progress/mode--default.png)
+
+### `buffer-value`
+
+Buffered progress value used when mode is buffer.
+
+![moni-progress — buffer-value=default](../assets/moni-progress/bufferValue--default.png)
+
+### `stop-indicator`
+
+Shows the optional 4px M3 stop indicator at the end of a linear track.
+
+![moni-progress — stop-indicator=false](../assets/moni-progress/stopIndicator--false.png)
+
+![moni-progress — stop-indicator=true](../assets/moni-progress/stopIndicator--true.png)
+
+### `wave-transition`
+
+Smoothly morphs wavy indicators to flat and back without changing progress.
+
+![moni-progress — wave-transition=false](../assets/moni-progress/waveTransition--false.png)
+
+![moni-progress — wave-transition=true](../assets/moni-progress/waveTransition--true.png)
+
+### `aria-label`
+
+Accessible name announced by assistive technology.
+
+![moni-progress — aria-label=default](../assets/moni-progress/label--default.png)