@ajuarezso/sui-design-system 0.20.0 → 0.21.0

package/docs/sui-breadcrumbs/README.md

@@ -0,0 +1,122 @@
+---
+name: sui-breadcrumbs
+selector: sui-breadcrumbs
+resumen: Ruta de migas en web que dice dónde estás dentro de una jerarquía de 3 o más niveles y deja volver a cualquiera
+alternativas: [sui-page-header (título de la pantalla), botón de volver del layout (mobile), sui-tab-menu-horizontal (secciones del mismo nivel)]
+---
+
+# sui-breadcrumbs
+
+Story: [Molecules/Breadcrumbs/Breadcrumbs](https://sui-design-system.web.app/?path=/docs/molecules-breadcrumbs-breadcrumbs--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** en **web** cuando una pantalla está **3 o más niveles adentro** y sirve volver a un nivel
+intermedio sin pasar por todos: «Productos › Hamburguesas › Clásica con queso» en el panel de la
+empresa, «Locales › Sabores Andinos › Pedidos» en el super admin.
+
+**No lo uses** para:
+
+- **Mobile**: ahí se vuelve con la flecha del layout. Una fila de migas en 390 px se corta y
+  compite con el título.
+- **Una pantalla de 1 o 2 niveles**: el título y el volver ya lo dicen.
+- Secciones del mismo nivel: `sui-tab-menu-horizontal`.
+- Los pasos de un flujo: `sui-stepper`.
+
+Regla corta: **3+ niveles en web → breadcrumbs · mobile o 1-2 niveles → flecha de volver.**
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: «guía mostrando el camino dentro de una app o sitio». Ejemplos con
+> flecha (default), **como enlaces** y con **separador `/`**. El ítem activo es la página actual. No
+> trae do/don't.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`): **0 usos**.
+
+### `divider`
+
+| divider | cuándo | fuente |
+|---|---|---|
+| `arrow` (default) | Siempre en la app. | según la guía del DS (es su default) |
+| `slash` | No: misma función que la flecha; dos estilos en la misma app se leen como dos cosas. | según la guía del DS (la forma existe); el no es propuesta |
+| `dot` | No: el punto separa metadatos («12 min · S/ 4.50»), no niveles. Extensión de SUI. | propuesta, falta aprobación |
+
+### Ítems (`items`)
+
+| qué | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre el nombre real del nivel («Hamburguesas», no «Categoría»). Un id nunca es el nombre. | canon (CLAUDE.md, «un identificador nunca es el título de nada») |
+| `href` | Cada nivel anterior con su ruta interna (`/empresa/productos`): navega con el router, sin recargar. | propuesta, falta aprobación |
+| sin `href` + `(navigate)` | Cuando volver no es una ruta (cerrar un panel, limpiar un filtro). | propuesta, falta aprobación |
+| `icon` solo en el primero | El inicio como casa (`home-5-line`) con `ariaLabel`. | según la guía del DS (ítems con ícono); el cuándo es propuesta |
+| `active` | No hace falta: el último ya es el activo. Solo si la página actual no va al final (raro). | según el código |
+
+Usos de hoy que rompen las reglas: **0** (no se usa).
+
+## Tamaño en mobile y en web
+
+Alto fijo de **20 px** (texto 14, ícono 20), sin `size`. **No tiene tamaño para mobile**: no se usa ahí.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| ruta de 3+ niveles | no se usa: flecha de volver | `sui-breadcrumbs` | propuesta, falta aprobación |
+
+```html
+@if (!bp.isMobile()) {
+  <sui-breadcrumbs [items]="ruta()" />
+}
+```
+
+## «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 | ninguna pantalla pasa de 2 niveles con salto a uno intermedio | el detalle de un producto dentro de una categoría en el panel web, o un local dentro del super admin |
+| `slash` | ya hay flecha; mezclar estilos confunde | nunca, mientras la flecha sea el estilo de la app |
+| `dot` | el punto es separador de metadatos | nunca para niveles |
+| en mobile | 20 px de alto y la ruta se corta | nunca |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `items` | `readonly SuiBreadcrumbEntry[]` | — (requerido) |
+| `divider` | `'arrow' \| 'slash' \| 'dot'` | `'arrow'` |
+
+| output | payload |
+|---|---|
+| `navigate` | `SuiBreadcrumbEntry` |
+<!-- api:fin -->
+
+```ts
+interface SuiBreadcrumbEntry {
+  label?: string;
+  icon?: string;       // RemixIcon, 20 px
+  href?: string;       // interno → router; externo → navegador
+  active?: boolean;    // default: el último
+  ariaLabel?: string;  // obligatorio si va solo el ícono
+}
+type SuiBreadcrumbDivider = 'arrow' | 'slash' | 'dot';
+```
+
+## Trampas
+
+- **`navigate` sale en todo clic**, también en los que tienen `href` (el navegador ya navega). Si
+  usas `href`, no navegues otra vez en `(navigate)`.
+- **El último ítem es el activo solo**: no es clicable y va en negro.
+- **No corta texto largo**: con nombres de producto largos la fila crece. Acórtalos tú.
+- El host dice `aria-label="Ruta de navegación"` (hasta el 03-10-2026, «Breadcrumb») y no se puede cambiar.
+- `SuiBreadcrumbEntry` (los datos) no es `SuiBreadcrumbItem` (el componente de cada miga).
+
+## Ejemplo
+
+```html
+<sui-breadcrumbs
+  [items]="[{ icon: 'home-5-line', href: '/empresa/inicio', ariaLabel: 'Inicio' },
+            { label: 'Productos', href: '/empresa/productos' },
+            { label: 'Hamburguesas', href: '/empresa/productos?categoria=hamburguesas' },
+            { label: 'Clásica con queso' }]" />
+```

package/docs/sui-button/README.md

@@ -122,6 +122,23 @@ flujo nuevo cae en la columna de la derecha, se usa (aprobado por el dueño, 03-
 | `sui-button-group` (0 usos) | hoy no hay opciones combinables pegadas | días del horario del local o filtros que se suman |
 | `sui-topbar-button` (0 usos) | las barras de la app tienen sus íconos propios | si se unifica la barra superior del admin con la del DS |
 
+## Tamaño en mobile y en web
+
+En mobile se toca con el dedo: 40 px como mínimo y 48 en la acción principal. En web, 28–40.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| acción principal de la pantalla o footer de modal | `large` (48) | `medium` (40) | canon (aprobado por el dueño, 03-10-2026) (footer de modal siempre `large`) |
+| acción dentro de una card o una fila | `medium` (40) | `small` (36) / `xsmall` (32) | canon (aprobado por el dueño, 03-10-2026) |
+| acción en una tabla densa | — (no hay tablas en mobile) | `2xsmall` (28) | canon (aprobado por el dueño, 03-10-2026) |
+| CTA de landing | `xlarge` (52) | `large` (48) | propuesta, falta aprobación |
+
+Patrón (la app ya lo usa en 27 lugares; `bp` = `BreakpointsService`, mobile hasta 767 px):
+
+```html
+<sui-button [size]="bp.isMobile() ? 'large' : 'medium'" …/>
+```
+
 ## API
 
 <!-- api:inicio -->

package/docs/sui-card/README.md

@@ -0,0 +1,168 @@
+---
+name: sui-card
+selector: sui-card
+resumen: Superficie con borde, radio y sombra que agrupa contenido, con slots de header, cuerpo, media y footer
+alternativas: [sui-content-card (una fila «cara + nombre + detalle» dentro de su cajita), sui-radio-card / sui-checkbox-card / sui-switch-card (la card ES la opción que se elige), sui-product-card (un producto de la carta), sui-store-card (un local en un listado del cliente), sui-modal-sheet (contenido encima de la pantalla)]
+---
+
+# sui-card
+
+Story: [Molecules/Card/Card](https://sui-design-system.web.app/?path=/docs/molecules-card-card--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** como la superficie de una sección o de un ítem: un bloque de KPIs, un gráfico con su
+título, una fila de lista que se toca, un formulario corto dentro de una página.
+
+**No lo uses** para:
+
+- Una fila «foto o ícono + nombre + detalle»: eso es `sui-content-card` (o `sui-content-label`
+  dentro de una card que ya existe).
+- Una opción que se elige: `sui-radio-card`, `sui-checkbox-card` o `sui-switch-card` ya traen la
+  card, el estado elegido y el área táctil.
+- Un producto de la carta o un local del listado del cliente: `sui-product-card` y
+  `sui-store-card`.
+- Contenido que aparece encima de la pantalla: `sui-modal` / `sui-modal-sheet`.
+
+Regla corta: **agrupa contenido → card · es una fila con cara → content-card · se elige → card de
+selección.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página de la card.** Nada de lo que sigue sale de una guía: lo
+> marcado «propuesta» sale de cómo la usa la app y falta el ok del dueño; lo «canon» ya está
+> aprobado.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (sin `master-preview`,
+> `master-prototipos`, `mockup-*`, `dx/*`, `_guia-*`, `master-rutina`, `master-medico`,
+> `master-ejercicios`): **253 cards en 79 archivos**. Variantes: 227 `default` explícito, 24 sin
+> `variant` (también default), 2 `elevated`, 0 `flat`. Tamaños: 95 `small`, 123 `medium`
+> explícito + 21 sin `size`, 14 `large`, 0 `xlarge`. 9 con `[interactive]`. Slots: 23
+> `sui-card-header`, 11 `sui-card-footer`, 4 `sui-card-media`.
+
+### `variant`
+
+| variant | cuándo | fuente |
+|---|---|---|
+| `default` | Lo normal: la card sobre el fondo de la app (borde + sombra x-small). 251 de 253. | propuesta (práctica de la app) |
+| `elevated` | La card flota sobre un mapa, una foto o un fondo de color, donde el borde se pierde y hace falta la sombra media. Precedente: el seguimiento público del pedido (`pages/public/pedido-en-vivo/pedido-en-vivo.html:19`, `:69`). | propuesta |
+| `flat` | Ver «No usar». | propuesta |
+
+### `size` (padding × gap entre slots)
+
+| size | medidas | cuándo | fuente |
+|---|---|---|---|
+| `small` | 16 / 12 | Filas de una lista de cards, KPIs chicos, cards tocables. **Toda card en mobile.** | propuesta |
+| `medium` (default) | 20 / 16 | Secciones en web. | propuesta |
+| `large` | 24 / 20 | La sección principal de una pantalla de web (los 14 de hoy son gráficos de reportes y los pasos del onboarding). | propuesta |
+| `xlarge` | 28 / 24 | Ver «No usar». Extensión SUI (no está en Figma). | propuesta |
+
+### `interactive`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `true` | La card entera es **una** acción: abre un detalle o lleva a otra pantalla («Mis direcciones», una factura). Da cursor, hover, foco y el arreglo de iOS. | propuesta |
+| `false` (default) | La card tiene 2 acciones o más adentro, o ninguna. Las acciones van como botones dentro. | propuesta |
+
+### Slots
+
+| slot | cuándo | fuente |
+|---|---|---|
+| `[sui-card-header]` | Título de la card a la izquierda y, si hace falta, una acción chica a la derecha (`sui-link-button` «Ver todo»). | propuesta |
+| cuerpo (sin atributo) | El contenido. **Con 2 bloques o más, envuélvelos en un div propio con `display:flex; flex-direction:column; gap`** (ver Trampas). | canon (memoria del proyecto, 10-05-2026) |
+| `[sui-card-media]` | Gráfico, mapa o foto de borde a borde, al final. Si después va un footer, la media deja de comerse el borde inferior. | propuesta |
+| `[sui-card-footer]` | La acción de la card o un resumen. Si son dos botones, siguen el orden de `sui-modal-footer` (secundario a la izquierda, primario a la derecha). | canon (orden de botones, CLAUDE.md) |
+
+**Usos de hoy que rompen las reglas:**
+
+- **18 cards en 6 archivos con `gap` puesto en la clase del `sui-card`**, que no llega a los hijos
+  del cuerpo: `pages/central/central-inicio/central-inicio.html:36` (×6),
+  `pages/super-admin/master-semanas/master-semanas.html:21` (×4),
+  `pages/central/central-ingresos/central-ingresos.html:36` (×3), `pages/invoices/invoices.html:19`
+  (×2), `pages/driver/driver-history/driver-history.html:17` (×2) y
+  `pages/driver/driver-wallet/driver-wallet.html:154` (ahí además el `flex-direction: row` del host
+  no pone el badge al lado del monto: el cuerpo es un solo hijo).
+- **3 cards tocables armadas a mano** (`(click)` o `routerLink` sin `[interactive]`): sin foco, sin
+  hover y sin el arreglo de iOS. `pages/super-admin/master-users/master-users.html:156` (con
+  `role="button"` y `touchstart` a mano), `pages/super-admin/master-settings/master-settings.html:601`,
+  `pages/driver/driver-dashboard/driver-dashboard.html:990`.
+
+## Tamaño en mobile y en web
+
+El `size` de la card es su padding, no un área táctil: no tiene que llegar a 44. Lo que importa en
+mobile es no perder ancho.
+
+| uso | mobile | web |
+|---|---|---|
+| sección, KPI, gráfico | `small` (16) | `medium` (20) |
+| sección principal de un reporte | `small` | `large` (24) |
+| fila de lista tocable | `small` | `small` |
+
+```html
+<sui-card [size]="bp.isMobile() ? 'small' : 'medium'"> … </sui-card>
+```
+
+`bp` es el `BreakpointsService` de la app. Va al ritmo de los gaps de página (12 / 16 / 20 por
+breakpoint). Si la card es tocable, el alto de la fila (≥ 44) lo da su contenido, no el `size`.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `variant="flat"` (0 usos) | la app siempre pone la card sobre el fondo gris, donde la sombra ayuda | una card dentro de otra superficie blanca (un sheet, otra card), donde la sombra dobla el borde |
+| `size="xlarge"` (0 usos) | ninguna pantalla lo pide; no está en Figma | un hero de desktop (la portada de un reporte impreso) |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `variant` | `'default' \| 'elevated' \| 'flat'` | `'default'` |
+| `size` | `'small' \| 'medium' \| 'large' \| 'xlarge'` | `'medium'` |
+| `interactive` | `boolean` | `false` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+Slots: `[sui-card-header]`, cuerpo (`<ng-content>`), `[sui-card-media]`, `[sui-card-footer]`.
+
+## Trampas
+
+- **El `gap` del host separa slots, no hijos.** El cuerpo va dentro de `.sui-card__body` (flex en
+  columna, sin gap). Poner `gap` en una clase del `sui-card` no separa nada de lo que proyectas: se
+  necesita un wrapper propio (`<div class="x__card-body">` con flex y gap).
+- Sin header ni footer el host queda con `gap: 0` (`:has(> .sui-card__body:only-child)`).
+- **`interactive` no trae output, pero sí teclado** (desde 03-10-2026): pone `role="button"`,
+  `tabindex="0"`, hover y foco, y **Enter / Espacio hacen click en la card**, así que tu `(click)`
+  (o el `routerLink` de un `<a>` que la envuelve) también responde al teclado. No agregues
+  `(keydown.enter)` además: se dispararía dos veces. Una tecla dentro de un campo o botón
+  proyectado es de ese control, no de la card.
+- Los slots son **atributos** (`sui-card-header`), no `slot="…"`.
+- El host tiene `overflow: hidden` y radio 16: lo que sobresalga (un badge colgado de la esquina)
+  se corta.
+- `sui-card-media` rompe el padding con margen negativo leído de `--sui-card-padding-x`; si le
+  cambias el padding a la card desde afuera, la media queda corrida.
+- En modo oscuro `elevated` usa `--sui-card-elevated-border` para el borde (la sombra no se ve).
+
+## Ejemplo
+
+```html
+<!-- Sección con título, dos bloques y una acción -->
+<sui-card [size]="bp.isMobile() ? 'small' : 'medium'">
+  <div sui-card-header class="ganancias__head">
+    <h3>Tus días del mes</h3>
+    <sui-link-button variant="primary" size="small" (click)="verTodo()">Ver todo</sui-link-button>
+  </div>
+  <div class="ganancias__card-body">   <!-- display:flex; flex-direction:column; gap:12px -->
+    <span>Martes 3 · 6 entregas · S/ 42.00</span>
+    <span>Miércoles 4 · 4 entregas · S/ 28.50</span>
+  </div>
+</sui-card>
+
+<!-- Fila tocable -->
+<sui-card size="small" [interactive]="true" (click)="abrirDirecciones()">
+  …
+</sui-card>
+```

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>
+```