metis-desk/docs/implementacion-uiux-ficha-puesto-v2.1.md

Implementación UI/UX v2.1: ficha de puesto

Fecha: 24 de octubre de 2026. Ruta: /companies/:companyId/workstations/:id.

Resultado y alcance

M03 mantiene la tabla y redistribuye sus atributos según el ancho del panel. M04 distingue la información esencial de carpeta de sus detalles técnicos. M06 añade totales conocidos y explica cuántos elementos muestra el resumen. Se conservan las entidades, acciones, estados y valores completos.

M01/M02 constituyen la línea base v1 y conservan su código. M05/M07/M08/M09 quedan fuera de esta iteración. No se añaden queries, contratos HTTP, modelos, dependencias, tokens, componentes vendor ni cambios en archive/. Las primitivas y APIs compartidas no cambian.

Estado inicial y fuentes

Se registraron pwd, git status --short, Node v24.20.0 y PNPM 11.25.0 antes de modificar producción. El registro inicial local está en /tmp/metis-uiux-v21-initial-status.txt. Existían cambios de v1, búsqueda, controllers, documentación, pruebas y scripts. Durante el trabajo también cambiaron fuentes de Recursos; esos cambios se conservan y no se atribuyen a v2.1.

Se contrastaron la auditoría, el informe/comparaciones de v1, DESIGN.md, los dos patrones de listados, estructura web, matriz de skills, documentación vigente WD04.1–WD04.3 y procedimiento Playwright. La implementación real ya integra perfiles y configuraciones y presenta soporte como resumen con gestión modal. No se recuperan paneles retirados.

La línea base se capturó con M01/M02 ya presentes. Tras agotar el pool de conexiones de la API de auditoría durante varias sesiones MCP simultáneas, se retiró únicamente el preparador propio y se reprodujeron las mismas fixtures en otro entorno desechable. Se renovó la comparación sobre ese conjunto. Para capturar v1 se restauraron temporalmente solo los tres ficheros de esta iteración que estaban limpios al inicio, con copia de seguridad, comprobación de cambios concurrentes y restauración en finally. No se revirtió ningún cambio ajeno.

Skills consultadas y aplicación efectiva

Skill	Aplicación
ux-tables, principal	Preservar comparación en tabla, identidad legible, alineación superior, atributos completos y distribución según capacidad real. El patrón compacto normativo prevalece sobre sugerencias genéricas de añadir herramientas de inventario.
frontend-design	Jerarquía perfil/persona antes que metadatos; agrupación y ritmo vertical usando Inter, colores y espaciados existentes. Refinamiento mediante capturas.
shadcn	APIs instaladas de Button, Badge y Collapsible Base UI; render para el trigger, panel con identidad y estado accesible. Sin regenerar vendor ni descargar componentes.
ux-dashboard	Mantener cobertura, autorización, estado y revisión visibles; revelar progresivamente únicamente la información técnica extensa.
ux-navigation	Conservar enlaces independientes de perfil/persona/cuenta y destinos de gestión; separar expansión de perfil de detalles de carpeta.
ux-microcopy	Ámbito «Perfiles activos» frente a «activos y archivados»; alcance explícito y botón sin otro total repetido. Traducciones es/en.
ui-ux-pro-max	Búsqueda local long token wrapping, dominio UX: resultado verificado «Long Token Wrapping». Ajuste de tokens extensos con min-w-0 y overflow-wrap:anywhere; sin generar otro sistema visual.
vercel-composition-patterns	Separar identidad, elemento de configuración y descripción de metadatos por responsabilidades reales, sin Context ni flags nuevos.
vercel-react-best-practices	Derivar recuentos y filas del render, sin copiar datos remotos ni añadir efectos de sincronización.
rdx-solid	Cambio local proporcional, contratos existentes, pruebas de comportamiento y separación de responsabilidades.
ux-design-review	Revisión consolidada de usabilidad, textos, estados, foco y responsive bajo el sistema visual existente.

Los auditores especializados ux-heuristics-audit, ux-microcopy-audit, ux-accessibility-audit, ux-aesthetics-audit y ux-mobile-responsiveness-audit no están instalados. No se ejecutaron ni instalaron; las verificaciones directas disponibles se realizan con MCP. No se afirma una auditoría automatizada equivalente.

M03: Personas y perfiles

WorkstationProfiles conserva CompactTable, el orden existente y las acciones por perfil. WorkstationProfileIdentity agrupa los datos según el contenedor:

