project.linkedcorp.net/docs/UI-UX-WINDOWS.md

# UI/UX — Identidad para aplicaciones de escritorio Windows (cómo construir pantallas)

> 🖥️ **Muestra viva:** `UI-UX-WINDOWS.html` (en esta misma carpeta) — ábrela en el navegador para
> VER todos los elementos (ventana con barra de título propia, panel de navegación, comandos,
> listado con clic derecho, maestro-detalle, diálogos, flyouts, configuración). **Es lo primero que
> se le muestra al usuario** al arrancar un proyecto de escritorio Windows para que apruebe o pida
> ajustes de la identidad antes de construir. Usa dos JS **locales** junto al HTML (sin CDN, offline):
> `lucide.min.js` (íconos) y `chart.umd.js` (gráficas Chart.js) — cópialos junto al HTML si se mueve.

> ⚠️ **Este documento es la referencia visual y de interacción** (look & feel, tokens, componentes,
> nomenclatura de regiones). **No asume una tecnología de implementación concreta**: sirve tanto para
> una app WinUI 3/.NET nativa como para una app Electron/Tauri, o cualquier otro stack de escritorio
> Windows. Cada proyecto decide su stack al copiar este documento; lo que **no cambia** es el
> comportamiento y la identidad descritos aquí — son los que hacen que la app "se sienta Windows".

Estilo de referencia: **Fluent Design / Windows 11** (Mica, esquinas redondeadas, tipografía Segoe UI
Variable, paleta de acento del sistema). Pensado **primero para mouse** (hover, clic derecho, arrastre),
sin dejar de ser accesible por teclado.

---

## 1. Identidad visual (tokens y tema)

Colores como **variables CSS RGB** (o el equivalente del framework elegido: `DynamicResource` en
WPF/WinUI, CSS vars en Electron/Tauri), para poder escribir `rgb(var(--accent)/.2)` y variantes con
transparencia. Tema **oscuro por defecto** + claro vía `data-theme="light"`.

| Token | Uso | Oscuro (ref.) | Claro (ref.) |
|---|---|---|---|
| `canvas` | fondo de ventana (equivalente a Mica) | `32 32 32` | `243 243 243` |
| `surface` | tarjetas, diálogos, flyouts | `43 43 43` | `255 255 255` |
| `panel` | panel de navegación, hover de filas | `51 51 51` | `249 249 249` |
| `field` | fondo de campos de entrada | `43 43 43` | `255 255 255` |
| `body` | texto principal | `255 255 255` | `32 32 32` |
| `muted` | texto secundario, labels, hints | `168 168 168` | `96 96 96` |
| `line` | bordes y divisores | `70 70 70` | `225 225 225` |
| `accent` | acción primaria — **el acento del sistema** | `0 120 212` | `0 103 192` |
| `success` / `warning` / `danger` | estados | `108 203 95` / `255 185 0` / `255 105 97` | `16 124 16` / `157 93 0` / `196 43 28` |

