@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-badge/README.md

@@ -0,0 +1,329 @@
+---
+name: sui-badge
+selector: sui-badge
+resumen: Etiqueta corta o número que clasifica algo sin competir con el contenido
+alternativas: [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-badge
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-badge`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+Story: [Atoms/Badge/Badge](https://sui-design-system.web.app/?path=/docs/atoms-badge-badge--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para marcar algo con una o dos palabras o un número: una categoría, un conteo
+(«3 pendientes»), «Nuevo», «Agotado», un metadato al lado de un nombre.
+
+**No lo uses** para:
+
+- **Un estado de ciclo** (completado, pendiente, fallido, deshabilitado) que sale de un campo
+  `status`: eso es `sui-status-badge`, que trae el color y el ícono resueltos por el estado. La
+  guía del DS admite el badge para estados en general; lo que se acota al status-badge son esos
+  cuatro (ver «`sui-badge` o `sui-status-badge`» abajo).
+- Un chip que la persona puede quitar (filtro aplicado): `sui-tag`.
+- Un botón: no tiene output ni foco, y lleva `role="status"`.
+- Un texto que tiene que envolver en varias líneas: eso es un `sui-alert`.
+
+Regla corta: **etiqueta, número o estado con muchos valores → badge · completado/pendiente/fallido/deshabilitado → status-badge · se puede quitar → tag.**
+
+## Qué variante usar
+
+> **La guía del DS no dice cuándo usar cada relleno.** Su página del badge muestra los cuatro
+> rellenos, los colores, los tamaños y la API, sin do/don't ni jerarquía. Lo marcado
+> «según la guía del DS» sale de su texto, de sus ejemplos o de su código publicado; el resto
+> sigue siendo **canon (aprobado por el dueño, 03-10-2026)**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 210 badges, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `master-rutina`,
+> `master-medico`, `dev-index`). Rellenos: 184 `lighter`, 16 `light`, 7 `filled`, 2 `stroke`,
+> 1 `dark`. Colores: 77 dinámicos, 42 `orange`, 28 `gray`, 27 `red`, 23 `green`, 7 `purple`,
+> 3 `blue`, 3 `yellow`.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: un texto corto con estilo propio para que se lea como **metadato del
+  contexto**: un estado, una categoría u otro dato al margen. Ojo: la guía **sí admite el badge
+  para estados**.
+- **El status-badge** es para resaltar el estado de algo en poco espacio, y trae cuatro estados
+  fijos: completado, pendiente, fallido y deshabilitado (SUI le suma `information`).
+- **El tag** es para categorizar y etiquetar contenido (y se puede quitar).
+- **Números**: la forma cuadrada (en SUI, `type="number"`) es la indicada para mostrar números.
+- **`small` va en MAYÚSCULAS**: está en su código, no es un detalle de SUI.
+- **Cada color es un estado de la paleta.** El badge no pinta con el tono crudo: cada `color`
+  apunta a un token de estado, y SUI hace lo mismo (`$sui-badge-colors` en `sui-badge.scss`,
+  tokens `--sui-state-*`). Es la única pista de significado que da la guía, y viene del nombre
+  de los tokens, no de un texto que lo explique.
+- **Default**: la guía arranca en `filled`; SUI, en `lighter`. Es un default, no una
+  recomendación de uso.
+
+### `color` — qué significa cada uno
+
+| color | estado de la paleta | cuándo | fuente |
+|---|---|---|---|
+| `gray` (default) | faded | Neutro, apagado, inactivo, sin carga. | según la guía del DS (nombre del estado) |
+| `blue` | information | Dato informativo. | según la guía del DS (nombre del estado) |
+| `orange` | warning | Pendiente o pide atención. | según la guía del DS (nombre del estado) |
+| `red` | error | Problema, rechazado, terminado mal. | según la guía del DS (nombre del estado) |
+| `green` | success | Bien, activo, aprobado, pagado. | según la guía del DS (nombre del estado) |
+| `yellow` | away | Ausente o en pausa temporal. **No** es «advertencia»: eso es `orange`. | según la guía del DS (nombre del estado) |
+| `purple` | feature | Novedad o función en prueba. | según la guía del DS (nombre del estado) |
+| `sky` | verified | Verificado. | según la guía del DS (nombre del estado) |
+| `pink` | highlighted | Destacado. | según la guía del DS (nombre del estado) |
+| `teal` | stable | Estable. | según la guía del DS (nombre del estado) |
+| (categorías) | — | Una categoría sin carga de bien/mal va en `gray`. Si tiene que distinguirse de otras en la misma fila, el color cuyo estado le calce (`purple` para lo nuevo, `pink` para lo destacado). | canon (aprobado por el dueño, 03-10-2026) |
+| (distintivos del local) | — | «Local exclusivo» en `pink` (destacado) y «Mismo precio que en el local» en `sky` (verificado), `type="left-icon"`. Salen de `core/distintivos-local.ts` en master-pedidos; antes eran un `sui-status-badge` y no son un estado. | canon (aprobado por el dueño, 03-10-2026) |
+
+**Usos de hoy que rompen la guía** (estado con el color de otro estado; se evaluaron los colores
+fijos y los ternarios legibles en el template; el resto de los 77 dinámicos, que salen de
+funciones o campos, no):
+
+- **5 casos.** «Pendiente» en `red`: `pages/super-admin/super-admin.html:637`. «Pendiente» en
+  `yellow` (ausente): `pages/super-admin/master-gastos/master-gastos.html:67` y `:115`. «No cuadra»
+  en `yellow`: `pages/super-admin/master-gastos/master-gastos.html:60` y `:129`. Los cinco pasan a
+  `orange`.
+- Sin evaluar: `pages/super-admin/master-drivers/master-drivers.html:201` (`yellow` con un texto
+  que viene de datos).
+
+**Usos de hoy que rompen la regla de categorías** (categoría pintada con color de estado):
+
+- **15 casos.** «Por delivery» en `green` y «Sueldo fijo» en `blue`: `pages/drivers/drivers.html:134`,
+  `:136`, `:255`, `:257`. «Primer pedido» en `orange`: `pages/driver/driver-order-detail/driver-order-detail.html:482`,
+  `pages/super-admin/master-orders/master-orders.html:205` y `:505`. El plan en `purple`:
+  `pages/super-admin/super-admin.html:116`, `:252`, `pages/super-admin/master-earnings/master-earnings.html:95`.
+  «Envío» y «Mandadito» en `purple`: `pages/super-admin/master-orders/master-orders.html:83` y `:87`.
+  «Compartida» en `purple`: `components/add-product-modal/add-product-modal.html:234`.
+- **Mismo dato, dos colores:** «Administrado» es `orange` en `pages/super-admin/super-admin.html:104`
+  y `purple` en `pages/super-admin/master-orders/master-orders.html:534`.
+- **A discutir: 12 rótulos de sección en `orange`** en las landings y precios
+  (`pages/public/landing-business/landing-business.html:86`, `pages/public/landing-customers/landing-customers.html:94`,
+  `pages/public/pricing/pricing.html:10`…). Son el naranja de marca de SUI, no una advertencia,
+  pero por la paleta se leen como «warning».
+
+### `variant` — el relleno
+
+Aquí `variant` es el **relleno** (en `sui-alert` esa misma palabra es el tipo de mensaje). Cómo
+pinta cada uno (`.scss`): `lighter` = fondo pálido con texto del color **base**; `light` = fondo
+un paso más fuerte con texto **oscuro**; `filled` = fondo saturado con texto blanco.
+
+| variant | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `lighter` (default SUI) | Todo badge en listas, cards, tablas y cabeceras sobre fondo claro. Se lee sin robar la vista. | `pages/drivers/drivers.html:279` («Fuera») · `components/settings-panel/settings-panel.html:164` («Conectado») | canon (aprobado por el dueño, 03-10-2026) |
+| `filled` (default de la guía) | Solo dos casos: (1) **un conteo que pide acción** (pendientes, notificaciones), y (2) un badge **encima de una foto**, donde un fondo pálido se pierde. | `components/glass-tab-bar/glass-tab-bar.html:13` (conteo del tab) · `components/product-detail-view/product-detail-view.html:40` («Agotado» sobre la foto) | canon (aprobado por el dueño, 03-10-2026) |
+| `light` | Solo sobre una **superficie ya teñida** (dentro de un alert `lighter`, una card de color), donde el `lighter` se confunde con el fondo. | (sin uso correcto hoy) | canon (aprobado por el dueño, 03-10-2026) |
+| `stroke` | Metadato **neutro** (`gray`) que convive con badges de color en la misma fila y no debe leerse como estado: «Obligatorio», «12 secciones». | `components/product-detail-view/product-detail-view.html:93` («Obligatorio») · `pages/settings/team/team.html:136` | canon (aprobado por el dueño, 03-10-2026) |
+| `dark` | Solo sobre una **superficie oscura** (card negra, foto oscura). Extensión de SUI: la guía no lo tiene. | `pages/mi-negocio/mi-negocio.html:94` (precio sobre la card negra del plan) | canon (aprobado por el dueño, 03-10-2026) |
+
+**Usos de hoy que rompen la regla:**
+
+- **16 `light` → `lighter`** (salvo que estén sobre superficie teñida; no se verificó
+  renderizado). Ejemplos: `pages/super-admin/master-drivers/master-drivers.html:781`, `:783`, `:785`,
+  `pages/super-admin/master-users/master-user-sheet.html:44`, `pages/reports/reports.html:217`.
+- **1 `filled` como metadato → `lighter`:** `pages/customer/profile/profile.html:122` («Por defecto»).
+  A discutir: `pages/public/pricing/pricing.html:37` (el «Popular» del plan destacado).
+- **1 `lighter` sobre superficie oscura → `dark`:** `pages/mi-negocio/mi-negocio.html:89` («Mes gratis»).
+
+### `size` y `type`
+
+| eje | valor | cuándo | fuente |
+|---|---|---|---|
+| `size` | `small` (default, 16 px) | **No usar**: es chico (D16). Es el default del componente, así que hay que pasar `size` siempre. Va en MAYÚSCULAS (eso sí es de la guía). Hasta el 05-10-2026 era el normal de web. | D16, dueño 05-10-2026 (reemplaza la regla del 03-10-2026) · mayúsculas y default: según la guía del DS |
+| `size` | `medium` (20 px) | **Lo normal en la computadora, la tablet y el celular chico** (el badge no se toca), sin mayúsculas. En el celular, `large` o `xlarge` (ver «Tamaño»). | canon (dueño, 05-10-2026, D16); antes, canon del 03-10-2026 solo para nombres, montos y títulos grandes |
+| `type` | `number` | **Números**: queda cuadrado/circular. | según la guía del DS |
+| `type` | `number` | Va con `filled` cuando el conteo pide acción. | canon (aprobado por el dueño, 03-10-2026) |
+| `type` | `with-dot` | Un estado **vivo** que cambia solo (abierto, en línea, en curso). La guía lo muestra pero no dice cuándo. | canon (aprobado por el dueño, 03-10-2026) |
+| `type` | `left-icon` / `right-icon` | Cuando hay ícono. Sin este `type` el padding queda mal aunque proyectes el ícono. | canon (aprobado por el dueño, 03-10-2026) |
+
+Usos de hoy que rompen la regla de números: **0**. Los badges con solo un número ya llevan
+`type="number"` (`components/glass-tab-bar/glass-tab-bar.html:13`, `:27`,
+`pages/driver/driver-earnings/driver-earnings.html:216`); los demás con interpolación son
+porcentajes o texto.
+
+### `sui-badge` o `sui-status-badge`
+
+| caso | componente | fuente |
+|---|---|---|
+| El estado cae en completado / pendiente / fallido / deshabilitado | `sui-status-badge` | canon (aprobado por el dueño, 03-10-2026) (la guía define esos estados para el status-badge, pero no le prohíbe estados al badge) |
+| Estado con más valores que esos (los de un pedido: preparando, en camino…) o una categoría | `sui-badge` | canon (aprobado por el dueño, 03-10-2026) |
+
+Candidatos de hoy: **17 badges con un estado de ciclo escrito a mano** («Pendiente», «Aprobado»,
+«Rechazado», «En revisión», «Pagado», «Anulado»). Ejemplos: `pages/super-admin/master-drivers/master-drivers.html:781`,
+`pages/driver/driver-profile/driver-profile.html:83`, `pages/central/central-gastos/central-gastos.html:57`.
+Además hay **40 ligados a un campo `status`/`estado`** que hay que mirar uno por uno: los de
+dos valores (`pages/invoices/invoices.html:50` pagado/reembolsado,
+`pages/super-admin/master-gastos/master-gastos.html:67` confirmado/pendiente) son candidatos; los de
+pedidos con muchos estados (`pages/orders/orders.html:113`) se quedan como badge.
+
+## Tamaño en mobile y en web
+
+En mobile el badge se lee de más lejos y al lado de textos de 16 px; en la computadora, la tablet y el celular chico va `medium`, un paso más chico (P1 b), y nunca `small` (D16).
+`large` (24) y `xlarge` (28) son extensión SUI del 03-10-2026.
+
+| size | alto | texto | ícono del slot |
+|---|---|---|---|
+| `small` (default) | 16 px | 11/12, MAYÚSCULAS | 12 |
+| `medium` | 20 px | 12/16 | 16 |
+| `large` | 24 px | 14/20 | 16 |
+| `xlarge` | 28 px | 16/24 | 20 |
+
+Ojo con la regla de tamaños del 03-10-2026 (en `large`/`xlarge` el texto va en 16): el badge
+`large` queda en 14. El README de `sui-button` toma esta escala como referencia de los chips:
+`sui-tag` y `sui-status-badge` van en 14 en `large` y 16 en `xlarge`. **Excepción documentada,
+canon (dueño, 04-10-2026):** el badge mantiene su escala propia 12 / 14 / 16 (`medium` / `large` /
+`xlarge`) y no sube a 16 en `large`; tag y status-badge la siguen. El badge no se toca: no tiene
+área táctil.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| estado en una lista o card | `large` (24) | `medium` (20) | mobile: canon (aprobado por el dueño, 03-10-2026) · web: canon (dueño, 05-10-2026, D16), antes `small` (03-10-2026) · un paso de diferencia: canon (dueño, 05-10-2026, P1 b) |
+| junto a un título o un monto | `xlarge` (28) | `medium` (20) | canon (dueño, 05-10-2026, P1 b) |
+| conteo (`type="number"`) | `large` (24) | `medium` (20) | canon (dueño, 05-10-2026, P1 b); web `medium`: canon (dueño, 05-10-2026, D16) · antes de migrar, ver en captura que el contador de 24 no tape el ícono de la barra inferior |
+
+Patrón (`bp` = `BreakpointsService`). Medido el 06-10-2026 en `master-pedidos/src/app` (sin
+`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `master-rutina`, `master-medico`
+ni `dev-index`): 211 de los 228 badges ya van con `bp.sizeBadge()`. Quedan **17 fijos**:
+
+- **2 en `small`**, el conteo de la barra inferior: `components/glass-tab-bar/glass-tab-bar.html:16`
+  y `:33` (pendiente de ver en captura que el de 24 no tape el ícono).
+- **15 en `medium`**, que en el celular no suben (van a `large`, o a `xlarge` si están junto a un
+  título o un monto, según la tabla de arriba):
+  `components/product-categories/product-categories.html:17` y `:52`,
+  `components/total-sales/total-sales.html:20`, `components/metrics-cards/metrics-cards.html:15`,
+  `pages/products/products.html:61`, `pages/customers/customers.html:16`,
+  `pages/discounts/discounts.html:20`,
+  `pages/super-admin/master-semanas/master-semanas.html:26`, `:40`, `:52` y `:64`,
+  `pages/overview/components/overview-visitors/overview-visitors.html:11`,
+  `pages/overview/components/overview-conversion/overview-conversion.html:11`,
+  `pages/overview/components/overview-sales/overview-sales.html:11` y
+  `pages/reports/reports.html:40`.
+
+```html
+<sui-badge size={bp.sizeBadge()} …/>
+```
+
+### Por dispositivo (D16)
+
+El badge no se toca: sube **solo en el celular de 380 px o más**. Fuente: D16, dueño 05-10-2026.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | `medium` | no se toca: no sube aunque sea un celular |
+| celular (380–767) | `large` (`xlarge` junto a un título o un monto) | un paso más que en la computadora |
+| tablet táctil (`pointer: coarse`) | `medium` | no se toca: el puntero no cambia nada |
+| computadora (`pointer: fine`) | `medium` | nunca `small`; `medium` va sin MAYÚSCULAS |
+
+En el ultrawide, igual que en la computadora.
+
+En master-pedidos: `size={bp.sizeBadge()}` (`large` en el celular, `medium` en el resto). Junto
+a un título o un monto, donde el celular va en `xlarge`, el helper no alcanza (solo devuelve
+`large` o `medium`): `size={bp.celular() ? 'xlarge' : 'medium'}`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `color` | `color` | `"blue" \| "gray" \| "green" \| "orange" \| "pink" \| "purple" \| "red" \| "sky" \| "teal" \| "yellow"` | `'gray'` |
+| `disabled` | `disabled` | `boolean` | `false` |
+| `size` | `size` | `"large" \| "medium" \| "small" \| "xlarge"` | `'small'` |
+| `type` | `type` | `"basic" \| "left-icon" \| "number" \| "right-icon" \| "with-dot"` | `'basic'` |
+| `variant` | `variant` | `"dark" \| "filled" \| "light" \| "lighter" \| "stroke"` | `'lighter'` |
+
+Eventos: ninguno.
+
+Slots: `start`, `(por defecto)`, `end`.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+Slots: `<slot>` (el texto), `slot="start"`, `slot="end"`.
+
+```ts
+// Lo reciben los componentes con badge embebido (checkbox-label, switch-label,
+// integration-switch, checkbox-card, radio-card, switch-card).
+interface SuiBadgeConfig {
+  label: string;
+  color?: SuiBadgeColor;
+  variant?: SuiBadgeVariant;
+  size?: SuiBadgeSize;
+}
+```
+
+## Trampas
+
+- **`variant` aquí es el relleno**; en `sui-alert` y `sui-banner` `variant` es el tipo de
+  mensaje y el relleno se llama `variantStyle`. En `sui-status-badge` el relleno es `appearance`
+  y en `sui-tag` es `tagStyle`.
+- **`size="small"` fuerza MAYÚSCULAS** (`text-transform: uppercase`). «Pendiente» sale «PENDIENTE».
+  `medium` no.
+- **El default es `lighter`, no `filled`** (la guía del DS arranca en `filled`), y el color default es `gray`.
+- En `lighter` el texto es del color **base**; en `light` es del tono **oscuro**. Por eso no son
+  intercambiables aunque se parezcan.
+- Los slots usan **`slot=`**, no `slot=` (alert y banner sí usan `slot=`).
+- Proyectar un ícono no basta: hace falta `type="left-icon"` o `"right-icon"`.
+- El punto de `with-dot` mide 4 px en todos los tamaños; el de `sui-status-badge` mide 6 px en
+  `medium` y 8 en `large`/`xlarge`. Son distintos a propósito.
+- `disabled` no baja la opacidad: pinta todo en los grises de deshabilitado.
+- El host lleva `role="status"`: el lector de pantalla anuncia los cambios.
+
+## Bien y mal
+
+Estado pendiente
+
+```html
+<!-- ❌ mal: red es error; «Pendiente» pide atención (pages/super-admin/super-admin.html:637) -->
+<sui-badge variant="lighter" color="red" size={bp.sizeBadge()}>Pendiente</sui-badge>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-badge color="orange" size={bp.sizeBadge()}>Pendiente</sui-badge>
+```
+
+Categoría en una lista
+
+```html
+<!-- ❌ mal: light es solo para una superficie ya teñida; en una lista va lighter (pages/reports/reports.html:217) -->
+<sui-badge variant="light" color="gray" size={bp.sizeBadge()}>{product.category}</sui-badge>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-badge color="gray" size={bp.sizeBadge()}>{product.category}</sui-badge>
+```
+
+Metadato al lado de un nombre
+
+```html
+<!-- ❌ mal: filled es para un conteo que pide acción o encima de una foto; «Por defecto» es un metadato sin carga, va gray lighter (pages/customer/profile/profile.html:122) -->
+<sui-badge variant="filled" color="orange" size={bp.sizeBadge()}>Por defecto</sui-badge>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-badge color="gray" size={bp.sizeBadge()}>Por defecto</sui-badge>
+```
+
+## Ejemplo
+
+```html
+<!-- Metadato en una lista: lighter (default) -->
+<sui-badge color="green" size={bp.sizeBadge()}>Conectado</sui-badge>
+
+<!-- Estado vivo -->
+<sui-badge color="green" type="with-dot" size={bp.sizeBadge()}>Abierto</sui-badge>
+
+<!-- Conteo que pide acción -->
+<sui-badge color="orange" variant="filled" type="number" size={bp.sizeBadge()}>3</sui-badge>
+```

