@ajuarezso/sui-design-system 0.25.0 → 0.25.1

package/docs/sui-accordion/README.md

@@ -45,7 +45,7 @@ de cambios de una versión.
 
 | valor | cuándo | ejemplo real de la app | fuente |
 |---|---|---|---|
-| `[leftIcon]="false"` | el caso normal: el título se explica solo | `pages/envios/envios.html:412` («Más detalles (opcional)») | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `[leftIcon]="false"` | el caso normal: el título se explica solo | `pages/envios/envios.html:413` («Más detalles (opcional)») | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
 | `true` (default, `question-line`) | **solo** si el título es una pregunta de ayuda | `pages/driver/driver-profile/driver-profile.html:156` («¿Por qué no me llegan pedidos?») | propuesta |
 | un nombre de ícono | el ícono dice de qué es la sección y hay varias juntas | `pages/notifications/notifications.html:72` (`settings-3-line`) | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
 
@@ -63,11 +63,12 @@ son preguntas y van sin ícono; las dos de ayuda dentro de la app, con. Elegir u
 | `description` | **una respuesta corta en texto** (FAQ): aparece al abrir, alineada con el título | según el Figma del DS |
 | contenido proyectado | cualquier otra cosa: campos, listas, cards, tablas | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
 
-**A revisar:** 4 accordions pasan un **resumen** en `description` (`resumenReto()`,
-`resumenVotaciones()`, `resumenDetalles()`…) que, por cómo funciona el componente, **solo se ve
-con el accordion abierto**. Si la idea era ver el resumen cerrado, hoy no se ve:
-`pages/driver/driver-dashboard/driver-dashboard.html:287` y `:486`,
-`pages/envios/envios.html:412`, `pages/customer/mandadito/mandadito.html:188`.
+**A revisar:** 2 accordions pasan un **resumen** en `description` (`resumenDetallesEnvio()`,
+`resumenDetalles()`) que, por cómo funciona el componente, **solo se ve con el accordion
+abierto**. Si la idea era ver el resumen cerrado, hoy no se ve:
+`pages/envios/envios.html:413` y `pages/customer/mandadito/mandadito.html:189`. Los dos del
+dashboard del repartidor («Votaciones» y «Reto semanal») ya pasaron su resumen al `badge`
+(05-10-2026), que sí se ve cerrado.
 
 ### `lazy` — cuándo diferir el contenido
 
@@ -79,15 +80,15 @@ con el accordion abierto**. Si la idea era ver el resumen cerrado, hoy no se ve:
 
 **Usos de hoy que no hacen lo que parecen:** 4 accordions usan `<ng-template suiAccordionContent>`
 **sin** `[lazy]="true"`, y sin `lazy` el template se crea al cargar igual que el contenido plano:
-`pages/envios/envios.html:418` y `:743`, `pages/customer/order-tracking/order-tracking.html:590`,
-`pages/customer/mandadito/mandadito.html:194`. Les falta `[lazy]="true"`.
+`pages/envios/envios.html:413` y `:756`, `pages/customer/order-tracking/order-tracking.html:611`,
+`pages/customer/mandadito/mandadito.html:189`. Les falta `[lazy]="true"`.
 
 ### `flipIcon` y `badge`
 
 | input | cuándo | fuente |
 |---|---|---|
 | `flipIcon="on"` | listas largas donde el «+» a la izquierda se escanea mejor que a la derecha. 0 usos hoy | según el Figma del DS (la variante existe) |
-| `badge` | marcar una sección como nueva o actualizada («Nuevo»). Extensión de SUI; 0 usos hoy | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `badge` | marcar una sección como nueva o actualizada («Nuevo»), o dejar a la vista con la fila cerrada un estado de una o dos palabras («Sin reto», «3 de 10»). Extensión de SUI; 2 usos hoy, los dos del segundo tipo: `pages/driver/driver-dashboard/driver-dashboard.html:332` y `:516` | «Nuevo»: canon (aprobado por el dueño, 05-10-2026, bloque B9) · estado con la fila cerrada: pedido del dueño, 05-10-2026 (`core/resumen-acordeones-repartidor.ts`) |
 
 ## Tamaño en mobile y en web
 
