@ajuarezso/sui-design-system 0.24.1 → 0.25.1

package/docs/sui-toast/README.md

@@ -37,7 +37,8 @@ toast · bandeja → notification.**
 
 > La guía del DS define el toast pero no dice cuándo va cada tipo. Lo marcado «según la guía del
 > DS» sale de su texto o de su código publicado; «canon» es lo ya aprobado (README de `sui-alert`,
-> `docs/CANON-SUI.md` o un pedido del dueño escrito en el código); el resto es **propuesta**.
+> `docs/CANON-SUI.md`, un pedido del dueño escrito en el código o su aprobación del 05-10-2026); lo que
+> quede en **propuesta** espera decisión.
 >
 > Uso medido el 04-10-2026 en `master-pedidos/src/app` (sin prototipos, vitrinas ni tests):
 > **705 llamadas en 108 archivos**, todas con el `SuiToastService` de la copia local. El desglose
@@ -58,11 +59,11 @@ toast · bandeja → notification.**
 
 | método | cuándo | ejemplo real de la app | fuente |
 |---|---|---|---|
-| `success()` | La acción salió como se esperaba. Dice **qué** quedó hecho. | `pages/sales-channels/instagram/instagram.ts:102` («Cambios guardados») | propuesta (sigue la regla canon del alert) |
+| `success()` | La acción salió como se esperaba. Dice **qué** quedó hecho. | `pages/sales-channels/instagram/instagram.ts:102` («Cambios guardados») | canon (aprobado por el dueño, 05-10-2026, bloque B2; sigue la regla canon del alert) |
 | `error()` | La acción **no** salió. Dice qué no se pudo, nunca «Error al…» ni el mensaje técnico. | `pages/driver/driver-profile/driver-profile.ts:516` («No se pudo guardar el vehículo») | canon (copy: `docs/CANON-SUI.md` §5.7) |
-| `warning()` | Salió, **pero** con un pero que la persona tiene que saber. | `pages/super-admin/master-promos/master-promos.ts:171` («Push enviada, pero ningún cliente está dentro del radio») | propuesta |
-| `info()` | Algo que **llega** y no es el resultado de lo que hiciste: un push con la app abierta, una versión nueva. | `core/services/aviso-unico.service.ts:52` · `core/services/update.service.ts:59` | propuesta |
-| `feature()` | No usar hoy (0 usos). **Cuándo sí:** avisar una función nueva en el momento en que se activa («Ya puedes programar tus pedidos»). | — | propuesta |
+| `warning()` | Salió, **pero** con un pero que la persona tiene que saber. | `pages/super-admin/master-promos/master-promos.ts:171` («Push enviada, pero ningún cliente está dentro del radio») | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `info()` | Algo que **llega** y no es el resultado de lo que hiciste: un push con la app abierta, una versión nueva. | `core/services/aviso-unico.service.ts:52` · `core/services/update.service.ts:59` | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `feature()` | No usar hoy (0 usos). **Cuándo sí:** avisar una función nueva en el momento en que se activa («Ya puedes programar tus pedidos»). | — | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
 | `show({ variant })` | Lo mismo que los de arriba, cuando hace falta pasar todo junto. | `pages/empresa/about/about.ts:103` | según el componente |
 
 ### `style` — el relleno
@@ -70,25 +71,25 @@ toast · bandeja → notification.**
 | style | cuándo | fuente |
 |---|---|---|
 | `stroke-dark` (default SUI) | **Siempre.** Flota sobre cualquier pantalla y el oscuro contrasta con todas. | canon (README de `sui-alert`: «default del toast») |
-| `stroke` (default de la guía) | No usar hoy: blanco sobre blanco se confunde con el contenido. **Cuándo sí:** una pantalla de fondo oscuro (una landing), donde el oscuro se pierde. | propuesta |
-| `lighter` · `light` · `filled` | No usar hoy: un toast que pesa más que el oscuro compite con el botón principal, y si tiene que pesar más, no es un toast. **Cuándo sí:** ninguno previsto; ese caso es un alert o un modal. | propuesta |
+| `stroke` (default de la guía) | No usar hoy: blanco sobre blanco se confunde con el contenido. **Cuándo sí:** una pantalla de fondo oscuro (una landing), donde el oscuro se pierde. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `lighter` · `light` · `filled` | No usar hoy: un toast que pesa más que el oscuro compite con el botón principal, y si tiene que pesar más, no es un toast. **Cuándo sí:** ninguno previsto; ese caso es un alert o un modal. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
 
 ### Tiempo, cierre, acción y texto
 
 | opción | valor | cuándo | fuente |
 |---|---|---|---|
 | `duration` | `4000` (default) | Un título corto. | según el componente (valor de Sonner) |
-| `duration` | `6000` | Título más `description`, o un título largo que no se alcanza a leer en 4 s. | propuesta |
+| `duration` | `6000` | Título más `description`, o un título largo que no se alcanza a leer en 4 s. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
 | `duration` | `60_000` | Los avisos de un pedido que llegan con la app abierta: tiempo de verlos sin quedarse tapando. | canon (pedido del dueño, 28-09-2026, en `aviso-unico.service.ts`) |
-| `duration` | `Infinity` | **Solo con `action`**: hay algo que hacer y no se puede perder («Actualizar»). Sin acción, es un alert. | propuesta |
+| `duration` | `Infinity` | **Solo con `action`**: hay algo que hacer y no se puede perder («Actualizar»). Sin acción, es un alert. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
 | `dismissible` | `true` (default) | Siempre: la X permite quitarlo antes. La guía lo trae cerrable por defecto. | según la guía del DS |