Ancho real del Card	Composición
Desde 840 px	Cinco columnas: perfil, persona, cuenta, estado y configuraciones.
Desde 600 hasta menos de 840 px	Cuatro columnas: persona debajo del perfil; cuenta, estado y configuraciones conservan columnas propias.
Menos de 600 px	Dos columnas: identidad con persona, cuenta etiquetada y estado; resumen y expansión de configuraciones independientes.

El umbral intermedio corresponde a una tabla útil de unos 808 px, después de 32 px de padding. El reparto amplio reserva aproximadamente 210/202/154/97/145 px. Por debajo, agrupar persona/perfil evita comprimir el nombre para sostener una quinta columna. Se comprobaron 599/600/601 y 839/840/841 px de contenedor, no de viewport.

La revisión visual a 320 px detectó que las dos acciones de cabecera juntas excedían su ancho útil. Se apilan localmente cuando el contenedor de cabecera tiene menos de 300 px; el orden y las acciones se conservan. Sus límites se miden en navegador a 320 y 390 px.

La tabla usa anchura fija proporcional, cabeceras ajustables y celdas alineadas arriba. Los valores largos se ajustan completos; no hay elipsis ni reducción global de tipografía. CSS oculta la presentación equivalente que no corresponde a ese ancho, manteniendo una sola copia accesible de cada enlace.

Se conserva el contrato de aria-expanded, aria-controls, nombre accesible, selección única y detalles fuera del contenedor desplazable de tabla. La ampliación conserva una fila seleccionada que quede fuera de los cinco primeros; el alcance cuenta esa sexta fila.

M04: configuraciones y detalles técnicos

WorkstationConfigurationFamily delega cada fila en WorkstationConfigurationItem. WorkstationConfigurationMetadata mantiene los pares dl/dt/dd y las traducciones del modelo documental.

En carpetas permanecen visibles nombre, estado, unidad, cobertura de cuenta, autorización, revisión y notas. Ruta, permisos declarados y cuenta utilizada se agrupan bajo «Ver detalles técnicos» / «Ocultar detalles técnicos», con nombre accesible que identifica la configuración. Se usa Collapsible Base UI con trigger Button, panel identificado y valores completos. Las otras cuatro familias conservan su presentación directa.

El estado se compone junto al nombre en las cinco familias: no desciende al centro de la fila cuando se abre la información técnica. Los metadatos aprovechan así todo el ancho disponible. Este ajuste se decidió al inspeccionar la carpeta abierta y se verifica midiendo la posición del badge.

No cambia la semántica: cobertura documental y autorización registrada no comprueban permisos SMB efectivos; aplicaciones del perfil no equivalen a instalaciones; pendiente, revisión y cobertura desconocida conservan sus estados. El filtro existente «Solo pendientes» continúa filtrando por estado pending; no se amplía silenciosamente a cualquier revisión. Los enlaces de las cinco familias conservan compañía y perfil.

M06: totales y alcance

Equipamiento usa DetailPanel.count para contar los miembros del puesto, incluidos los que todavía no se resuelven como activo. La advertencia de referencia no resuelta permanece. Personas y perfiles cuenta los activos por defecto; al mostrar archivados cuenta la colección combinada y cambia la descripción de ámbito.

Con más de cinco elementos se muestra «5 de 50 perfiles activos» o «5 de 80 elementos de equipamiento». Al ampliar, contraer o conservar una selección se calcula el número realmente renderizado. «Mostrar todos» evita una tercera repetición del total en el botón. No cambian CollectionPreview ni DetailPanel.

Cero solo se muestra con datos disponibles. Carga inicial, error inicial y datos retenidos tras error omiten el contador; conservan los mensajes de disponibilidad, reintento y filas anteriores existentes. Un refetch en curso conserva el total conocido y anuncia la actualización. No se añade estado derivado ni consultas.

Ficheros y decisiones

Fuentes principales, bajo modules/companies/src/web/workstations/detail/ui/:

• Modificados: workstation-profiles.tsx, workstation-assets.tsx, workstation-configuration-family.tsx, workstation-detail.test.tsx.
• Nuevos: workstation-profile-identity.tsx, workstation-configuration-item.tsx, workstation-configuration-metadata.tsx.
• Traducciones: modules/assets/src/common/locales/{es,en}.json.
• Pruebas MCP reproducibles: scripts/workstation-uiux-v21.test.py.

Se descartó mantener cinco columnas en unos 625 px útiles: la línea base con cuenta extensa alcanzaba una tabla de 1364 px. También se descartó usar dos columnas en todos los tamaños, ocultar valores mediante elipsis, plegar todas las familias, trasladar incidencias al disclosure y ampliar componentes genéricos sin necesidad. No se añaden búsqueda, paginación, virtualización ni acciones de M05.

