@ajuarezso/sui-design-system 0.19.0 → 0.21.0

package/docs/sui-progress-bar/README.md

@@ -0,0 +1,132 @@
+---
+name: sui-progress-bar
+selector: sui-progress-bar
+resumen: Barra que muestra cuánto falta para completar algo, pintada con el estado de lo que mide
+alternativas: [sui-progress-bar-label (la misma barra con título, número y descripción), sui-circular-progress-bar (el avance en un círculo, junto a un título), un gráfico (repartir un total entre partes)]
+---
+
+# sui-progress-bar
+
+Story: [Atoms/Progress/Progress Bar](https://sui-design-system.web.app/?path=/docs/atoms-progress-progress-bar--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para mostrar **cuánto avanzó algo hacia un final**: una descarga, una foto que se sube,
+la meta del día, el saldo que queda. Va pelada (sin texto) solo cuando otra cosa de la pantalla ya
+dice qué mide y cuánto.
+
+**No lo uses** para:
+
+- Una barra con título o número visible: `sui-progress-bar-label` (la arma con la tipografía y el
+  espaciado del DS).
+- **Repartir un total entre partes** (visitas por dispositivo, ventas por canal): eso no es un
+  avance hacia algo, es una proporción. Va un gráfico, o la barra en `blue` si es una sola cifra.
+- Una espera sin porcentaje conocido: un spinner o un skeleton.
+
+## Qué variante usar
+
+> **La guía del DS lo define como «un gráfico simple para mostrar qué tan completo está algo»**
+> y trae cuatro colores (`blue` default, `red`, `orange`, `green`), una sola altura, `value` y
+> `max`. No dice cuándo usar cada color. Cada color apunta a un token de estado
+> (`--sui-state-*`), igual que el badge: de ahí sale su significado, que es el mismo que el del
+> badge aprobado. Lo marcado «según la guía del DS» sale de ahí; el resto es **propuesta, falta
+> aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **2 barras peladas en 1 pantalla**
+> (`overview-visitors`), sin contar prototipos ni vitrinas (`master-preview`,
+> `master-prototipos`, `mockup-sheets-*`, `dx/*`, `_guia-*`, `master-rutina`, `master-medico`,
+> `master-ejercicios`, `dev-index`). Las otras 4 barras de la app usan `sui-progress-bar-label`.
+
+### `color` — el estado de lo que mide
+
+| color | token | cuándo | ejemplo | fuente |
+|---|---|---|---|---|
+| `blue` (default) | `information` | Avance neutro: no hay nada que juzgar. | Subir una foto, descargar, pasos de un formulario | según la guía del DS (default y token) · propuesta (cuándo) |
+| `green` | `success` | Se cumplió o va bien. | Meta cumplida, saldo alto | según la guía del DS (token) · propuesta (cuándo) |
+| `orange` | `warning` | Va en curso y pide atención. | Saldo bajando, meta del día a medias | según la guía del DS (token) · propuesta (cuándo) |
+| `red` | `error` | Se perdió o se acabó. | Meta perdida, saldo agotado | según la guía del DS (token) · propuesta (cuándo) |
+| `purple` | `feature` | **No usar** (ver abajo). Extensión SUI. | — | propuesta, falta aprobación |
+
+**Ojo con el naranja**: en este proyecto el `orange` de estado (`--sui-state-warning-base`) es
+el mismo `#fa7319` de la marca. Una barra naranja sin un juicio detrás se lee como «marca», no
+como «atención».
+
+### `size`
+
+| size | alto | cuándo | fuente |
+|---|---|---|---|
+| `small` | 4 px | Web: dentro de una card o una fila densa. | propuesta, falta aprobación |
+| `medium` (default) | 6 px | Web: lo normal y la barra principal. Mobile: dentro de una fila densa. Es la única altura de la guía. | según la guía del DS |
+| `large` | 8 px | Mobile: lo normal y la barra principal (descarga, meta del día). | propuesta, falta aprobación |
+| `xlarge` | 10 px | **No usar** (ver abajo). | propuesta, falta aprobación |
+
+### `value` y `ariaLabel`
+
+| propiedad | regla | fuente |
+|---|---|---|
+| `value` | Siempre de 0 a 100. Si el dato viene como fracción (0,6) o como «3 de 5», se convierte antes. | propuesta, falta aprobación |
+| `ariaLabel` | **Obligatorio** en la barra pelada: sin título visible, el lector de pantalla no sabe qué mide. | propuesta, falta aprobación |
+
+**Usos de hoy que rompen la regla — a discutir, 2:**
+`pages/overview/components/overview-visitors/overview-visitors.html:22` y `:45` pintan en
+`orange` cómo se reparten las visitas por dispositivo. No es un avance ni pide atención: con esta
+regla va `blue`, o mejor un gráfico. Tampoco llevan `ariaLabel`.
+
+## No usar: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `color="purple"` | No está en la guía y no hay caso. | El avance de una función en prueba, con el mismo morado que el badge «Beta». |
+| `size="xlarge"` | Ninguna barra es lo único de su pantalla. | Una pantalla de carga larga, donde la barra es lo único (importar la carta de un local). |
+
+## Tamaño en mobile y en web
+
+Criterio de la app: **en mobile se lee y se toca con el dedo, así que va más grande; en web
+(desktop), más chico.** Mobile es `≤ 767 px`, el mismo corte de `BreakpointsService.isMobile()`
+en master-pedidos. Fuente: canon del dueño (03-10-2026), el mismo patrón que ya usan 27 controles
+de la app.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Dentro de una fila o card densa | `medium` (6) | `small` (4) | propuesta, falta aprobación |
+| Lo normal, y la barra que es lo principal (descarga, meta del día) | `large` (8) | `medium` (6) | propuesta, falta aprobación |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+```html
+<sui-progress-bar [value]="progreso()" [size]="bp.isMobile() ? 'medium' : 'small'" ariaLabel="Subiendo la foto" />
+```
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `value` | `number` | `0` |
+| `color` | `'blue' \| 'green' \| 'orange' \| 'red' \| 'purple'` | `'blue'` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `ariaLabel` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **No hay `max`** (la guía sí lo tiene): `value` es un porcentaje de 0 a 100, con tope.
+- **El default es `blue`**, no el naranja de la marca.
+- El azul de la barra es `--sui-state-information-base`, **no** `--sui-primary-base` (que en
+  este proyecto es naranja).
+- El ancho es el 100 % del padre: dentro de un flex, dale `flex: 1` o un ancho.
+- Lleva `role="progressbar"` con `aria-valuenow`; la animación se apaga con
+  `prefers-reduced-motion`.
+
+## Ejemplo
+
+```html
+<!-- Dentro de una fila que ya dice «Subiendo la foto · 64 %» -->
+<sui-progress-bar [value]="progreso()" ariaLabel="Subiendo la foto" />
+```

package/docs/sui-progress-bar-label/README.md

@@ -0,0 +1,143 @@
+---
+name: sui-progress-bar-label
+selector: sui-progress-bar-label
+resumen: La barra de progreso con lo que mide, cuánto va y, si hace falta, qué hacer
+alternativas: [sui-progress-bar (la barra pelada, cuando otra cosa ya la rotula), sui-circular-progress-bar (el avance en un círculo, junto a un título)]
+---
+
+# sui-progress-bar-label
+
+Story: [Atoms/Progress/Progress Bar Label](https://sui-design-system.web.app/?path=/docs/atoms-progress-progress-bar-label--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** siempre que una barra de progreso lleve **título o número visible**: «Descargando
+actualización 64 %», «Meta del día · 3 de 5 entregas», «Saldo restante · S/ 12.40 de S/ 20.00».
+Arma la barra (`sui-progress-bar` adentro), el título, el número y una fila opcional con
+descripción y link, con el espaciado del DS.
+
+**No lo uses** para:
+
+- Una barra que ya está rotulada por la fila donde vive: `sui-progress-bar`.
+- Un avance que va en un cuadrado al lado de un título: `sui-circular-progress-bar`.
+- Repartir un total entre partes: un gráfico.
+
+## Qué variante usar
+
+> **La guía del DS no tiene una página propia para esto**: son los ejemplos «With Label» y
+> «Advanced» de la página de la barra de progreso (título + «80%», y debajo un link
+> «Upgrade» con una descripción). No dice cuándo usar cada forma. Lo marcado «según la guía del
+> DS» sale de esos ejemplos; el resto es **propuesta, falta aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **4 en 3 pantallas** (la descarga del
+> OTA, el saldo y la meta del día en el dashboard del repartidor, el saldo en la billetera), sin
+> contar prototipos ni vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`,
+> `dx/*`, `_guia-*`, `master-rutina`, `master-medico`, `master-ejercicios`, `dev-index`). Todas
+> `on-top`; 3 con `percentage` de texto; 1 con `showBottom`; ninguna con `link`.
+
+`color` y `size` se eligen con las tablas de `sui-progress-bar`: el color es el **estado de lo
+que mide** (blue neutro, green cumplido, orange pide atención, red perdido o agotado).
+
+| propiedad | valor | cuándo | ejemplo real | fuente |
+|---|---|---|---|---|
+| `type` | `on-top` (default) | Título y número arriba, barra abajo. Lo normal. | Las 4 de la app | según la guía del DS («With Label») |
+| `type` | `on-right` | Sin título: barra y número en una línea, dentro de una fila que ya dice qué mide a la izquierda. | Pedidos por distrito en una tabla | propuesta, falta aprobación |
+| `title` | texto | Qué mide, en sentence case, sin punto: «Saldo restante», «Meta del día». | `pages/driver/driver-wallet/driver-wallet.html:43` | según la guía del DS |
+| `percentage` | `true` (default) | El porcentaje es la unidad que importa (una descarga). | `components/ota-update/ota-update.html:132` | según la guía del DS («80%») |
+| `percentage` | texto | Hay una unidad real: entregas, soles. «3 de 5 entregas», «S/ 12.40 de S/ 20.00». | `pages/driver/driver-dashboard/driver-dashboard.html:512` | propuesta, falta aprobación |
+| `percentage` | `false` | El número ya está escrito al lado, o no significa nada. | — | propuesta, falta aprobación |
+| `showBottom` + `description` | texto | Qué está pasando o qué hacer mientras avanza: «No cierres la app, estamos dejando todo listo.» | `components/ota-update/ota-update.html:132` | según la guía del DS («Advanced») |
+| `link` | texto o `{ label, href }` | La acción que resuelve lo que la barra avisa: «Recargar» cuando el saldo está en rojo. Va con `showBottom`. | — (sin usos) | según la guía del DS («Upgrade») · propuesta (cuándo) |
+| `ariaLabel` | texto | Lo que mide, si el título no alcanza («Saldo restante sobre el saldo de cortesía»). | `pages/driver/driver-dashboard/driver-dashboard.html:240` | propuesta, falta aprobación |
+
+**Usos de hoy que rompen la regla — a discutir, 1:**
+`components/ota-update/ota-update.html:132` pinta la descarga en `orange`. Una descarga es avance
+neutro: con la regla de color va `blue`. En la app el naranja se lee como la marca, así que puede
+ser una decisión de marca y no un error: decide el dueño. Las de saldo y meta (`driver-wallet:43`,
+`driver-dashboard:240` y `:512`) ya pintan verde, naranja y rojo según el estado: cumplen.
+
+## No usar: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `type="on-right"` | Ninguna barra de hoy vive en una fila con su nombre al lado. | Una tabla del super admin con el avance por distrito o por local. |
+| `link` | Ninguna barra de hoy ofrece la acción que la resuelve. | «Recargar» bajo el saldo del repartidor cuando está en rojo. |
+
+## Tamaño en mobile y en web
+
+Criterio de la app: **en mobile se lee y se toca con el dedo, así que va más grande; en web
+(desktop), más chico.** Mobile es `≤ 767 px`, el mismo corte de `BreakpointsService.isMobile()`
+en master-pedidos. Fuente: canon del dueño (03-10-2026), el mismo patrón que ya usan 27 controles
+de la app.
+
+El `size` solo cambia la barra; el título y el número no cambian de tamaño.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| Dentro de una card o fila densa (saldo en el dashboard) | `medium` (6) | `small` (4) | propuesta, falta aprobación |
+| Lo normal, y la barra que es lo principal (descarga, meta del día) | `large` (8) | `medium` (6) | propuesta, falta aprobación |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+```html
+<sui-progress-bar-label title="Saldo restante" [value]="balancePercent()"
+  [size]="bp.isMobile() ? 'large' : 'medium'" [color]="balanceColor()" />
+```
+
+Hoy las 4 de la app tienen un size fijo para las dos plataformas.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `value` | `number` | `0` |
+| `type` | `'on-top' \| 'on-right'` | `'on-top'` |
+| `title` | `string` | `''` |
+| `percentage` | `boolean \| string` | `true` |
+| `showBottom` | `boolean` | `false` |
+| `description` | `string` | `''` |
+| `link` | `SuiLinkConfig \| string \| null` | `null` |
+| `color` | `'blue' \| 'green' \| 'orange' \| 'red' \| 'purple'` | `'blue'` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `ariaLabel` | `string \| null` | `null` |
+
+| output | payload |
+|---|---|
+| `linkClick` | `void` |
+<!-- api:fin -->
+
+Output: `(linkClick)`. Con `link` de texto el `<a>` no navega y solo emite; con
+`{ label, href }` navega y además emite.
+
+## Trampas
+
+- **`description` y `link` solo se ven con `[showBottom]="true"`.**
+- **`on-right` ignora `title`, `description` y `link`**: solo barra y número.
+- `percentage` acepta `true`, `false` o un texto: un texto vacío vuelve al porcentaje.
+- El porcentaje automático se redondea (`64.6` → «65%»).
+- El link se pinta en el azul de información, no en el naranja de la marca.
+- Si no hay `title` y `percentage` es `false`, no se dibuja la fila de arriba.
+- Tiene el strip del `title` nativo: no aparece el tooltip gris del navegador.
+
+## Ejemplo
+
+```html
+<!-- Meta del día del repartidor -->
+<sui-progress-bar-label
+  title="Meta del día"
+  [value]="hechas / meta * 100"
+  [percentage]="hechas + ' de ' + meta + ' entregas'"
+  [color]="perdida ? 'red' : cumplida ? 'green' : 'orange'"
+  size="large" />
+
+<!-- Saldo en rojo, con la acción que lo resuelve -->
+<sui-progress-bar-label
+  title="Saldo restante" [value]="18" percentage="S/ 3.60 de S/ 20.00" color="red"
+  [showBottom]="true" link="Recargar" description="para seguir recibiendo pedidos"
+  (linkClick)="abrirRecarga()" />
+```

package/docs/sui-radio/README.md

@@ -0,0 +1,134 @@
+---
+name: sui-radio
+selector: sui-radio
+resumen: El círculo solo para elegir una opción de una lista corta, sin texto propio
+alternativas: [sui-radio-label (círculo con su texto, lista densa), sui-radio-card (opción con peso o que se toca en el teléfono), sui-select (más de 6 opciones), sui-segmented-control (2-4 modos que se aplican al instante), sui-checkbox (varias a la vez)]
+---
+
+# sui-radio
+
+Story: [Atoms/Checkbox, Radio & Switch/Radio](https://sui-design-system.web.app/?path=/docs/atoms-checkbox-radio-switch-radio--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir **una** opción de una lista corta, solo como círculo: cuando el texto vive
+en otra parte (una columna «Por defecto» en una tabla, una fila propia con foto y precio).
+Va dentro de un `sui-radio-group`, que es el que hace que elegir una desmarque la otra.
+
+**No lo uses** para:
+
+- Un círculo con su texto en una lista densa (franjas horarias): `sui-radio-label`.
+- Opciones con peso (ícono, descripción, borde) o que se tocan en el teléfono: `sui-radio-card`
+  (método de pago, tipo de entrega, motivos de cancelación). Crece con `bp.controlSize()`; el
+  radio-label no tiene `size`.
+- Más de ~6 opciones: `sui-select`.
+- 2-4 modos de la misma vista que se aplican al instante: `sui-segmented-control`.
+- Varias a la vez: `sui-checkbox`.
+
+Regla corta: **lista densa de texto → radio-label · con peso o en el teléfono → radio-card · muchas → select · sin texto → este.**
+
+## Qué variante usar
+
+> **La guía del DS lo define como control para «una sola selección de una lista corta de
+> opciones»**, y su ejemplo con label es una lista de motivos para reportar algo («Spam»,
+> «Acoso», «Infringe las reglas»). Muestra deshabilitado, con label y con label avanzado. No
+> trae do/don't de tamaños.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **2 `sui-radio` en 2 archivos**, ambos en modo suelto (`standaloneChecked`), con tamaño
+> dinámico. Más **1 `<input type="radio">` nativo**.
+
+### Estado y modo
+
+| qué | cuándo | fuente |
+|---|---|---|
+| dentro de `sui-radio-group` + `[value]` | Siempre que haya más de una opción. El grupo hace la exclusión y se enchufa a `[(ngModel)]`. | según la guía del DS (es un radio group) |
+| suelto con `[(standaloneChecked)]` | Solo cuando la exclusión la hace la fila o el padre (la fila de opciones del detalle de producto). **Suelto, al tocarlo se desmarca** como un checkbox. | propuesta, falta aprobación |
+| `disabled` | La opción existe pero no aplica ahora (una variante agotada). | según la guía del DS |
+
+### `size`
+
+| size | px | cuándo | fuente |
+|---|---|---|---|
+| `xlarge` | 28 | Mobile, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026: «componentes grandes») |
+| `large` | 24 | Desktop, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026) |
+| `medium` (default) | 20 | Solo dentro de un componente que fija su escala (detalle de producto). Es el único tamaño de la guía. | según la guía del DS (único tamaño); el «cuándo» es propuesta |
+
+**Usos de hoy que rompen la regla:**
+
+- **1 radio nativo → `sui-radio-card type="basic"`:**
+  `pages/driver/driver-order-detail/driver-order-detail.html:812` (motivos de cancelación del
+  repartidor, el mismo caso del ejemplo de la guía). La pantalla hermana del local ya lo resolvió
+  así: `pages/orders/orders.html:566`.
+- **1 suelto que se puede desincronizar:** `pages/super-admin/master-settings/master-settings.html:105`
+  (categoría por defecto). Usa `[standaloneChecked]` + `$event && …`: al tocar el que ya está
+  elegido, el círculo se apaga por dentro pero el padre sigue diciendo que es el elegido. Va en
+  un `sui-radio-group` con `[ngModel]`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web |
+|---|---|---|
+| círculo en una fila o tabla | `xlarge` (28 px) | `large` (24 px) |
+| dentro de un componente que fija su escala | lo que pase el padre | lo que pase el padre |
+
+```html
+<sui-radio [size]="bp.controlSize()" … />   <!-- isMobile() ? 'xlarge' : 'large' -->
+```
+
+El más grande mide 28 px: el área táctil de 44 px la tiene que dar la fila.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| suelto (`standaloneChecked`) fuera de una fila propia | se desmarca al tocarlo de nuevo: no es un radio | nunca como grupo; solo como dibujo dentro de una fila que maneja el clic |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+### `sui-radio`
+
+| input | tipo | default |
+|---|---|---|
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `value` | `SuiRadioValue` | `null` |
+| `disabled` | `boolean` | `false` |
+| `standaloneChecked` · model, `[(standaloneChecked)]` | `boolean` | `false` |
+
+Outputs: ninguno.
+
+### `sui-radio-group`
+
+Inputs: ninguno.
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+`sui-radio-group`: sin inputs; implementa `ControlValueAccessor` (`[(ngModel)]`, `formControlName`)
+y proyecta los radios (`sui-radio`, `sui-radio-label`, `sui-radio-card`).
+
+## Trampas
+
+- **Suelto, togglea.** `standaloneChecked` se invierte con cada toque: se puede desmarcar. Para
+  semántica de radio, `sui-radio-group`.
+- **`sui-radio-group` no tiene `value`**: se maneja con `[(ngModel)]` o un form control.
+- **`sui-radio-group` es `inline-flex` en fila con gap 16.** Para lista vertical hay que darle
+  `flex-direction: column; align-items: flex-start` desde afuera.
+- **Deshabilitar el control del grupo no deshabilita los radios** (`setDisabledState` no hace
+  nada): pasa `[disabled]` a cada uno.
+- No hay `small`: el más chico es `medium` (20 px).
+- Sin marcar, en foco, el círculo se pinta del color de marca: viene del Figma, no es un error.
+- No dibuja texto ni `aria-label`: pelado, pon el texto en un `<label>` o usa `sui-radio-label`.
+
+## Ejemplo
+
+```html
+<sui-radio-group [(ngModel)]="categoriaPorDefecto">
+  @for (cat of categorias; track cat.id) {
+    <sui-radio [size]="bp.controlSize()" [value]="cat.id" [attr.aria-label]="cat.nombre" />
+  }
+</sui-radio-group>
+```

package/docs/sui-radio-card/README.md

@@ -0,0 +1,160 @@
+---
+name: sui-radio-card
+selector: sui-radio-card
+resumen: Opción con tarjeta (ícono o foto, título, descripción y el radio) para elegir UNA de una lista corta
+alternativas: [sui-radio-label (la misma elección sin tarjeta, en un formulario denso), sui-select (lista larga o que no entra en pantalla), sui-segmented-control (2–4 vistas de la misma pantalla), sui-checkbox-card (se pueden elegir varias), sui-switch-card (se prende o se apaga un ajuste)]
+---
+
+# sui-radio-card
+
+Story: [Molecules/Card/Radio Card](https://sui-design-system.web.app/?path=/docs/molecules-card-radio-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir una sola opción de una lista corta cuando cada opción merece explicarse:
+«Delivery / Recojo en tienda», cómo cobrar («A mi saldo / Por Yape»), el medio de pago, el motivo
+de una cancelación, el modo de asignación de repartidores.
+
+**No lo uses** para:
+
+- Varias opciones que se suman: `sui-checkbox-card`.
+- Un ajuste que se prende o se apaga: `sui-switch-card`.
+- Una lista larga (más de 6–7 opciones) o que crece con los datos: `sui-select`.
+- Cambiar de vista dentro de la misma pantalla: `sui-segmented-control` o tabs.
+
+Regla corta: **una de pocas, con explicación → radio-card · una de muchas → select · varias →
+checkbox-card.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la radio card.** De la guía sale solo lo del radio que lleva
+> adentro: **«para elegir una sola opción de una lista corta»**. El resto es práctica de la app
+> («propuesta») o regla ya aprobada («canon»).
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **31
+> radio-cards en 14 archivos**. Tipos: 23 `left-icon` (3 de ellos con emoji animado por
+> `iconSrc`), 6 `basic`, 1 `avatar`, 1 `company`. Tamaños: 24 `bp.controlSize()`, 4 `medium`, 1
+> `xlarge` fijo, 1 dinámico, 1 sin `size`. 6 con `sublabel`, 3 con `disabled`, 1 con `badge`.
+
+### `type` (el leading)
+
+| type | cuándo | fuente |
+|---|---|---|
+| `left-icon` con `icon` | Lo normal: un ícono Remix que dice de qué va la opción (`truck-line` Delivery, `store-2-line` Recojo). | propuesta (práctica de la app) |
+| `left-icon` con `iconSrc` | Emoji animado cuando la elección es de las grandes del rol (el vehículo del repartidor, el rol al registrarse, el tipo de mandadito). Los emojis van de `assets/emojis/` o `FLUENT_EMOJI_ANIM`. | propuesta |
+| `left-icon` con `emoji` | Lo mismo con un nombre de `SuiEmoji` en vez de una URL. Hoy 0 usos; vale igual. | propuesta |
+| `basic` | Opciones de texto puro: motivos de cancelación, quién paga el envío, los premios de una meta. | propuesta |
+| `avatar` (`imageUrl`) | El logo redondo de un medio de pago (Yape, Plin, efectivo en el checkout). | propuesta |
+| `company` (`imageUrl`) | Elegir entre tus locales (cambiar de negocio en mi-negocio). | propuesta |
+| `brand`, `card-provider` | Ver «No usar». | propuesta |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `value` (obligatorio) | Siempre, aunque no haya grupo. Es lo que emite `selected`. | propuesta |
+| `label` | Siempre. El nombre de la opción, corto: «Delivery», «Lo antes posible». | propuesta |
+| `description` | Casi siempre: la consecuencia de elegirla («Lo revisamos y te transferimos. Puede tardar unas horas.»). | propuesta |
+| `sublabel` | Una precisión corta entre paréntesis («(canal estable)», «(sin OTA)»). Nunca la explicación: eso es `description`. | propuesta |
+| `badge` | Marca una opción frente a las otras: «Por defecto». Con string sale azul `light`; pasa el objeto con el color que corresponda según el badge (un «Por defecto» es `gray`). | propuesta |
+| `disabled` | La opción existe pero hoy no se puede: di por qué en la `description` («El local está cerrado ahora»). | propuesta |
+| `checked` / `[(ngModel)]` / `sui-radio-group` | El estado: `[checked]` + `(selected)` sueltos (lo normal en la app), o `ngModel` con `name` (checkout), o dentro de un `sui-radio-group`. | propuesta |
+
+### `size` (el radio de adentro)
+
+| size | cuándo | fuente |
+|---|---|---|
+| `xlarge` (28) | Mobile, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026: «componentes grandes») |
+| `large` (24) | Desktop, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026) |
+| `medium` (20, default) | No usar en pantallas nuevas. | canon (aprobado por el dueño, 28-09-2026) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **5 sin el size del breakpoint**: `components/por-cobrar-card/por-cobrar-card.html:38` y `:48`,
+  `pages/driver/driver-dashboard/driver-dashboard.html:581`,
+  `pages/super-admin/master-orders/master-orders.html:720` (los cuatro en `medium`) y
+  `pages/mi-negocio/mi-negocio.html:22` (sin `size`). Además `pages/customer/mandadito/mandadito.html:30`
+  va en `xlarge` fijo (en web debería ser `large`).
+- **A revisar:** `pages/super-admin/master-orders/master-orders.html:720` lista a los repartidores
+  candidatos, una lista que crece con la flota (con muchos, `sui-select` o una lista con búsqueda).
+  `pages/role-selector/role-selector.html:24` usa la radio como botón: elegir ya avanza, sin
+  `[checked]`.
+
+## Tamaño en mobile y en web
+
+La card entera es el área táctil (≥ 72 de alto con descripción, 16 de padding): llega al piso de
+44 sola. El `size` cambia solo el radio.
+
+| uso | mobile | web |
+|---|---|---|
+| toda radio-card | `xlarge` (radio 28) | `large` (radio 24) |
+
+```html
+<sui-radio-card [size]="bp.controlSize()" … />   <!-- isMobile() ? 'xlarge' : 'large' -->
+```
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `type="brand"` (0 usos) | no hay servicios de terceros que elegir | elegir el canal por el que te contactamos (WhatsApp, correo) con su logo (`brand`) |
+| `type="card-provider"` (0 usos) | no hay pago con tarjeta guardada | elegir una tarjeta guardada en el checkout, cuando entre Culqi / Niubiz |
+| `size="medium"` | el radio de 20 se pierde en el teléfono | una tabla densa solo de desktop |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `type` | `'basic' \| 'left-icon' \| 'avatar' \| 'card-provider' \| 'brand' \| 'company'` | `'basic'` |
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `value` | `string` | — (requerido) |
+| `label` | `string` | `''` |
+| `sublabel` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `icon` | `string \| null` | `null` |
+| `emoji` | `SuiEmojiName \| null` | `null` |
+| `iconSrc` | `string \| null` | `null` |
+| `imageUrl` | `string \| null` | `null` |
+| `brand` | `SuiBrandLogoCompany \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `disabled` | `boolean` | `false` |
+| `checked` · model, `[(checked)]` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `selected` | `string` |
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` (el valor del form es el `value` elegido). Dentro de un
+`sui-radio-group`, el grupo decide cuál está marcada.
+
+## Trampas
+
+- **`value` es obligatorio** aunque la uses suelta: sin él Angular tira error de input requerido.
+- **Precedencia del leading en `left-icon`: `icon` > `emoji` > `iconSrc`.** Si pasas `icon` y
+  `iconSrc`, gana el ícono.
+- Con `iconSrc` el círculo pasa a modo «relleno» (sin padding): el emoji ocupa los 40 × 40.
+- `avatar`, `company` y `card-provider` leen la imagen de **`imageUrl`**; `brand` lee `brand` (o
+  `imageUrl` si la marca no está en el catálogo). No hay slot para proyectar el leading (a
+  diferencia de `sui-checkbox-card`).
+- Suelta (sin grupo), elegirla la marca pero **no desmarca a las otras**: el padre tiene que
+  bindear `[checked]` de todas a la misma señal.
+- `badge` con string sale **azul `light` `small`** (en `sui-content-label` sale naranja).
+- `size` cambia solo el radio, no el padding ni el alto de la card.
+
+## Ejemplo
+
+```html
+<sui-radio-card
+  [size]="bp.controlSize()"
+  type="left-icon"
+  value="pickup"
+  icon="store-2-line"
+  label="Recojo en tienda"
+  description="Lo recoges en el local"
+  [checked]="modo() === 'pickup'"
+  (selected)="modo.set('pickup')" />
+```