@@ -100,6 +101,35 @@ cómoda en mobile.
 | fila | ancho completo, 48 px | igual | componente |
 | texto | Label/Small 14 y Paragraph/Small 14 | igual | según el Figma del DS |
 
+### Por dispositivo (D16)
+
+La fila no tiene `size`: mide 48 en todos los dispositivos, que ya pasa los 44 del dedo en el
+celular y la tablet, y en la computadora no estorba. Lo único con tamaño es el **`badge`**, que
+no se toca y sigue la fila de `badge` de D16. El accordion lo pinta en `small` si no le pasas
+`size` (también con el atajo `badge="Nuevo"`), y D16 no deja nada en `small`:
+
+| dispositivo | size del `badge` | nota |
+|---|---|---|
+| celular chico (< 380) | `medium` | lo que no se toca no sube en el celular chico |
+| celular (380–767) | `large` | un paso más que en la computadora (P1 b). No `xlarge`: ver abajo |
+| tablet táctil | `medium` | |
+| computadora | `medium` | `medium` va sin MAYÚSCULAS |
+
+Ultrawide: igual que la computadora. Fuente: D16, dueño 05-10-2026.
+
+**Por qué `large` y no `xlarge` en el celular**, aunque el badge va en la fila del título
+(`.sui-accordion__title-row`): la excepción «`xlarge` junto a un título» de D16 es para un título
+de encabezado o un monto: según el README de `sui-badge`, en el celular el badge va al lado de
+textos de 16. El título del accordion es
+Label/Small 14/20, el mismo nivel que una fila de lista: un `xlarge` (28, texto 16) tendría letra
+más grande que el título que acompaña, y `large` (24, texto 14) lo iguala. Es una lectura de D16,
+no una decisión aparte del dueño; si se quiere `xlarge` aquí, lo decide él. `bp.sizeBadge()` ya da
+`large`/`medium`, así que no hace falta otra expresión.
+
+En master-pedidos: `[badge]="{ label: 'Nuevo', size: bp.sizeBadge() }"`. Hoy los dos badges del
+dashboard del repartidor salen en `medium` fijo (`core/resumen-acordeones-repartidor.ts:19`):
+en el celular les falta subir a `large`.
+
 ## API
 
 <!-- api:inicio -->
@@ -150,6 +180,50 @@ Slots: contenido plano (o con el atributo `sui-accordion-body`) y el template
   contenido cambia de alto estando abierto, acompaña.
 - El host borra el atributo `title` nativo (sin tooltip gris del navegador).
 
