@ajuarezso/sui-design-system 0.19.0 → 0.21.0

package/docs/sui-chart-legend/README.md

@@ -0,0 +1,140 @@
+---
+name: sui-chart-legend
+selector: sui-chart-legend
+resumen: Leyenda de un gráfico — punto de color, nombre de la serie y su valor — dibujada fuera del gráfico
+alternativas: [sui-chart-legend-dot (el punto suelto, en una fila o tabla), la leyenda propia de ECharts (cuando hay que poder apagar series tocándolas), sui-badge (una etiqueta, no una serie)]
+---
+
+# sui-chart-legend
+
+Story: [Molecules/Chart/Chart Legend](https://sui-design-system.web.app/?path=/docs/molecules-chart-chart-legend--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** debajo o al lado de un gráfico para decir **qué es cada color**, y cuánto suma cada
+serie si el número importa («Yape 42 · Efectivo 31 · Plin 9»). Es texto de la página, así que se lee
+igual en el celular, sin tocar nada.
+
+**No lo uses** para:
+
+- Una leyenda que tiene que **apagar series** al tocarlas: eso lo hace la leyenda de ECharts
+  (`legend: {…}`), que es interactiva. Esta no tiene clic.
+- Un estado o una categoría que no viene de un gráfico: `sui-badge` o `sui-status-badge`.
+- Esconder los números en un tooltip: en el celular no hay hover (así lo hizo bien
+  `pages/super-admin/master-drivers/master-drivers.html:226`).
+
+## Qué variante usar
+
+> La guía del DS no tiene página para este componente: sale del Figma del DS (set «Chart Legends»).
+> Todo lo de abajo es **propuesta**, salvo lo marcado «según el componente» o «canon».
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas): **1 uso**, más
+> **5 leyendas hechas a mano** y **9 gráficos con la leyenda de ECharts**.
+
+### `items` — cada serie
+
+| campo | valor | cuándo | fuente |
+|---|---|---|---|
+| `label` | nombre corto | El nombre de la serie, tal como se dice en la app: «Entregados», «Yape». | propuesta |
+| `color` | sin pasar | **Lo normal** en categorías sin bien ni mal (canales, métodos de pago, distritos): el componente reparte azul, naranja, rojo, verde… en orden. | según el componente (orden) · cuándo: propuesta |
+| `color` | el del estado | Cuando la serie **es un estado**: entregados `green`, cancelados `red`, pendientes `orange`. Mismo significado que en `sui-badge`. | canon (colores con significado del badge) |
+| `customColor` | el color que ya usa el gráfico | Solo cuando el gráfico tiene su propia paleta y el punto tiene que coincidir. Va el mismo valor en los dos lados. | propuesta |
+| `value` | número o texto | Cuando el número importa para leer el gráfico: «42», «S/ 1,200», «38 %». | propuesta |
+| `disabled` | `true` | Una serie sin datos en el período: se ve, apagada, para que no parezca que falta. | propuesta |
+
+Los 12 valores de `color`, uno por uno y con su regla, están en el README de `sui-chart-legend-dot`.
+
+Para que el gráfico y la leyenda pinten **el mismo color**, ECharts recibe la paleta desde
+`SUI_CHART_LEGEND_HEX` (exportado por el paquete): `color: [SUI_CHART_LEGEND_HEX.blue, …]`.
+
+### `orientation`
+
+| orientation | cuándo | fuente |
+|---|---|---|
+| `horizontal` (default) | Debajo de un gráfico de barras o de líneas. Si no entra, baja a la línea siguiente. | propuesta |
+| `vertical` | Al lado de una dona o un pie, con el `value` de cada serie. En mobile, debajo de la dona. | propuesta |
+
+### Usos de hoy que romperían la regla
+
+- **5 leyendas hechas a mano** (punto con `[style.background]` + nombre + valor) → `sui-chart-legend`
+  con `customColor` o la paleta del DS: `components/marketing-channels/marketing-channels.html:10`,
+  `components/customer-segments/customer-segments.html:26`,
+  `pages/overview/components/overview-retention/overview-retention.html:12`,
+  `pages/reports/reports.html:59` y `:80`.
+- **A discutir — 9 gráficos con la leyenda de ECharts**: `pages/super-admin/master-semanas/master-semanas.ts:187`
+  (y `:248`, `:288`, `:335`), `pages/super-admin/master-overview/master-overview.ts:264` y `:401`,
+  `pages/reports/reports.ts:338` y `:381`, `core/utils/chart-barras-repartidores.ts:166`. Si nadie
+  apaga series tocándolas, pasarían a `sui-chart-legend` (fuente, tamaño y color del DS en vez de
+  `#525252` y 12 px puestos a mano). `pages/reports/` tiene además la leyenda a mano: hay dos
+  leyendas para el mismo gráfico.
+
+## Tamaño en mobile y en web
+
+**No tiene `size`**: punto de 16 px y texto de 12 en las dos. No se toca, así que no tiene mínimo
+para el dedo; lo que cambia por plataforma es la orientación.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| bajo barras o líneas | `horizontal` (envuelve) | `horizontal` | propuesta |
+| junto a una dona | `vertical`, **debajo** de la dona | `vertical`, a la derecha | propuesta |
+
+```html
+<sui-chart-legend [orientation]="bp.isMobile() ? 'horizontal' : 'vertical'" [items]="metodos()" />
+```
+
+El texto de 12 px queda chico en mobile y el componente no tiene un tamaño mayor: no se cambia aquí.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `disabled` | ningún gráfico muestra series vacías | una serie sin datos en el período elegido |
+| `customColor` con un hex propio | la paleta del DS ya cubre las series | un gráfico con colores de marca de terceros (Yape morado, Plin celeste) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `items` | `readonly SuiChartLegendItem[]` | — (requerido) |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+```ts
+interface SuiChartLegendItem {
+  label: string;
+  color?: SuiChartLegendColor;  // 'gray' | 'light-gray' | 'blue' | 'orange' | 'red' | 'green' | 'yellow' | 'purple' | 'sky' | 'pink' | 'teal' | 'disabled'
+  customColor?: string;         // cualquier color CSS; gana sobre `color`
+  value?: string | number;
+  disabled?: boolean;           // gana sobre los dos colores
+}
+```
+
+## Trampas
+
+- **Sin `color`, los colores salen en orden fijo** (azul, naranja, rojo, verde, amarillo…), no los
+  del gráfico: si ECharts usa otra paleta, el punto y la barra no coinciden. Usa
+  `SUI_CHART_LEGEND_HEX` en el gráfico o pasa el color.
+- El orden automático empieza en **azul**, no en el naranja de la marca.
+- `value` sale a 4 px del nombre, en negro (el nombre va en gris): el formato («S/ 1,200», «38 %») lo arma quien la usa.
+- Host con `role="list"` y cada item `role="listitem"`; el punto es decorativo.
+- `items` es obligatorio.
+
+## Ejemplo
+
+```html
+<sui-chart-legend orientation="vertical" [items]="[
+  { label: 'Yape', value: 42 },
+  { label: 'Efectivo', value: 31 },
+  { label: 'Plin', value: 9 },
+]" />
+
+<sui-chart-legend [items]="[
+  { label: 'Entregados', color: 'green', value: '86 %' },
+  { label: 'Cancelados', color: 'red', value: '14 %' },
+]" />
+```