-| `dismissible` | `false` | No usar hoy. **Cuándo sí:** un toast de progreso que se reemplaza solo usando el mismo `id` («Subiendo foto…» → «Foto subida»). | propuesta (la guía muestra un ejemplo no cerrable) |
-| `action` | `{ label, onClick, keepOpen? }` | **Una** acción corta que resuelve ahí mismo: «Actualizar», «Deshacer», «Reintentar». Se dibuja como link subrayado. | propuesta |
+| `dismissible` | `false` | No usar hoy. **Cuándo sí:** un toast de progreso que se reemplaza solo usando el mismo `id` («Subiendo foto…» → «Foto subida»). | canon (aprobado por el dueño, 05-10-2026, bloque B6; la guía muestra un ejemplo no cerrable) |
+| `action` | `{ label, onClick, keepOpen? }` | **Una** acción corta que resuelve ahí mismo: «Actualizar», «Deshacer», «Reintentar». Se dibuja como link subrayado. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
 | `title` | frase corta | Qué pasó, en sentence case, **sin punto final**. Una idea. | canon (copy de la app) |
-| `description` | segunda frase | Si hace falta una segunda frase, va aquí y no pegada al título con un punto. | propuesta |
-| `position` | `bottom-right` (default) | Siempre. En mobile toda posición pasa a ancho completo; las `bottom-*` quedan abajo, por encima de la barra inferior. | propuesta |
-| `position` | `top-*` | No usar hoy. **Cuándo sí:** una pantalla con una barra de acción fija abajo que el toast taparía. | propuesta |
-| `position` | `bottom-left` · `bottom-center` | No usar hoy: dos esquinas abren dos pilas. **Cuándo sí:** si se decide cambiar la esquina de toda la app, con `setDefaultPosition()`, una sola vez. | propuesta |
+| `description` | segunda frase | Si hace falta una segunda frase, va aquí y no pegada al título con un punto. | canon (CLAUDE.md «Canon de UI» → `docs/VOZ-Y-ESCRITURA.md` «Toasts: la regla completa»: dos frases nunca en el título; D10) |
+| `position` | `bottom-right` (default) | Siempre. En mobile toda posición pasa a ancho completo; las `bottom-*` quedan abajo, por encima de la barra inferior. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `position` | `top-*` | No usar hoy. **Cuándo sí:** una pantalla con una barra de acción fija abajo que el toast taparía. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+| `position` | `bottom-left` · `bottom-center` | No usar hoy: dos esquinas abren dos pilas. **Cuándo sí:** si se decide cambiar la esquina de toda la app, con `setDefaultPosition()`, una sola vez. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
 | `id` | texto | Para reemplazar un toast en curso o no repetir el mismo aviso. | según el componente |
 
 ### Usos de hoy que rompen la regla
@@ -100,14 +101,15 @@ arma el título con variables. La pasada de copy del 03-10-2026 en la app ya cor
 `duration: Infinity` de «Acerca de» (ahora duran 6 s). Queda:
 
 - **Rompe el canon de copy — 1 error que empieza con «Error…»:**
-  `pages/driver/driver-order-detail/driver-order-detail.ts:1548` («Error al cancelar el pedido»).
+  `pages/driver/driver-order-detail/driver-order-detail.ts:1647` («Error al cancelar el pedido»; línea al 06-10-2026).
 - **Rompen el canon de copy — 18 errores que muestran `e.message`** cuando existe (puede salir
-  texto técnico o en inglés): `components/transfer-tenant-modal/transfer-tenant-modal.ts:82`,
-  `pages/driver/driver-dashboard/driver-dashboard.ts:1601`, `pages/central/central-gastos/central-gastos.ts:183`.
-  Algunos de esos textos de respaldo además llevan punto final (`pages/super-admin/master-viajes/master-viajes.ts:82`).
+  texto técnico o en inglés): `components/transfer-tenant-modal/transfer-tenant-modal.ts:84`,
+  `pages/driver/driver-dashboard/driver-dashboard.ts:1706`, `pages/central/central-gastos/central-gastos.ts:185`
+  (y `:205`). Algunos de esos textos de respaldo además llevan punto final
+  (`pages/super-admin/master-viajes/master-viajes.ts:243`, «No se pudo habilitar.»; líneas al 06-10-2026).
 - **Romperían la propuesta — 57 errores al cargar como toast** («No se pudo cargar…») → alert o
   empty state con «Reintentar»: `pages/driver/driver-history/driver-history.ts:200`,
-  `pages/settings/team/team.ts:307`.
+  `pages/settings/team/team.ts:308`.
 
 ## Tamaño en mobile y en web
 
@@ -123,6 +125,26 @@ El toast **no tiene `size`**: siempre es un alert `large`.
 No hay patrón `bp.isMobile()`: el outlet ya cambia solo por breakpoint. Lo que sí cambia por
 plataforma es el largo del texto: en mobile el título envuelve antes, así que una sola idea por toast.
 