+## Bien y mal
+
+Contenido diferido
+
+```html
+<!-- ❌ mal: el template sin [lazy] se crea al cargar igual (pages/envios/envios.html:756) -->
+<sui-accordion [title]="tituloDetalle(e)" [leftIcon]="false" [(open)]="detalleAbierto">
+  <ng-template suiAccordionContent>…</ng-template>
+</sui-accordion>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-accordion [title]="tituloDetalle(e)" [leftIcon]="false" [lazy]="true" [(open)]="detalleAbierto">
+  <ng-template suiAccordionContent>…</ng-template>
+</sui-accordion>
+```
+
+Resumen de la fila cerrada
+
+```html
+<!-- ❌ mal: description solo se ve abierto; cerrado, el resumen no aparece (pages/envios/envios.html:413) -->
+<sui-accordion title="Más detalles (opcional)" [description]="resumenDetallesEnvio()"
+  [leftIcon]="false" />
+```
+
+```html
+<!-- ✅ bien: lo que tiene que verse cerrado va en el título, como en master-orders.html:673 -->
+<sui-accordion [title]="'Más detalles · ' + resumenDetallesEnvio()" [leftIcon]="false" />
+```
+
+Badge en la fila
+
+```html
+<!-- ❌ mal: el atajo de string sale en small, y D16 no deja nada en small -->
+<sui-accordion title="Reto semanal" badge="Nuevo" [leftIcon]="false" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-accordion title="Reto semanal" [badge]="{ label: 'Nuevo', size: bp.sizeBadge() }"
+  [leftIcon]="false" />
+```
+
 ## Ejemplo
 
 ```html

package/docs/sui-activity-feed/README.md

@@ -69,6 +69,16 @@ de texto **envuelve** (`flex-wrap`), así que en mobile un «Ana aprobó la reca
 En táctil, el botón de tres puntos y la descarga miden 20 y 28: por debajo del área cómoda. Si
 el feed va en mobile con acciones, esa es la primera mejora que pide el componente.
 
+### Por dispositivo (D16)
+
+No aplica: el feed **no tiene `size`** y nada en él cambia por dispositivo (avatar o ícono de 32,
+texto 14/20). Si va o no en el celular y la tablet táctil sigue **pendiente** (P59: antes hay que
+decidir si el feed es solo de web), porque los tres puntos (20) y la descarga (28) no llegan a 44.
+Lo que va alrededor sí sigue D16: el «Cargar más» es un `sui-button` con
+`[size]="bp.sizeControl()"`. El avatar del leading lo fija el feed en 32 (`SuiActivityAvatarRef`
+no tiene `size`), así que no sube un paso en el celular como pide D16 para `avatar`: cambiarlo es
+código del DS.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |
@@ -130,13 +140,57 @@ interface SuiActivityTask { state: 'success' | 'warning' | 'pending' | 'error';
 - No hay estado vacío ni de carga: cuando `items` está vacío no se ve nada. Usa `sui-empty-state`
   afuera, y un skeleton mientras llega la primera página.
 
+## Bien y mal
+
+Historial vacío
+
+```html
+<!-- ❌ mal: con items vacío el feed no pinta nada y queda un hueco (Trampas) -->
+<sui-activity-feed [items]="historial()" />
+```
+
+```html
+<!-- ✅ bien -->
+@if (historial().length) {
+  <sui-activity-feed [items]="historial()" />
+} @else {
+  <sui-empty-state title="Todavía no hay actividad" />
+}
+```
+
+Descargar un archivo
+
+```html
+<!-- ❌ mal: file.href no lo lee la plantilla; sin (fileDownload) el chip no baja nada -->
+<sui-activity-feed [items]="comprobantes()" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-activity-feed [items]="comprobantes()" (fileDownload)="descargar($event.file)" />
+```
+
+Menú de los tres puntos
+
+```html
+<!-- ❌ mal: los outputs hacen stopPropagation; el (click) del padre no se entera -->
+<div (click)="abrirMenu()">
+  <sui-activity-feed [items]="historial()" />
+</div>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-activity-feed [items]="historial()" (action)="abrirMenu($event.item)" />
+```
+
 ## Ejemplo
 
 ```html
 <sui-card>
   <sui-activity-feed [items]="historial()" (fileDownload)="descargar($event.file)" />
   @if (hayMas()) {
-    <sui-button variant="stroke" color="neutral" [size]="bp.isMobile() ? 'large' : 'medium'"
+    <sui-button variant="stroke" color="neutral" [size]="bp.sizeControl()"
                 (click)="cargarMas()">Cargar más</sui-button>
   }
 </sui-card>

package/docs/sui-activity-filter/README.md

@@ -46,10 +46,19 @@ igual que `sui-tab-chips`; así nadie se queda con un historial vacío por combi
 
 | uso | mobile | web | fuente |
 |---|---|---|---|
