@ajuarezso/sui-design-system 0.18.10 → 0.20.0

package/docs/INDEX.md

@@ -0,0 +1,136 @@
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+# SUI Design System — componentes
+
+Una fila por componente: qué es y qué usar en su lugar cuando no calza. Para elegir,
+se lee esta lista; para usar uno, se abre su doc:
+
+- en el paquete npm: `node_modules/@ajuarezso/sui-design-system/docs/<name>/README.md`
+- en Storybook: `<storybook>/<name sin sui->.md` (ej. `/alert.md`) y la lista en `/index.md`
+- en el repo: `projects/sui-design-system/src/lib/<name>/README.md`
+
+Documentados: 42 de 116.
+
+| name | resumen | alternativas |
+|---|---|---|
+| `sui-alert` | Aviso que se queda en la pantalla, en el lugar donde pasa lo que avisa | sui-toast (efímero, resultado de una acción) · sui-banner (afecta a toda la app o la pantalla) · sui-notification (fila de la bandeja) · sui-form-hint (ayuda de un solo campo) |
+| `sui-app-store-badge` | El sello oficial de App Store o Google Play que lleva a descargar la app | sui-link-button (link directo de descarga, «Descargar la app») · sui-social-button (entrar con una cuenta de Google o Apple) |
+| `sui-avatar` | La cara de alguien (o el logo de un local) en un círculo, con iniciales cuando no hay foto | sui-avatar-group (varias personas apiladas) · sui-compact-avatar-group (varias personas en una celda de tabla) · sui-key-icon (un ícono en círculo que no es nadie) · sui-image-upload-profile (subir o cambiar la foto) |
+| `sui-avatar-group` | Varias personas apiladas en una fila, con «+N» cuando no entran todas | sui-compact-avatar-group (la versión en píldora, para celdas de tabla) · sui-avatar (una sola persona) |
+| `sui-badge` | Etiqueta corta o número que clasifica algo sin competir con el contenido | sui-status-badge (estado de ciclo: completado, pendiente, fallido, deshabilitado) · sui-tag (chip que se puede quitar) · sui-alert (mensaje que tiene que envolver) |
+| `sui-brand-logo` | El logo oficial de otra marca (WhatsApp, Google, Apple, Instagram…) en su color, sin tocarlo | sui-icon (el mismo logo como ícono monocromo de una línea) · sui-logo (el logo de Master Pedidos) · sui-social-button (botón de entrar con Google o Apple) |
+| `sui-button` | Botón base para que la persona dispare una acción | sui-link-button (acción que se lee como texto) · sui-compact-button (ícono de 20-28 px en filas y barras) · sui-fancy-button (el CTA héroe) · sui-social-button (entrar con Google/Apple) · sui-button-group (opciones que se ven como un solo control) |
+| `sui-button-group` | Opciones pegadas en una fila que se prenden y se apagan, varias a la vez | sui-segmented-control (cambiar de vista o elegir una sola opción) · sui-checkbox (opciones que se suman dentro de un formulario largo) · sui-tab-chips (filtros en chips que se pueden desplazar) |
+| `sui-button-group-item` | Cada opción de un sui-button-group; no se usa suelto | sui-button-group (el grupo, que ya pinta sus ítems desde items[]) · sui-segmented-control (elegir una sola opción) · sui-switch (prender o apagar algo suelto) |
+| `sui-checkbox` | La casilla sola para marcar una o varias opciones, sin texto propio | sui-checkbox-label (casilla con su texto, el caso normal) · sui-checkbox-card (cada opción es una tarjeta) · sui-switch (prende algo que se aplica al instante) · sui-radio (opciones excluyentes) |
+| `sui-checkbox-label` | Casilla con su texto (y opcionalmente descripción, badge y link) para opciones que se suman | sui-checkbox (la casilla sola, el texto vive en otra parte) · sui-checkbox-card (cada opción es una tarjeta) · sui-switch-label (se aplica al instante) · sui-radio-label (una sola opción) |
+| `sui-circular-progress-bar` | El avance de algo en un anillo, para cuando cabe en un cuadrado al lado de un título | sui-progress-bar-label (barra con título y número, cuando hay ancho) · sui-progress-bar (barra pelada) |
+| `sui-color-dot` | Una opción de color para elegir (o mostrar el color elegido); no es un punto de estado | sui-color-picker (el selector completo, con hex propio) · sui-badge type="with-dot" (punto de estado vivo) · sui-status-badge withDot (punto de estado de un ciclo) |
+| `sui-color-picker` | Botón que abre un panel para elegir un color libre (espectro, matiz, hex) o uno de los recomendados | sui-color-dot (un punto de color, para armar una grilla propia) · sui-select o sui-radio-card (el color es una categoría con nombre, no un color libre) |
+| `sui-compact-avatar-group` | Varias personas en una píldora baja con el «+N» en texto, para tablas y filas apretadas | sui-avatar-group (la pila grande, para cards y cabeceras) · sui-avatar (una sola persona) |
+| `sui-compact-button` | Botón de solo ícono, chico, para cuando falta espacio | sui-button (acción con texto, o de ícono con onlyIcon en tamaños de 28 a 52) · sui-link-button (acción que se lee como texto) · sui-topbar-button (ícono de la barra superior) |
+| `sui-content-divider` | Línea con algo encima: el «o» entre dos opciones, la cabecera de un grupo o un botón entre bloques | sui-divider (la línea sola, horizontal o vertical) |
+| `sui-divider` | Línea de 1 px que separa bloques (horizontal) o datos en una fila (vertical) | sui-content-divider (línea con texto o botones encima, o el «o» entre dos opciones) |
+| `sui-emoji` | Un emoji 3D animado (Fluent) para los momentos con emoción: estados vacíos, celebraciones, onboarding | sui-icon (ícono funcional, monocromo) · sui-empty-state (el estado vacío completo, que ya trae su emoji) |
+| `sui-fancy-button` | Botón con brillo y degradé para el CTA de una landing o campaña | sui-button (toda acción dentro de la app) · sui-app-store-badge (descargar la app desde una landing) |
+| `sui-file-icon` | El ícono de un archivo con su extensión (PDF, XLSX, JPG…) en el color de su tipo | sui-file-upload-card (el archivo que se está subiendo, con progreso) · sui-icon (un ícono genérico de documento) |
+| `sui-flag` | La bandera circular de un país | sui-emoji (un emoji con emoción) · sui-icon (un ícono funcional) |
+| `sui-form-hint` | Una línea de ayuda o de error debajo de un campo o de un grupo de controles | el hint propio de sui-input / sui-select / sui-textarea (campo de texto) · sui-alert (un aviso de la pantalla o algo que salió bien) · sui-tooltip (ayuda escondida tras un toque) · sui-form-label (el rótulo de arriba) |
+| `sui-form-label` | Rótulo de un campo o de un grupo de controles que no traen el suyo (asterisco, opcional, ayuda y link) | el label propio de sui-input / sui-select / sui-textarea (campo de texto) · sui-checkbox-label / sui-radio-label / sui-switch-label (un control con su texto) · sui-page-header o sui-content-label (título de sección) · sui-form-hint (la ayuda debajo) |
+| `sui-icon` | Un ícono monocromo de RemixIcon (o uno propio del DS) que toma el color del texto | sui-key-icon (el ícono dentro de un círculo de color) · sui-emoji (emoji con emoción) · sui-brand-logo (el logo de otra marca en su color) · sui-compact-button (un ícono que se toca) |
+| `sui-kbd` | Una tecla dibujada para mostrar un atajo de teclado (⌘K, Esc, ↑ ↓) | sui-badge (una etiqueta corta que no es una tecla) · sui-tag (un chip) |
+| `sui-key-icon` | Un ícono dentro de un círculo, con fondo de color si el ícono dice un estado | sui-icon (el ícono suelto) · sui-avatar (cuando es una persona o un local) · sui-payment-icon (el círculo ya armado para un pago de servicio) |
+| `sui-link-button` | Acción que se lee como texto, sin caja | sui-button (acción con caja: la principal o la secundaria de un grupo) · sui-compact-button (solo ícono, sin texto) · sui-alert (sus acciones se pasan en actions[] y ya salen como link) |
+| `sui-logo` | El logo de Master Pedidos (la M y la palabra), dibujado en SVG y coloreable | sui-brand-logo (logos de OTRAS marcas: WhatsApp, Google, Apple…) · sui-avatar (el logo de un local, que es una foto) |
+| `sui-payment-icon` | El círculo de color de un pago de servicio (agua, gas, luz, internet, alquiler…) | sui-key-icon (cualquier otro ícono en círculo) · sui-brand-logo (el logo de un medio de pago con marca) |
+| `sui-progress-bar` | Barra que muestra cuánto falta para completar algo, pintada con el estado de lo que mide | sui-progress-bar-label (la misma barra con título, número y descripción) · sui-circular-progress-bar (el avance en un círculo, junto a un título) · un gráfico (repartir un total entre partes) |
+| `sui-progress-bar-label` | La barra de progreso con lo que mide, cuánto va y, si hace falta, qué hacer | sui-progress-bar (la barra pelada, cuando otra cosa ya la rotula) · sui-circular-progress-bar (el avance en un círculo, junto a un título) |
+| `sui-radio` | El círculo solo para elegir una opción de una lista corta, sin texto propio | sui-radio-label (círculo con su texto, lista densa) · sui-radio-card (opción con peso o que se toca en el teléfono) · sui-select (más de 6 opciones) · sui-segmented-control (2-4 modos que se aplican al instante) · sui-checkbox (varias a la vez) |
+| `sui-radio-label` | Círculo con su texto (y opcionalmente descripción, badge y link) para elegir una opción de una lista corta | sui-radio (el círculo solo) · sui-radio-card (cada opción es una tarjeta) · sui-select (más de 6 opciones) · sui-checkbox-label (varias a la vez) |
+| `sui-rating` | Muestra una nota con estrellas o la pide (estrellas, emojis, corazones o números) | sui-icon (una estrella o un corazón sueltos, sin nota) · sui-badge (la nota escrita como dato corto) |
+| `sui-segmented-control` | Píldora de 2 a 4 opciones hermanas donde se elige una y se aplica en el momento | sui-tab-menu-horizontal (navegar entre secciones de contenido) · sui-tab-chips (fila de filtros con muchas opciones) · sui-radio-card (elegir una opción de un formulario que se guarda después) · sui-button-group (varias opciones a la vez) |
+| `sui-slider` | Barra para elegir un valor, o un rango, dentro de una escala donde importa ver la posición | sui-counter-input (cantidad chica y exacta con − y +) · sui-input type="number" (valor exacto o rango abierto) · sui-progress-bar (avance de solo lectura) |
+| `sui-social-button` | Botón para iniciar sesión o registrarse con una cuenta de Google o Apple | sui-button (cualquier otra acción, aunque mencione una marca) · sui-app-store-badge (descargar la app de una tienda) |
+| `sui-status-badge` | El resultado de un ciclo (completado, pendiente, fallido, deshabilitado) con su color y su ícono ya resueltos | sui-badge (estado con muchos valores, categoría o distinción) · sui-tag (chip neutro que se puede quitar) · sui-alert (mensaje que hay que leer) |
+| `sui-switch` | Interruptor solo para prender o apagar algo que se aplica al instante, sin texto propio | sui-switch-label (interruptor con su texto, el caso normal) · sui-switch-card (cada ajuste es una tarjeta) · sui-integration-switch (fila de integración con logo) · sui-checkbox (valor que se confirma después con un botón) |
+| `sui-switch-label` | Interruptor con su texto (y opcionalmente descripción, badge y link) para un ajuste que se aplica al instante | sui-switch (el interruptor solo, el texto vive en otra parte) · sui-switch-card (cada ajuste es una tarjeta) · sui-integration-switch (fila de integración con logo) · sui-checkbox-label (se confirma después) |
+| `sui-tag` | Chip neutro que nombra algo elegido o aplicado y que la persona puede quitar | sui-badge (etiqueta de solo lectura, con color y significado) · sui-status-badge (resultado de un ciclo) · sui-tab-chips / sui-filter (chips para elegir) · sui-tag-input (campo que junta tags) |
+
+## Sin documentar
+
+Existen en el paquete pero todavía no tienen doc; antes de usarlos, leer su `.d.ts`.
+
+- `sui-accordion`
+- `sui-activity-feed`
+- `sui-activity-filter`
+- `sui-banner`
+- `sui-breadcrumb-item`
+- `sui-breadcrumbs`
+- `sui-card`
+- `sui-chart-legend`
+- `sui-chart-legend-dot`
+- `sui-checkbox-card`
+- `sui-command-menu-footer`
+- `sui-command-menu-item`
+- `sui-command-menu-search`
+- `sui-compact-select`
+- `sui-compact-select-for-input`
+- `sui-content-card`
+- `sui-content-label`
+- `sui-counter-input`
+- `sui-date-selector`
+- `sui-datepicker`
+- `sui-day-cell`
+- `sui-day-label`
+- `sui-drawer-footer`
+- `sui-drawer-header`
+- `sui-dropdown-caption`
+- `sui-dropdown-item`
+- `sui-dropdown-menu`
+- `sui-dropdown-search`
+- `sui-empty-state`
+- `sui-file-upload`
+- `sui-file-upload-card`
+- `sui-filter`
+- `sui-href`
+- `sui-image-upload`
+- `sui-image-upload-profile`
+- `sui-img-retry`
+- `sui-inline-input`
+- `sui-inline-select`
+- `sui-input`
+- `sui-integration-switch`
+- `sui-modal`
+- `sui-modal-footer`
+- `sui-modal-header`
+- `sui-modal-sheet`
+- `sui-notification`
+- `sui-notification-footer`
+- `sui-notification-tab-menu`
+- `sui-otp-input`
+- `sui-page-header`
+- `sui-pagination`
+- `sui-password-strength`
+- `sui-period-range`
+- `sui-popover`
+- `sui-product-card`
+- `sui-radio-card`
+- `sui-rich-editor`
+- `sui-select`
+- `sui-sidebar`
+- `sui-stepper`
+- `sui-store-card`
+- `sui-switch-card`
+- `sui-tab-chips`
+- `sui-tab-menu-horizontal`
+- `sui-tab-menu-vertical`
+- `sui-table`
+- `sui-tag-input`
+- `sui-textarea`
+- `sui-time-picker`
+- `sui-toast`
+- `sui-tooltip`
+- `sui-topbar`
+- `sui-topbar-button`
+- `sui-topbar-item`
+- `sui-topbar-user`

