@ajuarezso/sui-stencil 0.0.0-stage → 0.1.0

package/docs/sui-form-label/README.md

@@ -0,0 +1,211 @@
+---
+name: sui-form-label
+selector: sui-form-label
+resumen: Rótulo de un campo o de un grupo de controles que no traen el suyo (asterisco, opcional, ayuda y link)
+alternativas: [el label propio de sui-input / sui-select / sui-textarea (campo de texto), sui-checkbox-label / sui-radio-label / sui-switch-label (un control con su texto), sui-page-header o sui-content-label (título de sección), sui-form-hint (la ayuda debajo)]
+---
+
+# sui-form-label
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-form-label`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+>
+> **La API de aquí no es igual a la de Angular.** Lo que el texto nombre y figure en «Diferencias con
+> el SUI Angular» (dentro de API) aquí no existe.
+
+Story: [Atoms/Form/Form Label](https://sui-design-system.web.app/?path=/docs/atoms-form-form-label--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para titular un campo **que no tiene label propio**: un grupo de `sui-radio-card`
+(«¿Cómo quieres recibir tu pedido?»), un bloque de casillas («Permisos»), un `sui-image-upload`
+(«Logo»), el punto en el mapa («Tu punto en el mapa»), una fila de chips.
+
+**No lo uses** para:
+
+- **Encima de un `sui-input`, `sui-select` o `sui-textarea`**: esos ya dibujan su label, asterisco,
+  sublabel y tooltip con `label`, `required`, `sublabel`, `tooltip`. Ponerle uno afuera
+  duplica la pieza y deja el `required` y el error separados del campo. El label interno sí
+  lleva `for` al `id` del control (desde el 04-10-2026); uno puesto afuera no lo conoce.
+- El texto de un solo checkbox, radio o switch: `sui-checkbox-label`, `sui-radio-label`,
+  `sui-switch-label`.
+- Un título de sección o de card («Datos personales»): `sui-page-header`, `sui-content-label` o
+  un heading.
+- Una explicación larga: va debajo, en `sui-form-hint`.
+
+Regla corta: **campo de texto → su propio `label` · grupo o control sin label → form-label · sección → heading.**
+
+## Qué variante usar
+
+> **La guía del DS dice que el label «da contexto a lo que la persona ingresa»** y trae tres
+> piezas: el label, el asterisco (campo obligatorio) y el sub (texto complementario). Su ejemplo
+> es «Last Name*(Optional)»: el opcional va **entre paréntesis** en el sub. Tiene un solo tamaño y
+> un estado deshabilitado. Info (tooltip) y el link de la derecha vienen del Figma del componente.
+>
+> Uso medido el 04-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`):
+> **37 usos en 13 archivos**: 13 con `required`, 7 con `sublabel="(Opcional)"`, 2 con `link`
+> («Cambiar»), 0 con `tooltip`, 0 con `disabled`; 6 con `size="medium"` explícito, el resto en el
+> default (`medium`).
+
+### Las piezas
+
+| prop | cuándo | fuente |
+|---|---|---|
+| `label` | Siempre. Una a tres palabras, sentence case, sin dos puntos ni punto final. | según la guía del DS (pieza); largo y forma según `docs/CANON-SUI.md` §5.4 |
+| `required` | Campo obligatorio: asterisco **rojo** (`state-error-base`). | según la guía del DS (asterisco = obligatorio); el color es canon (`docs/CANON-SUI.md` §4: excepción documentada) |
+| `sublabel` | «(Opcional)» en un formulario donde casi todo es obligatorio. Nunca el «opcional» dentro del `label`. | según la guía del DS (ejemplo «(Optional)») |
+| `tooltip` | Ayuda corta que no cabe en la pantalla y no hace falta para llenar el campo. Si hace falta, va visible en `sui-form-hint`. | canon (aprobado por el dueño, 05-10-2026, bloque B9) |
+| `link` | Una acción sobre el campo, a la derecha: «Cambiar» (el distrito). | canon (aprobado por el dueño, 05-10-2026, bloque B9); ya es práctica de la app: 2 usos |
+| `disabled` | El campo de abajo está deshabilitado. | según la guía del DS |
+| `for` | Siempre que el control de abajo tenga `id`. | propuesta, falta aprobación |
+
+### `size`
+
+| size | cuándo | fuente |
+|---|---|---|
+| `medium` (default) | Lo normal. | según la guía del DS (único tamaño) |
+| `small` | Es **idéntico** a `medium` (mismo CSS). No aporta. | — |
+| `xsmall` | No usar: con D16 no hay campos `xsmall`; en una tabla o filtro va `medium`. | canon (dueño, 05-10-2026, D16), reemplaza el «cuándo» del bloque B1 |
+
+La regla de controles grandes del dueño (28-09-2026) no aplica aquí: el `size` del label es
+tipografía, no área táctil.
+
+**Usos de hoy que rompen las reglas** (medido el 04-10-2026; los sublabels sin paréntesis, el
+«(opcional)» en el label, el número de paso en los labels de promociones y el Title Case de
+`drivers.html:28` ya se corrigieron en la app, commits `ce4a2d12` y `8128dc03`):
+
+- **8 encima de un campo que ya trae su label → pasar a `label` del campo:**
+  `pages/driver-onboarding/step-info/step-info.html:37` («Nombre completo»), `:56`, `:77`;
+  `pages/customer-onboarding/step-address/step-address.html:70` («Departamento», sobre
+  `sui-select`), `:87`, `:106`; `pages/driver-onboarding/step-vehicle/step-vehicle.html:49`, `:62`.
+  En esos mismos campos el `sui-form-hint` de abajo también es el `hint` del input.
+- **2 como título de sección → heading o `sui-content-label`:** `pages/customer/checkout/checkout.html:187`
+  («Datos personales») y `:35` («Recoges en el local»).
+- **1 encima de un `sui-textarea`**, que ya trae su `label`: `pages/promociones/promociones.html:201`
+  («Descripción»).
+- **3 con un switch armado a mano al lado → `sui-switch-label`:** `pages/discounts/discounts.html:204`,
+  `:316`; `components/add-product-modal/add-product-modal.html:206`.
+
+## Tamaño en mobile y en web
+
+| uso | mobile | web |
+|---|---|---|
+| rótulo de un grupo o control | `medium` (14 px) | `medium` (14 px) |
+| junto a un campo de una tabla o filtro | no aplica | `medium` (14 px): ya no hay campos `xsmall` (D16) |
+
+No necesita `bp`: es texto, no se toca. Lo único tocable es el `link` («Cambiar»), un
+`sui-link-button` de 12 px **sin tamaño para mobile**: su área táctil es la del texto. Si en
+mobile esa acción importa, conviene un botón aparte.
+
+### Por dispositivo (D16)
+
+No aplica: el `size` es tipografía, no área táctil, y no depende del dispositivo. Va `medium`
+(14 px) en el celular chico, el celular, la tablet táctil, la computadora y el ultrawide;
+`small` dibuja igual y `xsmall` no se usa (D16, dueño 05-10-2026: nada en `small`/`xsmall`).
+En master-pedidos: sin `size` (el default `medium` ya es el correcto) y sin `bp`.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| `size="small"` | dibuja igual que `medium` | nunca, hasta que el DS lo diferencie |
+| `tooltip` (0 usos) | toda la ayuda que hoy existe hace falta para llenar el campo, y va visible | un dato de contexto que la mayoría no necesita («¿Por qué pedimos tu DNI?») |
+| `disabled` (0 usos) | ningún grupo con form-label se deshabilita | un grupo de opciones que depende de otra elección previa |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `disabled` | `disabled` | `boolean` | `false` |
+| `htmlFor` | `html-for` | `null \| string` | `null` |
+| `label` | `label` | `string` | — (requerido) |
+| `link` | `link` | `SuiFormLabelLink \| null \| string` | `null` |
+| `required` | `required` | `boolean` | `false` |
+| `size` | `size` | `"medium" \| "small" \| "xsmall"` | `'medium'` |
+| `sublabel` | `sublabel` | `null \| string` | `null` |
+| `tooltip` | `tooltip` | `null \| string` | `null` |
+
+| evento | `event.detail` |
+|---|---|
+| `linkClick` | `MouseEvent` |
+
+### Diferencias con el SUI Angular
+
+- **Props de Angular que aquí no existen:** `for`
+- **Props solo de aquí:** `htmlFor`
+<!-- api:fin -->
+
+## Trampas
+
+- **`small` y `medium` se ven igual** (los dos 14 px). Solo `xsmall` cambia (12 px), y solo la letra.
+- **El sublabel no pone paréntesis**: escribe «(Opcional)» con paréntesis o queda pegado al label
+  (el espacio entre piezas es de 1 px).
+- **El asterisco es rojo**, no el naranja de marca (la guía lo pinta con el primario).
+- Los ejes del Figma se llaman distinto aquí: «Info» es `tooltip` y «Button» es `link`.
+- `link` como string emite `linkClick`; como objeto con `href` es un `<a>` real (con `_blank` agrega
+  `rel="noopener noreferrer"`). Se pinta en gris, empujado a la derecha.
+- El ícono de info es gris muy claro a propósito (baja jerarquía); se oscurece al pasar el mouse.
+
+## Bien y mal
+
+Campo de texto con su rótulo
+
+```html
+<!-- ❌ mal: sui-input ya dibuja su label y su asterisco (pages/driver-onboarding/step-info/step-info.html:37) -->
+<sui-form-label label="Nombre completo" required for="ob-name" />
+<sui-input size={bp.sizeControl()} type="text" value={nombre} onValueChange={(e) => (nombre = e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-input size={bp.sizeControl()} type="text" label="Nombre completo" required value={nombre} onValueChange={(e) => (nombre = e.detail)} />
+```
+
+Título de una sección
+
+```html
+<!-- ❌ mal: «Datos personales» titula la sección, no un campo (pages/customer/checkout/checkout.html:187) -->
+<section class="checkout__section">
+  <sui-form-label label="Datos personales" size="medium" />
+```
+
+```html
+<!-- ✅ bien -->
+<section class="checkout__section">
+  <h2 class="checkout__section-title">Datos personales</h2>
+```
+
+Rótulo de un switch
+
+```html
+<!-- ❌ mal: label, ayuda y switch armados a mano (pages/discounts/discounts.html:204) -->
+<sui-form-label label="Un uso por cliente" />
+<span class="discounts__form-hint">Si activas esto, cada cliente solo podrá usar el cupón…</span>
+<sui-switch size={bp.controlSize()} checked={unUso()} onCheckedChange={(e) => unUso.set(e.detail)} />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-switch-label size={bp.controlSize()} label="Un uso por cliente"
+                  description="Cada cliente usa el cupón una sola vez"
+                  active={unUso()} onActiveChange={(e) => unUso.set(e.detail)} />
+```
+
+## Ejemplo
+
+```html
+<!-- Grupo de opciones sin label propio -->
+<sui-form-label label="Método de pago" required />
+<sui-radio-group ngModel={metodo} onNgModelChange={(e) => (metodo = e.detail)}>…</sui-radio-group>
+
+<!-- Campo de texto: el label va en el propio input, no en un form-label -->
+<sui-input label="Placa del vehículo" sublabel="(Opcional)" value={placa} onValueChange={(e) => (placa = e.detail)} />
+```