-| filtros del activity feed | no usar: 30 no llega al dedo; usar `sui-tab-chips` en `xlarge` (44) | `sui-activity-filter` | canon (aprobado por el dueño, 05-10-2026, bloque B13) |
+| filtros del activity feed | no usar: 30 no llega al dedo; usar `sui-tab-chips` en `xlarge` (44). Vale también para la tablet táctil | `sui-activity-filter` | canon (aprobado por el dueño, 05-10-2026, bloque B13) · tablet: D16, dueño 05-10-2026 |
 
 La fila de chips la arma la pantalla: el componente no trae contenedor ni scroll lateral.
 
+### Por dispositivo (D16)
+
+No aplica: no tiene `size` (mide 30 en todos lados), así que D16 no le elige tamaño sino **si
+va**. Con 30 no llega a los 44 del dedo: en el celular (también el chico) y en la tablet táctil
+va `sui-tab-chips`, con los sizes de su fila de D16 (B13); en la computadora y el ultrawide, este
+chip. Fuente: D16, dueño 05-10-2026.
+
+En master-pedidos: `@if (bp.tactil()) { <sui-tab-chips [size]="bp.sizeChips()" …/> } @else { <sui-activity-filter …> }`.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |
@@ -88,6 +97,46 @@ Slot: `<ng-content>` (el texto del chip).
 - El foco usa un `outline` de 2 px naranja, no el doble anillo de los inputs del DS.
 - Ya trae el arreglo de iOS para el `:active` pegado.
 
+## Bien y mal
+
+Escuchar el toque
+
+```html
+<!-- ❌ mal: con (click) el filtro no responde a Enter ni Espacio (Trampas) -->
+<sui-activity-filter icon="chat-3-line" (click)="filtro.set('comentarios')">Comentarios</sui-activity-filter>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-activity-filter icon="chat-3-line" [active]="filtro() === 'comentarios'" (clicked)="filtro.set('comentarios')">Comentarios</sui-activity-filter>
+```
+
+El chip «Todos»
+
+```html
+<!-- ❌ mal: sin icon sale el de archivos por defecto -->
+<sui-activity-filter [active]="filtro() === 'todos'" (clicked)="filtro.set('todos')">Todos</sui-activity-filter>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-activity-filter [icon]="null" [active]="filtro() === 'todos'" (clicked)="filtro.set('todos')">Todos</sui-activity-filter>
+```
+
+En el celular o la tablet
+
+```html
+<!-- ❌ mal: 30 de alto no llega al dedo (B13 y D16) -->
+<sui-activity-filter icon="task-line" (clicked)="filtro.set('tareas')">Tareas</sui-activity-filter>
+```
+
+```html
+<!-- ✅ bien -->
+@if (bp.tactil()) {
+  <sui-tab-chips [chips]="filtros" [(value)]="filtro" [size]="bp.sizeChips()" />
+} @else { … }
+```
+
 ## Ejemplo
 
 ```html

package/docs/sui-alert/README.md

@@ -152,6 +152,16 @@ en mobile es el ancho: ocupa toda la columna.
 | la X de cerrar (`dismissible`) | se ve de 16 px en `xsmall`, 20 en `small`, 24 en `large`, 28 en `xlarge`; **se toca en 44 × 44** (`::before` invisible; en `xsmall`/`small` el alert mide 32/36 y recorta el área a su alto, y a la izquierda solo crece 4 para no pisar las acciones inline) | se ve igual, sin área extra | canon (dueño, 04-10-2026): piso táctil 44 en el teléfono |
 | las acciones (`actions[]`) | link de 20 px de alto en `large`/`xlarge`, 16 en `small`/`xsmall` | igual | según el componente |
 
+### Por dispositivo (D16)
+
+No aplica: el `size` del alert lo elige el **contenido** (con descripción `large`, de una línea
+`small`, dentro de un campo `xsmall`), no el dispositivo, y es el mismo en el celular, la tablet
+y la computadora. Por eso no hay helper de `bp`: se escribe el literal. Queda **pendiente** si
+`small`/`xsmall` chocan con el «nada en `small`» de D16: la hoja de decisiones las dejó fuera
+porque ahí el `size` cambia el layout, no la escala. También queda pendiente el área de 44 de la
+X en la **tablet táctil**: hoy se prende solo con `max-width: 767px`, y el arreglo (mixin
+`sui-tactil` con `pointer: coarse`) espera el sí del dueño.
+
 
 ## API
 
@@ -219,6 +229,50 @@ Slot: `<ng-content select="[slot=action]">` — legado; solo se usa si `actions`
 - El slot de acción usa `slot=`; los de badge y button usan `data-slot=`.
 - El host borra el atributo `title` nativo (no aparece el tooltip gris del navegador).
 
+## Bien y mal
+
+Aviso con descripción
+
+```html
+<!-- ❌ mal: en small la descripción no se pinta (pages/super-admin/master-settings/master-settings.html:635) -->
+<sui-alert size="small" title="Todavía no guardaste ninguna escala"
+  description="Estos son los niveles que trae la app." />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-alert size="large" title="Todavía no guardaste ninguna escala"
+  description="Estos son los niveles que trae la app." />
+```
+
+Aviso que solo informa
+
+```html
+<!-- ❌ mal: filled compite con el botón principal y no frena nada (pages/driver/driver-earnings/driver-earnings.html:16) -->
+<sui-alert variantStyle="filled" variant="info" title="Cobras por cada entrega"
+  description="Esto es lo que llevas ganado por las entregas que completaste." />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-alert variant="info" title="Cobras por cada entrega"
+  description="Esto es lo que llevas ganado por las entregas que completaste." />
+```
+
+Una sola acción
+
+```html
+<!-- ❌ mal: la primera acción va subrayada y esta no (pages/notifications/notifications.ts:200) -->
+<sui-alert variant="info" title="Activa las notificaciones"
+  [actions]="[{ label: 'Activar', onClick: activar }]" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-alert variant="info" title="Activa las notificaciones"
+  [actions]="[{ label: 'Activar', onClick: activar, underline: true }]" />
+```
+
 ## Ejemplo
 
 ```html

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

