@ajuarezso/sui-design-system 0.18.10 → 0.20.0

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-label/README.md

@@ -0,0 +1,143 @@
+---
+name: sui-checkbox-label
+selector: sui-checkbox-label
+resumen: Casilla con su texto (y opcionalmente descripción, badge y link) para opciones que se suman
+alternativas: [sui-checkbox (la casilla sola, el texto vive en otra parte), sui-checkbox-card (cada opción es una tarjeta), sui-switch-label (se aplica al instante), sui-radio-label (una sola opción)]
+---
+
+# sui-checkbox-label
+
+Story: [Atoms/Checkbox, Radio & Switch/Checkbox Label](https://sui-design-system.web.app/?path=/docs/atoms-checkbox-radio-switch-checkbox-label--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para toda casilla que tiene texto al lado: «Acepto los términos», cada permiso de un
+miembro del equipo, cada categoría de una lista. Toda la fila es clicable y se enchufa a un
+formulario. **Pendiente de decisión:** no tiene `size` (20 px), así que en una pantalla nueva de
+mobile choca con la regla de controles grandes; hasta que el DS le sume `size`, en mobile
+`sui-checkbox-card` es la salida grande.
+
+**No lo uses** para:
+
+- Prender algo que se aplica ya, sin botón de guardar: `sui-switch-label`.
+- Elegir una sola opción: `sui-radio-label`.
+- Opciones con peso propio (ícono o logo, descripción larga, borde): `sui-checkbox-card`.
+- Listas de 10+ palabras sueltas (talles, etiquetas): se vuelve un muro; ahí va una grilla de
+  `sui-checkbox` pelados o chips, como los de la calificación del pedido.
+
+Regla corta: **casilla con texto → este · casilla sin texto → `sui-checkbox` · opción con peso → card.**
+
+## Qué variante usar
+
+> **La guía del DS muestra las piezas, no cuándo usarlas.** Su ejemplo «con label avanzado»
+> arma Label + (Sublabel) + badge «NEW» + descripción + Link Button, y la variante invertida
+> (casilla a la derecha). No trae do/don't. Lo marcado «según la guía del DS» sale de ese ejemplo.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin prototipos ni vitrinas, misma lista
+> de exclusión que `sui-badge`): **0 usos**. Hay **5 casillas armadas a mano** que deberían ser
+> este componente (ver abajo).
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre. Qué se marca, en una a tres palabras («Gestionar productos»). | según la guía del DS (pieza); largo según `docs/CANON-SUI.md` §5.4 |
+| `sublabel` | Una precisión corta entre paréntesis: «(opcional)», «(12)». Va con paréntesis en el texto: el componente no los pone. | según la guía del DS («Label(Sublabel)») |
+| `description` | Cuando la opción necesita una frase que explique qué pasa si se marca («Recibe un correo cada vez que entra un pedido»). Pasa el label a peso medio. | según la guía del DS (pieza); el «cuándo» es propuesta |
+| `badge` | Solo para algo **nuevo** («Nuevo», en `purple` como el badge de novedad). Con string sale naranja `light`: pásale el objeto. | según la guía del DS (pieza «NEW»); el color es propuesta |
+| `link` | Un «Ver detalle» que abre más información sin marcar la casilla. **Solo se ve si hay `description`.** | según la guía del DS (pieza «Link Button») |
+| `flip` | No usar en formularios: la casilla va a la izquierda, como en la guía. | propuesta, falta aprobación |
+| `indeterminate` | El «seleccionar todo» de un grupo, cuando hay algunas marcadas. Hoy no usar (ver abajo). | propuesta, falta aprobación |
+| `disabled` | La opción existe pero no se puede tocar ahora; decir por qué en la descripción. | según la guía del DS |
+| `size` | `medium` (default, Figma): casilla 20, label 14/20. `large`: casilla 24, label 16/24. `xlarge`: casilla 28, label 16/24. En large y xlarge el sublabel y la descripción pasan a 14/20, el badge sin `size` propio sube a `medium` / `large` y el link a `medium`. Se usa con `[size]="bp.controlSize()"`. | `medium`: según la guía del DS · `large` / `xlarge`: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+
+**Usos de hoy que deberían ser este componente (5):**
+
+- **4 `sui-checkbox` + `<label>` a mano:** `pages/settings/team/team.html:225` y `:294`
+  (permisos), `components/option-sections-manager/option-sections-manager.html:188` y `:210`.
+- **1 nativo:** `pages/sales-channels/facebook/facebook.html:69`.
+
+**Antes de migrarlos:** los 4 de `sui-checkbox` hoy están en 24/28 px (`bp.controlSize()`,
+regla de controles grandes del dueño, 28-09-2026). Desde el 03-10-2026 el label tiene `size`
+(`large` 24 / `xlarge` 28): al migrar se le pasa `[size]="bp.controlSize()"` y no se achican.
+
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: el área táctil tiene que medir **44 px o más**. En web, con mouse,
+va un tamaño más chico. La app ya lo resuelve con `BreakpointsService`
+(`src/app/services/breakpoints.service.ts`, mobile = hasta 767 px); para controles,
+`bp.controlSize()` devuelve `xlarge` en mobile y `large` en web (regla de controles grandes del
+dueño, 28-09-2026).
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| casilla con texto en un formulario | `xlarge` (casilla 28, label 16/24) | `large` (casilla 24, label 16/24) | canon (aprobado por el dueño, 03-10-2026) |
+| lista densa de desktop (tabla, filtros) | — | `medium` (casilla 20, label 14/20) | propuesta, falta aprobación |
+
+```html
+<sui-checkbox-label [size]="bp.controlSize()" label="Recordar mi dirección" [(active)]="recordar" />
+```
+
+Toda la fila se toca (el host recibe el click), así que el área táctil es la fila entera, no solo
+la casilla. Con `xlarge` el contenido baja 2 px para que la línea del label (24) quede centrada
+con la casilla (28).
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `flip` | en un formulario la casilla va a la izquierda; a la derecha se confunde con un switch | una lista de ajustes donde las demás filas son switches a la derecha y una sola es casilla |
+| `badge` | ninguna opción marcable es nueva hoy | una opción recién agregada («Nuevo») en un formulario que el usuario ya conoce |
+| `link` | ninguna opción necesita abrir detalle | «Acepto los términos» con su «Ver términos» (con `description`) |
+| `indeterminate` | ninguna lista tiene «seleccionar todo» | el «Todos los permisos» arriba de la lista de permisos del equipo |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | `''` |
+| `sublabel` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `badge` | `SuiBadgeConfig \| string \| null` | `null` |
+| `link` | `SuiLinkConfig \| string \| null` | `null` |
+| `size` | `'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `flip` | `boolean` | `false` |
+| `disabled` | `boolean` | `false` |
+| `indeterminate` | `boolean` | `false` |
+| `active` · model, `[(active)]` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `linkClick` | `MouseEvent` |
+<!-- api:fin -->
+
+Implementa `ControlValueAccessor` (`[(ngModel)]`, `formControlName`).
+
+## Trampas
+
+- **El estado se llama `active`, no `checked`.** `[(checked)]` aquí no existe.
+- **No tiene `size`**: la casilla siempre mide 20 px.
+- **`link` solo se dibuja si hay `description`.** Sin descripción desaparece sin avisar.
+- **`description` cambia el label de peso** (regular → medio) y abre el bloque en columna.
+- El badge con string sale **naranja `light`**; en `sui-checkbox-card` el default es azul.
+  Pasa `{ label, color, variant }` para que combinen.
+- `link` con `href` es un `<a>` real; con `target: '_blank'` agrega `rel="noopener noreferrer"`.
+  Sin `href`, emite `linkClick` y no marca la casilla.
+- `flip` cambia el orden con CSS `order`: el lector de pantalla y el Tab siguen viendo la casilla primero.
+- Deshabilitado baja la opacidad del bloque a 0.5 (convención del proyecto).
+
+## Ejemplo
+
+```html
+<sui-checkbox-label label="Gestionar productos" [(active)]="permisos.productos" />
+
+<sui-checkbox-label
+  label="Avisarme por correo"
+  sublabel="(opcional)"
+  description="Te escribimos cuando entra un pedido nuevo."
+  [link]="{ label: 'Ver ejemplo', href: '/ayuda/correos', target: '_blank' }"
+  formControlName="avisoCorreo" />
+```

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

@@ -0,0 +1,131 @@
+---
+name: sui-circular-progress-bar
+selector: sui-circular-progress-bar
+resumen: El avance de algo en un anillo, para cuando cabe en un cuadrado al lado de un título
+alternativas: [sui-progress-bar-label (barra con título y número, cuando hay ancho), sui-progress-bar (barra pelada)]
+---
+
+# sui-circular-progress-bar
+
+Story: [Atoms/Progress/Circular Progress Bar](https://sui-design-system.web.app/?path=/docs/atoms-progress-circular-progress-bar--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando el avance tiene que entrar en **un cuadrado al lado de un título**, como un
+avatar: «Perfil 60 % completo» en el onboarding, los documentos al día de un repartidor, la meta
+del día en una card chica.
+
+**No lo uses** para:
+
+- Un avance con título y descripción, si hay ancho: `sui-progress-bar-label` se lee más rápido.
+- Varios avances en una lista: barras, que se comparan a simple vista; los anillos no.
+- Una espera sin porcentaje: un spinner.
+
+## Qué variante usar
+
+> **En la guía del DS se llama «Progress Circle»** («un gráfico simple para mostrar qué tan
+> completo está algo»). Trae cinco tamaños (80, 72, 64, 56 y 48; default 80), `value` y `max`,
+> y **un solo color** (el primario del DS, que en SUI es el azul de información). No dice cuándo
+> usar cada tamaño. 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`: **0 usos**, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `_guia-*`,
+> `master-rutina`, `master-medico`, `master-ejercicios`, `dev-index`).
+
+### `size`
+
+| size | número al centro | cuándo | fuente |
+|---|---|---|---|
+| `48` | no (solo el anillo) | Junto a un texto que ya dice el porcentaje. | según la guía del DS |
+| `56` | sí, 12 px | Web: en una fila o una card. | según la guía del DS (tamaño) · propuesta (cuándo) |
+| `64` (default SUI) | sí, 14 px | Mobile: en una fila o una card. | según la guía del DS (tamaño) · propuesta (cuándo) |
+| `72` | sí, 14 px | Web: lo principal de la pantalla. | según la guía del DS (tamaño) · propuesta (cuándo) |
+| `80` (default de la guía) | sí, 14 px | Mobile: lo principal de la pantalla. | según la guía del DS (tamaño) · propuesta (cuándo) |
+
+### `color` — misma regla que `sui-progress-bar`
+
+| color | cuándo | fuente |
+|---|---|---|
+| `blue` (default) | Avance neutro: perfil completado, pasos. | según la guía del DS (su único color) |
+| `green` | Se cumplió o va bien: documentos al día. | propuesta, falta aprobación |
+| `orange` | Va en curso y pide atención: meta del día a medias. | propuesta, falta aprobación |
+| `red` | Se perdió o se acabó: meta perdida. | propuesta, falta aprobación |
+| `purple` | **No usar** (ver abajo). | propuesta, falta aprobación |
+
+### El resto
+
+| propiedad | valor | cuándo | fuente |
+|---|---|---|---|
+| `number` | `true` (default) | Lo normal: el porcentaje al centro. | según la guía del DS |
+| `number` | `false` | El texto de al lado ya dice el número. | propuesta, falta aprobación |
+| `strokeWidth` | número | **No usar** (ver abajo). | propuesta, falta aprobación |
+| `ariaLabel` | texto | Siempre: lo que mide («Perfil completado»). | propuesta, falta aprobación |
+
+Usos de hoy que rompen la regla: **0** (no hay usos).
+
+## No usar: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| El componente entero (0 usos) | Los avances de hoy tienen ancho para una barra con título. | «Perfil 60 % completo» en el onboarding del repartidor o del local. |
+| `color="purple"` | Extensión SUI sin caso, igual que en la barra. | El avance de una función en prueba. |
+| `strokeWidth` | El grosor por tamaño ya sale de la guía (8 % del diámetro; 14 % en 48). | Ninguno: si hace falta otro grosor, se pide al DS. |
+
+## 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 |
+|---|---|---|---|
+| Junto a un texto que ya dice el número | `48` | `48` | propuesta, falta aprobación |
+| En una fila o card | `64` | `56` | propuesta, falta aprobación |
+| Lo principal de la pantalla | `80` | `72` | propuesta, falta aprobación |
+
+```ts
+readonly bp = inject(BreakpointsService); // master-pedidos: src/app/services/breakpoints.service.ts
+```
+
+```html
+<sui-circular-progress-bar [value]="60" [size]="bp.isMobile() ? 64 : 56" ariaLabel="Perfil completado" />
+```
+
+`size` es un número: el ternario devuelve `64 : 56`, no `'64' : '56'`.
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `value` | `number` | `0` |
+| `size` | `48 \| 56 \| 64 \| 72 \| 80` | `64` |
+| `color` | `'blue' \| 'green' \| 'orange' \| 'red' \| 'purple'` | `'blue'` |
+| `number` | `boolean` | `true` |
+| `strokeWidth` | `number \| null` | `null` |
+| `ariaLabel` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **`size` es un número, no un texto**: `[size]="64"`, no `size="64"` (un string no tipa).
+- **En 48 no hay número**, aunque `number` sea `true`.
+- **No hay `max`**: `value` es un porcentaje de 0 a 100.
+- El default de SUI es **64**; el de la guía, **80**.
+- El porcentaje se redondea a entero.
+- El azul es `--sui-state-information-base`, no el naranja de `--sui-primary-base`.
+
+## Ejemplo
+
+```html
+<div class="perfil">
+  <sui-circular-progress-bar [value]="60" [size]="56" ariaLabel="Perfil completado" />
+  <span>Completa tu perfil para empezar a repartir</span>
+</div>
+```