Evidencias y reproducibilidad

La comparación, medidas y resultados están en implementacion-v2.1. Las evidencias anteriores de auditoría y v1 se conservan.

Se utiliza el servidor MCP del proyecto, por Docker/stdio con la imagen fijada, Chromium headless y la sesión privada del preparador. No se instala Chromium en WSL. Los recorridos usan login real de usuario ordinario y exclusivamente metis_desk_test, en MariaDB desechable. No se exportan sesiones ni credenciales a documentación o Git.

Preparación: bash scripts/setup-playwright-wsl.sh, python3 scripts/visual-audit.py, scripts/visual-audit-volume.py y scripts/workstation-dashboard-fixtures.py; después test_00_prepare_long_data_and_volume en fase antes. Con la sesión privada únicamente en METIS_PLAYWRIGHT_STORAGE_STATE, METIS_UIUX_PHASE=antes ejecuta las capturas iniciales y METIS_UIUX_PHASE=despues las finales. La preparación se omite en fase final.

En el checkout correspondiente a v1 se ejecutan explícitamente WorkstationUiuxV21Tests.test_00_prepare_long_data_and_volume, test_01_comparable_captures y test_02_container_thresholds con fase antes. En el checkout final, METIS_UIUX_PHASE=despues python3 scripts/workstation-uiux-v21.test.py ejecuta los 13 métodos y omite la preparación. Cambiar la variable de fase no cambia la versión del código. La sesión privada se suministra exclusivamente por la variable documentada del preparador.

El script v2.1 adapta en memoria el selector de Equipamiento de las pruebas v1, cuyo nombre accesible ahora incluye el contador, y redirige sus resultados a regresiones-v1/. No modifica el runner ni las evidencias históricas de v1.

Volumen reproducido: 15 compañías; compañía principal con 59 personas, 135 activos, 73 recursos, 55 puestos y 64 perfiles en total. El puesto denso tiene 80 miembros y 50 perfiles activos más 10 archivados. El principal tiene dos miembros, dos perfiles activos y uno archivado, cinco familias, una cuenta de 141 caracteres y una ruta UNC de 219 caracteres coherente con su recurso. Los escenarios vacíos y fuentes incompletas se comprueban aparte.

Validación visual y funcional

Se revisaron 1600×1000, 1440×900, 1280×900, 1024×768, 768×1024, 390×844 y 320×720. Las capturas comparables cubren principal, perfiles, carpetas/configuraciones, Solo pendientes, vacío, 50 activos, 60 con archivados y 80 miembros. Se añaden detalles técnicos abiertos, cobertura desconocida con revisión, error parcial, reflow y tema oscuro.

Los 13 métodos MCP se validaron por tandas; uno reutiliza cinco recorridos de v1. Incluyen:

• Tabla y enlaces únicos alrededor de los dos umbrales; ausencia de overflow global y local en las muestras comprobadas.
• Preview/ampliación/contracción, 50→60 perfiles al incluir archivados, 80→5 miembros y sexta fila conservada. Cabecera de perfiles con total 50/60 correcto.
• Totales 6→5→1→0→50 durante refetch; cero confirmado frente a carga/error y datos retenidos; recuperación mediante reintento.
• Enter y Espacio para expansión; Espacio/Enter en detalles técnicos; Tab hacia el siguiente enlace; foco conservado y :focus-visible comprobado.
• Valores completos de ruta y cuenta, aria-controls hacia el panel real y conservación de ambas expansiones/foco tras refetch.
• Cobertura desconocida, revisión y notas visibles con el disclosure cerrado; Solo pendientes y foco desde su resumen; otras familias disponibles ante fallo de carpetas.
• Navegación real a activo, persona y perfil, retorno con History y rutas de las cinco familias. Un puesto de la compañía principal no aparece al pedirlo en otra compañía; una petición sin sesión devuelve 401.
• Regresiones v1: gestión con teclado/cancelación/foco, alta/edición/retirado/historial/borrado de soporte, errores/permisos/datos parciales, carga/stale/vacío/sin ordenador, retorno móvil/ciclo de vida y geometría del diálogo a 1440/390/320.

Las capturas y resultados exactos están en comparacion.md, mediciones.json y validaciones.json.

Validación técnica