@@ -77,13 +77,23 @@ Regla del dueño, 03-10-2026.
 | footer de las landings, «Descarga la app» | `[height]="44"` | `[height]="40"` (default) | mobile: canon (decisión del dueño 04-10-2026, piso táctil 44) · web: propuesta |
 
 ```html
-<sui-app-store-badge company="app-store" [height]="bp.isMobile() ? 48 : 40" href="…" target="_blank"
+<sui-app-store-badge company="app-store" [height]="bp.tactil() ? 48 : 40" href="…" target="_blank"
                      ariaLabel="Descargar Master Pedidos en App Store" />
 ```
 
 Los dos sellos siempre a la misma altura. Hoy los 10 usan la altura default (40) también en mobile:
 quedan 4 px por debajo de los 44.
 
+### Por dispositivo (D16)
+
+**No tiene `size`**: el alto va en px por `[height]`, así que no hay escala que repartir por
+dispositivo. Lo que sí aplica es la regla de lo que se toca: el sello es un link, y en toda
+pantalla táctil (celular, celular chico y tablet con `pointer: coarse`) va a **44 o más**; en la
+computadora, 40. En el ultrawide, igual que en la computadora. Por eso la condición es
+`bp.tactil()` y no `bp.isMobile()`: con `isMobile` el iPad se queda en 40.
+
+En master-pedidos: `[height]="bp.tactil() ? 44 : 40"` (footer) · `[height]="bp.tactil() ? 48 : 40"` (hero, propuesta).
+
 ## «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
@@ -126,13 +136,57 @@ Outputs: ninguno.
 - `height` escala el sello entero; no le pongas `width` desde afuera o se deforma.
 - El hover baja la opacidad a 0.85, como recomienda Apple; no hay estado activo propio de las tiendas.
 