+### Por dispositivo (D16)
+
+El toast no tiene `size` (siempre es un alert `large`): no hay size que elegir por dispositivo ni
+nada que pasar desde la app (en master-pedidos no lleva `bp`). Ancho y posición los resuelve el
+outlet solo, por ancho, y está bien así.
+
+Lo que **sí** queda corto es la X de cerrar, que se toca:
+
+| dispositivo | área de la X hoy | D16 pide |
+|---|---|---|
+| celular chico y celular (≤ 767 px) | 44 × 44 | 44 × 44 (cumple) |
+| tablet táctil (`pointer: coarse`, más de 767 px) | **40 × 40** | 44 × 44 |
+| computadora (`pointer: fine`) | 40 × 40 | sin piso de 44 (cumple) |
+
+**Pendiente del DS**, no de la app: el área de 44 se prende con `@media (max-width: 767px)`
+(`sui-toast-outlet.scss:182`), así que el iPad apaisado y la tablet ancha se quedan en 40. Se
+arregla con el mixin `sui-tactil` (`@media (max-width: 767px), (pointer: coarse)`) que propone la
+sección 0 de las decisiones D16; mientras no exista, no hay nada que la app pueda pasar para
+corregirlo.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 Nada se borra del DS. Si un flujo nuevo cae en la columna de la derecha, se usa.
@@ -172,6 +194,45 @@ Outputs: ninguno.
 - El título es texto plano; la `description` del alert interno va por `innerHTML`: no le pases
   texto escrito por el usuario sin sanear.
 
