@ajuarezso/sui-design-system 0.19.0 → 0.21.0

package/docs/sui-banner/README.md

@@ -0,0 +1,190 @@
+---
+name: sui-banner
+selector: sui-banner
+resumen: Barra de aviso a todo el ancho, arriba de la pantalla, para algo que afecta a toda la app
+alternativas: [sui-alert (aviso ligado a una sección o una card), sui-toast (resultado efímero de una acción), sui-notification (fila de la bandeja), sui-modal (algo que bloquea todo, como quedarse sin conexión)]
+---
+
+# sui-banner
+
+Story: [Molecules/Feedback/Banner](https://sui-design-system.web.app/?path=/docs/molecules-feedback-banner--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando el aviso es de **toda la app o de toda la pantalla**, no de una parte: el plan
+del local venció, estás administrando un local como super admin, hay una versión nueva, la app
+está en modo de prueba. Va pegado arriba, a todo el ancho, y se queda mientras dure la situación.
+
+**No lo uses** para:
+
+- Un aviso de una sección, una card o un paso del flujo («Cobras S/ 12.00 al local al recoger»):
+  eso es `sui-alert`, aunque sea importante. El banner no tiene tamaños ni descripción larga: no
+  está hecho para vivir en medio del contenido.
+- Confirmar que algo salió bien: `sui-toast`.
+- Algo que impide usar la app (sin conexión, cuenta suspendida): un `sui-modal` o una pantalla
+  propia. La app ya lo hace así con «Sin conexión».
+
+Regla corta (canon, la misma del alert): **contexto → alert · toda la app → banner · efímero →
+toast · bandeja → notification.**
+
+## Qué variante usar
+
+> La guía del DS dice **para qué** es el banner, pero no cuándo va cada relleno ni cada tipo. Lo
+> marcado «según la guía del DS» sale de su texto o de sus ejemplos publicados; lo marcado
+> «canon» ya lo aprobó el dueño en el README de `sui-alert`; el resto es **propuesta** y falta su ok.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`, sin contar prototipos ni vitrinas
+> (`master-preview`, `master-prototipos`, `mockup-*`, `dx/*`, `_guia-*`, `master-rutina`,
+> `master-medico`, `master-ejercicios`, `dev-index`): **2 banners** en 2 archivos, más **1 barra
+> hecha a mano** que debería ser banner.
+
+### Lo que sí dice la guía del DS
+
+- **Para qué es**: avisos cruciales, **arriba de la pantalla** y a la vista. Coincide con «toda la
+  app → banner».
+- **Una sola línea**: título, punto medio, descripción y **un link** como acción. El link es un
+  `sui-link-button` `modifiable`, `medium` y **subrayado**: toma el color del banner.
+- **Botón de cerrar** en todos sus ejemplos.
+- **Defaults**: la guía arranca en relleno `filled` y tipo `feature`; SUI arranca en `stroke` e
+  `info`. Es un default, no una recomendación de uso.
+
+### `variant` — qué tipo de aviso es
+
+Los mismos cinco tipos que `sui-alert`, con el mismo significado.
+
+| variant | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `info` (default) | Un dato de toda la app que conviene saber y no pide nada: hay una versión nueva, estás viendo datos de prueba. | (sin uso hoy) | propuesta (sigue la regla canon del alert) |
+| `success` | Un estado bueno que dura y afecta a todo: «Tu local ya está publicado». Si es la confirmación de un clic, es toast. | (sin uso hoy) | propuesta (sigue la regla canon del alert) |
+| `warning` | Hay que hacer algo pronto o lo que hagas tiene consecuencia para toda la cuenta: el plan vence, estás administrando un local que no es tuyo. | `components/subscription-banner/subscription-banner.html:5` («Tu plan vence en 3 días») · candidato: `components/impersonation-banner/impersonation-banner.ts:17` | propuesta (sigue la regla canon del alert) |
+| `error` | Algo ya pasó y afecta a toda la cuenta. | `components/subscription-banner/subscription-banner.html:5` («Tu plan venció») | propuesta (sigue la regla canon del alert) |
+| `feature` | Novedad que alcanza a toda la app. **Aquí es gris**, no morado como en el alert. | (sin uso hoy) | canon (decisión documentada en el `.ts`, recogida en el README del alert) |
+
+### `variantStyle` — el peso visual
+
+Misma pregunta que en el alert: **¿este aviso tiene que ganarle a todo lo demás de la pantalla?**
+
+| variantStyle | cuándo | ejemplo real de la app | fuente |
+|---|---|---|---|
+| `lighter` | El aviso **acompaña**: hay que tenerlo presente, pero se puede seguir trabajando. Es el caso normal. | `subscription-banner.html:7` en el caso «vence en N días» (hoy en `light`) | propuesta |
+| `filled` (default de la guía) | Hay que **actuar ya**, o la app está en un **modo que cambia lo que haces**: el plan venció, estás administrando otro local. Uno a la vez. | `subscription-banner.html:7` («Tu plan venció») | propuesta |
+| `light` | No usar hoy, como en el alert. **Cuándo sí:** un banner dentro de una zona ya teñida, donde `lighter` se pierde. | — | propuesta |
+| `stroke` (default SUI) | No usar hoy: un banner blanco con borde se confunde con la barra superior. **Cuándo sí:** arriba de una pantalla a sangre (un mapa o una foto), donde la banda blanca sí se distingue. | — | propuesta |
+
+### `dismissible`, `showIcon`, acción y título
+
+| prop | valor | cuándo | fuente |
+|---|---|---|---|
+| `dismissible` | `true` | Solo si el aviso se puede ignorar sin problema (versión nueva, novedad). La guía lo muestra en todos sus ejemplos. | según la guía del DS (que exista) · propuesta (cuándo) |
+| `dismissible` | `false` (default) | Todo `filled` y todo aviso que tiene que seguir ahí: plan vencido, administrando otro local. Cerrarlo no arregla nada. | propuesta |
+| `showIcon` | `true` (default) | Siempre: el ícono es la mitad del significado del tipo. | propuesta |
+| `showIcon` | `false` | No usar hoy. **Cuándo sí:** cuando se proyecta un avatar o logo en `slot="icon"` (ver abajo), que ya ocupa ese lugar. | propuesta |
+| `slot="icon"` | avatar o logo | Reemplaza al ícono del tipo: el logo del local que estás administrando. | propuesta |
+| `slot="action"` | **un** `sui-link-button` `variant="modifiable"` con `[underline]="true"` | La única acción del banner: «Renovar plan», «Salir», «Actualizar». Nunca un `sui-button`, nunca dos. | según la guía del DS |
+| `title` | frase corta | Lo que pasa, en sentence case y sin punto final. | canon (copy de la app) |
+| `description` | complemento | Qué hacer o hasta cuándo. Una línea en web; en mobile se envuelve. | según la guía del DS (una línea) |
+
+### Usos de hoy que rompen la regla
+
+- **Rompe el canon — 1 banner en contexto → `sui-alert`:**
+  `pages/driver/driver-order-detail/driver-order-detail.html:391` («Cobras S/ … al local al
+  recoger»). Es el aviso de **un pedido**, dentro de su detalle: va `sui-alert` (`error` `filled`
+  si cobra en el mostrador, `info` `lighter` si cobra en la puerta).
+- **Barra hecha a mano que es un banner — 1:** `components/impersonation-banner/impersonation-banner.ts:17`
+  («Estás administrando … como super admin» + botón «Salir»), con `#fff` y `rgb()` sueltos. Pasaría a
+  `<sui-banner variant="warning" variantStyle="filled">` con un link «Salir».
+- **Romperían la propuesta — 1 `light` → `lighter`:** `components/subscription-banner/subscription-banner.html:7`
+  (el caso «vence en N días»).
+- No confundir: `components/upgrade-banner/` (6 pantallas) se llama «banner» pero es un aviso dentro
+  de una sección; su destino es `sui-alert`, ya anotado en `docs/CANON-SUI.md`.
+
+## Tamaño en mobile y en web
+
+El banner **no tiene `size`**: mide 44 px de alto en web, centrado; en mobile (≤ 767 px) pasa a
+`min-height: 44px`, se alinea a la izquierda y el texto se envuelve en varias líneas.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| la barra | 44 px mínimo, crece si el texto envuelve | 44 px fijos, una línea | según el componente |
+| el link de acción | `large` (24 px) cuando se publique (hoy `medium`, 20 px) | `medium` (20 px) | propuesta |
+| la X de cerrar | se ve de 24 px; **se toca en 40 × 40** | igual | canon (aprobado por el dueño, 03-10-2026): área táctil invisible, extensión SUI |
+
+```html
+<sui-banner variant="warning" variantStyle="lighter" title="Tu plan vence en 3 días"
+  description="Renueva para seguir recibiendo pedidos">
+  <sui-link-button slot="action" variant="modifiable" [underline]="true"
+    [size]="bp.isMobile() ? 'large' : 'medium'" (clicked)="renovar()">Renovar plan</sui-link-button>
+</sui-banner>
+```
+
+`size="large"` del link-button está en el repo del DS y todavía no en el paquete publicado 0.19.0:
+hasta entonces va `medium` en las dos.
+
+## «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 |
+|---|---|---|
+| `light` | queda a medio camino entre `lighter` y `filled` | un banner dentro de una zona ya teñida |
+| `stroke` | blanco con borde: se confunde con la barra superior | arriba de un mapa o una foto a sangre |
+| `success` | no hay estados buenos que afecten a toda la app | «Tu local ya está publicado» el día que sale al aire |
+| `feature` | no hay novedades anunciadas arriba | anunciar una función nueva a todos los locales, con X para cerrarlo |
+| `showIcon=false` | sin el ícono se pierde el tipo | con un avatar o logo en `slot="icon"` |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `variant` | `'info' \| 'success' \| 'warning' \| 'error' \| 'feature'` | `'info'` |
+| `variantStyle` | `'filled' \| 'light' \| 'lighter' \| 'stroke'` | `'stroke'` |
+| `title` | `string \| null` | `null` |
+| `description` | `string \| null` | `null` |
+| `showIcon` | `boolean` | `true` |
+| `dismissible` | `boolean` | `false` |
+
+| output | payload |
+|---|---|
+| `closed` | `void` |
+<!-- api:fin -->
+
+Signal pública: `dismissed` (`signal(false)`). Slots: `[slot=icon]` (reemplaza el ícono del tipo)
+y `[slot=action]` (el link).
+
+## Trampas
+
+- **Defaults distintos al alert:** el banner arranca en `stroke` (blanco con borde), el alert en
+  `lighter`. Pásale siempre `variantStyle`.
+- **`feature` es gris** aquí (estado «faded» de la paleta) y morado en `sui-alert`.
+- No tiene `size` ni `actions[]`: la acción va **proyectada** en `slot="action"`, a diferencia del
+  alert. Los slots usan `slot=`, no `data-slot=`.
+- En web la altura es **fija** (44 px): un título más una descripción largos se cortan. En mobile sí
+  envuelve.
+- **La X se toca en 40 × 40** aunque se vea de 24 (un `::before` invisible sobre su `<button>`,
+  desde 03-10-2026). En mobile esa área se mete 4 px en el espacio del texto o del link de acción
+  (el padding derecho es 40 y la X ocupa de 4 a 44 px desde el borde): un toque justo en la última
+  letra del link puede caer en la X.
+- Al tocar la X se oculta solo (`dismissed`) y emite `closed`; no recuerda nada: si tiene que
+  quedarse cerrado entre sesiones, lo guarda el padre.
+- El host lleva `role="region"` con `aria-label` = `title`, y borra el `title` nativo.
+- En mobile, una pantalla con modal a pantalla completa tapa el banner: el de la suscripción se
+  esconde con `uiOverlay.fullscreenOpen()` para no quedar encima.
+
+## Ejemplo
+
+```html
+<!-- Aviso que acompaña -->
+<sui-banner variant="warning" variantStyle="lighter"
+  title="Tu plan vence en 3 días" description="Renueva para seguir recibiendo pedidos">
+  <sui-link-button slot="action" variant="modifiable" [underline]="true" (clicked)="renovar()">Renovar plan</sui-link-button>
+</sui-banner>
+
+<!-- Modo que cambia lo que haces: filled, sin X -->
+<sui-banner variant="warning" variantStyle="filled" title="Estás administrando Pollería El Dorado como super admin">
+  <sui-link-button slot="action" variant="modifiable" [underline]="true" (clicked)="salir()">Salir</sui-link-button>
+</sui-banner>
+```

package/docs/sui-brand-logo/README.md

@@ -0,0 +1,143 @@
+---
+name: sui-brand-logo
+selector: sui-brand-logo
+resumen: El logo oficial de otra marca (WhatsApp, Google, Apple, Instagram…) en su color, sin tocarlo
+alternativas: [sui-icon (el mismo logo como ícono monocromo de una línea), sui-logo (el logo de Master Pedidos), sui-social-button (botón de entrar con Google o Apple)]
+---
+
+# sui-brand-logo
+
+Story: [Atoms/Brand Logo](https://sui-design-system.web.app/?path=/docs/atoms-brand-logo--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** cuando **la marca es el contenido**: «Escríbenos por WhatsApp», los logos de redes de
+un negocio, una tarjeta de contacto. Va con su color oficial y no se tiñe.
+
+**No lo uses** para:
+
+- Un ícono más dentro de un botón o de una fila de íconos monocromos: ahí va `sui-icon`
+  (`whatsapp-line`, `apple-fill`), que toma el color del texto.
+- El botón de entrar con Google o Apple: `sui-social-button`, que ya lo trae adentro.
+- El logo de Master Pedidos: `sui-logo`.
+
+Regla corta: **la marca es lo que se muestra → brand-logo · es un ícono más → sui-icon.**
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para este componente.** Todo es **propuesta, falta
+> aprobación**.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos directos**. Lo usan por dentro
+> `sui-content-card` (`type="brand"`), `sui-social-button`, `sui-content-label`,
+> `sui-dropdown-item` y `sui-radio-card`. Además hay 9 logos de marca hechos con `sui-icon`
+> (`whatsapp-line`, `apple-fill`), que están bien donde son un ícono más.
+
+### `company`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `whatsapp` | Soporte y contacto con el negocio. | propuesta |
+| `google`, `apple` | Entrar con esa cuenta (vía `sui-social-button`). | propuesta |
+| `instagram`, `facebook` | Las redes del negocio o de la app. | propuesta |
+| las otras 23 (`adobe`, `notion`, `slack`, `stripe`…) | No usar hoy. | propuesta |
+
+**No hay TikTok** en el catálogo (son 28 marcas), aunque la app hace publicidad ahí.
+
+### `variant`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `original` (default) | El normal: sobre fondo claro, con su color oficial. | propuesta |
+| `white` | Sobre fondo oscuro o sobre foto. | propuesta |
+| `black` | No usar hoy. | propuesta |
+
+### `size`
+
+| valor | px | cuándo | fuente |
+|---|---|---|---|
+| `xs` | 16 | Dentro de un texto o de un tag. | propuesta |
+| `sm` | 20 | Dentro de un botón (lo usa `sui-social-button`). | propuesta |
+| `md` (default) | 24 | Fila de una lista. | propuesta |
+| `lg` | 32 | Tarjeta de contacto (el tamaño del Figma). | propuesta |
+| `xl` | 40 | Tarjeta grande. | propuesta |
+| `2xl` | 48 | Lo pide `sui-content-label` en tamaño grande. | propuesta |
+
+### `href`, `target`, `rel`, `disabled`, `ariaLabel`
+
+| input | cuándo | fuente |
+|---|---|---|
+| `href` + `target="_blank"` | El logo lleva a la red social. `rel` ya viene en `noopener noreferrer`. | propuesta |
+| `ariaLabel` | Con `href`, siempre: «Síguenos en Instagram». Sin `href`, el default («Instagram logo») alcanza. | propuesta |
+| `disabled` | No usar hoy. | propuesta |
+
+Usos de hoy que rompen la regla: **0**.
+
+## Tamaño en mobile y en web
+
+En mobile se lee y se toca con el dedo, así que va más grande; en web, más chico. En las
+pantallas que se usan en los dos (panel del local, super admin) se elige con el servicio de
+breakpoints de la app (`bp`, en `services/breakpoints.service.ts`); en las que solo existen en
+el celular (cliente, repartidor) va directo el valor de mobile. Todo es **propuesta**.
+
+| uso | mobile | web |
+|---|---|---|
+| tarjeta de contacto, fila | `lg` (32) | `md` (24) |
+| como link (con `href`, se toca) | `2xl` (48) | `lg` (32) |
+
+```html
+<sui-brand-logo company="instagram" [size]="bp.isMobile() ? '2xl' : 'lg'" [href]="url" target="_blank"
+                ariaLabel="Síguenos en Instagram" />
+```
+
+Con `href` el logo **es** el área táctil: en mobile tiene que medir 44 px o más, y el único
+tamaño que llega es `2xl` (48). Si se quiere un logo de 32 px tocable, el link va en un
+contenedor de 44 px.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| las 23 marcas ajenas | la app no se relaciona con Adobe, Notion, Slack… | una integración real (pagos con Stripe o PayPal) |
+| `variant` `black` | no hay un fondo donde vaya | una fila de «nos encuentras en» o de aliados donde el color distrae |
+| `disabled` | un logo apagado no explica nada | una integración que el local todavía no conectó, con el motivo al lado |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `company` | `SuiBrandLogoCompany` | — (requerido) |
+| `variant` | `'original' \| 'black' \| 'white'` | `'original'` |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| '2xl'` | `'md'` |
+| `href` | `string \| null` | `null` |
+| `target` | `string \| null` | `null` |
+| `rel` | `string \| null` | `'noopener noreferrer'` |
+| `disabled` | `boolean` | `false` |
+| `ariaLabel` | `string \| null` | `null` |
+
+Outputs: ninguno.
+<!-- api:fin -->
+
+## Trampas
+
+- **Los SVG no vienen en el paquete npm.** Se piden a `/assets/brand/brand-logos/<marca>-<variant>.svg`:
+  la app tiene que tener la carpeta copiada en `src/assets/brand/brand-logos/` (hoy la tiene, 84
+  archivos). Si falta, sale una imagen rota.
+- **No se tiñe**: es un `<img>`. Si necesitas otro color, es `sui-icon`.
+- **`variant` es el color**, no el tamaño ni la forma.
+- Con `href` y `disabled` a la vez, no se vuelve link.
+- El `aria-label` por defecto está en inglés («WhatsApp logo»): pasa `ariaLabel` en español.
+
+## Ejemplo
+
+```html
+<!-- Tarjeta de soporte -->
+<sui-brand-logo company="whatsapp" size="lg" />
+
+<!-- Red del negocio, como link -->
+<sui-brand-logo company="instagram" size="md" [href]="tenant.instagramUrl" target="_blank"
+                ariaLabel="Síguenos en Instagram" />
+```

package/docs/sui-breadcrumb-item/README.md

@@ -0,0 +1,96 @@
+---
+name: sui-breadcrumb-item
+selector: sui-breadcrumb-item
+resumen: Una miga suelta de la ruta; casi siempre la dibuja sui-breadcrumbs por ti
+alternativas: [sui-breadcrumbs (la ruta completa con separadores), sui-link-button (un enlace de texto suelto)]
+---
+
+# sui-breadcrumb-item
+
+Story: [Molecules/Breadcrumbs/Breadcrumb Item](https://sui-design-system.web.app/?path=/docs/molecules-breadcrumbs-breadcrumb-item--docs)
+
+## Cuándo usarlo / cuándo no
+
+**No lo uses directo.** `sui-breadcrumbs` lo dibuja por cada entrada de `items`, pone los
+separadores y decide cuál es el activo. Las reglas de cuándo mostrar una ruta están en el README de
+`sui-breadcrumbs`.
+
+**Úsalo suelto** solo si armas una ruta que `sui-breadcrumbs` no cubre: una miga con un menú
+desplegable al lado o un separador propio. Hoy no hay ningún caso.
+
+**Tampoco** para un enlace de texto que no es parte de una ruta («Ver todas»): `sui-link-button`.
+
+## Qué variante usar
+
+> **Lo que dice la guía del DS**: el ítem de la ruta tiene un estado `active` (la página actual),
+> puede llevar **ícono** y puede ser **un enlace**. No trae do/don't.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`): **0 usos**
+> directos (y 0 de `sui-breadcrumbs`).
+
+| input | valor | cuándo | fuente |
+|---|---|---|---|
+| `label` | texto | El nombre del nivel. | según la guía del DS |
+| `icon` | nombre RemixIcon | Solo el primer nivel (inicio), y con `ariaLabel` si va sin texto. | según la guía del DS (el ícono existe); el cuándo es propuesta |
+| `href` | ruta | Con ruta: dibuja un `<a>`; una ruta interna (`/…`) navega con el router sin recargar. | según la guía del DS (como enlace) |
+| `href` | vacío | Dibuja un `<button>` y avisa por `(clicked)`. | según el código |
+| `active` | `true` | La página actual: no es clicable, va en negro y lleva `aria-current="page"`. | según la guía del DS |
+| `ariaLabel` | texto | Obligatorio cuando va solo el ícono. | propuesta, falta aprobación |
+
+Usos de hoy que rompen las reglas: **0** (no se usa).
+
+## Tamaño en mobile y en web
+
+Alto fijo de **20 px**, sin `size`. **No tiene tamaño para mobile**, igual que `sui-breadcrumbs`:
+no se usa en mobile.
+
+| uso | mobile | web | fuente |
+|---|---|---|---|
+| miga | no se usa | el componente (dentro de `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 |
+|---|---|---|
+| suelto, fuera de `sui-breadcrumbs` | `sui-breadcrumbs` cubre todos los casos | una ruta con un selector en una miga (cambiar de local desde la ruta en web) |
+| en mobile | 20 px de alto | nunca |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| input | tipo | default |
+|---|---|---|
+| `label` | `string` | `''` |
+| `icon` | `string` | `''` |
+| `href` | `string` | `''` |
+| `active` | `boolean` | `false` |
+| `ariaLabel` | `string` | `''` |
+
+| output | payload |
+|---|---|
+| `clicked` | `void` |
+<!-- api:fin -->
+
+## Trampas
+
+- **`clicked` no sale cuando el ítem es `active`.**
+- **Con `href`, el clic navega y además emite `clicked`**: no navegues dos veces.
+- **El nombre de la clase es `SuiBreadcrumbItem`** y el de los datos de `sui-breadcrumbs` es
+  `SuiBreadcrumbEntry`. No son lo mismo.
+- No trae separador: el separador lo pone `sui-breadcrumbs`.
+
+## Ejemplo
+
+```html
+<!-- Lo normal: que lo dibuje sui-breadcrumbs -->
+<sui-breadcrumbs [items]="[{ label: 'Productos', href: '/empresa/productos' }, { label: 'Hamburguesas' }]" />
+
+<!-- Suelto, solo si de verdad hace falta -->
+<sui-breadcrumb-item icon="home-5-line" ariaLabel="Inicio" href="/empresa/inicio" />
+```

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' }]" />
+```