Comando	Resultado
pnpm --filter @metis/companies --filter @metis/web typecheck	Correcto en el código final.
Biome dirigido a los siete TSX y dos JSON afectados	Nueve ficheros correctos.
ESLint dirigido a los siete TSX	Correcto.
TSX_TSCONFIG_PATH=../../tsconfig.json node --import tsx --test src/web/workstations/detail/ui/workstation-detail.test.tsx, desde Companies	20/20; cinco pruebas nuevas con casos es/en, límites, estados y preservación de metadatos.
pnpm build	Correcto, dos tareas. Conserva la advertencia de tamaño de chunk.
pnpm typecheck	Falla en vendor: packages/shadcn-ui/src/components/calendar.tsx:165, opcionalidad de locale, ya señalado en v1.
pnpm lint	15 errores ajenos, una advertencia y cuatro informaciones en la ejecución registrada.
pnpm check	168 errores ajenos, una advertencia y cuatro informaciones. Los nueve ficheros de esta iteración pasan el check dirigido.
pnpm test	Companies: 229/231; fallan dos assertions en companies-page.test.tsx:180 y :210. El fichero no cambia en esta entrega. V1 ya señalaba fallos en esa suite; se informa del resultado actual, sin atribuir ambos a v1.
git diff --check dirigido y parseo AST del runner Python	Correctos.

Una comprobación intermedia de tipos encontró resource.aggregate.ts:43 durante modificaciones concurrentes de Recursos. La comprobación final de Companies/Web ya pasa sin cambiar ese código desde esta tarea. No se repararon áreas ajenas para forzar los checks globales. No se modifican fronteras/exports compartidos y no se requiere un grafo de dependencias nuevo.

Accesibilidad y límites

Se verifican tabla semántica, cabeceras, nombres y relaciones de expansión, enlaces independientes, contenido completo, estados textuales, teclado, foco visible, orden de Tab y presentación responsive sin duplicación accesible de enlaces. Las acciones estrechas se comprueban mediante sus límites reales; los badges de configuración permanecen al principio de la fila, incluso abierta.

Se comprueba el modo oscuro a 390 px. El reflow de 200/400 % se emula mediante CDP con viewport efectivo 720×450/DPR 2 y 360×225/DPR 4 sobre una ventana de referencia 1440×900. No equivale a probar el control nativo de zoom del navegador ni ampliación exclusiva de texto; esas verificaciones quedan pendientes. No había lector de pantalla disponible. No se afirma conformidad WCAG completa ni una auditoría exhaustiva de contraste o tecnologías de asistencia.

Revisión final, incidencias y riesgos residuales

La revisión visual produjo dos ajustes adicionales dentro del alcance: apilado de acciones en la cabecera de perfiles estrecha y alineación del estado junto al nombre en las cinco familias. Se corrigieron también selectores de pruebas que cambiaban de «Mostrar» a «Ocultar», la espera de un control tras retirarlo con Solo pendientes y la expectativa incorrecta de h1 en páginas existentes con h2. No requirieron modificar navegación ni estados de negocio.

Las primeras sesiones simultáneas agotaron el pool de la API desechable. Se retiró exclusivamente el preparador propio y se renovaron fixtures/evidencias; las tandas finales se ejecutaron secuencialmente. No se investigó ni corrigió la causa de concurrencia del servidor dentro de esta tarea de frontend. La evidencia no demuestra ausencia de problemas de concurrencia en backend.

Una cuenta de 141 caracteres sigue produciendo varias líneas: se conserva el valor íntegro para consulta. La altura móvil de las filas no se reduce artificialmente. La revisión es de estos fixtures y tamaños; nombres arbitrarios, traducciones futuras o tecnologías de asistencia adicionales requieren sus propias comprobaciones.

Para v2.2 quedan M05 (acciones repetidas), M07 (ayudas repetidas en vacío), M08 (recetas de avisos) y M09 (transición de carga/CLS), además de lector de pantalla y zoom nativo. No se implementaron esas mejoras.

Mediciones finales

A 1440 px, el Card de perfiles mide 656,6 px y su área útil 624,6 px. La tabla anterior con cuenta extensa medía 1364,4 px; la nueva cabe en 624,6 px. La primera fila pasa de 233 a 193 px. Los tres enlaces de identidad/persona/cuenta permanecen disponibles en cada composición.

A 390 px, las configuraciones pasan de 949 a 661 px (30,3 % menos) con detalles cerrados. Abrirlos conserva los 219 caracteres de ruta y los 141 de cuenta. El badge permanece a la misma altura que el nombre tanto a 1440 como a 390 px.

Se conservan 25 capturas antes, 33 después y tres de regresión modal, con hashes contrastados. La comparación detalla las siete resoluciones y los seis anchos de contenedor.

Los dos preparadores propios se cerraron por sus PID registrados; se confirmó la eliminación de ambas sesiones privadas y la retirada de sus servicios desechables. No se terminaron procesos por coincidencias de nombres ni se realizaron limpiezas globales.