+## Bien y mal
+
+El copy del error
+
+```ts
+// ❌ mal: «Error al…» en vez de decir qué no se pudo (pages/driver/driver-order-detail/driver-order-detail.ts:1647)
+this.toast.error('Error al cancelar el pedido');
+```
+
+```ts
+// ✅ bien
+this.toast.error('No se pudo cancelar el pedido');
+```
+
+El mensaje técnico en el título
+
+```ts
+// ❌ mal: e.message puede ser técnico o en inglés (pages/driver/driver-dashboard/driver-dashboard.ts:1706)
+this.toast.error((e instanceof Error && e.message) || 'No se pudo abrir la votación');
+```
+
+```ts
+// ✅ bien: el detalle va a la consola; la persona lee qué no se pudo
+console.error('[votación]', e);
+this.toast.error('No se pudo abrir la votación');
+```
+
+Un error al cargar la pantalla (sigue en propuesta: ver «Usos de hoy que rompen la regla»)
+
+```ts
+// ❌ mal: el toast se va y deja la lista vacía sin explicación (pages/driver/driver-history/driver-history.ts:200)
+this.toast.error('No se pudo cargar el historial');
+```
+
+```ts
+// ✅ bien: la pantalla queda con un sui-alert o un sui-empty-state con «Reintentar»
+this.errorAlCargar.set(true);
+```
+
 ## Ejemplo
 
 ```ts

package/docs/sui-tooltip/README.md

@@ -32,7 +32,8 @@ servicio»). Es un extra: la pantalla tiene que entenderse sin él.
 ## Qué variante usar
 
 > La guía del DS dice para qué es y cómo se llaman sus tamaños, pero no cuándo va cada uno. Lo
-> marcado «según la guía del DS» sale de su texto o su código publicado; el resto es **propuesta**.
+> marcado «según la guía del DS» sale de su texto o su código publicado; lo marcado canon lo aprobó
+> el dueño (05-10-2026); lo que sigue en **propuesta** espera decisión.
 >
 > Uso medido el 04-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas): **0 tooltips**.
 > Los 6 que había el 03-10-2026 (2 `suiTooltip` sobre un `<svg>` en el panel del local y 4
@@ -51,18 +52,18 @@ servicio»). Es un extra: la pantalla tiene que entenderse sin él.
 
 | SUI | guía | qué es | cuándo | fuente |
 |---|---|---|---|---|
-| `small` (caja de 20 px en `dark`, 22 en `light` por el borde; 24 con la flecha; texto 12) | `xsmall` | texto de una línea, chico | El nombre de un ícono en una tabla o barra densa. | escala según la guía del DS · cuándo: propuesta |
-| `medium` (caja de 28 px en `dark`, 30 en `light`; 34 con la flecha; texto 14) — default SUI | `small` (default de la guía) | texto de una línea | Lo normal: una frase corta que explica. | escala según la guía del DS · cuándo: propuesta |
-| `large` (280 px, título + descripción + ícono) | `medium` | contenido rico | Explicar un término con título y una o dos frases. Se activa solo al usar `[suiTooltipLarge]`. | escala según la guía del DS · cuándo: propuesta |
+| `small` (caja de 20 px en `dark`, 22 en `light` por el borde; 24 con la flecha; texto 12) | `xsmall` | texto de una línea, chico | No usar: es chico. El nombre de un ícono también va en `medium`. | escala según la guía del DS · no usarlo: canon (dueño, 05-10-2026, D16), reemplaza el «cuándo» del bloque B1 |
+| `medium` (caja de 28 px en `dark`, 30 en `light`; 34 con la flecha; texto 14) — default SUI | `small` (default de la guía) | texto de una línea | Lo normal: una frase corta que explica, o el nombre de un ícono. | escala según la guía del DS · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B1) · el nombre de un ícono: canon (dueño, 05-10-2026, D16) |
+| `large` (280 px, título + descripción + ícono) | `medium` | contenido rico | Explicar un término con título y una o dos frases. Se activa solo al usar `[suiTooltipLarge]`. | escala según la guía del DS · cuándo: canon (aprobado por el dueño, 05-10-2026, bloque B1) |
 | `xlarge` (320 px) | — | rico, más ancho | No usar hoy. Extensión de SUI. **Cuándo sí:** una explicación rica que en 280 px queda en más de cuatro líneas. | propuesta |
 
 ### Contenido: `suiTooltip` o `suiTooltipLarge`
 
 | input | cuándo | ejemplo real de la app | fuente |
 |---|---|---|---|
-| `suiTooltip="…"` | Una frase, sin punto final. | (sin uso hoy) | propuesta |
-| `[suiTooltipLarge]="{ title, description, icon }"` | Un término que necesita título y explicación. | (sin uso hoy) | propuesta |
-| `suiTooltipLarge.dismissible: true` | No usar hoy: lo deja abierto hasta tocar la X o Escape, que es lo que hace un popover. **Cuándo sí:** en web, una explicación larga que la persona lee con calma mientras mueve el mouse. | (sin uso hoy) | propuesta |
+| `suiTooltip="…"` | Una frase, sin punto final. | (sin uso hoy) | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `[suiTooltipLarge]="{ title, description, icon }"` | Un término que necesita título y explicación. | (sin uso hoy) | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `suiTooltipLarge.dismissible: true` | No usar hoy: lo deja abierto hasta tocar la X o Escape, que es lo que hace un popover. **Cuándo sí:** en web, una explicación larga que la persona lee con calma mientras mueve el mouse. | (sin uso hoy) | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
 
 ### `theme`, `position` y el resto
 
@@ -71,14 +72,14 @@ servicio»). Es un extra: la pantalla tiene que entenderse sin él.
 | `theme` | `auto` | **Siempre.** Oscuro sobre la app en claro (lo que pide la guía) y claro sobre la app en oscuro. | propuesta (la guía: `dark` por default) |
 | `theme` | `dark` | Igual que `auto` en modo claro, pero no se invierte en modo oscuro. | según la guía del DS (default) |
 | `theme` | `light` (default SUI) | No usar hoy: sobre una página clara parece una card más. **Cuándo sí:** ya lo da `auto` en modo oscuro. | propuesta |
-| `position` | `top` (default) | Siempre que haya espacio. Si no lo hay, el CDK lo da vuelta solo. | propuesta |
-| `position` | `right` · `left` | Íconos de una barra lateral angosta (el sidebar colapsado). | propuesta |
-| `position` | `bottom` · `*-start` · `*-end` | Un elemento pegado al borde de arriba o a un costado de la pantalla. | propuesta |
-| `delay` | `200` (default) | Siempre: evita que se abra al cruzar con el mouse. | propuesta |
-| `delay` | otro valor | No usar hoy. **Cuándo sí:** ninguno previsto. | propuesta |
-| `disabled` | `true` | Cuando lo que dice ya está a la vista (el sidebar expandido muestra el nombre). | propuesta |
+| `position` | `top` (default) | Siempre que haya espacio. Si no lo hay, el CDK lo da vuelta solo. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `position` | `right` · `left` | Íconos de una barra lateral angosta (el sidebar colapsado). | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `position` | `bottom` · `*-start` · `*-end` | Un elemento pegado al borde de arriba o a un costado de la pantalla. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `delay` | `200` (default) | Siempre: evita que se abra al cruzar con el mouse. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `delay` | otro valor | No usar hoy. **Cuándo sí:** ninguno previsto. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `disabled` | `true` | Cuando lo que dice ya está a la vista (el sidebar expandido muestra el nombre). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
 | `showArrow` | `true` (default) | Siempre: la flecha dice de qué elemento habla. | según la guía del DS |
-| `showArrow` | `false` | No usar hoy. **Cuándo sí:** sobre un punto de un gráfico, donde la flecha tapa el dato. | propuesta |
+| `showArrow` | `false` | No usar hoy. **Cuándo sí:** sobre un punto de un gráfico, donde la flecha tapa el dato. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
 
 ### Usos de hoy que rompen la regla
 
@@ -91,21 +92,38 @@ dos `<svg>` con tooltip del panel del local pasaron a subtítulo
 
 | uso | mobile | web | fuente |
 |---|---|---|---|
-| nombre de un ícono | no aplica: el ícono lleva el nombre escrito o `aria-label` | `small` | propuesta |
-| frase que explica | no aplica: el texto va visible bajo el dato (`sui-form-hint`) | `medium` | propuesta |
-| explicación con título | no aplica: `sui-modal-sheet` al tocar el ícono | `large` (automático con `[suiTooltipLarge]`) | propuesta |
+| nombre de un ícono | no aplica: el ícono lleva el nombre escrito o `aria-label` | `medium` | mobile: canon (aprobado por el dueño, 05-10-2026, bloque B7) · web: canon (dueño, 05-10-2026, D16), antes `small` |
+| frase que explica | no aplica: el texto va visible bajo el dato (`sui-form-hint`) | `medium` | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
+| explicación con título | no aplica: `sui-modal-sheet` al tocar el ícono | `large` (automático con `[suiTooltipLarge]`) | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
 
-En pantallas que se usan en los dos (panel del local, super admin), el tooltip se apaga en mobile
-y la ayuda se muestra de otra forma:
+En pantallas que se usan en los dos (panel del local, super admin), el tooltip se apaga en el
+celular y en la tablet táctil, y la ayuda se muestra de otra forma:
 
 ```html
 <button class="info" type="button" aria-label="Qué es la tarifa de servicio"