package/docs/sui-alert/README.md

@@ -0,0 +1,216 @@
+---
+name: sui-alert
+selector: sui-alert
+resumen: Aviso que se queda en la pantalla, en el lugar donde pasa lo que avisa
+alternativas: [sui-toast (efímero, resultado de una acción), sui-banner (afecta a toda la app o la pantalla), sui-notification (fila de la bandeja), sui-form-hint (ayuda de un solo campo)]
+---
+
+# sui-alert
+
+Story: [Molecules/Feedback/Alert](https://sui-design-system.web.app/?path=/docs/molecules-feedback-alert--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando la persona tiene que leer algo **ahí mismo, junto a lo que está haciendo**,
+y el mensaje tiene que seguir visible hasta que cambie la situación: un error que impide
+seguir, una advertencia antes de confirmar, una explicación de cómo funciona una sección,
+el motivo por el que se canceló un pedido.
+
+**No lo uses** para:
+
+- Confirmar que una acción salió bien («Producto guardado»): eso es `sui-toast`. Un alert que
+  hay que cerrar a mano para decir «guardado» estorba.
+- Algo que afecta a toda la app (sin conexión, modo demo, versión nueva): `sui-banner`.
+- La ayuda de un solo campo de formulario: `sui-form-hint`.
+- Decorar. Lleva `role="alert"`: el lector de pantalla lo anuncia apenas aparece.
+
+Regla corta: **contexto → alert · toda la app → banner · efímero → toast · bandeja → notification.**
+
+## Qué variante usar
+
+El alert tiene **dos ejes** y se eligen por separado: `variant` dice **qué tipo de mensaje es**
+(el color y el ícono) y `variantStyle` dice **cuánto peso visual tiene** (el relleno).
+
+> **La guía del DS no dice cuándo usar cada relleno ni cada tipo.** Su página del alert muestra
+> las combinaciones, la API y un ejemplo por tamaño, pero no trae do/don't ni jerarquía. Por eso
+> casi todo lo de abajo sigue siendo **canon (aprobado por el dueño, 03-10-2026)**. Solo lo marcado
+> «según la guía del DS» sale de ahí (de su texto o de sus ejemplos publicados).
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 117 alerts, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `master-rutina`,
+> `master-medico`, `dev-index`) ni las copias locales de `components/sui/`.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: aparece entre campos o pegado al elemento importante, para algo crítico. Su
+  ejemplo es el de la contraseña incorrecta al iniciar sesión. Coincide con «contexto → alert».
+- **Hermanos**: el banner es para avisos cruciales **arriba de la pantalla**; el toast, para
+  feedback **breve** que se puede apilar; la notification, para avisos **temporales en una
+  esquina** (un pago, una actualización); el hint, para ayuda **debajo de un campo**.
+- **Composición por tamaño**: `xsmall`/`small` = **una línea**: título y como mucho una acción a
+  la derecha, sin descripción. `large` = título + **descripción (idealmente dos líneas)** +
+  hasta **dos acciones** separadas por punto medio.
+- **Las acciones son links, no botones**: en todos sus ejemplos la acción es un link que toma el
+  color del texto del alert, y **solo la primera va subrayada**. En SUI eso es `actions[]` (que
+  dibuja `sui-link-button`), con `underline: true` en la primera.
+- **Defaults**: la guía arranca en relleno `filled` y tamaño `small`; SUI arranca en `lighter` y
+  `large`. Es un default, no una recomendación de uso.
+
+### `variantStyle` — el peso visual (lo que más se confunde)
+
+Hoy cada tipo de mensaje se reparte casi mitad y mitad: 59 `filled`, 54 `lighter`, 2 `stroke` y
+2 que cambian según el caso. No hay criterio, y la guía tampoco lo da. La regla propuesta sale
+de la jerarquía: `filled` es un bloque de color saturado con texto blanco y compite con el
+botón principal; `lighter` es un fondo pálido con texto oscuro y acompaña sin taparlo.
+
+| variantStyle | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `lighter` (default SUI) | El aviso **acompaña** al contenido: explica, da contexto, advierte sin frenar. También los errores de formulario que se corrigen ahí mismo. Es el caso normal. | `pages/orders/orders.html:281` («Recojo en tienda») · `pages/auth/login/login.html:31` (error de login) | canon (aprobado por el dueño, 03-10-2026) |
+| `filled` (default de la guía) | El aviso **es lo principal del momento** y hay que leerlo antes de actuar: la persona no puede seguir, va a hacer algo que no se deshace, o el resultado es final (cancelado, rechazado). Uno por pantalla como máximo. | `pages/mi-negocio/mi-negocio.html:1242` («Se eliminará permanentemente») · `pages/customer/order-tracking/order-tracking.html:194` («Pedido cancelado») | canon (aprobado por el dueño, 03-10-2026) |
+| `light` | No usar hoy: queda a medio camino entre los dos de arriba (0 usos). **Cuándo sí:** un aviso dentro de una superficie ya teñida (un banner de color) donde `lighter` se pierde. | — | canon (aprobado por el dueño, 03-10-2026) |
+| `stroke` | Solo sobre una **superficie flotante** o encima de un mapa o una foto, donde un fondo pálido no se lee. | (sin uso correcto hoy) | canon (aprobado por el dueño, 03-10-2026) |
+| `stroke-dark` | Igual que `stroke`, en oscuro. Default del toast. Extensión de SUI: la guía no lo tiene. | `sui-toast/sui-toast.service.ts:92` del DS | canon (aprobado por el dueño, 03-10-2026) |
+
+**Usos de hoy que romperían la propuesta:**
+
+- **24 `filled` que solo informan → `lighter`.** Los 22 `info filled` y los 5 `success filled`,
+  menos los 3 que sí frenan (`pages/promociones/promociones.html:106` «No disponible en tu plan»,
+  `pages/drivers/add-driver/add-driver.html:21`, `pages/super-admin/master-orders/master-orders.html:714`
+  «Ningún repartidor disponible»). Ejemplos: `pages/driver/driver-earnings/driver-earnings.html:18`
+  («Cobras por cada entrega»), `pages/driver/driver-wallet/driver-wallet.html:12`,
+  `pages/customer/store-browser/store-browser.html:573` («Tu local fue aprobado»).
+- **5 `warning filled` que no frenan nada → `lighter`:** `pages/super-admin/master-roles/master-roles.html:6`,
+  `pages/driver/driver-schedule/driver-schedule.html:12` y `:40`, `pages/customer/favorites/favorites.html:100`,
+  `pages/customer/order-tracking/order-tracking.html:314` («Esperando que el local confirme»).
+- **4 errores de carga en `lighter` → `filled`** (la pantalla queda vacía; el aviso es lo único
+  que hay): `pages/envios/envios.html:11`, `pages/super-admin/master-drivers/master-drivers.html:697`,
+  `pages/super-admin/master-roles/master-roles.html:79`, `pages/super-admin/master-approvals/master-approvals.html:17`.
+  El mismo caso ya está en `filled` en `pages/super-admin/master-orders/master-orders.html:347`.
+- **2 `stroke` inline sobre fondo blanco → `lighter`:** `pages/role-selector/role-selector.html:52`,
+  `pages/driver/driver-order-detail/driver-order-detail.html:360`.
+
+La pregunta para decidir es una: **¿este aviso tiene que ganarle al botón principal?** Si no, `lighter`.
+
+### `variant` — qué tipo de mensaje es
+
+La guía lista los cinco tipos pero no dice cuándo va cada uno.
+
+| variant | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `info` (default) | Un dato que conviene saber. No pide hacer nada. | `pages/orders/orders.html:281` | canon (aprobado por el dueño, 03-10-2026) |
+| `success` | Un resultado bueno que se queda (aprobado, verificado, enviado). Si es la confirmación de un clic, es toast. | `components/transfer-tenant-modal/transfer-tenant-modal.html:16` («Cuenta verificada») | canon (aprobado por el dueño, 03-10-2026) |
+| `warning` | Hay que atender algo o va a tener una consecuencia. | `pages/driver/driver-order-detail/driver-order-detail.html:856` («Se te cobran S/ 0.50») | canon (aprobado por el dueño, 03-10-2026) |
+| `error` | Algo falló o no se puede hacer. Su ejemplo de uso (contraseña incorrecta) es de este tipo. | `pages/auth/login/login.html:31` | canon (aprobado por el dueño, 03-10-2026) (el ejemplo sí es de la guía) |
+| `feature` | Novedad o función en prueba. Solo eso. El color sale del estado «feature» de la paleta. | `pages/customer/viaje/viaje.html:81` («Viajes está en prueba») | canon (aprobado por el dueño, 03-10-2026) |
+
+**Usos de hoy que romperían la propuesta:** 3 alerts `feature` muestran la **nota que dejó el
+cliente**, que no es una novedad: `pages/envios/envios.html:725`,
+`pages/driver/driver-order-detail/driver-order-detail.html:177`,
+`pages/customer/order-tracking/order-tracking.html:551`. Pasarían a `info`.
+
+### `size` y acciones
+
+| size | cuándo | fuente |
+|---|---|---|
+| `large` (default SUI) | Siempre que haya **descripción**: título + descripción de hasta dos líneas + hasta dos acciones. | según la guía del DS |
+| `small` / `xsmall` | Un aviso de **una línea**: título y como mucho una acción, sin descripción. `small` es el default de la guía. | según la guía del DS |
+| `xlarge` | Extensión de SUI (la guía no lo tiene). Sin uso hoy. | canon (aprobado por el dueño, 03-10-2026) |
+
+| acciones | regla | fuente |
+|---|---|---|
+| tipo | Links por `actions[]`, nunca un `sui-button` proyectado en el slot. | según la guía del DS |
+| cuántas | Hasta dos, separadas por punto medio. | según la guía del DS |
+| subrayado | Solo la primera, con `underline: true`. | según la guía del DS |
+
+**Usos de hoy que rompen la guía:**
+
+- **3 alerts con descripción en `small` → `large`.** El componente hace lo que dice la guía
+  (en `small` no hay descripción), así que no es un bug del componente: es un error de uso, y la
+  descripción hoy **no se ve**. `pages/customer/checkout/checkout.html:417` (la descripción del
+  cupón), `pages/super-admin/master-settings/master-settings.html:633` y `:680`.
+- **5 alerts con un `sui-button` en el slot `action` → `actions[]`:** `pages/role-selector/role-selector.html:52`,
+  `pages/overview/overview.html:34`, `pages/mi-negocio/mi-negocio.html:376`,
+  `pages/customer/cart/cart.html:29`, `pages/customer/viaje/viaje.html:86` (este último es un
+  `filled primary` dentro del alert: el CTA de la pantalla no debería vivir ahí).
+- **2 acciones únicas sin subrayar → `underline: true`:** `pages/notifications/notifications.ts:197`
+  y `:198` (`accionActivar`, `accionReintentar`, usadas en `notifications.html:17` y `:23`).
+- Más de dos acciones: 0.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `variant` | `'info' \| 'success' \| 'warning' \| 'error' \| 'feature'` | `'info'` |
+| `variantStyle` | `'filled' \| 'light' \| 'lighter' \| 'stroke' \| 'stroke-dark'` | `'lighter'` |
+| `size` | `'xsmall' \| 'small' \| 'large' \| 'xlarge'` | `'large'` |
+| `title` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `showIcon` | `boolean` | `true` |
+| `dismissible` | `boolean` | `false` |
+| `autoHideOnDismiss` | `boolean` | `true` |
+| `actions` | `readonly SuiAlertAction[]` | `[]` |
+
+| output | payload |
+|---|---|
+| `closed` | `void` |
+<!-- api:fin -->
+
+`description` se pinta con `innerHTML`: acepta HTML y no se escapa.
+
+Signal pública: `dismissed` (`signal(false)`).
+
+```ts
+interface SuiAlertAction {
+  label: string;
+  onClick?: () => void;
+  underline?: boolean;   // canon: solo la primera en true
+  href?: string;         // con href se dibuja <a>; sin href, <button>
+  target?: '_blank' | '_self' | '_parent' | '_top';
+  color?: string;        // pisa el color automático
+}
+```
+
+Slot: `<ng-content select="[slot=action]">` — legado; solo se usa si `actions` está vacío y en
+`large`/`xlarge`.
+
+## Trampas
+
+- **Los nombres están cruzados respecto al Figma de origen.** Allá «Style» es el relleno y
+  «Status» el tipo; aquí el relleno es `variantStyle` y el tipo es `variant`. Y en `sui-badge`,
+  `variant` es el **relleno**: misma palabra, otro eje.
+- La prop de relleno se llama `variantStyle` en alert, banner, compact-button y social-button;
+  `appearance` en status-badge; `tagStyle` en tag.
+- **Defaults distintos entre hermanos:** alert arranca en `lighter`, banner en `stroke`, toast en
+  `stroke-dark`. La guía del DS arranca el alert en `filled` y `small`; SUI, en `lighter` y `large`.
+- `small`/`xsmall` **descartan la descripción** sin avisar, y la acción pasa a dibujarse en la
+  misma línea, a la derecha. Es lo que define la guía del DS para esos tamaños: si hay
+  descripción, va `large`.
+- `description` va por `innerHTML`: no le pases texto escrito por el usuario sin sanear.
+- Las acciones toman el **color del texto** del alert (blanco en `filled`, casi negro en el
+  resto), no el color del tipo. Para forzar otro, `color` en la acción.
+- `feature` es **morado** aquí y **gris** en `sui-banner` (decisión documentada en los dos `.ts`).
+- Con `autoHideOnDismiss` en `true` (default) el alert se oculta solo al tocar la X. Si el padre
+  necesita animar la salida antes de quitarlo, pásalo en `false` y escucha `(closed)`.
+- El slot de acción usa `slot=`; los de badge y button usan `data-slot=`.
+- El host borra el atributo `title` nativo (no aparece el tooltip gris del navegador).
+
+## Ejemplo
+
+```html
+<!-- Aviso que acompaña: lighter (default) -->
+<sui-alert
+  variant="warning"
+  title="Tu local todavía no está en el mapa"
+  description="Marca la ubicación en Mi negocio: sin ella no podemos calcular la distancia." />
+
+<!-- Aviso que frena: filled, con acción -->
+<sui-alert
+  variant="error"
+  variantStyle="filled"
+  title="Se eliminará permanentemente"
+  description="Todos los productos, historial de pedidos y horarios."
+  [actions]="[{ label: 'Ver qué se borra', underline: true, onClick: verDetalle }]" />
+```