package/docs/sui-color-dot/README.md

@@ -0,0 +1,112 @@
+---
+name: sui-color-dot
+selector: sui-color-dot
+resumen: Una opción de color para elegir (o mostrar el color elegido); no es un punto de estado
+alternativas: [sui-color-picker (el selector completo, con hex propio), sui-badge type="with-dot" (punto de estado vivo), sui-status-badge withDot (punto de estado de un ciclo)]
+---
+
+# sui-color-dot
+
+Story: [Atoms/Color/Color Dot](https://sui-design-system.web.app/?path=/docs/atoms-color-color-dot--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para que la persona **elija un color** de una fila de opciones, o para mostrar el color
+que ya eligió: el color de una variante de producto («Rojo vino»), el color de una etiqueta. Es
+un `<button role="radio">`: se toca.
+
+**No lo uses** para:
+
+- **Un estado** (en línea, abierto, pendiente): el color del dot es el color literal, sin
+  significado. Va `sui-badge type="with-dot"` o `sui-status-badge [withDot]="true"`, que pintan
+  con los tokens de estado.
+- Un punto decorativo o una leyenda de gráfico: un `<span>` con el token del color.
+- Elegir un color que no está en los 10: `sui-color-picker` (que usa este dot por dentro).
+
+## Qué variante usar
+
+> **En la guía del DS es la fila «Recommended Colors» del selector de color**: muestras para
+> elegir un color recomendado. No dice cuándo usar cada estado. 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`: **0 usos**, sin contar prototipos ni
+> vitrinas (`master-preview`, `master-prototipos`, `mockup-sheets-*`, `dx/*`, `_guia-*`,
+> `master-rutina`, `master-medico`, `master-ejercicios`, `dev-index`). Candidato:
+> `components/add-product-modal/add-product-modal.html:289` elige el color de una variante con
+> `<input type="color">`, que abre un selector distinto en iOS, Android y escritorio.
+
+| propiedad | valor | cuándo | fuente |
+|---|---|---|---|
+| `color` | los 10 (`gray`, `blue`, `orange`, `red`, `green`, `yellow`, `purple`, `sky`, `pink`, `teal`) | El color literal que se ofrece. **No significan nada**: son la paleta `-500`, no los tokens de estado del badge. Se ofrecen en ese orden. | según la guía del DS (colores recomendados) |
+| `customHex` | `#rrggbb` | Un color exacto que no está en los 10 (el de una variante de producto). Pisa a `color`. | propuesta, falta aprobación |
+| `state` | `default` | Opción disponible. | según la guía del DS |
+| `state` | `selected` | El color elegido. Uno solo por fila; lo setea la pantalla. | según la guía del DS |
+| `state` | `disabled` | Un color que no se puede elegir (agotado en esa variante). | propuesta, falta aprobación |
+| `state` | `hover` | **No usar** (ver abajo). | propuesta, falta aprobación |
+| `size` | `medium` (default) · `large` | `medium` 24 (Figma) en web; `large` 32 en mobile. En `large` el dot mide 22, 18 en hover y 16 seleccionado, con anillo de 24. | `medium`: según la guía del DS · `large`: canon (aprobado por el dueño, 03-10-2026), extensión SUI |
+| `ariaLabel` | texto | El nombre del color para el lector de pantalla. Por default dice «Rojo», «Celeste»; con `customHex`, el hex. Con hex propio, pasar el nombre («Rojo vino»). | propuesta, falta aprobación |
+
+Usos de hoy que rompen la regla: **0** (no hay usos).
+
+## No usar: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| El componente entero (0 usos) | La app no ofrece colores para elegir. | El color de una variante de producto en `add-product-modal`, en lugar del selector nativo. |
+| `state="hover"` | El CSS ya lo pone al pasar el mouse. | Vitrinas y capturas del DS. |
+
+## 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 |
+|---|---|---|---|
+| Cualquiera | `large` (32 × 32) | `medium` (24 × 24) | canon (aprobado por el dueño, 03-10-2026) |
+| Separación entre dots | 12 px | 4 px | propuesta, falta aprobación |
+
+```html
+<sui-color-dot [color]="c" [size]="bp.isMobile() ? 'large' : 'medium'" [state]="c === elegido() ? 'selected' : 'default'" />
+```
+
+`large` mide 32, todavía por debajo de los 44 px del dedo: los 12 px de separación completan el
+área para no tocar el vecino.
+
+## 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'` |
+| `customHex` | `string \| null` | `null` |
+| `state` | `'default' \| 'hover' \| 'selected' \| 'disabled'` | `'default'` |
+| `size` | `'medium' \| 'large'` | `'medium'` |
+| `ariaLabel` | `string` | `''` |
+
+| output | payload |
+|---|---|
+| `clicked` | `void` |
+<!-- api:fin -->
+
+Output: `(clicked)`, solo si no está `disabled`. El dot no cambia su propio `state`: la pantalla
+lo pasa a `selected`.
+
+## Trampas
+
+- **Es un botón**: dentro de otro botón o de un link, rompe el HTML y el foco.
+- **El dot no se marca solo** al tocarlo: `(clicked)` avisa y la pantalla setea `state`.
+- `disabled` pinta el dot gris claro, no el color atenuado.
+- Con `customHex`, el `color` se ignora.
+- `medium` mide 24 × 24 y `large` 32 × 32: los dos quedan por debajo de los 44 del dedo. En mobile va `large` con 12 px de separación entre dots.
+
+## Ejemplo
+
+```html
+@for (c of colores; track c) {
+  <sui-color-dot [color]="c" [state]="c === elegido() ? 'selected' : 'default'" (clicked)="elegido.set(c)" />
+}
+```

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

@@ -0,0 +1,124 @@
+---
+name: sui-color-picker
+selector: sui-color-picker
+resumen: Botón que abre un panel para elegir un color libre (espectro, matiz, hex) o uno de los recomendados
+alternativas: [sui-color-dot (un punto de color, para armar una grilla propia), sui-select o sui-radio-card (el color es una categoría con nombre, no un color libre)]
+---
+
+# sui-color-picker
+
+Story: [Atoms/Color/Color Picker](https://sui-design-system.web.app/?path=/docs/atoms-color-color-picker--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando la persona tiene que **crear o elegir un color libre** y guardarlo como hex: el
+color de una variante de producto («Rojo», «Azul marino» en una polera), el color de una etiqueta.
+Se ve igual en iOS, Android y desktop porque no usa el selector del sistema.
+
+**No lo uses** para:
+
+- Elegir entre colores que son categorías con nombre (estados, tipos): `sui-select` o
+  `sui-radio-card`. El picker es para color **libre**.
+- Una grilla fija de colores siempre visible, sin botón: arma la grilla con `sui-color-dot`.
+- El selector nativo (`<input type="color">`): abre algo distinto en cada sistema.
+
+Regla corta: **color libre que se guarda → color-picker · una de N categorías → select · grilla siempre a la vista → color-dot.**
+
+## Qué variante usar
+
+> **La guía del DS lo define para «elegir o crear colores específicos»** y lo muestra de dos
+> formas: el panel a la vista y dentro de un popover con su botón («Pick Color»), con una
+> sección de colores recomendados. No dice cuándo va cada pieza.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **0 usos**. Hay **1 `<input type="color">` nativo** que es exactamente su caso.
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `value` | El hex guardado (`[(value)]`). Sin valor, el botón muestra el `placeholder`. | según la guía del DS (popover con botón) |
+| `placeholder` | «Elegir color» (default). Cambiarlo solo si el campo dice qué color es («Color de la variante»). | propuesta, falta aprobación |
+| `alpha` | **`false` por defecto en la app**: la base guarda 6 caracteres (`#rrggbb`). Con `true` (default del componente) puede emitir 8. | propuesta, falta aprobación |
+| `colors` | Acotar los recomendados a los que tengan sentido para el caso. Default: los 10 de SUI. | según la guía del DS (sección «Recommended Colors») |
+| `recommendedLabel` | «Colores recomendados» (default). | propuesta, falta aprobación |
+| `presetsOnly` | Solo la grilla de recomendados, sin espectro ni hex: cuando el color tiene que salir de la paleta. | propuesta, falta aprobación |
+| `eyedropper` | Dejar el default (`true`): solo aparece donde el navegador lo soporta (Chromium de escritorio). | propuesta, falta aprobación |
+| `showFormatLabel` | `false`: el «Hex» con flecha es decorativo, no cambia de formato. | propuesta, falta aprobación |
+| `disabled` | El campo existe pero no se puede tocar ahora. | propuesta, falta aprobación |
+| `ariaLabel` | Siempre que el botón no tenga un label al lado que diga qué color es. | propuesta, falta aprobación |
+
+**Usos de hoy que rompen la regla:**
+
+- **1 nativo → `sui-color-picker` con `[alpha]="false"`:**
+  `components/add-product-modal/add-product-modal.html:293` (color de cada opción cuando el grupo
+  se muestra «como colores»; guarda `swatchHex` de 6 caracteres).
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web |
+|---|---|---|
+| botón que abre el panel | 32 px de alto (no hay `size`) | 32 px |
+
+**No tiene un tamaño grande para mobile.** El botón mide unos 32 px de alto y los puntos de
+color del panel 24 px. En mobile funciona, pero queda debajo de los 44 px de área táctil.
+Agrandarlo es una decisión del DS.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `alpha` en `true` | el modelo de datos espera `#rrggbb`; con opacidad emite `#rrggbbaa` | un color de marca sobre imágenes donde la transparencia es parte del diseño (fondo de un banner) |
+| `presetsOnly` | el único caso de hoy (colores de una variante) necesita colores libres | el color de una etiqueta interna con paleta cerrada |
+| `showFormatLabel` en `true` | muestra «Hex» con una flecha que no hace nada | nunca, hasta que el DS soporte RGB o HSL |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `colors` | `readonly SuiColorDotColor[]` | `SUI_COLOR_DOT_COLORS` |
+| `value` · model, `[(value)]` | `string \| null` | `null` |
+| `placeholder` | `string` | `'Elegir color'` |
+| `recommendedLabel` | `string` | `'Colores recomendados'` |
+| `presetsOnly` | `boolean` | `false` |
+| `alpha` | `boolean` | `true` |
+| `eyedropper` | `boolean` | `true` |
+| `showFormatLabel` | `boolean` | `true` |
+| `disabled` | `boolean` | `false` |
+| `ariaLabel` | `string` | `'Seleccionar color'` |
+
+| output | payload |
+|---|---|
+| `change` | `string` |
+<!-- api:fin -->
+
+`SuiColorDotColor`: `'gray' | 'blue' | 'orange' | 'red' | 'green' | 'yellow' | 'purple' | 'sky' | 'pink' | 'teal'`.
+
+## Trampas
+
+- **`alpha` viene en `true`**: si la persona baja la opacidad, el valor pasa a 8 caracteres.
+  Pasa `[alpha]="false"` si lo guardas como `#rrggbb`.
+- **El «Hex» con flecha es decorativo**: solo lee y emite hex.
+- **El cuentagotas no aparece en iOS, Android, Safari ni Firefox**: no es un error.
+- El hex escrito a mano se aplica al salir del campo o con Enter; si es inválido, vuelve al anterior
+  sin avisar.
+- Acepta 3, 4, 6 u 8 caracteres con o sin `#`, y siempre emite con `#`.
+- El botón muestra el nombre en español si el color es uno de los 10 («Naranja»); si no, el hex
+  en mayúsculas.
+- Elegir un recomendado **cierra** el panel; arrastrar el espectro no.
+- El panel vive en un overlay del CDK: escapa a cualquier `overflow: hidden` del contenedor.
+- No implementa `ControlValueAccessor`: se usa con `[(value)]`.
+
+## Ejemplo
+
+```html
+<sui-color-picker
+  [alpha]="false"
+  [showFormatLabel]="false"
+  placeholder="Color de la variante"
+  [value]="opcion.swatchHex ?? null"
+  (valueChange)="cambiarColor(opcion, $event)" />
+```