-  [suiTooltipLarge]="tarifa" theme="auto" [disabled]="bp.isMobile()"
-  (click)="bp.isMobile() && abrirExplicacion()">
+  [suiTooltipLarge]="tarifa" theme="auto" [disabled]="bp.tactil()"
+  (click)="bp.tactil() && abrirExplicacion()">
   <sui-icon name="information-line" [size]="16" />
 </button>
 ```
 
+### Por dispositivo (D16)
+
+Fila `tooltip` de la tabla D16 (dueño, 05-10-2026). Solo existe donde hay mouse: con el dedo no hay
+hover, y eso incluye la tablet aunque sea ancha.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | no aplica | sin hover: texto visible o un `sui-modal-sheet` al tocar |
+| celular (380–767 px) | no aplica | igual que el celular chico |
+| tablet táctil (`pointer: coarse`) | no aplica | también sin hover; `bp.isMobile()` no la apaga (mide más de 767), `bp.tactil()` sí |
+| computadora (`pointer: fine`) | `medium` (default) | también el nombre de un ícono; `large` sale solo con `[suiTooltipLarge]`; `small` no se usa |
+
+Ultrawide (≥ 1920 px): igual que la computadora.
+
+En master-pedidos: sin helper de tamaño (`medium` es el default, no se pasa `suiTooltipSize`); se
+apaga con `[disabled]="bp.tactil()"` y la ayuda va por otro lado.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |
@@ -171,7 +189,7 @@ no se usa directo en pantallas.
 ## Trampas
 
 - **El tamaño se pasa como `suiTooltipSize`**, no como `size`: así no choca con el `size` del
-  componente que lo lleva (`<sui-button size="small" suiTooltip="…">`).
+  componente que lo lleva (`<sui-button size="medium" suiTooltip="…">`).
 - **`position`, `theme`, `delay` y `disabled` sí se llaman así, sin prefijo**: si el host es un
   componente con un input del mismo nombre (`disabled` de `sui-button`), el valor llega a los dos.
 - **`suiTooltipSize="large"` con `suiTooltip` de texto dibuja una caja vacía**: el tamaño rico solo
@@ -183,6 +201,46 @@ no se usa directo en pantallas.
   gris del navegador).
 - En `dark`, el ícono del tooltip rico usa un gris fijo del `.scss`, no un token.
 
+## Bien y mal
+
+Tooltip sobre un ícono suelto
+
+```html
+<!-- ❌ mal: un <svg> no se enfoca (con teclado nunca aparece) y en el celular no hay hover (components/customer-segments/customer-segments.html, antes de 77ac547a) -->
+<svg suiTooltip="Ingresos por tipo de cliente" position="top" width="16" height="16" viewBox="0 0 16 16">…</svg>
+```
+
+```html
+<!-- ✅ bien: si es una aclaración del título, va escrita -->
+<p class="customer-segments__subtitle">Ingresos por tipo de cliente</p>
+```
+
+Explicación en una pantalla del cliente
+
+```html
+<!-- ❌ mal: el carrito se usa en el celular, sin hover; la tarifa queda sin explicar (pages/customer/cart/cart.html, antes de 77ac547a) -->
+<button type="button" aria-label="Qué es la tarifa de servicio" [suiTooltipLarge]="serviceFeeTooltip" theme="dark">
+  <sui-icon name="information-line" [size]="14" />
+</button>
+```
+
+```html
+<!-- ✅ bien: la explicación va visible bajo el dato -->
+<span class="cart__fee-hint">{{ serviceFeeExplicacion }}</span>
+```
+
+Tamaño rico con texto plano
+
+```html
+<!-- ❌ mal: suiTooltipSize="large" solo lee suiTooltipLarge: con texto dibuja una caja vacía (ver Trampas) -->
+<sui-compact-button icon="download-2-line" ariaLabel="Exportar" suiTooltip="Exportar" suiTooltipSize="large" theme="auto" />
+```
+
+```html
+<!-- ✅ bien: el nombre de un ícono va en medium, el default -->
+<sui-compact-button icon="download-2-line" ariaLabel="Exportar" suiTooltip="Exportar" theme="auto" />
+```
+
 ## Ejemplo
 
 ```html

package/docs/sui-topbar/README.md

@@ -21,7 +21,7 @@ Compone las tres piezas de la familia (`sui-topbar-item`, `sui-topbar-button`,
 - La navegación de los roles de la app (empresa, cliente, repartidor, super admin): es
   `sui-sidebar`, y en el teléfono la barra inferior. Hoy la topbar tiene **0 usos** en la app.
 - El título de una pantalla con sus acciones: `sui-page-header`.
-- Nada que se vea en un teléfono: el componente no tiene versión mobile (ver «Tamaño»).
+- Nada que se vea en un celular o una tablet táctil: el componente no tiene versión mobile (ver «Tamaño»).
 
 Regla corta: **navegación de la app → sidebar · título de pantalla → page header · web de escritorio
 navegada por arriba → topbar.**
@@ -30,20 +30,20 @@ navegada por arriba → topbar.**
 
 > **La guía del DS no tiene página de la topbar.** El componente sale del Figma de SUI (Topbar
 > [Navigation], frame 3814:25274, cuatro ejemplos: con y sin íconos, con buscador abierto o en
-> botón). Sin uso en la app, **todo lo de abajo es propuesta, falta aprobación**, salvo lo que el
-> componente ya fija.
+> botón). Sin uso en la app. Las reglas marcadas canon están aprobadas (05-10-2026) y no queda
+> ninguna en propuesta; lo marcado «Figma» lo fija el componente.
 >
 > Uso medido el 03-10-2026 en `master-pedidos/src/app`: `sui-topbar`, `sui-topbar-item` y
 > `sui-topbar-user` tienen 0 usos; `sui-topbar-button`, 1 en la vitrina de variantes.
 
 | decisión | opción | cuándo | fuente |
 |---|---|---|---|
