@ajuarezso/sui-design-system 0.25.0 → 0.25.2

package/docs/sui-file-icon/README.md

@@ -69,6 +69,21 @@ El ícono no se toca: si la fila abre el archivo, la fila da los 44 px. `medium`
 grande que tiene y `xsmall` es chico (D16), así que va igual en las dos: es la excepción a P1 b
 («un paso más grande en el celular»), porque no hay un paso más.
 
+### Por dispositivo (D16)
+
+No se toca; la fila de `file-icon` de la tabla D16 manda (canon, dueño, 05-10-2026, D16).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380 px) | `medium` (40) | |
+| celular (380–767 px) | `medium` (40) | es el más grande que tiene: no hay un paso más para subir (P1 b) |
+| tablet táctil (`pointer: coarse`) | `medium` (40) | si la fila abre el archivo, los 44 los da la fila |
+| computadora (`pointer: fine`) | `medium` (40) | también en filas densas y tablas; `xsmall` no se usa |
+
+Ultrawide (≥ 1920 px): igual, `medium`.
+
+En master-pedidos: `size="medium"` fijo, o se omite (es el default). No hay helper ni hace falta `bp`.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |
@@ -98,9 +113,49 @@ Outputs: ninguno.
 - El nombre para el lector de pantalla es «Archivo PDF» (en español desde el 04-10-2026) y no se puede cambiar.
 - `size` es `xsmall` o `medium`: no hay `small` ni `large`.
 
+## Bien y mal
+
+**Un archivo en una tabla**
+
+```html
+<!-- ❌ mal: xsmall es chico (D16). La vitrina (master-preview/_guia-atomos/identidad.ts:422)
+     todavía lo ofrece para «filas densas, tablas» -->
+<sui-file-icon [filename]="doc.nombre" size="xsmall" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-file-icon [filename]="doc.nombre" size="medium" />
+```
+
+**El color del tipo**
+
+```html
+<!-- ❌ mal: forzar el color miente; un CSV en rojo parece PDF (vitrina identidad.ts:424) -->
+<sui-file-icon filename="ventas.csv" color="red" />
+```
+
+```html
+<!-- ✅ bien: el color sale solo de la extensión (CSV en verde) -->
+<sui-file-icon filename="ventas.csv" />
+```
+
+**Un archivo que se está subiendo**
+
+```html
+<!-- ❌ mal: el ícono solo no dice cómo va la subida («Cuándo no») -->
+<sui-file-icon filename="carta-octubre.pdf" />
+```
+
+```html
+<!-- ✅ bien: la card ya trae el ícono, la barra y el estado -->
+<sui-file-upload-card file="carta-octubre.pdf" state="in-progress" [progress]="45"
+                      description="1.2 MB de 2.6 MB" />
+```
+
 ## Ejemplo
 
 ```html
 <sui-file-icon filename="comprobante-yape.pdf" />
-<sui-file-icon filename="ventas-setiembre.csv" size="xsmall" />
+<sui-file-icon filename="ventas-setiembre.csv" size="medium" />
 ```

package/docs/sui-file-upload/README.md

@@ -31,7 +31,9 @@ elegido → file-upload-card.**
 > («Elige un archivo o arrástralo aquí»), una línea con **formatos y tamaño máximo** («JPEG, PNG,
 > PDF y MP4, hasta 50 MB») y el botón **«Buscar archivo»**. Trae aparte el ícono por tipo de
 > archivo (en SUI, `sui-file-icon`). No dice cuándo usar cada tamaño. Lo de abajo marcado canon