package/docs/sui-href/README.md

@@ -0,0 +1,67 @@
+---
+name: sui-href
+selector: (función, sin elemento)
+resumen: Port de la directiva Angular `a[suiHref]`. En Stencil no hay directivas ni Router, así que es una función que los componentes del DS llaman desde el `onClick` de su `<a>`. No dibuja nada
+alternativas: []
+---
+
+# sui-href
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> Utilidad, no elemento: no hay `<sui-href>`. Este doc sale de `src/components/sui-href/readme.md`, escrito a mano porque
+> Stencil no documenta funciones.
+
+Port de la directiva Angular `a[suiHref]`. En Stencil no hay directivas ni Router, así que es una
+**función** que los componentes del DS llaman desde el `onClick` de su `<a>`. No dibuja nada.
+
+```tsx
+import { suiHrefClick } from '../sui-href/sui-href';
+
+<a href={this.href} target={this.target} onClick={(ev) => suiHrefClick(ev, this.href)}>…</a>
+```
+
+Hoy la usa `sui-topbar-item`. Los demás componentes del DS con `href` (`sui-link-button`,
+`sui-compact-button`, `sui-fancy-button`, `sui-social-button`, `sui-breadcrumb-item`,
+`sui-brand-logo`, `sui-app-store-badge`, `sui-rating`, `sui-progress-bar-label`) todavía pintan un
+`href` crudo: pasarlos a `suiHrefClick` es un pendiente aparte.
+
+## Cómo navega sin recargar
+
+En vez de `router.navigateByUrl(href)` (Angular), despacha el evento **`suiNavigate`**
+(cancelable, `bubbles` + `composed`, `detail: { href }`). El router de la app lo escucha y llama
+`preventDefault()`; recién ahí se cancela el click y no hay recarga:
+
+```js
+document.addEventListener('suiNavigate', (e) => {
+  e.preventDefault();
+  router.navigateByUrl(e.detail.href); // o history.pushState, el router que use la app
+});
+```
+
+Si nadie lo escucha, el link es un `<a href>` común y corriente (el «sin Router» del Angular).
+
+| `href` | qué hace al tocarlo |
+|---|---|
+| empieza con `/` (no `//`) | `suiNavigate`; si la app lo cancela, navegación sin recargar (conserva query y `#`) |
+| `https://…`, `mailto:`, `tel:`, `#…`, `//host` | lo que haga el navegador |
+| cualquiera, con `target` distinto de `_self` | lo que haga el navegador (nueva pestaña) |
+| cualquiera, con cmd/ctrl/shift/alt o botón del medio | lo que haga el navegador |
+| `null` o `''` | nada (el componente no pinta `href`) |
+
+## API
+
+<!-- api:inicio -->
+| export | tipo |
+|---|---|
+| `suiHrefClick(ev, href)` | `(MouseEvent, string \| null \| undefined) => boolean` — `true` si la navegación la tomó la app |
+| `SUI_NAVIGATE_EVENT` | `'suiNavigate'` |
+| `SuiNavigateDetail` | `{ href: string }` |
+<!-- api:fin -->
+
+## Trampas
+
+- El atributo `href` real queda puesto: clic del medio, «copiar enlace» y «abrir en pestaña nueva»
+  siguen funcionando. Solo el clic normal se intercepta.
+- Si el componente ya hizo `preventDefault()` antes, no navega.
+- Un `href` relativo sin `/` inicial (`pedidos/123`) **no** se intercepta: pasa rutas absolutas.