-| items | sin `icon` | El caso normal: 3-6 secciones con nombre corto. | propuesta, falta aprobación |
-| items | con `icon` | Si **todos** llevan ícono. Mezclar con y sin se lee desordenado. | propuesta, falta aprobación |
-| item con `rightIcon: 'arrow-down-s-line'` | — | Un «Más ⌄» que abre un menú. El menú lo pones tú (`sui-dropdown-menu`) al escuchar `(itemClicked)`. | propuesta, falta aprobación |
+| items | sin `icon` | El caso normal: 3-6 secciones con nombre corto. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| items | con `icon` | Si **todos** llevan ícono. Mezclar con y sin se lee desordenado. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| item con `rightIcon: 'arrow-down-s-line'` | — | Un «Más ⌄» que abre un menú. El menú lo pones tú (`sui-dropdown-menu`) al escuchar `(itemClicked)`. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
 | `search` | objeto con `placeholder` | Buscador abierto de 232 px cuando buscar es la acción principal. | Figma (Type=Default) |
 | `search` | `{ compact: true }` | Ícono de lupa en la zona de acciones; tú abres el buscador real (`sui-modal` o una paleta de comandos) en `(searchClicked)`. | Figma (Type=With Icon) |
-| `actions` | 1-3 íconos | Avisos, ayuda, acciones rápidas. `dot: true` = hay algo nuevo. | propuesta, falta aprobación |
+| `actions` | 1-3 íconos | Avisos, ayuda, acciones rápidas. `dot: true` = hay algo nuevo. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
 | `user` | config | El chip abre el menú de la cuenta: pásale `[userOpen]` mientras el menú está abierto. | Figma |
 | `accent` | `brand` (default) | Siempre. `information` es el azul del Figma original. | canon del DS (accent = marca) |
 
@@ -55,14 +55,27 @@ oculto si no entra.
 
 | uso | mobile | web | fuente |
 |---|---|---|---|
-| navegación de una web de escritorio | **no usar** | `sui-topbar` | propuesta, falta aprobación |
+| navegación de una web de escritorio | **no usar** | `sui-topbar` | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
 
 **Qué pasa en mobile:** nada se adapta. Los 44 px laterales se comen el ancho, los items se
 esconden detrás de un scroll lateral sin pista visual, el buscador no se achica y no hay
 `safe-area-inset-top` (en la app nativa queda debajo del notch). En mobile se usa el patrón de la
-app: barra inferior + cajón `sui-sidebar`. Si algún día hace falta topbar en el teléfono, primero
+app: barra inferior + cajón `sui-sidebar`. Si algún día hace falta topbar en celular o tablet táctil, primero
 hay que agregarle al componente un modo mobile (menú hamburguesa, buscador en botón, safe area).
 