+## Bien y mal
+
+Texto para el lector de pantalla
+
+```html
+<!-- ❌ mal: alt genérico, no dice qué app (components/landing-footer/landing-footer.html:18) -->
+<sui-app-store-badge company="app-store" appearance="alternative" href="…" target="_blank"
+  ariaLabel="Descargar en App Store" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-app-store-badge company="app-store" appearance="alternative" [height]="bp.tactil() ? 44 : 40"
+  href="…" target="_blank" ariaLabel="Descargar Master Pedidos en App Store" />
+```
+
+Alto en una pantalla táctil
+
+```html
+<!-- ❌ mal: sin [height] queda en 40 también en el celular, 4 px bajo el piso de 44 (pages/public/landing-customers/landing-customers.html:32) -->
+<sui-app-store-badge company="google-play" appearance="preferred" href="…" target="_blank"
+  ariaLabel="Descargar Master Pedidos en Google Play" />
+```
+
+```html
+<!-- ✅ bien: 44 es el piso táctil; en el hero, 48 si se aprueba esa propuesta -->
+<sui-app-store-badge company="google-play" appearance="preferred" [height]="bp.tactil() ? 44 : 40"
+  href="…" target="_blank" ariaLabel="Descargar Master Pedidos en Google Play" />
+```
+
+Sello que no lleva a ningún lado
+
+```html
+<!-- ❌ mal: sin href pinta solo la imagen, sin foco ni clic (ver «Trampas») -->
+<sui-app-store-badge company="app-store" ariaLabel="Descargar Master Pedidos en App Store" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-app-store-badge company="app-store" [height]="bp.tactil() ? 44 : 40"
+  href="https://apps.apple.com/pe/app/master-pedidos/id6764676191"
+  target="_blank" ariaLabel="Descargar Master Pedidos en App Store" />
+```
+
 ## Ejemplo
 
 ```html
-<sui-app-store-badge company="app-store"
+<sui-app-store-badge company="app-store" [height]="bp.tactil() ? 44 : 40"
   href="https://apps.apple.com/pe/app/master-pedidos/id6764676191" target="_blank"
   ariaLabel="Descargar Master Pedidos en App Store" />
-<sui-app-store-badge company="google-play"
+<sui-app-store-badge company="google-play" [height]="bp.tactil() ? 44 : 40"
   href="https://play.google.com/store/apps/details?id=com.masterpedidos.app" target="_blank"
   ariaLabel="Descargar Master Pedidos en Google Play" />
 ```

package/docs/sui-avatar/README.md

@@ -181,12 +181,32 @@ se migra todo ahora, no solo al tocar cada pantalla.
 | cabecera de una ficha | `3xl` (64) | `2xl` (56) |
 
 ```html
-<sui-avatar [size]="bp.isMobile() ? 'lg' : 'md'" color="blue" [initials]="c.nombre" [alt]="c.nombre" />
+<sui-avatar [size]="bp.sizeAvatar('md')" color="blue" [initials]="c.nombre" [alt]="c.nombre" />
 ```
 
 El avatar no se toca solo: si la fila o la card es tocable, el área táctil (44 px o más) la da
-la fila, no el avatar. Hoy **ningún** avatar cambia de tamaño por breakpoint; las pantallas del
-cliente y del repartidor usan `lg` en las tarjetas, un paso por debajo de esta tabla.
+la fila, no el avatar. Medido el 06-10-2026: 56 de los 57 avatares de la app ya van con
+`bp.sizeAvatar(…)`; el único fijo es `pages/driver-onboarding/step-info/step-info.html:31`
+(`3xl`, tu foto al registrarte).
+
+### Por dispositivo (D16)
+
+El avatar no se toca: sube un paso **solo en el celular de 380 px o más**. Fuente: D16, dueño
+05-10-2026 (P1 b).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | valor «web» (`md` en una fila) | no se toca: no sube aunque sea un celular |
+| celular (380–767) | valor «mobile» (`lg` en una fila) | un paso más que en la computadora |
+| tablet táctil (`pointer: coarse`) | valor «web» (`md` en una fila) | no se toca: el puntero no cambia nada |
+| computadora (`pointer: fine`) | valor «web» (`md` en una fila) | |
+
+En el ultrawide, igual que en la computadora: el espacio extra va a más columnas, no a avatares
+más grandes.
+
+En master-pedidos: `[size]="bp.sizeAvatar('md')"` — recibe el valor de la computadora y en el
+celular devuelve el siguiente de la escala, con tope en `3xl` (no sube a `4xl`/`5xl`). No uses
+`bp.isMobile() ? 'lg' : 'md'`: `isMobile` incluye el celular chico, que va con el valor de web.
 
 ## «No usar»: por qué no hoy y cuándo sí
 
