@ajuarezso/sui-design-system 0.25.0 → 0.25.2

package/docs/sui-time-picker/README.md

@@ -79,10 +79,12 @@ pocas horas → select.**
 | `disabled` | Mientras se guarda (como hacen el horario y los turnos). | canon (aprobado por el dueño, 05-10-2026, bloque B8) |
 | `placeholder` | El default «Elige una hora» sirve. Si hace falta decir qué hora, en imperativo con tuteo: «Elige la hora de cierre». | canon (dueño, 05-10-2026, P4 a); el default cambió en la 0.25.0 (antes «Seleccionar hora») |
 
-Usos de hoy que rompen la regla: los 7 cumplen `12h`, `durationPresets=[]` y `label`, pero **los 7
-van con `size="medium"` fijo**, también en pantallas del teléfono (turnos y votaciones del
-repartidor): campo de 40, contra el `large` de la tabla de «Tamaño». Cancelar / Aplicar ya salen en
-48 en el teléfono desde el 04-10-2026 (el componente los fuerza en mobile).
+Usos de hoy que rompen la regla (medido de nuevo el 06-10-2026): los 7 cumplen `12h`,
+`durationPresets=[]` y `label`, y ya no van en `medium` fijo, pero **los 7 van con
+`bp.isMobile() ? 'large' : 'medium'`** en vez de `bp.sizeControl()`: en la tablet táctil el campo
+queda en 40 mientras el botón de al lado ya sube a 48 (p. ej.
+`pages/driver/driver-dashboard/driver-dashboard.html:1521` junto a «Pedir cierre»). Cancelar /
+Aplicar ya salen en 48 en el teléfono desde el 04-10-2026 (el componente los fuerza en mobile).
 
 ### Las piezas que trae (exportadas, sin carpeta ni story propias)
 
