@ajuarezso/sui-design-system 0.19.0 → 0.20.0

package/docs/sui-avatar/README.md

@@ -0,0 +1,263 @@
+---
+name: sui-avatar
+selector: sui-avatar
+resumen: La cara de alguien (o el logo de un local) en un círculo, con iniciales cuando no hay foto
+alternativas: [sui-avatar-group (varias personas apiladas), sui-compact-avatar-group (varias personas en una celda de tabla), sui-key-icon (un ícono en círculo que no es nadie), sui-image-upload-profile (subir o cambiar la foto)]
+---
+
+# sui-avatar
+
+Story: [Atoms/Avatar/Avatar](https://sui-design-system.web.app/?path=/docs/atoms-avatar-avatar--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para mostrar **quién es**: un cliente, un repartidor, un local, un miembro del equipo.
+Lleva la foto si la hay y, si no, las iniciales del nombre.
+
+**No lo uses** para:
+
+- Un ícono en un círculo que no representa a nadie (un candado, un check, un reloj): eso es
+  `sui-key-icon`.
+- Subir o cambiar la foto: `sui-image-upload-profile`.
+- Varias personas juntas: `sui-avatar-group` o `sui-compact-avatar-group`.
+- Decir el estado de una cuenta (activa, pendiente, bloqueada): eso es un `sui-badge` o
+  `sui-status-badge` al lado del nombre, no el punto de `status`.
+
+Regla corta: **es alguien → avatar · es una cosa → key-icon · son varios → avatar-group.**
+
+## Qué variante usar
+
+> **La guía del DS dice qué es y qué opciones tiene, no cuándo usar cada una.** Lo marcado
+> «según la guía del DS» sale de su texto o de su código publicado; lo marcado «canon» ya es
+> regla escrita del proyecto (`CLAUDE.md`); el resto es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 55 avatares en 25 archivos, sin contar
+> prototipos ni vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`,
+> `master-rutina`, `master-medico`, `dev-index`). Tamaños: 23 `lg`, 19 `md`, 5 `sm`, 3 `xs`,
+> 3 `xl`, 1 `2xl`, 1 `3xl`. Colores: 34 `orange`, 7 `blue`, 7 con `bgColor`, 3 `green`,
+> 1 `purple`, 1 `gray`, 1 `slate`, 1 dinámico. 34 traen `src`.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: una imagen que representa a una persona o a una organización.
+- **Tamaños**: 80, 72, 64, 56, 48, 40, 32, 24 y 20 px; el default de la guía es 80 (en SUI,
+  `md` = 32).
+- **Colores**: solo seis, `gray` (default), `yellow`, `blue`, `sky`, `purple` y `red`. Son el
+  fondo de las iniciales. `orange`, `green`, `pink`, `teal` y `slate` son **extensiones de SUI**.
+- **Texto**: las iniciales van en MAYÚSCULAS.
+- **Placeholder**: sin contenido sale una silueta (de persona o de empresa).
+- **Indicadores**: el estado (`online`, `offline`, `busy`, `away`) y el logo de la empresa van
+  **abajo** a la derecha; la notificación (punto rojo) y el sello de verificado van **arriba**.
+
+### Contenido: qué se muestra
+
+La cascada es fija: `src` → `memojiSrc` → `illustrationSrc` → `initials` → `icon` → silueta. Si
+la foto falla al cargar, cae sola a las iniciales.
+
+| contenido | cuándo | fuente |
+|---|---|---|
+| foto (`src`) | Siempre que exista. Si es la foto **de otra persona**, es su `avatarUrl` de nuestro Storage, denormalizada en el documento por la Cloud Function y filtrada por `fotoDeStorage()`. **Nunca `photoURL` de Google**: solo carga en el navegador del dueño de esa cuenta. | canon (`CLAUDE.md`, «Fotos de otra persona») |
+| `initials` | Sin foto. Pasa el **nombre completo**: el componente saca las iniciales. | según la guía del DS |
+| `icon` | Solo para «todavía no hay nadie»: pedido sin repartidor (`e-bike-2-line`), envío sin destinatario (`user-3-line`). Va con `color="gray"`. Extensión de SUI. | propuesta |
+| silueta | Cae sola cuando no hay ni nombre. No se pide a propósito. | según la guía del DS |
+
+### `size`
+
+| size | px | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|---|
+| `xs` | 20 | Pegado a un texto en la misma línea. | `components/sidebar/sidebar.html:77` (selector de local) · `pages/envios/envios.html:249` | propuesta |
+| `sm` | 24 | Chips y filas compactas. | `pages/driver/driver-dashboard/driver-dashboard.html:1046` (quién tomó el pedido) | propuesta |
+| `md` (default SUI) | 32 | Filas de listas y tablas. | `pages/super-admin/master-orders/master-orders.html:197` | propuesta |
+| `lg` | 40 | La tarjeta de una persona o de un local. | `pages/customer/order-tracking/order-tracking.html:348` (tu repartidor) | propuesta |
+| `xl` | 48 | Cabecera de un panel. | `pages/driver/driver-dashboard/driver-dashboard.html:19` (tu foto) | propuesta |
+| `2xl` | 56 | Cabecera de una ficha. | `pages/super-admin/master-users/master-user-sheet.html:21` | propuesta |
+| `3xl` | 64 | Tu propia foto al registrarte. | `pages/driver-onboarding/step-info/step-info.html:31` | propuesta |
+| `4xl` / `5xl` | 72 / 80 | No usar hoy (ver «No usar»). | — | propuesta |
+
+Hasta `md` (32 px) se ve **una** inicial; desde `lg` (40 px), dos. Es del Figma: en chico dos
+letras no entran.
+
+### `color` — solo se ve cuando no hay foto
+
+La guía no le da significado al color. En Master Pedidos dice **qué rol** tiene la persona, para
+que en una pantalla con cliente, local y repartidor juntos (el detalle de un pedido) se distingan
+sin leer el nombre.
+
+| color | cuándo | fuente |
+|---|---|---|
+| `orange` | Locales (y la gente del local: su equipo y sus empleados). Extensión de SUI. | canon (aprobado por el dueño, 03-10-2026) |
+| `green` | Repartidores, también el propio repartidor en su app. Extensión de SUI. | canon (aprobado por el dueño, 03-10-2026) |
+| `blue` | Clientes y destinatarios, también quien firma una reseña de cliente. | canon (aprobado por el dueño, 03-10-2026) |
+| `gray` (default de la guía) | «Todavía nadie», con `icon` (pedido sin repartidor, envío sin destinatario). | canon (aprobado por el dueño, 03-10-2026) |
+| `slate` (default SUI) | No hace falta en la app: todo avatar tiene un rol o es «todavía nadie». | consecuencia del canon de arriba |
+| `purple`, `sky`, `yellow`, `pink`, `teal`, `red` | No se usan para personas: un quinto color no diría ningún rol. | consecuencia del canon de arriba |
+
+Reglas que van con la tabla:
+
+- **Un mismo rol en una lista no cambia de color por persona.** Las reseñas de `ratings-detail`
+  ya no llevan un color por id: van azules (cliente) o verdes (repartidor) según quién opina.
+- **El color sale del rol de quien se muestra, no de la pantalla.** El logo del local en la app
+  del repartidor sigue siendo `orange`; el repartidor en el seguimiento del cliente, `green`.
+- **Un componente que muestra a «alguien» que cambia según quién lo usa** recibe el color del que
+  lo llama, no lo fija adentro (`ratings-detail` con `entityColor` / `autoresColor`,
+  `rate-entity-card` con `color`).
+- **`bgColor` con un hex no se usa para personas**: era un color por nombre que no decía nada.
+- **Las configs (`SuiAvatarConfig`) llevan el `color` explícito**: `sui-content-card` cae a
+  `orange` y `sui-content-label` a `slate`, así que confiar en el default pinta mal a la mitad.
+
+Aplicado en toda la app (fuera de `master-preview`, prototipos, mockups y `/dx`) el 03-10-2026.
+Pendiente: el perfil de los sidebars (`SuiSidebarProfile`) no acepta `color`, así que la persona
+logueada sigue en el default.
+
+### `status` — el punto de abajo
+
+| status | cuándo | fuente |
+|---|---|---|
+| `online` | Conectado **ahora** (repartidor en línea). No significa «cuenta activa». | propuesta (el valor es de la guía) |
+| `away` | En pausa: conectado pero sin recibir pedidos. | propuesta (el valor es de la guía) |
+| `busy` | Ocupado: ya lleva un pedido. | propuesta (el valor es de la guía) |
+| `offline` | Desconectado. Si en esa lista todos estarían `offline` casi siempre, mejor sin punto. | propuesta (el valor es de la guía) |
+| `company` | Repartidor propio de un local: el logo del local abajo (con `companyLogoSrc`). | propuesta (la guía lo muestra como «con logo de marca») |
+
+**Usos de hoy que rompen la regla: 2.** Los dos usan el punto para el **estado de la cuenta**,
+no para la presencia: `pages/settings/team/team.html:99` (activo/pendiente/inactivo →
+online/away/offline, mapeo en `pages/settings/team/team.ts:99`) y `pages/employees/employees.html:70`
+(«Activo» por pedidos recientes → `online`). Eso va en un `sui-badge` al lado del nombre.
+
+### `topBadge` — la insignia de arriba
+
+| topBadge | cuándo | fuente |
+|---|---|---|
+| `verified` | Identidad revisada (repartidor aprobado). | propuesta (la guía muestra un sello de verificado arriba) |
+| `notification` | Tiene algo sin leer. | propuesta (el punto rojo arriba es de la guía) |
+| `favorite`, `pin`, `add`, `remove` | No usar hoy (ver «No usar»). | propuesta |
+
+Hoy no hay ningún `topBadge` en la app.
+
+### El resto de las propiedades
+
+| input | cuándo | fuente |
+|---|---|---|
+| `alt` | **Siempre** el nombre de quien es. Sin `alt`, el lector de pantalla no dice nada. | propuesta |
+| `companyLogoSrc` | Solo con `status="company"`. | propuesta |
+| `memojiSrc`, `illustrationSrc` | No usar hoy. | propuesta |
+| `bgColor` | No usar (ver abajo). | propuesta |
+
+**Usos de hoy sin `alt`: 9** (más uno decorativo que está bien sin él,
+`pages/super-admin/master-orders/master-orders.html:586`). Ejemplos:
+`pages/super-admin/master-drivers/master-drivers.html:250`, `:770`, `pages/employees/employees.html:70`.
+
+**`bgColor` en la app: 0** (eran 7 hasta el 03-10-2026). Los cinco con paleta saturada escrita a
+mano (clientes, empleados, reporte de repartidores y equipo) rompían la rampa `*-200` del DS y
+dejaban las iniciales sin contraste; los dos con `var(--sui-bg-weak-50)` eran un `slate`
+disfrazado. Todos pasaron a `color` por rol.
+
+### La foto de otra persona (regla del proyecto)
+
+- **1 violación**: `core/services/orders.service.ts:403` hace `user?.avatarUrl ?? user?.photoURL`
+  sin filtrar y lo **congela** en el pedido (`driverPhotoUrl`), que es lo que ve el cliente en
+  `pages/customer/order-tracking/order-tracking.html:348`. Si el repartidor todavía tiene la de
+  Google, el cliente ve la foto rota para siempre.
+- **A revisar** (pintan un `avatarUrl` de otra persona sin el filtro de `fotoMostrable` a la
+  vista): `pages/super-admin/master-drivers/master-drivers.html:706` (`r.foto`), `:770`
+  (`s.avatarUrl`) y `pages/drivers/add-driver/add-driver.html:73`.
+- **Latente**: `pages/customers/customers.ts:280` arma `avatarUrl || photoURL`, pero la tabla
+  hoy no lo pinta.
+
+## Tamaño en mobile y en web
+
+En mobile se lee y se toca con el dedo, así que va más grande; en web, más chico. En las
+pantallas que se usan en los dos (panel del local, super admin) se elige con el servicio de
+breakpoints de la app (`bp`, en `services/breakpoints.service.ts`); en las que solo existen en
+el celular (cliente, repartidor) va directo el valor de mobile. Todo es **propuesta**.
+
+| uso | mobile | web |
+|---|---|---|
+| pegado a un texto | `sm` (24) | `xs` (20) |
+| fila de lista o tabla | `lg` (40) | `md` (32) |
+| tarjeta de una persona o un local | `xl` (48) | `lg` (40) |
+| cabecera de una ficha | `3xl` (64) | `2xl` (56) |
+
+```html
+<sui-avatar [size]="bp.isMobile() ? 'lg' : '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.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+Nada se borra del DS. Lo marcado «no usar» no tiene caso en la app de hoy; si un flujo nuevo
+cae en la columna de la derecha, se usa.
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `size` `4xl`, `5xl` | ninguna pantalla muestra una foto tan grande | un perfil público del repartidor o del local con la foto como protagonista |
+| `color` `red` | un círculo rojo se lee como error | ninguno previsto; se deja porque la guía lo tiene |
+| `topBadge` `favorite`, `pin`, `add`, `remove` | no hay favoritos, fijados ni selección de personas con avatar | elegir varios repartidores para una zona (`add`/`remove`) o fijar un chat (`pin`) |
+| `memojiSrc`, `illustrationSrc` | no hay memojis ni ilustraciones de personas | avatares ilustrados por defecto para quien no sube foto |
+| `bgColor` | pinta colores fuera de la paleta y deja el texto sin contraste | una entidad con su color de marca guardado que tiene que verse igual en todas partes |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl' \| '5xl'` | `'md'` |
+| `src` | `string \| null` | `null` |
+| `alt` | `string` | `''` |
+| `initials` | `string` | `''` |
+| `color` | `'slate' \| 'gray' \| 'blue' \| 'orange' \| 'red' \| 'green' \| 'yellow' \| 'purple' \| 'sky' \| 'pink' \| 'teal'` | `'slate'` |
+| `status` | `'online' \| 'offline' \| 'away' \| 'busy' \| 'company' \| null` | `null` |
+| `memojiSrc` | `string \| null` | `null` |
+| `illustrationSrc` | `string \| null` | `null` |
+| `icon` | `string \| null` | `null` |
+| `companyLogoSrc` | `string \| null` | `null` |
+| `topBadge` | `'verified' \| 'pin' \| 'favorite' \| 'add' \| 'remove' \| 'notification' \| null` | `null` |
+| `bgColor` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+```ts
+// Lo reciben los componentes con avatar adentro (command-menu-item, content-label,
+// dropdown-item, tag…). Un string suelto = src.
+interface SuiAvatarConfig {
+  src?: string | null;
+  initials?: string;
+  color?: SuiAvatarColor;
+}
+```
+
+## Trampas
+
+- **`initials` recibe el nombre, no las iniciales.** «Rosa Quispe» → `RQ`; una sola palabra
+  («Rosa») → `RO`. Si le pasas `"R"` ya cortado, en `lg` sale `R` sola.
+- **Una letra hasta `md`, dos desde `lg`.** No es un bug: es el Figma.
+- **El color no se ve si hay foto.** Solo pinta el fondo de las iniciales, del ícono y de la silueta.
+- **`slate` (default de SUI) y `gray` (default de la guía) no son lo mismo**: `slate` es casi
+  blanco con texto gris; `gray` es gris claro con texto negro.
+- **El avatar no cambia con el tema oscuro**: fondos y texto de las iniciales son fijos a propósito.
+- **`bgColor` gana sobre `color`** pero no cambia el color del texto: con un fondo oscuro, las
+  iniciales quedan ilegibles.
+- **`status` y `topBadge` miden el 40 % del avatar**: en `xs` casi no se ven.
+- **`companyLogoSrc` solo se ve con `status="company"`.**
+- **Si la foto falla, cae sola a las iniciales**, y si cambia el `src` lo vuelve a intentar.
+- **No tiene `title`, ni output, ni es clickeable.** Para tocarlo, envuélvelo en un botón o en
+  la card que ya lo es.
+
+## Ejemplo
+
+```html
+<!-- Tu repartidor, en la tarjeta del seguimiento -->
+<sui-avatar size="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" />
+
+<!-- Todavía sin repartidor -->
+<sui-avatar size="md" color="gray" icon="e-bike-2-line" alt="Sin repartidor" />
+```

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

@@ -0,0 +1,115 @@
+---
+name: sui-avatar-group
+selector: sui-avatar-group
+resumen: Varias personas apiladas en una fila, con «+N» cuando no entran todas
+alternativas: [sui-compact-avatar-group (la versión en píldora, para celdas de tabla), sui-avatar (una sola persona)]
+---
+
+# sui-avatar-group
+
+Story: [Atoms/Avatar/Avatar Group](https://sui-design-system.web.app/?path=/docs/atoms-avatar-avatar-group--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando importa **cuántos y quiénes** a la vez: el equipo de un local, los repartidores
+conectados en una zona. Cada persona se ve chica; el grupo es lo que cuenta.
+
+**No lo uses** para:
+
+- Una sola persona: `sui-avatar`.
+- Una celda de tabla o una fila muy baja: `sui-compact-avatar-group`, que ocupa menos alto.
+- Una lista donde hay que leer el nombre de cada uno: ahí van filas con `sui-avatar` y el nombre.
+
+## Qué variante usar
+
+> **La guía del DS dice qué es y sus tamaños, no cuándo usarlo.** Lo marcado «según la guía
+> del DS» sale de su texto o de su código; el resto es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. El DS lo usa dentro
+> de `sui-table`.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: dos o más avatares en una pila en línea.
+- **Tamaños**: los mismos nueve del avatar (80 a 20 px); el default de la guía es 80.
+- **El «+N»**: un círculo gris (`bg-weak-50`, texto `text-sub-600`) del mismo tamaño que los
+  avatares. Su ejemplo muestra **tres** avatares y el «+9».
+
+### `size` y `max`
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `size` | `sm` (24) | Dentro de una fila: «los que tomaron pedidos hoy». | propuesta |
+| `size` | `md` (32, default SUI) | La card del equipo de un local. | propuesta |
+| `size` | `lg` (40) | La cabecera de un panel (repartidores en la zona). | propuesta |
+| `size` | `xs`, `xl` a `5xl` | No usar hoy: en `xs` el «+N» no se lee; desde `xl` ya no es un resumen. | propuesta |
+| `max` | `3` | Tres visibles y el «+N», como el ejemplo de la guía. El default de SUI es `4`. | propuesta |
+| `items` | — | Cada item es `{ src, initials, color, alt }`. Las reglas de foto y color son las de `sui-avatar` (la foto de otra persona es su `avatarUrl` de Storage). | canon (`CLAUDE.md`, «Fotos de otra persona») |
+
+Usos de hoy que rompen la regla: **0** (no hay usos).
+
+## Tamaño en mobile y en web
+
+En mobile se lee y se toca con el dedo, así que va más grande; en web, más chico. En las
+pantallas que se usan en los dos (panel del local, super admin) se elige con el servicio de
+breakpoints de la app (`bp`, en `services/breakpoints.service.ts`); en las que solo existen en
+el celular (cliente, repartidor) va directo el valor de mobile. Todo es **propuesta**.
+
+| uso | mobile | web |
+|---|---|---|
+| dentro de una fila | `md` (32) | `sm` (24) |
+| dentro de una card | `lg` (40) | `md` (32) |
+
+```html
+<sui-avatar-group [size]="bp.isMobile() ? 'md' : 'sm'" [max]="3" [items]="equipo" />
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| todo el componente (0 usos) | ninguna pantalla muestra varias personas juntas | el equipo de un local en su card, o los repartidores conectados en una zona del super admin |
+| `size` `xs` y de `xl` para arriba | en 20 px el «+N» no se lee; desde 48 px el grupo deja de ser un resumen | ninguno previsto |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl' \| '3xl' \| '4xl' \| '5xl'` | `'md'` |
+| `items` | `readonly SuiAvatarGroupItem[]` | `[]` |
+| `max` | `number` | `4` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+```ts
+interface SuiAvatarGroupItem {
+  src?: string;
+  initials?: string;
+  color?: SuiAvatarColor;
+  alt?: string;
+}
+```
+
+## Trampas
+
+- **No recibe avatares proyectados**: los arma él desde `items`. Para un indicador
+  (`status`, `topBadge`) en una persona del grupo, no hay forma.
+- **`max` cuenta avatares, no el total**: con 6 items y `max` 3 sale «+3».
+- **El «+N» no es un botón**: no tiene output. Si tiene que abrir la lista completa, envuélvelo.
+- 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.
+
+## Ejemplo
+
+```html
+<sui-avatar-group size="md" [max]="3" [items]="[
+  { initials: 'Carlos Mamani', color: 'green', alt: 'Carlos Mamani' },
+  { src: repartidor2.avatarUrl, alt: repartidor2.nombre },
+  { initials: 'Luis Huamán', color: 'green', alt: 'Luis Huamán' },
+  { initials: 'Ana Torres', color: 'green', alt: 'Ana Torres' }
+]" />
+```

package/docs/sui-badge/README.md

@@ -0,0 +1,212 @@
+---
+name: sui-badge
+selector: sui-badge
+resumen: Etiqueta corta o número que clasifica algo sin competir con el contenido
+alternativas: [sui-status-badge (estado de ciclo: completado, pendiente, fallido, deshabilitado), sui-tag (chip que se puede quitar), sui-alert (mensaje que tiene que envolver)]
+---
+
+# sui-badge
+
+Story: [Atoms/Badge/Badge](https://sui-design-system.web.app/?path=/docs/atoms-badge-badge--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para marcar algo con una o dos palabras o un número: una categoría, un conteo
+(«3 pendientes»), «Nuevo», «Agotado», un metadato al lado de un nombre.
+
+**No lo uses** para:
+
+- **Un estado de ciclo** (completado, pendiente, fallido, deshabilitado) que sale de un campo
+  `status`: eso es `sui-status-badge`, que trae el color y el ícono resueltos por el estado. La
+  guía del DS admite el badge para estados en general; lo que se acota al status-badge son esos
+  cuatro (ver «`sui-badge` o `sui-status-badge`» abajo).
+- Un chip que la persona puede quitar (filtro aplicado): `sui-tag`.
+- Un botón: no tiene output ni foco, y lleva `role="status"`.
+- Un texto que tiene que envolver en varias líneas: eso es un `sui-alert`.
+
+Regla corta: **etiqueta, número o estado con muchos valores → badge · completado/pendiente/fallido/deshabilitado → status-badge · se puede quitar → tag.**
+
+## Qué variante usar
+
+> **La guía del DS no dice cuándo usar cada relleno.** Su página del badge muestra los cuatro
+> rellenos, los colores, los tamaños y la API, sin do/don't ni jerarquía. Lo marcado
+> «según la guía del DS» sale de su texto, de sus ejemplos o de su código publicado; el resto
+> sigue siendo **canon (aprobado por el dueño, 03-10-2026)**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 210 badges, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `master-rutina`,
+> `master-medico`, `dev-index`). Rellenos: 184 `lighter`, 16 `light`, 7 `filled`, 2 `stroke`,
+> 1 `dark`. Colores: 77 dinámicos, 42 `orange`, 28 `gray`, 27 `red`, 23 `green`, 7 `purple`,
+> 3 `blue`, 3 `yellow`.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: un texto corto con estilo propio para que se lea como **metadato del
+  contexto**: un estado, una categoría u otro dato al margen. Ojo: la guía **sí admite el badge
+  para estados**.
+- **El status-badge** es para resaltar el estado de algo en poco espacio, y trae cuatro estados
+  fijos: completado, pendiente, fallido y deshabilitado (SUI le suma `information`).
+- **El tag** es para categorizar y etiquetar contenido (y se puede quitar).
+- **Números**: la forma cuadrada (en SUI, `type="number"`) es la indicada para mostrar números.
+- **`small` va en MAYÚSCULAS**: está en su código, no es un detalle de SUI.
+- **Cada color es un estado de la paleta.** El badge no pinta con el tono crudo: cada `color`
+  apunta a un token de estado, y SUI hace lo mismo (`$sui-badge-colors` en `sui-badge.scss`,
+  tokens `--sui-state-*`). Es la única pista de significado que da la guía, y viene del nombre
+  de los tokens, no de un texto que lo explique.
+- **Default**: la guía arranca en `filled`; SUI, en `lighter`. Es un default, no una
+  recomendación de uso.
+
+### `color` — qué significa cada uno
+
+| color | estado de la paleta | cuándo | fuente |
+|---|---|---|---|
+| `gray` (default) | faded | Neutro, apagado, inactivo, sin carga. | según la guía del DS (nombre del estado) |
+| `blue` | information | Dato informativo. | según la guía del DS (nombre del estado) |
+| `orange` | warning | Pendiente o pide atención. | según la guía del DS (nombre del estado) |
+| `red` | error | Problema, rechazado, terminado mal. | según la guía del DS (nombre del estado) |
+| `green` | success | Bien, activo, aprobado, pagado. | según la guía del DS (nombre del estado) |
+| `yellow` | away | Ausente o en pausa temporal. **No** es «advertencia»: eso es `orange`. | según la guía del DS (nombre del estado) |
+| `purple` | feature | Novedad o función en prueba. | según la guía del DS (nombre del estado) |
+| `sky` | verified | Verificado. | según la guía del DS (nombre del estado) |
+| `pink` | highlighted | Destacado. | según la guía del DS (nombre del estado) |
+| `teal` | stable | Estable. | según la guía del DS (nombre del estado) |
+| (categorías) | — | Una categoría sin carga de bien/mal va en `gray`. Si tiene que distinguirse de otras en la misma fila, el color cuyo estado le calce (`purple` para lo nuevo, `pink` para lo destacado). | canon (aprobado por el dueño, 03-10-2026) |
+
+**Usos de hoy que rompen la guía** (estado con el color de otro estado; se evaluaron los colores
+fijos y los ternarios legibles en el template; el resto de los 77 dinámicos, que salen de
+funciones o campos, no):
+
+- **5 casos.** «Pendiente» en `red`: `pages/super-admin/super-admin.html:617`. «Pendiente» en
+  `yellow` (ausente): `pages/super-admin/master-gastos/master-gastos.html:67` y `:115`. «No cuadra»
+  en `yellow`: `pages/super-admin/master-gastos/master-gastos.html:60` y `:129`. Los cinco pasan a
+  `orange`.
+- Sin evaluar: `pages/super-admin/master-drivers/master-drivers.html:201` (`yellow` con un texto
+  que viene de datos).
+
+**Usos de hoy que romperían la propuesta de categorías** (categoría pintada con color de estado):
+
+- **15 casos.** «Por delivery» en `green` y «Sueldo fijo» en `blue`: `pages/drivers/drivers.html:135`,
+  `:137`, `:256`, `:258`. «Primer pedido» en `orange`: `pages/driver/driver-order-detail/driver-order-detail.html:463`,
+  `pages/super-admin/master-orders/master-orders.html:205` y `:505`. El plan en `purple`:
+  `pages/super-admin/super-admin.html:116`, `:252`, `pages/super-admin/master-earnings/master-earnings.html:95`.
+  «Envío» y «Mandadito» en `purple`: `pages/super-admin/master-orders/master-orders.html:83` y `:87`.
+  «Compartida» en `purple`: `components/add-product-modal/add-product-modal.html:234`.
+- **Mismo dato, dos colores:** «Administrado» es `orange` en `pages/super-admin/super-admin.html:104`
+  y `purple` en `pages/super-admin/master-orders/master-orders.html:534`.
+- **A discutir: 12 rótulos de sección en `orange`** en las landings y precios
+  (`pages/public/landing-business/landing-business.html:86`, `pages/public/landing-customers/landing-customers.html:94`,
+  `pages/public/pricing/pricing.html:10`…). Son el naranja de marca de SUI, no una advertencia,
+  pero por la paleta se leen como «warning».
+
+### `variant` — el relleno
+
+Aquí `variant` es el **relleno** (en `sui-alert` esa misma palabra es el tipo de mensaje). Cómo
+pinta cada uno (`.scss`): `lighter` = fondo pálido con texto del color **base**; `light` = fondo
+un paso más fuerte con texto **oscuro**; `filled` = fondo saturado con texto blanco.
+
+| variant | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `lighter` (default SUI) | Todo badge en listas, cards, tablas y cabeceras sobre fondo claro. Se lee sin robar la vista. | `pages/drivers/drivers.html:279` («Fuera») · `components/settings-panel/settings-panel.html:164` («Conectado») | canon (aprobado por el dueño, 03-10-2026) |
+| `filled` (default de la guía) | Solo dos casos: (1) **un conteo que pide acción** (pendientes, notificaciones), y (2) un badge **encima de una foto**, donde un fondo pálido se pierde. | `components/glass-tab-bar/glass-tab-bar.html:13` (conteo del tab) · `components/product-detail-view/product-detail-view.html:40` («Agotado» sobre la foto) | canon (aprobado por el dueño, 03-10-2026) |
+| `light` | Solo sobre una **superficie ya teñida** (dentro de un alert `lighter`, una card de color), donde el `lighter` se confunde con el fondo. | (sin uso correcto hoy) | canon (aprobado por el dueño, 03-10-2026) |
+| `stroke` | Metadato **neutro** (`gray`) que convive con badges de color en la misma fila y no debe leerse como estado: «Obligatorio», «12 secciones». | `components/product-detail-view/product-detail-view.html:93` («Obligatorio») · `pages/settings/team/team.html:136` | canon (aprobado por el dueño, 03-10-2026) |
+| `dark` | Solo sobre una **superficie oscura** (card negra, foto oscura). Extensión de SUI: la guía no lo tiene. | `pages/mi-negocio/mi-negocio.html:92` (precio sobre la card negra del plan) | canon (aprobado por el dueño, 03-10-2026) |
+
+**Usos de hoy que romperían la propuesta:**
+
+- **16 `light` → `lighter`** (salvo que estén sobre superficie teñida; no se verificó
+  renderizado). Ejemplos: `pages/super-admin/master-drivers/master-drivers.html:781`, `:783`, `:785`,
+  `pages/super-admin/master-users/master-user-sheet.html:44`, `pages/reports/reports.html:215`.
+- **1 `filled` como metadato → `lighter`:** `pages/customer/profile/profile.html:122` («Por defecto»).
+  A discutir: `pages/public/pricing/pricing.html:37` (el «Popular» del plan destacado).
+- **1 `lighter` sobre superficie oscura → `dark`:** `pages/mi-negocio/mi-negocio.html:87` («Mes gratis»).
+
+### `size` y `type`
+
+| eje | valor | cuándo | fuente |
+|---|---|---|---|
+| `size` | `small` (default, 16 px) | Lo normal. **Va en MAYÚSCULAS.** | según la guía del DS (mayúsculas y default) |
+| `size` | `small` | Una o dos palabras, justamente por las mayúsculas. | canon (aprobado por el dueño, 03-10-2026) |
+| `size` | `medium` (20 px) | Texto que no debe ir en mayúsculas (nombres, montos) o un badge que acompaña un título grande. | canon (aprobado por el dueño, 03-10-2026) |
+| `type` | `number` | **Números**: queda cuadrado/circular. | según la guía del DS |
+| `type` | `number` | Va con `filled` cuando el conteo pide acción. | canon (aprobado por el dueño, 03-10-2026) |
+| `type` | `with-dot` | Un estado **vivo** que cambia solo (abierto, en línea, en curso). La guía lo muestra pero no dice cuándo. | canon (aprobado por el dueño, 03-10-2026) |
+| `type` | `left-icon` / `right-icon` | Cuando hay ícono. Sin este `type` el padding queda mal aunque proyectes el ícono. | canon (aprobado por el dueño, 03-10-2026) |
+
+Usos de hoy que rompen la regla de números: **0**. Los badges con solo un número ya llevan
+`type="number"` (`components/glass-tab-bar/glass-tab-bar.html:13`, `:27`,
+`pages/driver/driver-earnings/driver-earnings.html:216`); los demás con interpolación son
+porcentajes o texto.
+
+### `sui-badge` o `sui-status-badge`
+
+| caso | componente | fuente |
+|---|---|---|
+| El estado cae en completado / pendiente / fallido / deshabilitado | `sui-status-badge` | canon (aprobado por el dueño, 03-10-2026) (la guía define esos estados para el status-badge, pero no le prohíbe estados al badge) |
+| Estado con más valores que esos (los de un pedido: preparando, en camino…) o una categoría | `sui-badge` | canon (aprobado por el dueño, 03-10-2026) |
+
+Candidatos de hoy: **17 badges con un estado de ciclo escrito a mano** («Pendiente», «Aprobado»,
+«Rechazado», «En revisión», «Pagado», «Anulado»). Ejemplos: `pages/super-admin/master-drivers/master-drivers.html:781`,
+`pages/driver/driver-profile/driver-profile.html:83`, `pages/central/central-gastos/central-gastos.html:57`.
+Además hay **40 ligados a un campo `status`/`estado`** que hay que mirar uno por uno: los de
+dos valores (`pages/invoices/invoices.html:50` pagado/reembolsado,
+`pages/super-admin/master-gastos/master-gastos.html:67` confirmado/pendiente) son candidatos; los de
+pedidos con muchos estados (`pages/orders/orders.html:113`) se quedan como badge.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `color` | `'gray' \| 'blue' \| 'orange' \| 'red' \| 'green' \| 'yellow' \| 'purple' \| 'sky' \| 'pink' \| 'teal'` | `'gray'` |
+| `variant` | `'filled' \| 'light' \| 'lighter' \| 'stroke' \| 'dark'` | `'lighter'` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'small'` |
+| `type` | `'basic' \| 'with-dot' \| 'left-icon' \| 'right-icon' \| 'number'` | `'basic'` |
+| `disabled` | `boolean` | `false` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+Slots: `<ng-content>` (el texto), `[data-slot=start]`, `[data-slot=end]`.
+
+```ts
+// Lo reciben los componentes con badge embebido (checkbox-label, switch-label,
+// integration-switch, checkbox-card, radio-card, switch-card).
+interface SuiBadgeConfig {
+  label: string;
+  color?: SuiBadgeColor;
+  variant?: SuiBadgeVariant;
+  size?: SuiBadgeSize;
+}
+```
+
+## Trampas
+
+- **`variant` aquí es el relleno**; en `sui-alert` y `sui-banner` `variant` es el tipo de
+  mensaje y el relleno se llama `variantStyle`. En `sui-status-badge` el relleno es `appearance`
+  y en `sui-tag` es `tagStyle`.
+- **`size="small"` fuerza MAYÚSCULAS** (`text-transform: uppercase`). «Pendiente» sale «PENDIENTE».
+  `medium` no.
+- **El default es `lighter`, no `filled`** (la guía del DS arranca en `filled`), y el color default es `gray`.
+- En `lighter` el texto es del color **base**; en `light` es del tono **oscuro**. Por eso no son
+  intercambiables aunque se parezcan.
+- Los slots usan **`data-slot=`**, no `slot=` (alert y banner sí usan `slot=`).
+- Proyectar un ícono no basta: hace falta `type="left-icon"` o `"right-icon"`.
+- El punto de `with-dot` mide 4 px; el de `sui-status-badge` mide 6 px. Son distintos a propósito.
+- `disabled` no baja la opacidad: pinta todo en los grises de deshabilitado.
+- El host lleva `role="status"`: el lector de pantalla anuncia los cambios.
+
+## Ejemplo
+
+```html
+<!-- Metadato en una lista: lighter (default) -->
+<sui-badge color="green">Conectado</sui-badge>
+
+<!-- Estado vivo -->
+<sui-badge color="green" type="with-dot">Abierto</sui-badge>
+
+<!-- Conteo que pide acción -->
+<sui-badge color="orange" variant="filled" type="number">3</sui-badge>
+```