**Acento del sistema (do & don't):** Windows deja al usuario elegir un color de acento en la
configuración del sistema; la app debe **heredarlo** cuando el framework lo expone (WinUI 3 lo hace
automático vía `AccentColor`), o dar un selector propio con la paleta estándar si no hay acceso al
acento del SO. Paleta de referencia (la que usa la muestra viva): `blue #0078D4` (por defecto),
`purple #8764B8`, `green #10893E`, `red #C42B1C`, `orange #CA5010`, `teal #009984`.

**Tipografía:** **Segoe UI Variable** (Windows 11) como fuente del sistema — no requiere carga de
fuente web, ya está instalada en Windows: `font-family:'Segoe UI Variable Text','Segoe UI',system-ui,sans-serif`.
Los títulos grandes usan el corte *Display* de la misma familia (`Segoe UI Variable Display`).
Escala: `.72rem` metadatos/labels · `.8–.82rem` cuerpo/controles · `1.05–1.25rem` títulos de sección ·
`1.6rem+` valores KPI/Display. Pesos: 600–700 títulos y labels, 400 párrafos.

**Forma (radios de Fluent 2):** `--r-sm: 4px` en controles (botones, campos, checkboxes) y
`--r-lg: 8px` en superficies elevadas (tarjetas, diálogos, flyouts, menús, y la propia ventana).
No usar esquinas totalmente cuadradas ni "pill" (`999px`) salvo en `ToggleSwitch`, `badge` y `avatar`.

**Iconografía:** un solo set en toda la app. Dos opciones válidas:
- **Lucide** (la que usa la muestra viva, `lucide.min.js` local) — mismo estándar que ya usa el grupo
  en sus apps web (`UI-UX-LINKEDCORP.md`), da continuidad visual entre plataformas y permite compartir
  nombres de ícono entre el proyecto web y el de escritorio de un mismo cliente.
- **Segoe Fluent Icons** (fuente de glifos del propio Windows) — 100% nativo, cero peso adicional, pero
  solo tiene sentido en una implementación WinUI/WPF nativa (no está disponible como webfont fuera de Windows).
- Los íconos **heredan el color del contexto** (activo = `accent`, texto = `body`/`muted`). No mezclar
  ambos sets en la misma app.

---

## 2. Mensajes del sistema — jerarquía de avisos (REGLA DE ORO)

A diferencia de la web (donde todo pasa por un único `AppDialog`), una app de escritorio Windows tiene
**cuatro** mecanismos de aviso, cada uno con un propósito distinto. Elegir el correcto es parte de la
identidad:

| Mecanismo | Para qué | Bloquea | Ejemplo |
|---|---|---|---|
| **ContentDialog** (modal) | **toda decisión** del usuario (confirmar, elegir, error crítico) | Sí | "¿Eliminar el cliente CLI-002?" |
| **InfoBar** | estado o aviso **no bloqueante**, embebido en el contenido de la pantalla | No | "Sincronización activa", "Licencia por vencer" |
| **Toast/notificación** | evento de **fondo**, sin interacción esperada, autodesaparece | No | "Copia de seguridad completada" |
| **Flyout** | acción o info **contextual**, anclada a un control, se cierra al hacer clic fuera | No (light-dismiss) | menú de usuario, "¿seguro?" ligado a un botón puntual |

**Nunca** `MessageBox`/`alert`/`confirm` del sistema operativo ni del navegador si el shell es
web-based: siempre el `ContentDialog` propio, para mantener consistencia visual entre Windows y el resto
de plataformas del grupo.

Contrato del `ContentDialog` (equivalente al `openDialog` del template web):
```js
openDialog({
  tone: 'info' | 'success' | 'warning' | 'error',   // franja superior + color del ícono/título
  title: 'Título claro',
  message: 'Descripción en lenguaje del usuario',
  actions: [                                          // opcional; sin actions -> botón "Cerrar"
    { label: 'Cancelar', variant: 'standard' },
    { label: 'Eliminar', variant: 'danger', onClick: async () => { ... }, keepOpen: false },
  ],
});
```
- Sin `actions` ⇒ botón "Cerrar" (`accent`) automático. `keepOpen: true` mantiene el diálogo abierto
  tras el `onClick` (procesos largos).
- **Sets de botones estándar** (misma convención que la identidad web): Aceptar/Cancelar,
  Sí/No, Eliminar(danger)/Cancelar, Guardar/Descartar. **Acción primaria a la derecha**, Cancelar/No a
  la izquierda. Los botones de decisión **siempre muestran texto** (nunca solo ícono).
- El `ContentDialog` se centra sobre la **ventana de la app**, no sobre toda la pantalla del monitor.

---

## 3. Kit de componentes (resumen; ver el markup/CSS de referencia en `UI-UX-WINDOWS.html`)

- **Botones** — `accent` (relleno de color, acción primaria), `standard` (borde + fondo neutro),
  `subtle` (transparente, solo hover), `danger` (borde/texto rojo). Alto `32px` (`sm` `26px`). Todo
  botón compone **ícono (izq.) + texto**; en toolbars muy densas puede ir solo ícono con `tooltip`
  obligatorio indicando la acción.
- **Campos** — `TextBox`, `NumberBox` (con spinner +/-), `ComboBox` propio (desplegable redondeado,
  con buscador si la lista tiene **≥10 ítems**; nunca el `<select>`/combo nativo del SO — no se puede
  redondear ni estilar), `Textarea`, `CheckBox`, `RadioButtons`, `ToggleSwitch` (interruptor), `Slider`.
- **DatePicker/TimePicker** — calendario propio en un **flyout** anclado al campo (navegación de mes,
  día de hoy marcado, selección resaltada con `accent`); igual criterio que `ComboBox`: no usar el
  selector nativo del SO por falta de control visual.
- **ListView/DataGrid** — tabla con encabezados **ordenables** (clic ordena asc/desc), columna de
  **selección múltiple** (checkbox), fila con **hover** y **estado seleccionado** (`accent/.14`), y
  **clic derecho** que abre el menú contextual de esa fila (ver §6). Alternativa por fila sin mouse
  derecho: botón `⋯` que abre el mismo menú.
- **Master-Detail (Split View)** — patrón **nativo de Windows** (Correo, Configuración, Explorador):
  lista angosta a la izquierda + panel de detalle a la derecha que se actualiza **en el sitio** al
  seleccionar un ítem, sin modal. Preferir sobre "detalle en modal" cuando la pantalla es
  principalmente de exploración/lectura de una lista larga.
- **Menú contextual (clic derecho)** — el patrón de interacción **más característico de Windows**:
  ítems con ícono + label + acelerador de teclado a la derecha (`Ctrl+E`, `Del`…), separadores,
  submenú con flecha `▸` que se expande al pasar el mouse, ítem destructivo en `danger`. Debe estar
  disponible en **toda fila/elemento accionable**, no solo en listados.
- **Barra de menú clásica** (`Archivo · Editar · Ver…`) — **opcional**, solo para apps de
  productividad/edición que lo necesiten (no todas las apps modernas la llevan; Configuración o
  Correo no la tienen). Si se usa, cada ítem abre un menú desplegable igual al contextual.
- **Flyout** — popover anclado a un control (avatar, botón), con **light-dismiss** (clic fuera o Esc
  cierra). Para menús de cuenta, ayuda contextual corta o una confirmación ligada a un botón puntual.
- **InfoBar** — banner de 4 tonos (`info/success/warning/error`) embebido en el contenido, con botón
  de cierre `✕`; no empuja al usuario a decidir, solo informa.
- **Toast** — notificación flotante (esquina inferior derecha), autodesaparece (~4s), apilable. Solo
  para eventos de fondo — si el usuario debe decidir algo, es un `ContentDialog`, no un toast.
- **Teaching Tip** — "coach mark" anclado con flecha, para presentar una función nueva la primera vez
  (onboarding); se descarta con un botón, no reaparece tras cerrarse.
- **Expander (patrón de Configuración)** — fila con ícono + título + descripción + chevron; al hacer
  clic expande un cuerpo con los controles de esa sección (toggles, botones). Es el patrón estándar
  para pantallas de **Configuración/Ajustes**.
- **Treeview** — árbol jerárquico estilo Explorador de Windows (`▾/▸` para expandir/colapsar,
  ícono de carpeta/archivo, selección resaltada). Para categorías, carpetas o estructuras anidadas.
- **Barra de título personalizada** — reemplaza el chrome nativo de Windows: ícono+nombre de la app a
  la izquierda (zona **arrastrable**, mueve la ventana), controles **minimizar / maximizar / cerrar**
  a la derecha. `Cerrar` se resalta en rojo (`#C42B1C`) al hover; `Maximizar` muestra, al hover, la
  vista previa de **Snap Layouts** (2/3/4 particiones) — detalle que distingue a una app "moderna".
- **NavigationView (panel de navegación)** — fijo a la izquierda, con **tres modos**: expandido
  (ícono+texto), compacto (solo ícono) y oculto (drawer). Se colapsa con el botón ☰; tiene buscador
  propio arriba y, al pie, la cuenta del usuario (abre un `Flyout`).
- **CommandBar** — franja de botones de acción de la vista actual (Nuevo, Actualizar, Eliminar…) con
  botón **"···" (overflow)** para acciones secundarias cuando no caben todos los botones.
- **BreadcrumbBar** — ruta de navegación bajo la barra de comandos, segmentos separados por `›`, el
  último en negrita y no clicable.
- **Barra de estado** — pie de ventana con texto pequeño: conteo de elementos/selección, estado de
  conexión, versión. Equivalente a la barra de estado del Explorador de Windows.
- **KPI / spinner / skeleton / progress bar** — igual criterio que en web: tarjetas de indicador con
  delta ▲/▼, spinner circular para cargas cortas, skeleton para listados, barra de progreso para
  procesos medibles.
- **Gráficas** — Chart.js local (`chart.umd.js`, sin CDN); colores desde los tokens del tema y se
  reconstruyen al cambiar tema/acento. `maintainAspectRatio:false` + contenedor con `max-height`.
- **Plantillas de ventana** — **Login** (ventana pequeña centrada, avatar, usuario/contraseña,
  recordarme), **Acerca de** (ventana utilitaria pequeña con ícono, versión, botón de actualización) y
  **Reporte/factura** (documento con `Imprimir`/`Exportar PDF`, aislado con `@media print` si el shell
  es web-based).

---

## 4. Layout (estructura de la ventana) y NOMENCLATURA de regiones

Úsalos para pedir cambios: "cambia X en `barra-comandos`". La muestra viva rotula visualmente cada
región (chip azul) y cada componente (chip verde) al activar el interruptor "Mostrar nombres" (vista
Resumen, o menú `···` de la barra de comandos).

| Nombre | Qué es | Comportamiento |
|---|---|---|
| `ventana` | contenedor raíz de la app | esquinas redondeadas (8px), sombra; simula el marco de una app de escritorio flotando sobre el escritorio |
| `barra-titulo` | barra de título personalizada | **arrastrable** salvo sobre sus controles; ícono+nombre a la izq., minimizar/maximizar/cerrar a la der. |
| `navegacion` | panel de navegación izquierdo (NavigationView) | **FIJO**, scroll propio si hay muchos ítems; modos expandido/compacto/oculto |
| `col-derecha` | columna derecha | todo lo no-navegación, alto completo de la ventana |
| `barra-comandos` | CommandBar de la vista actual | botones de acción + overflow `···` |
| `migas-pan` | BreadcrumbBar | bajo la barra de comandos; último nivel en negrita |
| `area-contenido` | contenido de la vista | **ÚNICA** región con scroll propio |
| `panel-detalle` | panel derecho en vistas maestro-detalle | se actualiza al seleccionar un ítem, sin modal |
| `divisor` | separador arrastrable entre paneles | cursor `col-resize`; el arrastre con mouse redimensiona los paneles adyacentes |
| `barra-estado` | pie de ventana | conteo de ítems/selección, estado; texto pequeño |

**Comportamiento clave:** `navegacion` queda **fija** (no se desplaza con `area-contenido`); solo
`area-contenido` hace scroll. `barra-titulo`, `barra-comandos`, `migas-pan` y `barra-estado`
permanecen siempre visibles.

**Ventanas secundarias vs. una sola ventana:** a diferencia de la web (todo en una pestaña), una app
Windows puede abrir **ventanas propias** para diálogos de larga duración o utilitarios (Acerca de,
Propiedades, un asistente). Regla: usar una **ventana secundaria** solo cuando el contenido necesita
vivir independientemente de la ventana principal (el usuario puede moverla, alternar entre ambas con
Alt+Tab); si es una decisión puntual ligada al contexto actual, es un `ContentDialog`, no una ventana nueva.

---

## 5. Interacción — pensada primero para mouse

- **Hover en todo lo accionable**: botones, filas de listado, ítems de navegación, ítems de menú y
  árbol cambian de fondo al pasar el mouse (`panel` o `accent/.14` si están seleccionados). Es la
  señal principal de "esto se puede interactuar" en una app de mouse.
- **Clic derecho = menú contextual**, en cualquier fila/elemento accionable (listados, árbol,
  tarjetas). Debe existir también una vía sin botón derecho (botón `⋯`) para paridad con touch/teclado.
- **Tooltips con retardo** (~350ms) en todo botón de solo-ícono y en controles cuyo propósito no sea
  obvio por el texto visible; nunca sustituyen a un `ContentDialog` para respuestas del sistema.
- **Cursores con significado**: `pointer` en clicables, `col-resize`/`row-resize` en divisores
  arrastrables, `move` en zonas de arrastre (barra de título), `text` en campos.
- **Anillo de foco solo para teclado** (`:focus-visible`), no al hacer clic con el mouse — evita el
  "flash" de foco en cada clic que resulta ruidoso en una app mouse-first, sin sacrificar accesibilidad
  por teclado (Tab/flechas siguen mostrando el anillo).
- **Snap Layouts**: al pasar el mouse sobre "Maximizar" se muestra la vista previa de particiones de
  pantalla — reforzar este detalle si el framework lo expone nativamente (Windows 11 lo da gratis en
  WinUI/WPF con el chrome nativo bien configurado).
- **Divisores/splitters arrastrables** entre paneles (p. ej. lista/árbol ↔ detalle) para que el usuario
  ajuste el espacio a su gusto; el ancho elegido se **persiste** por vista.
- **Sin scroll horizontal en tablas** cuando sea evitable: preferir ocultar columnas secundarias o
  usar `panel-detalle` para el resto de la información antes que forzar scroll-x.

---

## 6. Receta para construir una pantalla

1. **CommandBar** (`Nuevo`, `Actualizar`, acciones contextuales + overflow `···`).
2. **Elegir el patrón de datos** según el caso:
   - **Listado + Master-Detail**: lista con selección simple a la izquierda/arriba, detalle **en el
     sitio** a la derecha/abajo. Preferido cuando el usuario navega/lee mucho (correo, catálogos).
   - **Listado + ContentDialog de detalle**: al hacer clic en una fila se abre un `ContentDialog`
     (o una ventana secundaria si el contenido es largo) con el detalle y acciones (`Editar`,
     `Eliminar`). Preferido cuando el detalle es ocasional y la lista debe verse completa mientras se usa.
3. **Selección múltiple + acciones por lote**: casillas en la columna izquierda de la tabla; la barra
   de estado muestra "`N` de `M` seleccionados"; las acciones de lote aparecen en la `CommandBar`
   solo cuando hay selección.
4. **Clic derecho en cada fila** con el menú contextual estándar: Ver detalle, Editar, Duplicar,
   Exportar (submenú), separador, Eliminar (`danger`).
5. **Edición**: campos habilitados solo en modo edición; `Guardar` solo si hubo cambios reales;
   acciones destructivas siempre confirmadas con `ContentDialog` (tono `warning`, Cancelar/Eliminar).
6. **Pie de listado** (`pie-listado`, igual criterio que en la identidad web): líneas por página
   (5·10·20·50·Todo, **default 10**, persistente por listado), rango "Mostrando X–Y de N",
   paginación con ventana deslizante de 5 números, y **alto constante** entre páginas (filas de
   relleno invisibles en la última página parcial).

---

## 7. Reglas de identidad (do & don't)

- ✅ Barra de título **personalizada** (no la nativa del SO) con drag region + minimizar/maximizar/cerrar.
- ✅ Panel de navegación **fijo**, con modos expandido/compacto/oculto persistentes.
- ✅ Tema oscuro/claro **y** acento del sistema, ambos persistentes; heredar el acento del SO cuando el
  framework lo permita.
- ✅ **Toda decisión** del usuario pasa por `ContentDialog`; estados no bloqueantes por `InfoBar`;
  eventos de fondo por `Toast`; nada de `MessageBox`/`alert`/`confirm` nativos.
- ✅ **Clic derecho con menú contextual** en toda fila/elemento accionable — es la firma de interacción
  de una app Windows mouse-first.
- ✅ `ComboBox` y `DatePicker` **propios** (redondeados, estilables); nunca los controles nativos del
  SO/navegador para estos casos — igual criterio que la identidad web.
- ✅ Tipografía del sistema (**Segoe UI Variable**), sin cargar fuentes web — más estable y coherente
  con el resto de Windows.
- ✅ Radios de esquina consistentes: `4px` controles, `8px` superficies elevadas y la ventana misma.
- ✅ Un solo set de íconos en toda la app (Lucide o Segoe Fluent Icons), heredando color del contexto.
- ✅ Master-Detail para listas de exploración; `ContentDialog`/ventana secundaria para detalle ocasional.
- ✅ Foco visible solo con teclado (`:focus-visible`); hover visible siempre (mouse-first).
- ❌ `MessageBox`/`alert`/`confirm` del sistema. ❌ combos/selects/calendarios nativos sin estilar.
  ❌ mezclar sets de íconos. ❌ apilar listado + formulario + detalle en una sola pantalla sin
  separación clara. ❌ usar `Toast` para pedir una decisión al usuario.

> Para que una app "se sienta Windows moderna": misma barra de título, mismo panel de navegación,
> mismos cuatro mecanismos de aviso (`ContentDialog`/`InfoBar`/`Toast`/`Flyout`) bien diferenciados,
> clic derecho en todo lo accionable, y los mismos tokens de color/tipografía/radio. Abre
> `UI-UX-WINDOWS.html` para verlo funcionando y pide ajustes por el nombre de región/componente.