package/docs/sui-icon/README.md

@@ -0,0 +1,216 @@
+---
+name: sui-icon
+selector: sui-icon
+resumen: Un ícono monocromo de RemixIcon (o uno propio del DS) que toma el color del texto
+alternativas: [sui-key-icon (el ícono dentro de un círculo de color), sui-emoji (emoji con emoción), sui-brand-logo (el logo de otra marca en su color), sui-compact-button (un ícono que se toca)]
+---
+
+# sui-icon
+
+<!-- generado por scripts/gen-docs.mjs — no editar a mano; `npm run docs` -->
+
+> **De dónde sale este doc.** El criterio es el del SUI Angular (`sui-icon`); la API es la de este
+> paquete, leída del código. Los ejemplos se pasaron de Angular de forma mecánica: lo literal va como
+> atributo (`only-icon`, `size="large"`), lo dinámico entre llaves (`size={expr}` → `el.size = expr`)
+> y los eventos como `onValueChange={…}` → `el.addEventListener('valueChange', …)`. `@if`, `@for` y
+> `<ng-template>` quedan como en Angular: se leen como pseudocódigo.
+
+Story: [Atoms/Icon/Icon](https://sui-design-system.web.app/?path=/docs/atoms-icon-icon--docs)
+
+## Cuándo usarlo / cuándo no
+
+**Úsalo** para **todo ícono**: dentro de un texto, una fila, una card, un título. Es la única
+forma de poner un ícono: nada de `<i class="ri-…">` ni SVG pegado en el template. Los íconos
+propios del DS (`info-custom-fill`, `heart-half-fill`…) también pasan por aquí.
+
+**No lo uses** para:
+
+- Un ícono que se toca: `sui-compact-button` o un `sui-button` con `leftIcon`/`onlyIcon`.
+- Un ícono dentro de un círculo de color (cabecera de un modal, inicio de una fila): `sui-key-icon`.
+- Emoción (estado vacío, celebración): `sui-emoji`.
+- El logo de una marca cuando la marca es lo que se muestra: `sui-brand-logo`.
+
+## Qué variante usar
+
+> **La guía del DS no tiene página para el ícono**: usa RemixIcon en todos sus ejemplos, sin
+> reglas de tamaño. La escala de abajo sale de los tokens del DS (`--sui-icon-size-*` y
+> `--sui-icon-*` en `sui-tokens.scss`). Lo marcado «canon» ya es regla del proyecto; lo que sigue
+> en **propuesta** espera decisión.
+>
+> Uso medido el 03-10-2026 en `master-pedidos/src/app`: 406 íconos en 95 archivos, sin contar
+> prototipos ni vitrinas. 331 `-line`, 43 `-fill`. Ninguno usa el input `color`.
+
+### `size`
+
+| valor | tamaño de hoy | cuándo | fuente |
+|---|---|---|---|
+| `12` | 5 | Dentro de un badge `small`. | canon (aprobado por el dueño, 05-10-2026, bloque B1), token `--sui-icon-size-xs` |
+| `16` | 69 | Junto a texto chico: metadatos, botones `2xsmall`/`xsmall`, dentro de un kbd. | canon (aprobado por el dueño, 05-10-2026, bloque B1), token `--sui-icon-size-sm` |
+| `20` (default) | 114 | El normal: botones, inputs, filas, navegación. | canon (aprobado por el dueño, 05-10-2026, bloque B1), token `--sui-icon-size-md` |
+| `24` | 5 | Cabeceras y acciones sueltas. | canon (aprobado por el dueño, 05-10-2026, bloque B1), token `--sui-icon-size-lg` |
+| `32` | 2 | Ícono protagonista. Si va dentro de un círculo, es `sui-key-icon`. | canon (aprobado por el dueño, 05-10-2026, bloque B1), token `--sui-icon-size-xl` |
+| `26` | 7 | Solo el ícono del hero de los onboarding (`ob__hero-icon`). | canon (`CLAUDE.md`, patrón de los pasos de onboarding) |
+| `14`, `18` | 149 | Fuera de la escala, pero el DS mismo los usa (tabs, product-card). **A discutir**: no migrar en masa. | propuesta |
+| `13`, `22`, `28`, `44`… | 49 | Sin regla: van al más cercano de la escala. | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+
+**Usos de hoy fuera de la escala sin regla: 49.** `22` (20 usos: `components/ota-quick-fab/ota-quick-fab.html:11`,
+`pages/schedule/schedule.html:10`), `13` (14: `pages/super-admin/master-drivers/master-drivers.html:359`, `:419`),
+`28` (4: `pages/envios/envios.html:691`), `44`, `48` y `36` (6: `pages/support/support.html:9`,
+`components/product-detail-view/product-detail-view.html:30`), y uno cada uno de `10`, `11`, `15`,
+`30`, `34`. Los de 36 px en adelante casi siempre son un ícono protagonista que quiere ser
+`sui-key-icon` o un `sui-emoji`.
+
+### `name`: `-line` o `-fill`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| `-line` | El normal. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| `-fill` | El seleccionado (el tab activo) o un glifo chico sobre color. | canon (aprobado por el dueño, 05-10-2026, bloque B2) |
+| propios del DS (`info-custom-fill`, `heart-half-fill`, `building-skyline`, `avatar-placeholder`) | Los usan componentes del DS; en la app no hacen falta. | canon (aprobado por el dueño, 05-10-2026, bloque B6) |
+
+### `color`
+
+| valor | cuándo | fuente |
+|---|---|---|
+| sin `color` (default) | El normal: hereda el color del texto. Casi siempre es lo que se quiere. | canon (aprobado por el dueño, 05-10-2026, bloque B3) |
+| `var(--sui-icon-sub-600)` | Ícono de apoyo junto a un texto principal. | canon (CANON-SUI §4.1: los íconos siguen la semántica del texto; sub-600 = secundario que igual se lee) |
+| `var(--sui-icon-soft-400)` | Decorativo, metadatos. | canon (CANON-SUI §4.1: soft-400 = lo que no es contenido, metadata terciaria) |
+| `var(--sui-icon-disabled-300)` | Deshabilitado. | canon (CANON-SUI §4.1: disabled-300 solo para disabled) |
+| `var(--sui-icon-white-0)` | Sobre fondo oscuro o de color. | propuesta |
+| un hex o un color de estado | No usar: si el ícono dice un estado, va en `sui-key-icon` `lighter`. | propuesta |
+
+## 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) también se usa `bp`, porque el celular chico va con el valor de
+web. No se toca, así que la tablet va con el valor de web, y el celular chico (< 380 px) también (D16).
+Es **canon (dueño, 05-10-2026, P1 b)**: un paso más grande en el celular que en computadora, y
+se migra todo ahora, no solo al tocar cada pantalla.
+
+| uso | mobile | web |
+|---|---|---|
+| junto al texto de una fila | `20` | `16` |
+| ícono protagonista | `32` | `24` |
+| metadatos | `16` | `16` |
+| dentro de un botón o un input | lo decide el componente | igual |
+
+```html
+<sui-icon name="store-2-line" size={bp.celular() ? 20 : 16} />
+```
+
+Un ícono suelto **nunca** es el área táctil: si se toca, va en `sui-compact-button` o
+`sui-button` `onlyIcon`, que dan los 44 px. Hoy solo 2 íconos cambian por breakpoint
+(`pages/discounts/discounts.html:103` y `:108`, con `bp.isTablet() ? 20 : 16`), y los dos están
+mal: van dentro de un `sui-button`, que ya le da al ícono una caja de 20, así que no llevan
+`size`. Hasta 1024 px dibujan 20 y llenan la caja (no se nota); en una computadora de más de
+1024 px dibujan 16 y el glifo queda chico dentro de esa caja. Además `isTablet` no es un corte
+de D16 (ver «Bien y mal»).
+
+### Por dispositivo (D16)
+
+El ícono no se toca: sube un paso **solo en el celular de 380 px o más**. Fuente: D16, dueño
+05-10-2026 (P1 b).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | valor «web» (`16` en una fila, `24` protagonista) | no se toca: no sube aunque sea un celular |
+| celular (380–767) | valor «mobile» (`20` junto al texto de una fila, `32` protagonista) | un paso más que en la computadora |
+| tablet táctil (`pointer: coarse`) | valor «web» (`16` en una fila, `24` protagonista) | no se toca: el puntero no cambia nada |
+| computadora (`pointer: fine`) | valor «web» (`16` en una fila, `24` protagonista) | |
+
+En el ultrawide, igual que en la computadora: el espacio extra va a más columnas, no a íconos
+más grandes. Dentro de un botón o un input no se pasa `size`: lo decide el componente.
+
+En master-pedidos no hay helper: `size={bp.celular() ? 20 : 16}` (fila) o
+`size={bp.celular() ? 32 : 24}` (protagonista). No uses `bp.isMobile()` (incluye el celular
+chico) ni `bp.isTablet()` (incluye la tablet y la laptop de hasta 1024 px): los dos van con el
+valor de web.
+
+## «No usar»: por qué no hoy y cuándo sí
+
+| qué | por qué no hoy | cuándo sí, en un flujo nuevo |
+|---|---|---|
+| tamaños `13`, `22`, `28`, `44`… | no hay regla que los pida | ninguno: van al más cercano de 12/16/20/24/32 |
+| `color` con un hex | rompe el tema oscuro | ninguno |
+| `<i class="ri-…">` o SVG pegado | se salta el componente | ninguno |
+
+## API
+
+<!-- api:inicio -->
+<!-- generada: no editar a mano — `npm run docs` -->
+
+| prop | atributo | tipo | default |
+|---|---|---|---|
+| `color` | `color` | `string` | `''` |
+| `name` | `name` | `string` | — (requerido) |
+| `size` | `size` | `number \| string` | `20` |
+
+Eventos: ninguno.
+
+### Diferencias con el SUI Angular
+
+Ninguna en nombres de props, eventos y valores.
+<!-- api:fin -->
+
+## Trampas
+
+- **`name` va sin el prefijo `ri-`**: `name="store-2-line"`, no `ri-store-2-line`.
+- **`size` acepta número o string**: `size="20"` son px; `size="1.25em"` es CSS. Con
+  `size="20"` (string sin unidad) el ícono no toma tamaño.
+- **El nombre no se valida**: si no existe en RemixIcon, sale vacío sin error.
+- **No tiene `aria-label` y es decorativo siempre**: el SVG propio y el `<i>` de RemixIcon llevan
+  `aria-hidden="true"` (el `<i>` desde el 04-10-2026; antes el lector podía leer el glifo como un
+  símbolo raro). Si el ícono es lo único que dice algo, el texto va al lado o en el contenedor.
+- **La app necesita la fuente de RemixIcon** (`remixicon/fonts/remixicon.css` en `styles.scss`):
+  el paquete del DS no la trae.
+- Dentro de un `sui-kbd`, el kbd le fuerza el color `text-sub-600`.
+
+## Bien y mal
+
+Ícono de una acción en una tabla
+
+```html
+<!-- ❌ mal: el botón ya le da al ícono su caja de 20 y no hace falta size; en la computadora de más de 1024 px isTablet dibuja el glifo en 16 dentro de ella (pages/discounts/discounts.html:103) -->
+<sui-button variant="ghost" color="neutral" size={bp.sizeControl()} only-icon aria-label="Editar">
+  <sui-icon slot="start" name="edit-2-line" size={bp.isTablet() ? 20 : 16} />
+</sui-button>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-button variant="ghost" color="neutral" size={bp.sizeControl()} only-icon
+            left-icon="edit-2-line" aria-label="Editar" />
+```
+
+Ícono protagonista
+
+```html
+<!-- ❌ mal: 28 está fuera de la escala y no cambia por dispositivo (pages/envios/envios.html:712) -->
+<sui-icon class="seg__buscando-icono" name="e-bike-2-line" size="28" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-icon class="seg__buscando-icono" name="e-bike-2-line" size={bp.celular() ? 32 : 24} />
+```
+
+Tamaño como texto
+
+```html
+<!-- ❌ mal: un string sin unidad no es un tamaño CSS válido; el ícono no toma tamaño (Trampas) -->
+<sui-icon name="time-line" size="20" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-icon name="time-line" size="20" />
+```
+
+## Ejemplo
+
+```html
+<sui-icon name="store-2-line" size="16" />
+<sui-icon name="time-line" size="20" color="var(--sui-icon-sub-600)" />
+```