package/docs/sui-chart-legend-dot/README.md

@@ -0,0 +1,118 @@
+---
+name: sui-chart-legend-dot
+selector: sui-chart-legend-dot
+resumen: Punto de color de una serie de gráfico, para atar un número de una fila o una tabla con su color en el gráfico
+alternativas: [sui-chart-legend (la leyenda completa, que ya trae sus puntos), sui-color-dot (elegir un color, no nombrar una serie), sui-badge with-dot (un estado vivo)]
+---
+
+# sui-chart-legend-dot
+
+Story: [Molecules/Chart/Chart Legend Dot](https://sui-design-system.web.app/?path=/docs/molecules-chart-chart-legend-dot--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** suelto cuando una fila o una tabla **habla de una serie del gráfico** y el color la ata:
+«● Delivery 64 %» en el resumen bajo una dona, la columna de una tabla que repite las barras.
+
+**No lo uses** para:
+
+- La leyenda de un gráfico: `sui-chart-legend` ya trae sus puntos.
+- Elegir un color (variantes de un producto): `sui-color-dot`.
+- Marcar un estado vivo («Abierto», «En línea»): `sui-badge` con `type="with-dot"`.
+- La línea de tiempo de una actividad: `sui-activity-feed`.
+
+## Qué variante usar
+
+> La guía del DS no tiene página para este componente: sale del Figma del DS (set «Chart Legend
+> Dots»). Todo lo de abajo es **propuesta**, salvo lo marcado «según el componente» o «canon».
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos sueltos** (sí dentro de la única
+> `sui-chart-legend`), y **3 puntos de serie hechos a mano** fuera de una leyenda.
+
+### `color`
+
+Cada color apunta al mismo estado de la paleta que en `sui-badge`. En un gráfico manda una regla:
+**el mismo color que la serie en el gráfico**.
+
+| color | estado de la paleta | cuándo | fuente |
+|---|---|---|---|
+| `blue` | information | Primera serie de categorías sin carga (el orden automático arranca aquí). | según el componente (orden) |
+| `orange` | warning | Pendiente; o segunda serie de categorías. | canon (significado del badge) · como serie de categorías: propuesta |
+| `red` | error | Cancelado, rechazado, fallido. | canon (significado del badge) |
+| `green` | success | Entregado, pagado, aprobado. | canon (significado del badge) |
+| `yellow` | away | En pausa; o una serie más de categorías. | canon (significado del badge) · como serie de categorías: propuesta |
+| `purple` | feature | Lo nuevo; o una serie más de categorías. | canon (significado del badge) · como serie de categorías: propuesta |
+| `sky` · `pink` · `teal` | verified · highlighted · stable | Series de categorías a partir de la séptima. | propuesta |
+| `gray` (default) | faded | «Otros» o «Sin categoría»: lo que no se reparte. | propuesta |
+| `light-gray` | — | No usar: es el mismo gris del apagado. **Cuándo sí:** el resto de una barra de progreso partida («lo que falta»). | propuesta |
+| `disabled` | — | Una serie sin datos o apagada. Dentro de `sui-chart-legend` va por `disabled: true`, no por color. | según el componente |
+| `customColor` | el color que ya usa el gráfico | Solo si el gráfico tiene paleta propia; gana sobre `color`. | propuesta |
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `small` (16 px) | Junto a texto de 12 (como en la leyenda, que lo usa siempre). | según el componente |
+| `medium` (20 px, default) | Junto a texto de 14: filas y tablas. | propuesta |
+
+El círculo de color mide 12 px en los dos tamaños: lo que cambia es el aire alrededor.
+
+### Usos de hoy que romperían la regla
+
+- **3 puntos de serie hechos a mano** (`<span>` con `[style.background]`) → `sui-chart-legend-dot`:
+  `components/customer-retention/customer-retention.html:17`,
+  `components/order-fulfillment/order-fulfillment.html:17`,
+  `components/cancellation-rate/cancellation-rate.html:33`.
+- Las 5 leyendas hechas a mano están contadas en `sui-chart-legend`.
+
+## Tamaño en mobile y en web
+
+Es decorativo y no se toca: no tiene mínimo para el dedo.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| fila de resumen o tabla | `medium` (20) | `medium` (20) | propuesta |
+| junto a texto de 12 | `small` (16) | `small` (16) | según el componente |
+
+No cambia por plataforma: va con el tamaño del texto que acompaña, no con la pantalla.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `light-gray` | es el gris del apagado | el resto de una barra partida |
+| `sky`, `pink`, `teal` | ningún gráfico pasa de 6 series | un gráfico por distrito o por local con 7 series o más |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `color` | `'gray' \| 'light-gray' \| 'blue' \| 'orange' \| 'red' \| 'green' \| 'yellow' \| 'purple' \| 'sky' \| 'pink' \| 'teal' \| 'disabled'` | `'gray'` |
+| `size` | `'medium' \| 'small'` | `'medium'` |
+| `customColor` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+Constantes exportadas: `SUI_CHART_LEGEND_COLORS` (los 11 colores en el orden del Figma),
+`SUI_CHART_SERIES_COLORS` (el orden automático: azul, naranja, rojo, verde…) y
+`SUI_CHART_LEGEND_HEX` (color → hex, para darle la misma paleta a ECharts).
+
+## Trampas
+
+- **El default es `gray`**, no un color de serie: sin `color` todos los puntos salen grises.
+- `size` arranca en `medium` aquí, pero la leyenda usa siempre `small`.
+- El punto lleva un anillo blanco y una sombra para separarse del gráfico: sobre un fondo blanco
+  se ve un poco más chico que un círculo plano del mismo tamaño.
+- `SUI_CHART_LEGEND_HEX` tiene los hex del modo claro: en modo oscuro no se invierten.
+- Es decorativo (`aria-hidden`): el significado lo dice el texto de al lado.
+
+## Ejemplo
+
+```html
+<span class="fila"><sui-chart-legend-dot color="green" /> Entregados <b>86 %</b></span>
+<span class="fila"><sui-chart-legend-dot color="red" /> Cancelados <b>14 %</b></span>
+```

package/docs/sui-checkbox/README.md

@@ -0,0 +1,147 @@
+---
+name: sui-checkbox
+selector: sui-checkbox
+resumen: La casilla sola para marcar una o varias opciones, sin texto propio
+alternativas: [sui-checkbox-label (casilla con su texto, el caso normal), sui-checkbox-card (cada opción es una tarjeta), sui-switch (prende algo que se aplica al instante), sui-radio (opciones excluyentes)]
+---
+
+# sui-checkbox
+
+Story: [Atoms/Checkbox, Radio & Switch/Checkbox](https://sui-design-system.web.app/?path=/docs/atoms-checkbox-radio-switch-checkbox--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para marcar opciones que se suman (varias a la vez) y que se confirman después con
+un botón: permisos de un miembro del equipo, categorías a las que se aplica algo, productos de
+una lista. **Solo la casilla**: úsalo pelado cuando el texto vive en otra parte (una celda de
+tabla, una fila propia con foto y precio, el «seleccionar todo» de una cabecera).
+
+**No lo uses** para:
+
+- **Una casilla con su texto al lado** (el caso de casi siempre): eso es `sui-checkbox-label`,
+  que trae el texto, la descripción y el clic en toda la fila. Armar `<label>` + `sui-checkbox`
+  + `<span>` a mano es justo lo que ese componente evita.
+- Prender o apagar algo que se aplica al instante (notificaciones, disponibilidad): `sui-switch`.
+- Elegir una sola opción entre varias: `sui-radio` / `sui-radio-label`.
+- Una opción que merece tarjeta (ícono, descripción, borde que se pinta): `sui-checkbox-card`.
+
+Regla corta: **se suma y se confirma después → checkbox · se aplica ya → switch · una sola → radio.**
+
+## Qué variante usar
+
+> **La guía del DS dice para qué es, no qué tamaño usar.** Su página lo define como control de
+> formulario «para selecciones simples y múltiples» y muestra deshabilitado, con label y con label
+> avanzado (sublabel, badge, descripción y link). Lo marcado «según la guía del DS» sale de ahí;
+> el resto es canon del dueño o propuesta.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`, sin contar prototipos ni vitrinas
+> (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `_guia-*`, `master-rutina`,
+> `master-medico`, `dev-index`): **5 checkbox en 3 archivos**, todos con tamaño dinámico
+> (`bp.controlSize()` / `ctrlSize()` = `large` en desktop, `xlarge` en mobile, y uno con el
+> `size()` del padre). Más **1 `<input type="checkbox">` nativo** que debería ser este componente.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: selecciones simples y múltiples dentro de un formulario.
+- **Deshabilitado**: existe deshabilitado sin marcar y deshabilitado marcado.
+- **Con texto**: el texto al lado es parte del componente (en SUI, `sui-checkbox-label`).
+- Los tamaños de la guía son dos (16 y 20 px). `large` (24) y `xlarge` (28) son extensión de SUI.
+
+### Estado (`checked`, `indeterminate`, `disabled`)
+
+| estado | cuándo | fuente |
+|---|---|---|
+| sin marcar / marcado | Lo normal. `[(checked)]` o `formControlName`. | según la guía del DS |
+| `indeterminate` | Solo en el «seleccionar todo» de una lista cuando hay algunas marcadas y otras no. Se ve un guion. Hoy no usar (0 casos, ver abajo). | propuesta, falta aprobación |
+| `disabled` | La opción existe pero hoy no se puede tocar (un producto agotado en las opciones de un plato). Decir por qué cerca. | según la guía del DS (existe); el «cuándo» es propuesta |
+
+### `size`
+
+| size | px | cuándo | fuente |
+|---|---|---|---|
+| `xlarge` | 28 | Mobile. Viene de `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026: «componentes grandes») |
+| `large` | 24 | Desktop. Viene de `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026) |
+| `medium` (default) | 20 | Solo dentro de un componente que ya fija su escala (la fila de opciones del detalle de producto recibe el `size` del padre). | propuesta, falta aprobación |
+| `small` | 16 | No usar (ver abajo). | canon (aprobado por el dueño, 28-09-2026) |
+
+Regla: **`[size]="bp.controlSize()"`** en toda pantalla. Así ya están los 5 usos de hoy.
+
+**Usos de hoy que rompen la regla de componente:**
+
+- **4 `sui-checkbox` envueltos en un `<label>` hecho a mano con su texto → `sui-checkbox-label`.**
+  `pages/settings/team/team.html:225` y `:294` (permisos: «Gestionar productos»…),
+  `components/option-sections-manager/option-sections-manager.html:188` (categorías) y `:210`
+  (productos).
+- **1 checkbox nativo → `sui-checkbox-label`:** `pages/sales-channels/facebook/facebook.html:69`
+  («Qué se sincroniza»).
+- **Ojo antes de migrar:** `sui-checkbox-label` **no tiene `size`**; su casilla queda en 20 px.
+  Los 4 de arriba hoy están en 24/28 px. Migrarlos sin que el DS le sume `size` al label los
+  achica, contra la regla de controles grandes. Primero el `size` en el DS, después la migración.
+- El de `components/product-detail-view/product-detail-view.html:204` está bien pelado: la fila
+  es propia (foto, nombre, precio) y es la fila la que recibe el clic.
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: el control va grande y el área táctil (≥ 44 px) la da la fila
+que lo contiene. En web va un escalón más chico.
+
+| uso | mobile | web |
+|---|---|---|
+| casilla en una lista, tabla o fila de formulario | `xlarge` (28 px) | `large` (24 px) |
+| dentro de un componente que fija su escala (fila de opciones del detalle de producto) | lo que pase el padre | lo que pase el padre |
+
+```html
+<sui-checkbox [size]="bp.controlSize()" … />   <!-- controlSize() = isMobile() ? 'xlarge' : 'large' -->
+```
+
+El más grande mide 28 px: ningún tamaño llega a 44 px por sí solo. La fila (o el `<label>` que
+envuelve) tiene que medir al menos 44 px de alto para que el toque sea cómodo.
+
+## «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="small"` (16 px) | en el teléfono se pierde y no llega al área táctil (el dueño pidió controles grandes) | una tabla densa solo de desktop con selección por fila (super admin), donde 24 px desalinea la fila |
+| `indeterminate` (0 usos) | ninguna lista tiene «seleccionar todo» | el «seleccionar todo» de una lista de productos o pedidos con acciones en lote |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `checked` · model, `[(checked)]` | `boolean` | `false` |
+| `indeterminate` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor`: funciona con `[(ngModel)]` y `formControlName`. Sin slots.
+
+## Trampas
+
+- **No tiene `label`.** Para el texto está `sui-checkbox-label`. Y el host lleva `role="checkbox"`
+  sin `aria-label` propio: pelado, ponle `aria-label="…"` o un `<label>` que lo envuelva.
+- **`checked` es model; `indeterminate` es input.** Hay `[(checked)]` pero no `[(indeterminate)]`,
+  y el componente **no limpia el guion solo** al tocarlo: mientras `indeterminate` siga en `true`
+  se ve el guion aunque cambie `checked`.
+- El relleno marcado es el `primary` del proyecto (naranja), no el azul del Figma de origen.
+- Espacio **y** Enter lo marcan (un checkbox nativo solo responde a Espacio).
+- El tilde es un SVG dibujado a mano: no se cambia el ícono.
+- Ya trae el arreglo de iOS para el `:active` pegado: no lo agregues.
+
+## Ejemplo
+
+```html
+<!-- Pelado, el texto vive en la fila (celda de tabla, fila propia) -->
+<sui-checkbox [size]="bp.controlSize()" [(checked)]="seleccionado" aria-label="Elegir pedido" />
+
+<!-- Con texto: usa sui-checkbox-label, no esto a mano -->
+<sui-checkbox-label label="Gestionar productos" [(active)]="puedeProductos" />
+```

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

@@ -0,0 +1,150 @@
+---
+name: sui-checkbox-card
+selector: sui-checkbox-card
+resumen: Opción con tarjeta (ícono o foto, título, descripción y la casilla) para elegir VARIAS que se guardan después
+alternativas: [sui-checkbox-label (la misma casilla sin tarjeta, en un formulario denso), sui-switch-card (un ajuste que se aplica al toque, sin «Guardar»), sui-radio-card (se elige solo una), sui-tag-input (valores que la persona escribe)]
+---
+
+# sui-checkbox-card
+
+Story: [Molecules/Card/Checkbox Card](https://sui-design-system.web.app/?path=/docs/molecules-card-checkbox-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para elegir varias opciones que se suman y que se confirman con «Guardar»: las formas
+de entrega del local («Recojo en tienda» + «Delivery»), los métodos de pago que acepta, los días
+de atención.
+
+**No lo uses** para:
+
+- Un ajuste que tiene efecto al toque, sin botón de guardar: `sui-switch-card`.
+- Elegir una sola: `sui-radio-card`.
+- Una lista larga de casillas en un formulario: `sui-checkbox-label` (sin tarjeta, ocupa menos).
+- Aceptar términos o confirmar algo: `sui-checkbox-label`.
+
+Regla corta: **varias que se guardan después → checkbox-card · se aplica al toque → switch-card ·
+una → radio-card.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la checkbox card.** De la guía sale solo lo del checkbox que
+> lleva adentro: **«para selecciones simples y múltiples»**. La frontera con el switch («se
+> confirma después con Guardar → checkbox») ya es canon desde el README de `sui-switch-label`.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-card`): **3
+> checkbox-cards en 2 archivos**, los 3 `left-icon` con ícono y descripción (formas de entrega en
+> mi-negocio y en locales administrados). 2 con `bp.controlSize()`, 1 sin `size`. Hay **5
+> `sui-switch-card` que deberían ser este componente** (los métodos de pago de mi-negocio).
+
+### `type` (el leading)
+
+| type | cuándo | fuente |
+|---|---|---|
+| `left-icon` (`icon`, `emoji` o `iconSrc`) | Lo normal: un ícono que dice de qué va la opción. | propuesta (los 3 de hoy) |
+| `basic` | Ver «No usar». | propuesta |
+| `avatar` (`imageUrl`) | Ver «No usar». | propuesta |
+| `card-provider`, `brand`, `company` | Ver «No usar». El logo lo proyectas tú con `slot="leading"`. | propuesta |
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre. El nombre de la opción: «Delivery». | propuesta |
+| `description` | Lo que significa elegirla: «Llevas los pedidos a la dirección del cliente». | propuesta (los 3 de hoy) |
+| `sublabel` | Precisión corta entre paréntesis. | propuesta |
+| `badge` | Marca una opción frente a las otras («Nuevo»). Con string sale azul `light`. | propuesta |
+| `indeterminate` | Una casilla que resume a otras («Todos los días» con algunos marcados). | propuesta |
+| `disabled` | La opción no aplica hoy; di por qué en la `description`. | propuesta |
+| `checked` | `[checked]` + `(checkedChange)`, o `[(checked)]`, o `formControlName`. | propuesta |
+
+### `size` (la casilla de adentro)
+
+| size | cuándo | fuente |
+|---|---|---|
+| `xlarge` | Mobile, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026: «componentes grandes») |
+| `large` | Desktop, vía `bp.controlSize()`. | canon (aprobado por el dueño, 28-09-2026) |
+| `medium` (default), `small` | No usar en pantallas nuevas. | canon (aprobado por el dueño, 28-09-2026) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **1 sin `size`**: `pages/super-admin/master-administrados/master-administrados.html:172`.
+- **5 `sui-switch-card` que se guardan con «Guardar cambios»** y por lo tanto van aquí: los métodos
+  de pago de `pages/mi-negocio/mi-negocio.html:1181`, `:1190`, `:1199`, `:1208`, `:1217`
+  («Puedes seleccionar varias», dice la misma pantalla).
+
+## Tamaño en mobile y en web
+
+La card entera es el área táctil (≥ 72 con descripción): llega al piso de 44 sola. El `size`
+cambia solo la casilla.
+
+| uso | mobile | web |
+|---|---|---|
+| toda checkbox-card | `xlarge` | `large` |
+
+```html
+<sui-checkbox-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="basic"` (0 usos) | las opciones de hoy llevan ícono | opciones de texto que se suman (los días de atención, los tamaños de un producto) |
+| `type="avatar"` (0 usos) | no se elige gente de a varios | elegir a varios repartidores para mandarles un aviso |
+| `type="brand"` / `"company"` / `"card-provider"` (0 usos) | no hay integraciones ni tarjetas | prender varias integraciones a la vez (logo proyectado), varias sucursales de un local |
+| `size="medium"` / `"small"` | la casilla 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` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `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` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `indeterminate` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `checked` · model, `[(checked)]` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `checkedChange2` | `boolean` |
+<!-- api:fin -->
+
+Slot: `[slot=leading]` (solo para `card-provider`, `brand` y `company`). Implementa
+`ControlValueAccessor` (valor `boolean`).
+
+## Trampas
+
+- **Hay dos outputs con el mismo dato**: `checkedChange` (lo crea el `model`) y `checkedChange2`
+  (el explícito, nombre de compatibilidad). Usa `(checkedChange)` o `[(checked)]`, como la app.
+- **Es no controlada**: el toque cambia el estado adentro aunque no actualices nada afuera (al
+  revés que `sui-switch-card`). Si tu señal no se entera, el visual y tu estado se separan.
+- **El leading de `card-provider`, `brand` y `company` se proyecta** con `slot="leading"`
+  (atributo `slot=`, no `sui-…-leading` como en la switch-card). Sin proyección queda el hueco.
+- Con `avatar`, si `imageUrl` falla salen las iniciales del `label`.
+- El leading de 40 × 40 ya trae `box-sizing: border-box` (el proyecto no tiene reset global): si
+  proyectas una imagen con padding o borde propios, ponle `box-sizing` tú.
+- `badge` con string sale **azul `light` `small`**.
+
+## Ejemplo
+
+```html
+<sui-checkbox-card
+  [size]="bp.controlSize()"
+  type="left-icon"
+  icon="store-2-line"
+  label="Recojo en tienda"
+  description="El cliente recoge su pedido en tu local"
+  [checked]="ofreceRecojo()"
+  (checkedChange)="ofreceRecojo.set($event)" />
+```