@@ -252,15 +272,55 @@ interface SuiAvatarConfig {
 - **No tiene `title`, ni output, ni es clickeable.** Para tocarlo, envuélvelo en un botón o en
   la card que ya lo es.
 
+## Bien y mal
+
+Estado de la cuenta de un empleado
+
+```html
+<!-- ❌ mal: el punto es presencia (conectado ahora), no «cuenta activa»; y sin alt (pages/employees/employees.html:70) -->
+<sui-avatar [size]="bp.sizeAvatar('lg')" color="orange" [initials]="employee.initials"
+  [status]="employee.status === 'Activo' ? 'online' : 'offline'" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar [size]="bp.sizeAvatar('lg')" color="orange" [initials]="employee.initials" [alt]="employee.name" />
+<sui-badge [size]="bp.sizeBadge()" color="green">Activo</sui-badge>
+```
+
+Repartidor en una fila
+
+```html
+<!-- ❌ mal: sin alt, el lector de pantalla no dice quién es; y en una fila (aquí, el ranking de rendimiento) la tabla de tamaños pide md en web, no lg (pages/super-admin/master-drivers/master-drivers.html:256) -->
+<sui-avatar [size]="bp.sizeAvatar('lg')" color="green" [initials]="iniciales(d.nombre)" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar [size]="bp.sizeAvatar('md')" color="green" [initials]="iniciales(d.nombre)" [alt]="d.nombre" />
+```
+
+Color de una persona
+
+```html
+<!-- ❌ mal: el color sale del vehículo, no del rol. El conductor queda blue, que es el color de cliente, y el motorizado purple, que no dice ningún rol. Los dos son postulantes a repartidor: green. Y falta el alt (pages/super-admin/master-solicitudes/master-solicitudes.html:24) -->
+<sui-avatar [size]="bp.sizeAvatar('md')" [color]="f.tipo === 'conductor' ? 'blue' : 'purple'" [initials]="iniciales(f.nombre)" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar [size]="bp.sizeAvatar('md')" color="green" [initials]="iniciales(f.nombre)" [alt]="f.nombre" />
+```
+
 ## Ejemplo
 
 ```html
 <!-- Tu repartidor, en la tarjeta del seguimiento -->
-<sui-avatar size="lg" color="green" [src]="driverPhotoUrl()" [initials]="driverName" [alt]="driverName" />
+<sui-avatar [size]="bp.sizeAvatar('lg')" color="green" [src]="driverPhotoUrl()" [initials]="driverName" [alt]="driverName" />
 
 <!-- El local, en una fila -->
-<sui-avatar size="md" color="orange" [src]="tenantLogo" [initials]="tenantName" [alt]="tenantName" />
+<sui-avatar [size]="bp.sizeAvatar('md')" color="orange" [src]="tenantLogo" [initials]="tenantName" [alt]="tenantName" />
 
 <!-- Todavía sin repartidor -->
-<sui-avatar size="md" color="gray" icon="e-bike-2-line" alt="Sin repartidor" />
+<sui-avatar [size]="bp.sizeAvatar('md')" color="gray" icon="e-bike-2-line" alt="Sin repartidor" />
 ```

package/docs/sui-avatar-group/README.md

@@ -65,9 +65,29 @@ se migra todo ahora, no solo al tocar cada pantalla.
 | dentro de una card | `lg` (40) | `md` (32) |
 
 ```html
-<sui-avatar-group [size]="bp.isMobile() ? 'md' : 'sm'" [max]="3" [items]="equipo" />
+<sui-avatar-group [size]="bp.sizeAvatar('sm')" [max]="3" [items]="equipo" />
 ```
 
+### Por dispositivo (D16)
+
+El grupo no se toca: sigue la misma regla que `sui-avatar` y sube un paso **solo en el celular
+de 380 px o más**. Fuente: D16, dueño 05-10-2026 (P1 b).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | valor «web» (`sm` en una fila, `md` en una card) | no se toca: no sube aunque sea un celular |
+| celular (380–767) | valor «mobile» (`md` en una fila, `lg` en una card) | un paso más que en la computadora |
+| tablet táctil (`pointer: coarse`) | valor «web» | no se toca: el puntero no cambia nada |
+| computadora (`pointer: fine`) | valor «web» | |
+
+En el ultrawide, igual que en la computadora.
+
+En master-pedidos: `[size]="bp.sizeAvatar('sm')"` (fila) · `[size]="bp.sizeAvatar('md')"` (card).
+No hay un helper propio del grupo: `sizeAvatar` sirve porque usa la misma escala (`SuiAvatarSize`).
+No uses `bp.isMobile() ? 'md' : 'sm'`: `isMobile` incluye el celular chico, que va con el valor
+de web. Ojo: con `bp.sizeAvatar('lg')` (cabecera de un panel) el celular sale en `xl`, que arriba
+está en «no usar» — pendiente de decidir si la cabecera se queda en `lg` también en el celular.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |
@@ -107,10 +127,52 @@ interface SuiAvatarGroupItem {
 - El solape cambia con el tamaño (−4 px en `xs`/`sm`, −16 px desde `2xl`): en `lg` las iniciales
   de dos letras quedan tapadas a medias.
 
+## Bien y mal
+
+Hoy no hay usos en la app (0 el 06-10-2026): los pares salen de las reglas de arriba.
+
+Color de cada persona
+
+```html
+<!-- ❌ mal: items sin color caen a slate y no dicen el rol (ver «size y max») -->
+<sui-avatar-group [size]="bp.sizeAvatar('md')" [max]="3"
+  [items]="[{ initials: 'Carlos Mamani', alt: 'Carlos Mamani' }, { initials: 'Ana Torres', alt: 'Ana Torres' }]" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar-group [size]="bp.sizeAvatar('md')" [max]="3"
+  [items]="[{ initials: 'Carlos Mamani', color: 'green', alt: 'Carlos Mamani' }, { initials: 'Ana Torres', color: 'green', alt: 'Ana Torres' }]" />
+```
+
+Grupo dentro de una fila
+
+```html
+<!-- ❌ mal: en xs (20 px) el «+N» no se lee, y sin [max] salen 4 en vez de 3 -->
+<sui-avatar-group size="xs" [items]="equipo" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar-group [size]="bp.sizeAvatar('sm')" [max]="3" [items]="equipo" />
+```
+
+Tamaño fijo en una pantalla que se ve en los dos
+
+```html
+<!-- ❌ mal: md fijo en el panel; en el celular queda un paso por debajo (D16) -->
+<sui-avatar-group size="md" [max]="3" [items]="equipo" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-avatar-group [size]="bp.sizeAvatar('md')" [max]="3" [items]="equipo" />
+```
+
 ## Ejemplo
 
 ```html
-<sui-avatar-group size="md" [max]="3" [items]="[
+<sui-avatar-group [size]="bp.sizeAvatar('md')" [max]="3" [items]="[
   { initials: 'Carlos Mamani', color: 'green', alt: 'Carlos Mamani' },
   { src: repartidor2.avatarUrl, initials: repartidor2.nombre, color: 'green', alt: repartidor2.nombre },
   { initials: 'Luis Huamán', color: 'green', alt: 'Luis Huamán' },