package/docs/sui-app-store-badge/README.md

@@ -0,0 +1,137 @@
+---
+name: sui-app-store-badge
+selector: sui-app-store-badge
+resumen: El sello oficial de App Store o Google Play que lleva a descargar la app
+alternativas: [sui-link-button (link directo de descarga, «Descargar la app»), sui-social-button (entrar con una cuenta de Google o Apple)]
+---
+
+# sui-app-store-badge
+
+Story: [Atoms/App Store Badge](https://sui-design-system.web.app/?path=/docs/atoms-app-store-badge--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** donde se invita a descargar la app: las landings (`/clientes`, `/empresas`,
+`/repartidores`), su footer y piezas de «Descarga la app». Siempre los dos juntos, App Store y
+Google Play, en ese orden.
+
+**No lo uses** para:
+
+- **Dentro de la app** (la persona ya la tiene instalada).
+- **Un link de descarga directa** sin tienda: `sui-link-button` `primary` con
+  `leftIcon="download-2-line"`, como hacen las landings debajo de los sellos.
+- **Entrar con una cuenta de Google o Apple**: `sui-social-button`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente.** Todo lo de abajo es **canon (aprobado
+> por el dueño, 03-10-2026)** o propuesta. Los sellos son los oficiales de cada tienda (cada una
+> pide usar el suyo tal cual, sin recolorear ni tocar el logo).
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 10 sellos en 4 archivos, sin contar
+> prototipos ni vitrinas. 5 `app-store` y 5 `google-play`; 8 `preferred`, 2 `alternative`. Todos
+> con `href`, `target="_blank"` y `ariaLabel`.
+
+### `company`
+
+| company | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `app-store` | Landings y «Descarga la app». Va primero. | `pages/public/landing-customers/landing-customers.html:26` | canon (aprobado por el dueño, 03-10-2026) |
+| `google-play` | Siempre al lado del de App Store. | `pages/public/landing-customers/landing-customers.html:32` | canon (aprobado por el dueño, 03-10-2026) |
+| `huawei-appgallery`, `galaxy-store` | No: la app no está publicada ahí. | — | no usar · canon (aprobado por el dueño, 03-10-2026) |
+| `mac-app-store`, `amazon-appstore`, `f-droid`, `microsoft-store` | No: la app no está publicada ahí. | — | no usar · canon (aprobado por el dueño, 03-10-2026) |
+
+### `appearance`
+
+| appearance | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `preferred` (default) | Lo normal: el sello negro, que es el oficial de cada tienda. | `pages/public/landing-driver/landing-driver.html:24` | canon (aprobado por el dueño, 03-10-2026) |
+| `alternative` | Solo sobre un fondo oscuro o de color, donde el negro se pierde o pesa. | `components/landing-footer/landing-footer.html:16` y `:19` (footer de las landings, sobre el naranja de marca) | no usar salvo ese caso · canon (aprobado por el dueño, 03-10-2026) |
+
+**Usos de hoy que rompen la regla: 0.** Los 2 `alternative` del footer de las landings están sobre
+`--sui-primary-base` (`components/landing-footer/landing-footer.scss:5`): caen justo en el «cuándo sí».
+
+### `height`, `href`, `target`, `ariaLabel`, `disabled`
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `height` (40, default) | 40 en desktop y en el footer. El ancho sale solo de la proporción de cada sello. | propuesta |
+| `height` 48 | En el hero de una landing en mobile, si los sellos son el CTA principal. Los dos sellos siempre a la misma altura. | propuesta |
+| `href` | Siempre: el link de la ficha de la tienda (`apps.apple.com/pe/app/master-pedidos/…`, `play.google.com/store/apps/details?id=com.masterpedidos.app`). Sin `href` el sello no es un link. | canon (todos los usos de hoy) |
+| `target="_blank"` | Siempre que hay `href`: el `rel="noopener"` se aplica solo en ese caso. | propuesta |
+| `ariaLabel` | Siempre, en español: «Descargar Master Pedidos en App Store». Sin él, el texto alternativo sale en inglés («Download on the App Store»). | propuesta |
+| `disabled` | Sin caso: si la app no está en una tienda, no se muestra su sello. | propuesta |
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: el área táctil tiene que medir **44 px o más**. En web, con mouse,
+va un tamaño más chico. La app ya lo resuelve con `BreakpointsService`
+(`src/app/services/breakpoints.service.ts`, mobile = hasta 767 px):
+`[size]="bp.isMobile() ? 'large' : 'small'"`, 27 usos hoy en `master-pedidos` (16 `large`/`small`,
+9 `large`/`medium`, 2 `medium`/`xsmall`). Regla del dueño, 03-10-2026.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| hero de una landing, cuando los sellos son el CTA | `[height]="48"` | `[height]="40"` | propuesta |
+| footer de las landings, «Descarga la app» | `[height]="44"` | `[height]="40"` (default) | propuesta |
+
+```html
+<sui-app-store-badge company="app-store" [height]="bp.isMobile() ? 48 : 40" href="…" target="_blank"
+                     ariaLabel="Descargar Master Pedidos en App Store" />
+```
+
+Los dos sellos siempre a la misma altura. Hoy los 10 usan la altura default (40) también en mobile:
+quedan 4 px por debajo de los 44.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo cae
+en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `appearance="alternative"` | el `preferred` es el oficial de cada tienda | landings o piezas sobre fondo oscuro o de color (ya es el caso del footer de las landings) |
+| otras tiendas (`huawei-appgallery`, `galaxy-store`, `mac-app-store`, `amazon-appstore`, `f-droid`, `microsoft-store`) | la app no está publicada ahí | si se publica en Huawei AppGallery (teléfonos Huawei sin Google) o Galaxy Store |
+| `disabled` | un sello deshabilitado no se entiende | no se ve un caso |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `company` | `'app-store' \| 'mac-app-store' \| 'amazon-appstore' \| 'galaxy-store' \| 'huawei-appgallery' \| 'f-droid' \| 'google-play' \| 'microsoft-store'` | — (requerido) |
+| `appearance` | `'preferred' \| 'alternative'` | `'preferred'` |
+| `href` | `string \| null` | `null` |
+| `target` | `string \| null` | `null` |
+| `rel` | `string \| null` | `'noopener'` |
+| `height` | `number` | `40` |
+| `disabled` | `boolean` | `false` |
+| `ariaLabel` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **Los sellos están en inglés** («Download on the App Store», «Get it on Google Play»): son los
+  SVG oficiales y no se traducen. Lo que sí va en español es el `ariaLabel`.
+- **Sin `href` no hay link**: el componente pinta solo la imagen, sin foco ni clic.
+- **No tiene output**: es un link, no un botón. Para medir clics, escucha `(click)` en el host.
+- Los SVG se sirven desde `/assets/brand/store-badges/<company>-<appearance>.svg`: la app tiene que
+  tener esos archivos en sus assets (`master-pedidos` los tiene copiados en
+  `src/assets/brand/store-badges/`). Si falta uno, el sello sale como imagen rota.
+- `height` escala el sello entero; no le pongas `width` desde afuera o se deforma.
+- El hover baja la opacidad a 0.85, como recomienda Apple; no hay estado activo propio de las tiendas.
+
+## Ejemplo
+
+```html
+<sui-app-store-badge company="app-store"
+  href="https://apps.apple.com/pe/app/master-pedidos/id6764676191" target="_blank"
+  ariaLabel="Descargar Master Pedidos en App Store" />
+<sui-app-store-badge company="google-play"
+  href="https://play.google.com/store/apps/details?id=com.masterpedidos.app" target="_blank"
+  ariaLabel="Descargar Master Pedidos en Google Play" />
+```