package/docs/sui-banner/README.md

@@ -0,0 +1,298 @@
+---
+name: sui-banner
+selector: sui-banner
+resumen: Barra de aviso a todo el ancho, arriba de la pantalla, para algo que afecta a toda la app
+alternativas: [sui-alert (aviso ligado a una sección o una card), sui-toast (resultado efímero de una acción), sui-notification (fila de la bandeja), sui-modal (algo que bloquea todo, como quedarse sin conexión)]
+---
+
+# sui-banner
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-banner`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+Story: [Molecules/Feedback/Banner](https://sui-design-system.web.app/?path=/docs/molecules-feedback-banner--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando el aviso es de **toda la app o de toda la pantalla**, no de una parte: el plan
+del local venció, estás administrando un local como super admin, hay una versión nueva, la app
+está en modo de prueba. Va pegado arriba, a todo el ancho, y se queda mientras dure la situación.
+
+**No lo uses** para:
+
+- Un aviso de una sección, una card o un paso del flujo («Cobras S/ 12.00 al local al recoger»):
+  eso es `sui-alert`, aunque sea importante. El banner no tiene tamaños ni descripción larga: no
+  está hecho para vivir en medio del contenido.
+- Confirmar que algo salió bien: `sui-toast`.
+- Algo que impide usar la app (sin conexión, cuenta suspendida): un `sui-modal` o una pantalla
+  propia. La app ya lo hace así con «Sin conexión».
+
+Regla corta (canon, la misma del alert): **contexto → alert · toda la app → banner · efímero →
+toast · bandeja → notification.**
+
+## Ancho: siempre todo el de su contenedor (regla del dueño, 04-10-2026)
+
+El banner **ocupa siempre el ancho disponible de su contenedor**, de borde a borde. No se mete
+dentro de una columna centrada ni de una card, ni se le pone `border-radius` o márgenes laterales
+para que «encaje» con el contenido: si se ve como un rectángulo flotando entre cards, está mal
+puesto.
+
+- Va **fuera** de la columna con `max-width` de la página, como primer hijo del host.
+- Si el host tiene padding lateral (p. ej. `customer-page-base`: 32px en desktop y 16px en
+  mobile), el banner se come ese padding con margen negativo para llegar al borde.
+- Ejemplo real: el aviso de app cerrada en la bandeja del repartidor
+  (`driver-dashboard.html`, clase `.cerrada`).
+
+## Qué variante usar
+
+> La guía del DS dice **para qué** es el banner, pero no cuándo va cada relleno ni cada tipo. Lo
+> marcado «según la guía del DS» sale de su texto o de sus ejemplos publicados; lo marcado
+> «canon» ya lo aprobó el dueño (en el README de `sui-alert` o el 05-10-2026); el resto es **propuesta** y falta su ok.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`, sin contar prototipos ni vitrinas
+> (`master-preview`, `master-prototipos`, `mockup-*`, `dx/*`, `_guia-*`, `master-rutina`,
+> `master-medico`, `master-ejercicios`, `dev-index`): **2 banners** en 2 archivos, más **1 barra
+> hecha a mano** que debería ser banner.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: avisos cruciales, **arriba de la pantalla** y a la vista. Coincide con «toda la
+  app → banner».
+- **Una sola línea**: título, punto medio, descripción y **un link** como acción. El link es un
+  `sui-link-button` `modifiable`, `medium` y **subrayado**: toma el color del banner.
+- **Botón de cerrar** en todos sus ejemplos.
+- **Defaults**: la guía arranca en relleno `filled` y tipo `feature`; SUI arranca en `stroke` e
+  `info`. Es un default, no una recomendación de uso.
+
+### `variant` — qué tipo de aviso es
+
+Los mismos cinco tipos que `sui-alert`, con el mismo significado.
+
+| variant | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `info` (default) | Un dato de toda la app que conviene saber y no pide nada: hay una versión nueva, estás viendo datos de prueba. | (sin uso hoy) | canon (aprobado por el dueño, 05-10-2026, bloque B3) (sigue la regla canon del alert) |
+| `success` | Un estado bueno que dura y afecta a todo: «Tu local ya está publicado». Si es la confirmación de un clic, es toast. | (sin uso hoy) | canon (aprobado por el dueño, 05-10-2026, bloque B3) (sigue la regla canon del alert) |
+| `warning` | Hay que hacer algo pronto o lo que hagas tiene consecuencia para toda la cuenta: el plan vence, estás administrando un local que no es tuyo. | `components/subscription-banner/subscription-banner.html:5` («Tu plan vence en 3 días») · candidato: `components/impersonation-banner/impersonation-banner.ts:17` | canon (aprobado por el dueño, 05-10-2026, bloque B3) (sigue la regla canon del alert) |
+| `error` | Algo ya pasó y afecta a toda la cuenta. | `components/subscription-banner/subscription-banner.html:5` («Tu plan venció») | canon (aprobado por el dueño, 05-10-2026, bloque B3) (sigue la regla canon del alert) |
+| `feature` | Novedad que alcanza a toda la app. **Aquí es gris**, no morado como en el alert. | (sin uso hoy) | canon (decisión documentada en el `.ts`, recogida en el README del alert) |
+
+### `variantStyle` — el peso visual
+
+Misma pregunta que en el alert: **¿este aviso tiene que ganarle a todo lo demás de la pantalla?**
+
+| variantStyle | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `lighter` | El aviso **acompaña**: hay que tenerlo presente, pero se puede seguir trabajando. Es el caso normal. | `subscription-banner.html:7` en el caso «vence en N días» (hoy en `light`) | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `filled` (default de la guía) | Hay que **actuar ya**, o la app está en un **modo que cambia lo que haces**: el plan venció, estás administrando otro local. Uno a la vez. | `subscription-banner.html:7` («Tu plan venció») | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `light` | No usar hoy, como en el alert. **Cuándo sí:** un banner dentro de una zona ya teñida, donde `lighter` se pierde. | — | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `stroke` (default SUI) | No usar hoy: un banner blanco con borde se confunde con la barra superior. **Cuándo sí:** arriba de una pantalla a sangre (un mapa o una foto), donde la banda blanca sí se distingue. | — | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+
+### `dismissible`, `showIcon`, acción y título
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `dismissible` | `true` | Solo si el aviso se puede ignorar sin problema (versión nueva, novedad). La guía lo muestra en todos sus ejemplos. | según la guía del DS (que exista) · canon (aprobado por el dueño, 05-10-2026, bloque B8) (cuándo) |
+| `dismissible` | `false` (default) | Todo `filled` y todo aviso que tiene que seguir ahí: plan vencido, administrando otro local. Cerrarlo no arregla nada. | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
+| `showIcon` | `true` (default) | Siempre: el ícono es la mitad del significado del tipo. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `showIcon` | `false` | No usar hoy. **Cuándo sí:** cuando se proyecta un avatar o logo en `slot="icon"` (ver abajo), que ya ocupa ese lugar. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `slot="icon"` | avatar o logo | Reemplaza al ícono del tipo: el logo del local que estás administrando. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `slot="action"` | **un** `sui-link-button` `variant="modifiable"` con `underline` | La única acción del banner: «Renovar plan», «Salir», «Actualizar». Nunca un `sui-button`, nunca dos. | según la guía del DS |
+| `title` | frase corta | Lo que pasa, en sentence case y sin punto final. | canon (copy de la app) |
+| `description` | complemento | Qué hacer o hasta cuándo. Una línea en web; en mobile se envuelve. | según la guía del DS (una línea) |
+
+### Usos de hoy que rompen la regla
+
+- **Rompe el canon — 1 banner en contexto → `sui-alert`:**
+  `pages/driver/driver-order-detail/driver-order-detail.html:410` («Cobras S/ … al local al
+  recoger»). Es el aviso de **un pedido**, dentro de su detalle: va `sui-alert` (`error` `filled`
+  si cobra en el mostrador, `info` `lighter` si cobra en la puerta).
+- **Barra hecha a mano que es un banner — 1:** `components/impersonation-banner/impersonation-banner.ts:17`
+  («Estás administrando … como super admin» + botón «Salir»), con `#fff` y `rgb()` sueltos. Pasaría a
+  `<sui-banner variant="warning" variant-style="filled">` con un link «Salir».
+- **Rompe el canon (aprobado por el dueño, 05-10-2026, bloque B2) — 1 `light` → `lighter`:** `components/subscription-banner/subscription-banner.html:7`
+  (el caso «vence en N días»).
+- No confundir: `components/upgrade-banner/` (6 pantallas) se llama «banner» pero es un aviso dentro
+  de una sección; su destino es `sui-alert`, ya anotado en `docs/CANON-SUI.md`.
+
+## Tamaño en mobile y en web
+
+El banner **no tiene `size`**: mide 44 px de alto en web, centrado; en mobile (≤ 767 px) pasa a
+`min-height: 44px`, se alinea a la izquierda y el texto se envuelve en varias líneas.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| la barra | 44 px mínimo, crece si el texto envuelve | 44 px fijos, una línea | según el componente |
+| el link de acción | **pendiente (P8)**: `medium` con el área de 44 en la barra (a, recomendada) o `large` (b) | `medium` (20 px) | web: D16, dueño 05-10-2026 · mobile: pendiente P8 (antes decía `large` como propuesta) |
+| la X de cerrar | se ve de 24 px; **se toca en 44 × 44** | se ve de 24; se toca en 40 × 40 | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono (antes 40, pedido del dueño 03-10-2026): área táctil invisible, extensión SUI |
+
+```html
+<sui-banner variant="warning" variant-style="lighter" title="Tu plan vence en 3 días"
+  description="Renueva para seguir recibiendo pedidos">
+  <sui-link-button slot="action" variant="modifiable" underline onClicked={() => renovar()}>Renovar plan</sui-link-button>
+</sui-banner>
+```
+
+`size="large"` del link-button ya está publicado (la app usa 0.24.1), pero mientras P8 siga
+pendiente el link queda en su default (`medium`), que es como está hoy el de la suscripción
+(`subscription-banner.html:10`).
+
+### Por dispositivo (D16)
+
+La barra **no tiene `size`**: su alto lo decide el ancho (≤ 767 px envuelve con mínimo de 44; más
+ancho, 44 fijos en una línea). Lo único que cambia por dispositivo es el link del slot `action`, que
+sigue la fila de `link-button` de D16.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | link `medium` | la barra envuelve; la X se toca en 44 × 44 |
+| celular (380–767) | link **pendiente (P8)** | la barra envuelve; la X se toca en 44 × 44. Ningún size del link llega a 44 por sí solo |
+| tablet táctil (`pointer: coarse`) | link **pendiente (P8)** | con ≥ 768 px la barra va en una línea y la X se toca en 40 × 40: el área de 44 sale con `max-width: 767px`, no con el puntero (el mixin `sui-tactil` está propuesto, sin aprobar) |
+| computadora (`pointer: fine`) | link `medium` | 44 px fijos, una línea; X en 40 × 40 |
+
+Ultrawide: igual que la computadora; el banner ya ocupa todo el ancho de su contenedor.
+
+En master-pedidos: el banner no lleva `size`; el link va sin `size` (su default `medium`)
+hasta que se decida P8. No hay helper en `BreakpointsService` para el link.
+
+## «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.
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `light` | queda a medio camino entre `lighter` y `filled` | un banner dentro de una zona ya teñida |
+| `stroke` | blanco con borde: se confunde con la barra superior | arriba de un mapa o una foto a sangre |
+| `success` | no hay estados buenos que afecten a toda la app | «Tu local ya está publicado» el día que sale al aire |
+| `feature` | no hay novedades anunciadas arriba | anunciar una función nueva a todos los locales, con X para cerrarlo |
+| `showIcon=false` | sin el ícono se pierde el tipo | con un avatar o logo en `slot="icon"` |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `closeLabel` | `close-label` | `string` | `'Cerrar'` |
+| `description` | `description` | `null \| string` | `null` |
+| `dismissible` | `dismissible` | `boolean` | `false` |
+| `heading` | `heading` | `null \| string` | `null` |
+| `showIcon` | `show-icon` | `boolean` | `true` |
+| `variant` | `variant` | `"error" \| "feature" \| "info" \| "success" \| "warning"` | `'info'` |
+| `variantStyle` | `variant-style` | `"filled" \| "light" \| "lighter" \| "stroke"` | `'stroke'` |
+
+| evento | `event.detail` |
+|---|---|
+| `closed` | `void` |
+
+Slots: `icon`, `action`.
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `title`
+- **Props solo de aquí:** `closeLabel`, `heading`
+<!-- api:fin -->
+
+<!-- textos:inicio -->
+### Textos
+
+Lo que el componente escribe solo sale de `provideSuiTextos` (español por defecto, se cambia en vivo; ver `docs/TEXTOS.md`). El input de la última columna le gana al texto global.
+
+| clave | por defecto | se pisa con |
+|---|---|---|
+| `comun.cerrar` | Cerrar | — |
+<!-- textos:fin -->
+
+Signal pública: `dismissed` (`signal(false)`). Slots: `[slot=icon]` (reemplaza el ícono del tipo)
+y `[slot=action]` (el link).
+
+## Trampas
+
+- **Defaults distintos al alert:** el banner arranca en `stroke` (blanco con borde), el alert en
+  `lighter`. Pásale siempre `variantStyle`.
+- **`feature` es gris** aquí (estado «faded» de la paleta) y morado en `sui-alert`.
+- No tiene `size` ni `actions[]`: la acción va **proyectada** en `slot="action"`, a diferencia del
+  alert. Los slots usan `slot=`, no `slot=`.
+- En web la altura es **fija** (44 px): un título más una descripción largos se cortan. En mobile sí
+  envuelve.
+- **La X se toca en 44 × 44 en el teléfono** (40 × 40 en web) aunque se vea de 24 (un `::before`
+  invisible sobre su `<button>`; 44 desde el 04-10-2026). En mobile esa área crece hacia el borde
+  derecho y se mete solo 4 px en el espacio del texto o del link de acción (el padding derecho es 40
+  y la X ocupa de 0 a 44 px desde el borde): un toque justo en la última letra del link puede caer
+  en la X.
+- Al tocar la X se oculta solo (`dismissed`) y emite `closed`; no recuerda nada: si tiene que
+  quedarse cerrado entre sesiones, lo guarda el padre.
+- El host lleva `role="region"` con `aria-label` = `title`, y borra el `title` nativo.
+- En mobile, una pantalla con modal a pantalla completa tapa el banner: el de la suscripción se
+  esconde con `uiOverlay.fullscreenOpen()` para no quedar encima.
+
+## Bien y mal
+
+**Aviso de un pedido, no de toda la app**
+
+```html
+<!-- ❌ mal: es el cobro de UN pedido, dentro de su detalle (driver-order-detail.html:410) -->
+<sui-banner variant={pagaElLocal() ? 'error' : 'info'} variant-style="filled"
+  title={quienPagaTitulo()} description={cobro} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-alert variant={pagaElLocal() ? 'error' : 'info'} variantStyle={pagaElLocal() ? 'filled' : 'lighter'}
+  title={quienPagaTitulo()} description={cobro} />
+```
+
+**Plan por vencer: acompaña, no grita**
+
+```html
+<!-- ❌ mal: `light` no se usa hoy; el aviso que acompaña es `lighter` (subscription-banner.html:7) -->
+<sui-banner variant={isDanger() ? 'error' : 'warning'}
+  variantStyle={isDanger() ? 'filled' : 'light'} title={bannerTitle()} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-banner variant={isDanger() ? 'error' : 'warning'}
+  variantStyle={isDanger() ? 'filled' : 'lighter'} title={bannerTitle()} />
+```
+
+**Modo de toda la app hecho a mano**
+
+```html
+<!-- ❌ mal: barra propia con #fff y un <button> suelto (impersonation-banner.ts:17) -->
+<div class="imp" role="status">
+  <span class="imp__text">Estás administrando <strong>{t.name}</strong> como super admin</span>
+  <button type="button" class="imp__exit" onClick={() => exit()}>Salir</button>
+</div>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-banner variant="warning" variant-style="filled" title={'Estás administrando ' + t.name + ' como super admin'}>
+  <sui-link-button slot="action" variant="modifiable" underline onClicked={() => exit()}>Salir</sui-link-button>
+</sui-banner>
+```
+
+## Ejemplo
+
+```html
+<!-- Aviso que acompaña -->
+<sui-banner variant="warning" variant-style="lighter"
+  title="Tu plan vence en 3 días" description="Renueva para seguir recibiendo pedidos">
+  <sui-link-button slot="action" variant="modifiable" underline onClicked={() => renovar()}>Renovar plan</sui-link-button>
+</sui-banner>
+
+<!-- Modo que cambia lo que haces: filled, sin X -->
+<sui-banner variant="warning" variant-style="filled" title="Estás administrando Pollería El Dorado como super admin">
+  <sui-link-button slot="action" variant="modifiable" underline onClicked={() => salir()}>Salir</sui-link-button>
+</sui-banner>
+```