+### Por dispositivo (D16)
+
+No aplica una tabla: no tiene input `size` y sus piezas tienen tamaño fijo (items de 36, íconos y
+chip de 40, buscador de 40). Como se toca y no tiene un size que llegue a 44, B7 lo saca de todo lo
+táctil: en el celular chico, el celular y la tablet táctil **no se usa**; solo en la computadora
+(`pointer: fine`) y en el ultrawide, igual que en la computadora, con el ancho extra para el
+contenido y no para la barra. La columna «mobile» de D16 incluye la tablet en lo que se toca, así
+que el «no usar en mobile» de B7 la cubre.
+
+En master-pedidos: sin `[size]` ni helper; si algún día se monta, va detrás de `@if (!bp.tactil())`
+(`isMobile() || toque()`: todo celular por ancho y toda pantalla táctil). No `!bp.isMobile()`: ese
+es solo por ancho (≤ 768) y deja pasar un iPad de 769 a 1024 con `pointer: coarse`.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |
@@ -129,6 +142,47 @@ Slot: `<ng-content select="[topbar-logo]">` — el logo (una `<img>` directa se
 - El chip de usuario no abre ningún menú: emite `(userClicked)` y solo cambia de aspecto con
   `userOpen`.
 - El host lleva `role="banner"`: una sola por página.
+- `count` en `0` **se muestra** («0» rojo), igual que en `sui-topbar-item`: pasa
+  `pendientes() || undefined`.
+
+## Bien y mal
+
+El contador de un item
+
+```html
+<!-- ❌ mal: sin pendientes sale un «0» rojo -->
+<sui-topbar [items]="[{ value: 'pedidos', label: 'Pedidos', count: pendientes() }]" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar [items]="[{ value: 'pedidos', label: 'Pedidos', count: pendientes() || undefined }]" />
+```
+
+Las acciones de ícono
+
+```html
+<!-- ❌ mal: sin ariaLabel, el lector de pantalla lee el value («notifications») -->
+<sui-topbar [actions]="[{ value: 'notifications', icon: 'notification-3-line', dot: hayAvisos() }]" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar [actions]="[{ value: 'avisos', icon: 'notification-3-line',
+  ariaLabel: 'Avisos', dot: hayAvisos() }]" />
+```
+
+El item activo en una ruta con id
+
+```html
+<!-- ❌ mal: en /pedidos/123 la url nunca es igual a 'pedidos'; no se marca ninguno -->
+<sui-topbar [items]="items" [activeValue]="router.url" (itemClicked)="ir($event.value)" />
+```
+
+```html
+<!-- ✅ bien: seccion() saca 'pedidos' del primer tramo de la ruta -->
+<sui-topbar [items]="items" [activeValue]="seccion()" (itemClicked)="ir($event.value)" />
+```
 
 ## Ejemplo
 
@@ -136,7 +190,7 @@ Slot: `<ng-content select="[topbar-logo]">` — el logo (una `<img>` directa se
 <sui-topbar
   [items]="[
     { value: 'tablero', label: 'Tablero' },
-    { value: 'pedidos', label: 'Pedidos', count: pendientes() },
+    { value: 'pedidos', label: 'Pedidos', count: pendientes() || undefined },
     { value: 'mas', label: 'Más', rightIcon: 'arrow-down-s-line' }
   ]"
   [activeValue]="seccion()"

package/docs/sui-topbar-button/README.md

@@ -26,24 +26,36 @@ armada a mano que quiera verse como la topbar.
 
 > **La guía del DS no tiene página de este botón.** Sale del Figma de SUI (Topbar Item Button
 > [Topbar], set 3814:25156: Default, Hover, Active). Uso medido el 03-10-2026: **0 usos** en la
-> app, 1 en la vitrina de variantes (`master-preview/_guia-variantes`). Lo de abajo es
-> **propuesta, falta aprobación**.
+> app, 1 en la vitrina de variantes (`master-preview/_guia-variantes`). Las reglas marcadas
+> canon están aprobadas (05-10-2026) y no queda ninguna en propuesta.
 
 | prop | cuándo | fuente |
 |---|---|---|
-| `dot` | Hay algo nuevo detrás del ícono (avisos sin leer). Se apaga cuando la persona lo abre. Si el número importa, no alcanza: va un contador en otro lado. | propuesta, falta aprobación |
+| `dot` | Hay algo nuevo detrás del ícono (avisos sin leer). Se apaga cuando la persona lo abre. Si el número importa, no alcanza: va un contador en otro lado. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
 | `active` | Mientras el panel que abre el botón está abierto (pinta el ícono naranja y `aria-pressed`). | Figma (State=Active) |
 | `accent` | `brand` (default). `information` es el azul del Figma original: no usar. | canon del DS (accent = marca) |
 
 ## Tamaño en mobile y en web
 
-**No tiene `size`**: mide siempre 40×40 (padding 10 + ícono de 20), radio 10. En mobile 40 es el
-mínimo táctil aceptable, pero el botón vive en la topbar, que hoy es solo de escritorio (ver
-`sui-topbar`).
+**No tiene `size`**: mide siempre 40×40 (padding 10 + ícono de 20), radio 10. 40 queda debajo de
+los 44 que D1 y D16 piden para lo que se toca, y por eso no va en mobile (B7): vive en la topbar,
+que es solo de computadora (ver `sui-topbar`).
 
 | uso | mobile | web | fuente |
 |---|---|---|---|
-| ícono de la barra superior | no usar (no hay topbar en mobile) | 40×40 | propuesta, falta aprobación |
+| ícono de la barra superior | no usar (no hay topbar en mobile) | 40×40 | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
+
+### Por dispositivo (D16)
+
+No aplica una tabla: no tiene input `size` y mide 40×40 en todos los dispositivos. Como se toca y no
+tiene un size que llegue a 44, B7 lo saca de todo lo táctil: en el celular chico, el celular y la
+tablet táctil **no se usa**; solo en la computadora (`pointer: fine`) y en el ultrawide, igual que
+en la computadora. La columna «mobile» de D16 incluye la tablet en lo que se toca, así que el «no
+usar en mobile» de B7 la cubre.
+
+En master-pedidos: sin `[size]` ni helper; si algún día se monta, va detrás de `@if (!bp.tactil())`
+(`isMobile() || toque()`: todo celular por ancho y toda pantalla táctil). No `!bp.isMobile()`: ese
+es solo por ancho (≤ 768) y deja pasar un iPad de 769 a 1024 con `pointer: coarse`.
 
 ## «No usar»: por qué no hoy y cuándo sí
 
@@ -83,6 +95,48 @@ mínimo táctil aceptable, pero el botón vive en la topbar, que hoy es solo de
   de pantalla. Si importa, dilo en `ariaLabel` («Avisos, hay nuevos»).
 - Ya trae el arreglo de iOS para el `:active` pegado.
 
+## Bien y mal
+
+El ícono de avisos
+
+```html
+<!-- ❌ mal: el lector de pantalla dice «notifications» y no se entera del punto rojo -->
+<sui-topbar-button icon="notification-3-line" ariaLabel="notifications" [dot]="hayAvisos()" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar-button icon="notification-3-line" [dot]="hayAvisos()"
+  [ariaLabel]="hayAvisos() ? 'Avisos, hay nuevos' : 'Avisos'" />
+```
+
+El panel abierto
+
+```html
+<!-- ❌ mal: azul del Figma original y (click) en vez de la API -->
+<sui-topbar-button icon="question-line" ariaLabel="Ayuda" accent="information"
+  [active]="panelAyuda()" (click)="panelAyuda.set(!panelAyuda())" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar-button icon="question-line" ariaLabel="Ayuda"
+  [active]="panelAyuda()" (clicked)="panelAyuda.set(!panelAyuda())" />
+```
+
+Un ícono en una card
+
+```html
+<!-- ❌ mal: es el botón de la barra superior; en una card desentona (radio 10, 40 fijo) -->
+<sui-topbar-button icon="more-2-line" ariaLabel="Opciones" (clicked)="abrirMenu()" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-button variant="ghost" color="neutral" [size]="bp.sizeControl()" [onlyIcon]="true"
+  leftIcon="more-2-line" aria-label="Opciones" (click)="abrirMenu()" />
+```
+
 ## Ejemplo
 
 ```html

package/docs/sui-topbar-item/README.md

@@ -25,18 +25,18 @@ igual.
 ## Qué variante usar
 
 > **La guía del DS no tiene página de este item.** Sale del Figma de SUI (Topbar Items [Topbar],
-> set 3802:24588: Default, Hover, Active). Uso medido el 03-10-2026: **0 usos** en la app. Lo de
-> abajo es **propuesta, falta aprobación**.
+> set 3802:24588: Default, Hover, Active). Uso medido el 03-10-2026: **0 usos** en la app. Las reglas
+> marcadas canon están aprobadas (05-10-2026) y no queda ninguna en propuesta.
 
 | prop | cuándo | fuente |
 |---|---|---|
-| solo `label` | El caso normal. Una o dos palabras, sentence case. | propuesta, falta aprobación |
-| `icon` | Si **todos** los items de la barra lo llevan. | propuesta, falta aprobación |
+| solo `label` | El caso normal. Una o dos palabras, sentence case. | canon (aprobado por el dueño, 05-10-2026, bloque B4) |
+| `icon` | Si **todos** los items de la barra lo llevan. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
 | `rightIcon: 'arrow-down-s-line'` | El item abre un menú («Más ⌄»). El menú lo pones tú. | Figma |
 | `count` | Pendientes que piden acción («3» pedidos por aceptar). Número rojo. | Figma (notification=true) |
 | `badge` | Un «Nuevo» temporal en una sección recién lanzada. String = badge naranja `light` `small`. | Figma (badge=true) |
-| `href` | El item es un link: con ruta interna navega por el router; con `target="_blank"` abre otra pestaña con `rel` seguro. | propuesta, falta aprobación |
-| sin `href` | Es un `<button>`: navegas tú en `(clicked)`. | propuesta, falta aprobación |
+| `href` | El item es un link: con ruta interna navega por el router; con `target="_blank"` abre otra pestaña con `rel` seguro. | según el código |
+| sin `href` | Es un `<button>`: navegas tú en `(clicked)`. | según el código |
 | `active` | La sección actual (fondo gris, texto oscuro, ícono naranja y `aria-current="page"`). Uno solo por barra. | Figma (State=Active) |
 
 ## Tamaño en mobile y en web
@@ -46,11 +46,31 @@ topbar, que hoy es solo de escritorio.
 
 | uso | mobile | web | fuente |
 |---|---|---|---|
-| sección de la barra superior | no usar (no hay topbar en mobile) | tamaño único | propuesta, falta aprobación |
+| sección de la barra superior | no usar (no hay topbar en mobile) | tamaño único | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
 
 En mobile, 36 de alto queda por debajo del área táctil cómoda (44): si algún día se usa ahí, la
 barra tendría que darle más aire.
 
+### Por dispositivo (D16)
+
+No aplica una tabla: no tiene input `size` y mide 36 de alto en todos los dispositivos. Como se toca
+y no tiene un size que llegue a 44, B7 lo saca de todo lo táctil: en el celular chico, el celular y
+la tablet táctil **no se usa**; solo en la computadora (`pointer: fine`) y en el ultrawide, igual
+que en la computadora. La columna «mobile» de D16 incluye la tablet en lo que se toca, así que el
+«no usar en mobile» de B7 la cubre.
+
+Badges internos: el `count` va en `small` fijo (hardcodeado en el template, no se puede cambiar). El
+`badge` cae en `small` cuando no se le pasa `size` (el shorthand string siempre); con
+`SuiBadgeConfig` sí acepta `size`, y en la computadora va `medium`, que es lo que D16 da a lo que no
+se toca (lo mismo que devuelve `bp.sizeBadge()` fuera del celular):
+`[badge]="{ label: 'Nuevo', size: 'medium' }"`. Los dos `small` chocan con «nada en `small`» de D16:
+cambiar el default del badge y el `count` fijo es código del DS, **pendiente** («internos del DS en
+chico» en el doc de decisiones).
+
+En master-pedidos: sin `[size]` ni helper; si algún día se monta, va detrás de `@if (!bp.tactil())`
+(`isMobile() || toque()`: todo celular por ancho y toda pantalla táctil). No `!bp.isMobile()`: ese
+es solo por ancho (≤ 768) y deja pasar un iPad de 769 a 1024 con `pointer: coarse`.
+
 ## API
 
 <!-- api:inicio -->
@@ -85,6 +105,47 @@ barra tendría que darle más aire.
 - `accent="information"` es el azul del Figma original: en esta app no se usa.
 - Ya trae el arreglo de iOS para el `:active` pegado.
 
+## Bien y mal
+
+Pedidos por aceptar
+
+```html
+<!-- ❌ mal: sin pendientes sale un «0» rojo; solo null lo oculta -->
+<sui-topbar-item label="Pedidos" [count]="pendientes()" (clicked)="ir('pedidos')" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar-item label="Pedidos" [count]="pendientes() || null" (clicked)="ir('pedidos')" />
+```
+
+Un item que es link
+
+```html
+<!-- ❌ mal: con href el item ya navega y (clicked) navega otra vez -->
+<sui-topbar-item label="Reportes" href="/reportes" [active]="seccion() === 'reportes'"
+  (clicked)="router.navigateByUrl('/reportes')" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar-item label="Reportes" href="/reportes" [active]="seccion() === 'reportes'" />
+```
+
+Íconos en la barra
+
+```html
+<!-- ❌ mal: unos con ícono y otros sin; se lee desordenado -->
+<sui-topbar-item label="Tablero" icon="layout-grid-line" [active]="true" />
+<sui-topbar-item label="Pedidos" />
+```
+
+```html
+<!-- ✅ bien: todos sin ícono (el caso normal), o todos con -->
+<sui-topbar-item label="Tablero" [active]="true" />
+<sui-topbar-item label="Pedidos" />
+```
+
 ## Ejemplo
 
 ```html