@@ -120,10 +122,28 @@ campo y la de las filas van en 16/24; la fila sigue en 44 (el padding bajó de 1
 
 ```html
 <sui-time-picker label="Cierra" format="12h" [step]="5" [durationPresets]="[]"
-                 [size]="bp.isMobile() ? 'large' : 'medium'"
+                 [size]="bp.sizeControl()"
                  [value]="cierre()" (valueChange)="cierre.set($event)" />
 ```
 
+### Por dispositivo (D16)
+
+Fila `time-picker` de la tabla D16 (dueño, 05-10-2026), la misma de `sui-input` y `sui-select`: se
+toca, así que va por tipo de puntero además del ancho, y mide lo mismo que los campos y el botón
+que tiene al lado.
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `large` (48) | D16 pide `medium` con área tocable de 44; mientras el DS no estire el área de los `medium`, va `large` (interino) |
+| celular (380–767 px) | `large` (48) | `xlarge` (52) solo si va junto a campos `xlarge` |
+| tablet táctil (`pointer: coarse`) | `large` (48) | con `large` el panel también crece (filas de 44, Cancelar / Aplicar en 48); el arreglo automático del pie solo mira el ancho (≤ 767 px), así que en la tablet hace falta pasar `large` |
+| computadora (`pointer: fine`) | `medium` (40) | también en filas densas; `small` no se usa |
+
+Ultrawide (≥ 1920 px): igual que la computadora, `medium`; el espacio extra va a ancho y columnas,
+no a campos más altos.
+
+En master-pedidos: `[size]="bp.sizeControl()"`.
+
 ## «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
@@ -234,13 +254,56 @@ interface SuiTimeDurationPreset { label: string; minutes: number; }
   defecto (antes venían en inglés del Figma); `label` sigue sirviendo para cambiarlo.
 - El atributo `title` del host se borra solo (no sale el tooltip gris del navegador).
 
+## Bien y mal
+
+Hora junto a un botón
+
+```html
+<!-- ❌ mal: bp.isMobile() deja el campo en medium (40) en la tablet táctil, y el botón de al lado con bp.sizeControl() sube a large (48) (pages/driver/driver-dashboard/driver-dashboard.html:1521) -->
+<sui-time-picker [size]="bp.isMobile() ? 'large' : 'medium'" format="12h" [step]="5" [durationPresets]="[]"
+                 label="Cerrar hasta" [value]="horaCierreProp()" (valueChange)="onHoraCierreChange($event)" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-time-picker [size]="bp.sizeControl()" format="12h" [step]="5" [durationPresets]="[]"
+                 label="Cerrar hasta" [value]="horaCierreProp()" (valueChange)="onHoraCierreChange($event)" />
+```
+
+Presets de duración
+
+```html
+<!-- ❌ mal: los presets no suman sobre la hora: «30 min» deja 12:30 AM (ver Trampas) -->
+<sui-time-picker label="Cerrar por" [durationPresets]="[{ label: '30 min', minutes: 30 }, { label: '1 h', minutes: 60 }]"
+                 [value]="hasta()" (valueChange)="hasta.set($event)" />
+```
+
+```html
+<!-- ✅ bien: se pide la hora del día, sin presets -->
+<sui-time-picker label="Cerrar hasta" format="12h" [step]="5" [durationPresets]="[]" [size]="bp.sizeControl()"
+                 [value]="hasta()" (valueChange)="hasta.set($event)" />
+```
+
+Formato y paso
+
+```html
+<!-- ❌ mal: en Perú se dice «9:30 PM», y 60 minutos en la columna para una precisión que nadie pide -->
+<sui-time-picker label="Abre" format="24h" [step]="1" [value]="apertura()" (valueChange)="apertura.set($event)" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-time-picker label="Abre" format="12h" [step]="5" [durationPresets]="[]" [size]="bp.sizeControl()"
+                 [value]="apertura()" (valueChange)="apertura.set($event)" />
+```
+
 ## Ejemplo
 
 ```html
 <!-- Horario del local: abre / cierra -->
-<sui-time-picker label="Abre" format="12h" [step]="5" [durationPresets]="[]"
+<sui-time-picker label="Abre" format="12h" [step]="5" [durationPresets]="[]" [size]="bp.sizeControl()"
                  [value]="apertura()" (valueChange)="apertura.set($event)" />
-<sui-time-picker label="Cierra" format="12h" [step]="5" [durationPresets]="[]"
+<sui-time-picker label="Cierra" format="12h" [step]="5" [durationPresets]="[]" [size]="bp.sizeControl()"
                  [error]="cierraAntes()" errorMessage="Cierra antes de abrir"
                  [value]="cierre()" (valueChange)="cierre.set($event)" />
 ```

package/docs/sui-toast/README.md

@@ -101,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
 
@@ -124,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.
@@ -173,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

@@ -96,17 +96,34 @@ dos `<svg>` con tooltip del panel del local pasaron a subtítulo
 | 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 |
@@ -184,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.**
@@ -60,9 +60,22 @@ oculto si no entra.
 **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

@@ -37,14 +37,26 @@ armada a mano que quiera verse como la topbar.
 
 ## 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 | 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í
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |
@@ -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

@@ -51,6 +51,26 @@ topbar, que hoy es solo de escritorio.
 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

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

@@ -44,6 +44,19 @@ topbar, que hoy es solo de escritorio.
 |---|---|---|---|
 | cuenta en la barra superior | no usar (en mobile la cuenta va en el cajón del sidebar) | con nombre | canon (aprobado por el dueño, 05-10-2026, bloque B7) |
 
+### Por dispositivo (D16)
+
+No aplica una tabla: no tiene input `size`; mide 40 de alto con el avatar en `md` (32) fijo, 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** (la cuenta va en el cajón
+del sidebar); 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. El avatar no se pasa por `bp.sizeAvatar()`.
+
+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 -->
@@ -72,6 +85,49 @@ topbar, que hoy es solo de escritorio.
   barra de quien mira funciona, pero sigue siendo regla usar `avatarUrl`.
 - Ya trae el arreglo de iOS para el `:active` pegado.
 
+## Bien y mal
+
+La foto y el nombre de la cuenta
+
+```html
+<!-- ❌ mal: el correo empuja la barra y photoURL puede ser la foto de Google -->
+<sui-topbar-user [name]="usuario().email" [avatar]="usuario().photoURL"
+  (clicked)="menuCuenta.set(!menuCuenta())" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar-user [name]="usuario().nombre"
+  [avatar]="usuario().avatarUrl || { initials: usuario().iniciales, color: 'orange' }"
+  [open]="menuCuenta()" (clicked)="menuCuenta.set(!menuCuenta())" />
+```
+
+Sin foto
+
+```html
+<!-- ❌ mal: sin avatar sale la silueta gris, y verified no se usa en esta app -->
+<sui-topbar-user name="Sophia" [verified]="true" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-topbar-user name="Sophia" [avatar]="{ initials: 'S', color: 'orange' }" />
+```
+
+El repartidor de un pedido
+
+```html
+<!-- ❌ mal: es otra persona; la flecha promete un menú que no existe -->
+<sui-topbar-user [name]="pedido().repartidorNombre" [avatar]="pedido().repartidorFoto" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar [size]="bp.sizeAvatar('md')" [src]="pedido().repartidorFoto"
+  [alt]="pedido().repartidorNombre" />
+<span>{{ pedido().repartidorNombre }}</span>
+```
+
 ## Ejemplo
 
 ```html