-> está aprobado; lo que sigue en **propuesta** (el `small` en mobile) espera decisión.
+> está aprobado; el `small` en mobile sigue en propuesta: lo cubre **P13, pendiente**. D16 en
+> general no usa `small`, pero la hoja de decisiones (05-10-2026) dejó estas filas esperando la
+> respuesta a P13.
 >
 > Uso medido el 03-10-2026 en `master-pedidos/src/app`: **0 usos**. Hoy todo lo que se sube es
 > imagen y va con `sui-image-upload` (13) o con un `<input type="file">` a mano (3: `renewal-modal`,
@@ -57,8 +59,8 @@ elegido → file-upload-card.**
 
 | valor | padding | cuándo | fuente |
 |---|---|---|---|
-| `small` | 24 | En mobile y dentro de un modal o una card. | propuesta |
-| `medium` (default) | 32 | En web, en una página o un modal ancho. | guía (es el único tamaño que muestra) |
+| `small` | 24 | Propuesta: en mobile y dentro de un modal o una card. Pendiente (P13): la opción recomendada es que no (en mobile `medium` o `large`, por D8), y D16 en general no usa `small`, pero el dueño todavía no respondió. | pendiente (P13) |
+| `medium` (default) | 32 | En web, en una página o un modal ancho. En mobile: pendiente (P13). | guía (es el único tamaño que muestra) |
 | `large` | 40 | Cuando subir el archivo es lo único de la pantalla (importar la carta). | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
 | `xlarge` | 48 | No usar: más aire no ayuda a soltar el archivo. | no usar |
 
@@ -74,17 +76,17 @@ Usos de hoy que rompen la regla: **0** (no hay file-upload).
 ## Tamaño en mobile y en web
 
 En mobile se toca con el dedo: lo que se toca mide **44 px o más**. Aquí **toda el área se toca**
-(abre el selector), así que pasa en cualquier tamaño; en el celular no se arrastra, por eso va
-más compacta. En pantallas de los dos, con el servicio de breakpoints de la app (`bp`, en
-`services/breakpoints.service.ts`).
+(abre el selector), así que pasa en cualquier tamaño. En pantallas de los dos, con el servicio
+de breakpoints de la app (`bp`, en `services/breakpoints.service.ts`).
 
 | uso | mobile | web | fuente |
 |---|---|---|---|
-| subir un documento en un formulario o modal | `small` | `medium` | propuesta |
-| subir es lo único de la pantalla | `medium` | `large` | canon (aprobado por el dueño, 05-10-2026, bloque B1) |
+| subir un documento en un formulario o modal | pendiente (P13) | `medium` | mobile: pendiente (P13; la propuesta era `small`) · web: guía |
+| subir es lo único de la pantalla | `medium` | `large` | canon (aprobado por el dueño, 05-10-2026, bloque B1) · va al revés de D16: ver abajo |
 
 ```html
-<sui-file-upload [size]="bp.isMobile() ? 'small' : 'medium'"
+<!-- en web, en un formulario o modal; el size en mobile espera P13 -->
+<sui-file-upload size="medium"
                  title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB"
                  accept=".pdf" [maxSize]="10 * 1024 * 1024" (filesSelected)="subir($event)" />
 ```
@@ -93,6 +95,20 @@ Llena el ancho del contenedor (antes 400 fijo; extensión SUI, 03-10-2026). El b
 archivo» mide 32 px (`xsmall`) en todos los tamaños: solo, en mobile **no
 llegaría**; pasa porque el área entera también abre el selector.
 
+### Por dispositivo (D16)
+
+**Pendiente (P13).** `file-upload` no está en la tabla por componente de D16, y la hoja de
+decisiones (05-10-2026, «Lo que esta hoja no cierra») deja sus dos filas de tamaño esperando P13.
+Se toca, así que la regla general de D16 sería «lo que se toca»: grande en el celular y en la
+tablet, `medium` en la computadora (y en ultrawide). Eso choca con la fila de B1 («subir es lo
+único de la pantalla»: `medium` en mobile y `large` en web), que va en la dirección contraria, y
+D16 dice que reemplaza el tamaño por plataforma. Cuál manda no está decidido: se resuelve con P13.
+
+Hasta entonces, lo cerrado es: `medium` en la computadora en un formulario o modal (guía) y
+`xlarge` no se usa. Si P13 cierra con la regla general de D16, en master-pedidos quedaría
+`[size]="bp.tactil() ? 'large' : 'medium'"` (no hay helper propio; `sizeControl()` es de
+botón, input, select y textarea).
+
 ## «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
@@ -148,6 +164,50 @@ en la columna de la derecha, se usa (aprobado por el dueño, 03-10-2026).
   hace quien lo usa.
 - El atributo `title` del host se borra solo (no sale el tooltip gris del navegador).
 
+## Bien y mal
+
+**El error que se pasa a mano**
+
+```html
+<!-- ❌ mal: el componente ya muestra solo el aviso de tamaño debajo del área (y lo emite por errorEvent); este errorMessage lo tapa con otro texto -->
+<sui-file-upload accept=".pdf" [maxSize]="10 * 1024 * 1024"
+                 title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB"
+                 [error]="pesaDeMas()" errorMessage="El archivo pesa más de 10 MB" />
+```
+
+```html
+<!-- ✅ bien: errorMessage solo para lo que rechaza el servidor después de subirlo -->
+<sui-file-upload accept=".pdf" [maxSize]="10 * 1024 * 1024"
+                 title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB"
+                 [error]="rechazado()" errorMessage="El PDF está protegido con clave" />
+```
+
+**El límite de tamaño**
+
+```html
+<!-- ❌ mal: maxSize va en bytes (10 = 10 bytes) y el subtitle no dice formatos ni tamaño (Trampas) -->
+<sui-file-upload accept=".pdf" [maxSize]="10" title="Sube tu carta" />
+```
+
+```html
+<!-- ✅ bien: el mismo límite en el filtro y en el texto -->
+<sui-file-upload accept=".pdf" [maxSize]="10 * 1024 * 1024"
+                 title="Sube tu carta en PDF" subtitle="PDF, hasta 10 MB" />
+```
+
+**El filtro y el texto**
+
+```html
+<!-- ❌ mal: el subtitle promete Excel y accept lo rechaza: la persona elige un archivo que no entra -->
+<sui-file-upload accept=".pdf" title="Sube tu carta" subtitle="PDF o Excel, hasta 10 MB" />
+```
+
+```html
+<!-- ✅ bien: lo que promete el subtitle es lo que dejan pasar accept y maxSize -->
+<sui-file-upload accept=".pdf,.xlsx" [maxSize]="10 * 1024 * 1024"
+                 title="Sube tu carta" subtitle="PDF o Excel, hasta 10 MB" />
+```
+
 ## Ejemplo
 
 ```html

package/docs/sui-file-upload-card/README.md

@@ -65,10 +65,18 @@ reintente.
 | «Reintentar» | link de 20 px — **no llega** | link | medido |
 
 ```html
-<sui-file-upload-card [file]="a.nombre" [state]="a.estado" [progress]="a.pct"
-                      [description]="a.peso" (actionClicked)="quitar(a)" (retryClicked)="reintentar(a)" />
+<sui-file-upload-card [file]="a.nombre" [state]="a.estado" [progress]="a.pct" [description]="a.peso"
+                      (actionClicked)="a.estado === 'in-progress' ? cancelar(a) : quitar(a)"
+                      (retryClicked)="reintentar(a)" />
 ```
 
+### Por dispositivo (D16)
+
+No aplica: **no tiene input `size`** y nada en ella cambia por dispositivo (la fila llena el ancho y
+la X o el tacho mide 32 en el celular, la tablet y la computadora). Que esa X y «Reintentar» lleguen
+a 44 en lo táctil es trabajo pendiente del DS, no un `size` que se elija. En master-pedidos: sin
+`[size]` ni `bp`.
+
 ## «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
@@ -120,6 +128,49 @@ interface SuiFileUploadCardFile { filename: string; extension?: string; }
 - La barra de progreso es azul, no naranja.
 - No sube nada: refleja el estado que le pasan.
 
+## Bien y mal
+
+**El peso del archivo**
+
+```html
+<!-- ❌ mal: coma decimal; el canon es punto, como el «10.0 MB» de sui-file-upload
+     (vitrina master-preview/_guia-moleculas/fechas.ts:182) -->
+<sui-file-upload-card file="carta-octubre.pdf" state="in-progress" [progress]="45"
+                      description="1,2 MB de 2,6 MB" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-file-upload-card file="carta-octubre.pdf" state="in-progress" [progress]="45"
+                      description="1.2 MB de 2.6 MB" />
+```
+
+**Los textos de fábrica**
+
+```html
+<!-- ❌ mal: sin description sale «0 KB de 120 KB», y sin progress la barra arranca en 10 -->
+<sui-file-upload-card [file]="a.nombre" state="in-progress" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-file-upload-card [file]="a.nombre" state="in-progress" [progress]="a.pct" [description]="a.peso" />
+```
+
+**La X de la derecha**
+
+```html
+<!-- ❌ mal: mientras sube, la X cancela; tratarla siempre como «quitar» (Trampas) -->
+<sui-file-upload-card [file]="a.nombre" [state]="a.estado" [description]="a.peso"
+                      (actionClicked)="quitar(a)" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-file-upload-card [file]="a.nombre" [state]="a.estado" [description]="a.peso"
+                      (actionClicked)="a.estado === 'in-progress' ? cancelar(a) : quitar(a)" />
+```
+
 ## Ejemplo
 
 ```html

package/docs/sui-filter/README.md

@@ -40,7 +40,7 @@ panel (header + items + footer) · un filtro suelto → compact-select.**
 
 > **La guía del DS no tiene página de filtros**: estas piezas salen solo del Figma del DS
 > («Filters»: HorizontalFilter y VerticalFilter). Las reglas marcadas canon están aprobadas; lo
-> que sigue en **propuesta** (la barra y el item en mobile) espera decisión.
+> que sigue **pendiente** (el área de 44 de `sui-filter-item` en mobile, P19) espera decisión.
 >
 > Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-dropdown-menu`):
 > **0 usos**. Solo aparecen en la vitrina `master-preview`.
@@ -72,20 +72,42 @@ Ninguna pieza cambia sola en mobile, salvo la barra, que apila sus dos lados por
 
 | pieza | mobile | web | fuente |
 |---|---|---|---|
-| `sui-filter-bar` | sin tamaño; los controles adentro van `large` (48) | sin tamaño; los controles `medium` (40) | web: canon (dueño, 05-10-2026, D16) · mobile: propuesta (igual que `sui-compact-select` en una barra) |
-| `sui-filter-item` | 36 de alto, no se puede cambiar: debajo de los 44 del dedo | 36 | propuesta |
+| `sui-filter-bar` | sin tamaño; los controles adentro van `large` (48) | sin tamaño; los controles `medium` (40) | canon (D16, dueño 05-10-2026) |
+| `sui-filter-item` | 36 de alto, no se puede cambiar: debajo de los 44 del dedo | 36 | pendiente (P19: área invisible de 44 o no usarlo en mobile) |
 | `sui-filter-panel-footer` | `medium` (40) es lo más grande que tiene; en mobile, mejor `sui-modal-footer` (48) dentro de un `sui-modal-sheet` | `medium` (40) | canon para el 48 de mobile (CLAUDE.md: footer de modal `large`); web `medium` (40): canon (dueño, 05-10-2026, D16), reemplaza el `small` del bloque B1 (`small` es el default del componente: hay que pasarlo) |
 | `sui-filter-panel-header` | sin tamaño | sin tamaño | — |
 
 ```html
 <sui-filter-bar>
-  <sui-segmented-control slot="start" … />
+  <sui-segmented-control slot="start" [size]="bp.tactil() ? '2xlarge' : 'medium'" … />
   <div slot="end">
-    <sui-input type="search" [size]="bp.isMobile() ? 'large' : 'medium'" placeholder="Buscar pedido…" … />
+    <sui-input type="search" [size]="bp.sizeControl()" placeholder="Buscar pedido…" … />
   </div>
 </sui-filter-bar>
 ```
 
+### Por dispositivo (D16)
+
+Las piezas no tienen un `size` propio (salvo el pie): lo que cambia por dispositivo son los
+controles que se proyectan en la barra. Fuente: D16, dueño 05-10-2026 (fila `filter`).
+
+| dispositivo | size | nota |
+|---|---|---|
+| celular chico (< 380) | sin regla en la tabla (`—`) | la fila `filter` de D16 no lo define; `bp.sizeControl()` da `large`, igual que en el celular, mientras el DS no estire a 44 el área de los `medium` |
+| celular (380–767) | controles `large` · segmented `2xlarge` | el panel va en un `sui-modal-sheet` con `sui-modal-footer` (48), no con este pie; el área de 44 de `sui-filter-item` está pendiente (P19) |
+| tablet táctil (`pointer: coarse`) | controles `large` · segmented `2xlarge` | se toca como un celular: el panel lleva `sui-modal-footer` (48) en vez de este pie, que llega solo a `medium` (40). D16 no fija el pie en la tablet; esto sigue la columna «mobile» de arriba. El área de 44 de `sui-filter-item` está pendiente (P19), igual que en el celular |
+| computadora (`pointer: fine`) | controles `medium` · `sui-filter-panel-footer` `medium` | el default del pie es `small`: hay que pasarlo |
+
+En el ultrawide, igual que en la computadora: el espacio extra va al ancho de la tabla, no a
+controles más grandes.
+
+En master-pedidos: `[size]="bp.sizeControl()"` en el `sui-input`, `sui-select` o
+`sui-compact-select` de la barra, `[size]="bp.tactil() ? '2xlarge' : 'medium'"` en el
+`sui-segmented-control` (no tiene helper) y `size="medium"` fijo en `sui-filter-panel-footer`,
+que solo se usa en la computadora (solo tiene `small` y `medium`: `bp.sizeControl()` le pasaría un
+`large` que no existe); con `bp.tactil()` el panel lleva `sui-modal-footer` en su lugar. No uses
+`bp.isMobile() ? 'large' : 'medium'`: deja la tablet táctil en `medium`.
+
 ## API
 
 <!-- api:inicio -->
@@ -159,6 +181,53 @@ de `sui-drawer-footer`).
 - El footer no llega a `large`: en mobile queda más chico que el footer de cualquier modal.
 - `disabled` del item usa opacidad (no está en el Figma).
 
+## Bien y mal
+
+> Hoy no hay usos de estas piezas fuera de la vitrina `master-preview`: los pares salen de las
+> trampas de este README.
+
+Pie del panel en la computadora
+
+```html
+<!-- ❌ mal: sin size queda en small (36), y D16 no usa small -->
+<sui-filter-panel-footer (clear)="limpiar()" (apply)="aplicar()" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-filter-panel-footer size="medium" (clear)="limpiar()" (apply)="aplicar()" />
+```
+
+«Limpiar» en dos lugares
+
+```html
+<!-- ❌ mal: «Limpiar» en la cabecera y en el pie; se elige uno -->
+<sui-filter-panel-header label="Filtros" [clear]="true" (clearClick)="limpiar()" />
+<sui-filter-panel-footer size="medium" (clear)="limpiar()" (apply)="aplicar()" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-filter-panel-header label="Filtros" leftIcon="equalizer-line" />
+<sui-filter-panel-footer size="medium" (clear)="limpiar()" (apply)="aplicar()" />
+```
+
+Buscador de la barra
+
+```html
+<!-- ❌ mal: isMobile deja la tablet táctil en medium (40), debajo de los 44 -->
+<sui-filter-bar>
+  <sui-input slot="end" type="search" [size]="bp.isMobile() ? 'large' : 'medium'" />
+</sui-filter-bar>
+```
+
+```html
+<!-- ✅ bien -->
+<sui-filter-bar>
+  <sui-input slot="end" type="search" [size]="bp.sizeControl()" placeholder="Buscar pedido…" />
+</sui-filter-bar>
+```
+
 ## Ejemplo
 
 ```html

package/docs/sui-flag/README.md

@@ -63,11 +63,31 @@ se migra todo ahora, no solo al tocar cada pantalla.
 | fila de una lista | `md` (24) | `sm` (20) |
 
 ```html
-<sui-flag name="peru" [size]="bp.isMobile() ? 'sm' : 'xs'" ariaLabel="Perú" />
+<sui-flag name="peru" [size]="bp.celular() ? 'sm' : 'xs'" ariaLabel="Perú" />
 ```
 
 La bandera no se toca: el área táctil es la del select que la contiene.
 
+### Por dispositivo (D16)
+
+La bandera 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» (`xs` en el prefijo, `sm` en una fila) | no se toca: no sube aunque sea un celular |
+| celular (380–767) | valor «mobile» (`sm` en el prefijo, `md` en una fila) | un paso más que en la computadora |
+| tablet táctil (`pointer: coarse`) | valor «web» (`xs` / `sm`) | no se toca: el puntero no cambia nada |
+| computadora (`pointer: fine`) | valor «web» (`xs` / `sm`) | |
+
+En el ultrawide, igual que en la computadora: el espacio extra va a más columnas, no a banderas
+más grandes.
+
+En master-pedidos no hay helper: `[size]="bp.celular() ? 'sm' : 'xs'"` en el prefijo y
+`[size]="bp.celular() ? 'md' : 'sm'"` en una fila. No uses `bp.isMobile()`: incluye el celular
+chico, que va con el valor de web. Dentro de un select o un compact-select no se pasa nada: el
+componente elige el tamaño de su bandera.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |
@@ -97,6 +117,47 @@ Outputs: ninguno.
 - **El nombre va en inglés** y con las grafías del set (`slovania`, `mauritus`, `taijikistan`):
   copia el slug de `SUI_FLAG_NAMES`, no lo escribas de memoria.
 
+## Bien y mal
+
+> Hoy no hay usos directos fuera de la vitrina `master-preview`: los pares salen de las reglas
+> de este README.
+
+Bandera de adorno
+
+```html
+<!-- ❌ mal: la app es solo Perú; la bandera no le dice nada a nadie -->
+<p><sui-flag name="peru" size="sm" /> Delivery en todo el Perú</p>
+```
+
+```html
+<!-- ✅ bien -->
+<p>Delivery en todo el Perú</p>
+```
+
+País sin nombre al lado
+
+```html
+<!-- ❌ mal: sin ariaLabel es decorativa y el lector de pantalla no dice el país -->
+<sui-flag name="venezuela" [size]="bp.celular() ? 'md' : 'sm'" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-flag name="venezuela" [size]="bp.celular() ? 'md' : 'sm'" ariaLabel="Venezuela" />
+```
+
+Tamaño por dispositivo
+
+```html
+<!-- ❌ mal: isMobile sube la bandera también en el celular chico (< 380), que va con el valor de web -->
+<sui-flag name="peru" [size]="bp.isMobile() ? 'sm' : 'xs'" ariaLabel="Perú" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-flag name="peru" [size]="bp.celular() ? 'sm' : 'xs'" ariaLabel="Perú" />
+```
+
 ## Ejemplo
 
 ```html

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

@@ -32,7 +32,7 @@ Regla corta: **ayuda o error de un control sin hint propio → form-hint · camp
 > y opcional. No da reglas de largo ni de copy.
 >
 > Uso medido el 03-10-2026 en `master-pedidos/src/app` (misma exclusión que `sui-badge`; las cifras
-> siguen iguales el 04-10-2026, las líneas de abajo están actualizadas a esa fecha):
+> siguen iguales el 04-10-2026, las líneas de abajo se revisaron el 06-10-2026):
 > **36 usos en 18 archivos**: 11 `error`, 25 `neutral` (24 por default y 1 explícito), 0
 > `disabled`; 2 con `icon` propio (`information-line`). Hay además **al menos 14 hints escritos a
 > mano** con clases propias (`__form-hint`, `__hint`).
@@ -65,11 +65,11 @@ Regla corta: **ayuda o error de un control sin hint propio → form-hint · camp
   («Pausa tu sucursal…», bajo el título de la card), `:61`, `pages/drivers/drivers.html:29`,
   `pages/driver/driver-schedule/driver-schedule.html:92`.
 - **12 de más de 8 palabras** (4 son los subtítulos de arriba) → acortar, o `sui-alert` si de
-  verdad hace falta todo: `pages/super-admin/master-users/master-users.html:66` (26 palabras),
-  `pages/orders/orders.html:589` (23), `pages/driver/driver-order-detail/driver-order-detail.html:868` (23),
-  `pages/envios/envios.html:401` (15).
+  verdad hace falta todo: `pages/super-admin/master-users/master-users.html:68` (26 palabras),
+  `pages/orders/orders.html:590` (23), `pages/driver/driver-order-detail/driver-order-detail.html:898` (23),
+  `pages/envios/envios.html:402` (15).
 - **Al menos 14 hints a mano** con clases propias. Ejemplos: `pages/discounts/discounts.html:205`
-  (`discounts__form-hint`), `components/settings-panel/settings-panel.html:93`,
+  (`discounts__form-hint`), `components/settings-panel/settings-panel.html:95`,
   `pages/promociones/promociones.html:181`.
 
 ## Tamaño en mobile y en web
@@ -80,6 +80,12 @@ Regla corta: **ayuda o error de un control sin hint propio → form-hint · camp
 
 Es texto que no se toca: el mismo tamaño en las dos plataformas está bien.
 
+### Por dispositivo (D16)
+
+No aplica: no tiene `size` (la letra es fija de 12/16 px y no se toca), así que es la misma en el
+celular chico, el celular, la tablet táctil, la computadora y el ultrawide. En master-pedidos no
+lleva `bp`.
+
 ## «No usar»: por qué no hoy y cuándo sí
 
 | qué | por qué no hoy | cuándo sí, en un flujo nuevo |
@@ -115,6 +121,49 @@ Outputs: ninguno.
   (04-10-2026). Para enlazarlo a un control propio, pon `id` en el host y apúntalo con
   `aria-describedby`; los campos del DS ya lo hacen solos.
 
+## Bien y mal
+
+Ayuda debajo de un campo de texto
+
+```html
+<!-- ❌ mal: sui-input ya trae su hint (pages/driver-onboarding/step-info/step-info.html:50) -->
+<sui-input [size]="bp.sizeControl()" [errorMessage]="nameError() || null" … />
+@if (!nameError()) { <sui-form-hint message="Como aparece en tu DNI." /> }
+```
+
+```html
+<!-- ✅ bien -->
+<sui-input [size]="bp.sizeControl()" hint="Como aparece en tu DNI"
+           [error]="!!nameError()" [errorMessage]="nameError() || null" … />
+```
+
+Subtítulo de una card
+
+```html
+<!-- ❌ mal: no es ayuda de un campo, es el texto de la sección (pages/schedule/schedule.html:17) -->
+<h2 class="schedule__card-title">Estado de la sucursal</h2>
+<sui-form-hint message="Pausa tu sucursal sin perder el horario que ya configuraste." />
+```
+
+```html
+<!-- ✅ bien -->
+<h2 class="schedule__card-title">Estado de la sucursal</h2>
+<p class="schedule__card-subtitle">Pausa tu sucursal sin perder el horario que ya configuraste.</p>
+```
+
+Explicación de dos oraciones
+
+```html
+<!-- ❌ mal: 23 palabras; pasa las 8 del hint (pages/orders/orders.html:590) -->
+<sui-form-hint message="Si eliges un motivo de la lista, el cliente lo verá. Si escribes uno propio, verá “El local no pudo preparar tu pedido”." />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-alert variant="info"
+           description="Si eliges un motivo de la lista, el cliente lo verá. Si escribes uno propio, verá «El local no pudo preparar tu pedido»." />
+```
+
 ## Ejemplo
 
 ```html

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

@@ -78,7 +78,7 @@ tipografía, no área táctil.
 - **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:204`.
+  `:316`; `components/add-product-modal/add-product-modal.html:206`.
 
 ## Tamaño en mobile y en web
 
@@ -91,6 +91,13 @@ No necesita `bp`: es texto, no se toca. Lo único tocable es el `link` («Cambia
 `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 |
@@ -131,6 +138,51 @@ mobile esa acción importa, conviene un botón aparte.
   `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]="true" for="ob-name" />
+<sui-input [size]="bp.sizeControl()" type="text" [(value)]="nombre" />
+```
+
+```html
+<!-- ✅ bien -->
+<sui-input [size]="bp.sizeControl()" type="text" label="Nombre completo" [required]="true" [(value)]="nombre" />
+```
+
+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()" (checkedChange)="unUso.set($event)" />
+```
+
+```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()" (activeChange)="unUso.set($event)" />
+```
+
 ## Ejemplo
 
 ```html