metis-desk/docs/skills-frontend-ui-ux.md

Auditoría e integración de skills frontend y UI/UX

Fecha: 21 de octubre de 2026. Alcance: instalación local de Metis Desk y capacidades expuestas en esta sesión de Codex. Selección de skills formalizada en AGENTS.md; las mejoras propuestas de DESIGN.md y V01 siguen pendientes.

1. Diagnóstico y recomendación

Hay 15 skills pertinentes instaladas en .agents/skills/, coincidentes con las 15 entradas de skills-lock.json. Las cuatro anteriores cubrían dirección visual, shadcn/ui, composición y rendimiento React. Las once incorporaciones aportan diez guías UX especializadas —incluido un orquestador de revisión— y una base consultable con herramientas Python, ui-ux-pro-max.

Recomiendo seleccionar una skill principal por tarea, añadir shadcn cuando se compongan primitivas y consultar las reglas React/composición solo cuando exista una decisión técnica correspondiente. Utilizar las nuevas guías para concretar tareas, alternativas y comprobaciones; no para sustituir los patrones de Metis ni para ejecutar todas las revisiones en cada cambio.

Dos límites relevantes:

• ux-design-review está instalado, pero sus auditores dependientes *-audit no. Tampoco se ha localizado su política docs/orchestration-policy.md. Ofrece una estructura útil de revisión, pero su orquestación completa no está disponible.
• Las recomendaciones de ui-ux-pro-max y shadcn necesitan filtrado: hay generación de sistemas visuales, ejemplos abreviados de APIs, herramientas de instalación y consejos de otras plataformas. Su presencia no autoriza regenerar vendor, añadir dependencias ni reemplazar DESIGN.md.

No se necesita instalar más herramientas para aplicar las recomendaciones básicas. La ausencia de auditores especializados debe declararse, no ocultarse ni resolverse instalándolos automáticamente.

2. Fuentes, localización y método

Se consultaron los 15 SKILL.md, los recursos aplicables descritos más adelante, el lockfile, AGENTS.md, DESIGN.md, los patrones de listados y diálogos, la estructura frontend, la auditoría visual, la propuesta V01 y el procedimiento de Playwright MCP.

Se contrastaron también apps/web/components.json, los manifests del proyecto/vendor, la API pública de Button/Sheet y la configuración MCP de proyecto. La app es React 19.2.5, TypeScript 6.0.2, Tailwind 4.2.2 y Vite; vendor usa Base UI 1.8.0 y shadcn CLI 4.21.1. Son versiones declaradas en los manifests inspeccionados, no versiones inferidas de las skills. rsc:false, estilo base-vega e iconografía propia Tabler delimitan la aplicación de ejemplos externos.

Ubicaciones inspeccionadas:

Ubicación	Resultado y alcance
.agents/skills/ y skills-lock.json	Núcleo completo de 15 skills; inventario detallado en §3.
.codex/config.toml	Configura Playwright MCP; no constituye un registro adicional de skills UI.
/home/david/.agents/skills/	find-skills: descubrimiento/instalación, no guía de diseño. No se usa para instalar nada en esta tarea.
/home/david/.codex/skills/.system/	imagegen como capacidad visual auxiliar; herramientas de administración/documentación y review-agent, ajenas al núcleo UI. Un fichero presente no implica que sea invocable en esta sesión.
/home/david/.codex/config.toml	Se inspeccionó únicamente la estructura de registro de skills: no hay clave skills con rutas adicionales. No se reproducen otros ajustes ni secretos.
Caché de plugins de Codex	Skills de Sites y plantillas de documentos/artefactos; se separan en §4 de las guías para desarrollar Metis. Caché no equivale a plugin activo.

No se consultó upstream para deducir releases ni se instalaron/actualizaron skills. Se inspeccionaron estáticamente los scripts antes de ejecutar dos búsquedas locales sin persistencia (§11). No se ejecutaron scripts de generación, instalación, actualización de catálogos ni publicación.

3. Inventario de skills del repositorio

Todos los enlaces de esta sección resuelven al SKILL.md local. Las rutas son relativas a la raíz del repositorio. El lockfile registra procedencia GitHub, ruta upstream y computedHash; no registra commit, tag ni release. Las versiones 1.0.0 proceden del frontmatter y no identifican por sí solas una revisión inmutable. Las huellas siguientes están abreviadas; el valor completo está en el lockfile. No se confunden con un SHA de commit ni con el SHA-256 del fichero individual.

3.1. Procedencia y referencia instalada

Nombre / ubicación	Procedencia y ruta upstream declaradas en lock	Versión declarada	computedHash, prefijo
frontend-design	anthropics/skills · skills/frontend-design/SKILL.md	No declarada	89496d5dd00f
shadcn	shadcn-ui/ui · skills/shadcn/SKILL.md	No declarada	b864a9587655
ui-ux-pro-max	nextlevelbuilder/ui-ux-pro-max-skill · .claude/skills/ui-ux-pro-max/SKILL.md	No declarada	27b1e8c953e2
ux-dashboard	uxcel-lab/product-skills · ux/screens/dashboard/SKILL.md	1.0.0	4bf93a57b230
ux-design-review	uxcel-lab/product-skills · ux/workflows/design-review/SKILL.md	1.0.0	16b69fd0d31d
ux-empty-states	uxcel-lab/product-skills · ux/screens/empty-states/SKILL.md	1.0.0	82c55ab7d5d7
ux-error-recovery	uxcel-lab/product-skills · ux/flows/error-recovery/SKILL.md	1.0.0	9f77a4a62216
ux-inputs-and-forms	uxcel-lab/product-skills · ux/components/inputs-and-forms/SKILL.md	1.0.0	af498000a05f
ux-microcopy	uxcel-lab/product-skills · ux/foundations/microcopy/SKILL.md	1.0.0	980c00cfa403
ux-navigation	uxcel-lab/product-skills · ux/components/navigation/SKILL.md	1.0.0	3d3442366144
ux-notifications-and-toasts	uxcel-lab/product-skills · ux/components/notifications-and-toasts/SKILL.md	1.0.0	86574eaa1d14
ux-search	uxcel-lab/product-skills · ux/components/search/SKILL.md	1.0.0	9918d81eaa3d
ux-tables	uxcel-lab/product-skills · ux/components/tables/SKILL.md	1.0.0	92d4de539c6a
vercel-composition-patterns	vercel-labs/agent-skills · skills/composition-patterns/SKILL.md	1.0.0	f98931159fa9
vercel-react-best-practices	vercel-labs/agent-skills · skills/react-best-practices/SKILL.md	1.0.0	3219a1944e40

3.2. Propósito, instrucciones y activadores

Skill	Propósito e instrucciones principales	Activador recomendado en Metis	Compatibilidad / adaptación
frontend-design	Dirección visual intencionada; plan/wireframe, crítica y revisión; jerarquía y contenido específicos del producto.	Pantalla nueva o mejora visual con decisiones de composición.	Compatible como criterio. Conservar paleta, Inter, densidad y recetas; sus ejemplos de hero, tipografías nuevas y aversión general a mayúsculas no desplazan el patrón empresarial.
shadcn	Reutilizar componentes, inspeccionar configuración y docs, componer semánticamente, diferenciar Base UI/Radix y revisar resultado.	Uso de primitivas, formularios/modales o componentes compartidos.	Compatible con límites: render, APIs instaladas y wrappers rdx-ui. Prohibidos init/preset/add/vendor sin autorización específica.
ui-ux-pro-max	Buscar una intención observable y stack explícito; verificar pertinencia, reintentar una vez si no hay coincidencia; no presentar fallbacks como resultados.	Duda concreta de accesibilidad, interacción, responsive o patrón; consulta transversal de apoyo.	Compatible con adaptación de rutas, plataforma y sistema visual. No generar/persistir otro diseño para cada página de Metis.
ux-dashboard	Elegir métricas según la decisión del usuario, jerarquizar, agrupar y mantener comparaciones visibles; gráficos según datos.	Dashboard/resumen operativo, revisión de sobrecarga.	Compatible como guía, sin añadir métricas, tiempo real o gráficos sin consumidor/datos. No convertir «todos los ejes a cero» en regla universal para cualquier gráfico.
ux-design-review	Establecer contexto una vez, seleccionar lentes, suprimir rediseño de tokens con sistema existente y consolidar hallazgos por gravedad.	Auditoría integral de una pantalla/flujo, no revisión de un único aspecto.	Parcial: faltan auditores y política; usar estructura de informe y declarar qué comprobaciones se realizan directamente.
ux-empty-states	Distinguir primer uso, completado, sin resultados y error/404; explicar y ofrecer siguiente acción, con una primaria.	Estados vacíos de listas/asistentes y recuperación sin resultados.	Compatible con EmptyState/EntityTable existentes; no inventar datos de demostración en inventarios reales ni multiplicar CTA sin permisos.
ux-error-recovery	Prevenir fallos, validación contextual, conservar trabajo, dar salida y ajustar confirmación/undo a consecuencias.	Formularios fallidos, errores de red, borrados y rutas sin entidad.	Compatible como UX. Undo/autosave y explicaciones de seguridad dependen de contratos de negocio, no los crea la skill.
ux-inputs-and-forms	Justificar campos, etiquetas persistentes, agrupar, seleccionar control adecuado, validar y comunicar envío.	Formularios, asistentes y selectores.	Adaptar una columna obligatoria, «(opcional)», asterisco previo, defaults y validación al patrón de diálogos, FormLabel y schemas.
ux-microcopy	Tono según tarea, texto conciso y específico, verbos de acción, consistencia e inclusión.	Etiquetas, ayuda, tooltips, confirmaciones, errores y traducciones.	Compatible mediante i18n es/en y vocabulario de entidades. Fechas relativas no sustituyen fechas exactas necesarias para soporte/historial.
ux-navigation	Elegir patrón según amplitud/profundidad, contexto y rutas de entrada; orientación, estado activo y acceso a destinos.	Shell, compañía, navegación responsive y evaluación de V01.	Compatible con la justificación de V01; adaptar tamaños y prohibiciones absolutas de hamburguesa/iconos a capacidad real.
ux-notifications-and-toasts	Relacionar urgencia y canal; evitar interrupciones/repeticiones; mensajes comprensibles y control del usuario.	Feedback de mutaciones, avisos, banners o futura estrategia de notificaciones.	Compatible como criterio; no implementar un servicio de avisos por disponer de la skill ni confundir CountBadge con no leídos.
ux-search	Distinguir búsqueda conocida/exploratoria; consulta visible, recuperación, filtrado y orden separados.	Búsqueda de inventarios/pickers o global; problemas sin resultados.	Compatible sin introducir tendencias, historial, buscador transversal ni botón de enviar donde ya hay filtrado inmediato.
ux-tables	Escanear/comparar/actuar; alineación, formatos, orden, personalización y densidad ajustada a tareas.	Listados, tablas, sublistados y pickers.	Compatible con EntityTable. Acciones visibles y selección primera según Metis prevalecen sobre hover-only o controles a la derecha.
vercel-composition-patterns	Composición, variantes explícitas y separación de estado/presentación; evitar proliferación de flags.	APIs reutilizables, responsabilidades compartidas y refactors con consumidores reales.	Compatible con React 19. No exigir Context/compound components para componentes sencillos ni migraciones mecánicas de hooks.
vercel-react-best-practices	Evitar trabajo redundante, waterfalls, bundles innecesarios y estado derivado por efectos; optimizar con evidencia.	React con lógica, acceso remoto o problema de rendimiento medido.	Aplicar parte React/Vite; no introducir next/dynamic, RSC, next/server, SWR o cachés globales por copiar ejemplos.

3.3. Recursos, herramientas y dependencias

Diez skills Uxcel ux-*. Cada directorio instalado contiene únicamente SKILL.md, con licencia MIT y versión declaradas en frontmatter. Son guías de razonamiento/procedimiento, no ejecutables ni bibliotecas React. Incorporan tablas de decisiones, comprobaciones y enlaces a lecciones externas; esos enlaces no son contenido instalado ni han sido auditados aquí. No requieren un runtime para leerlas. Las referencias a otras skills son dependencias de orquestación, no paquetes npm.

frontend-design. SKILL.md y LICENSE.txt; sin scripts ni dependencias de ejecución. No tiene herramientas propias para renderizar, medir contraste o producir evidencias de navegador.

shadcn. Incluye agents/openai.yml, documentación CLI/MCP, registry/customization, reglas de forms/composition/icons/styling/Base-vs-Radix/chat, guías de design system/showcase, ejemplos TSX/CSS, iconos PNG, evals/evals.json y scripts/showcase-coverage.mjs. Se consultaron SKILL, Base-vs-Radix, las guías de composición/estilos pertinentes, la ruta de design system y el script de cobertura. El .mjs usa Node y filesystem, compara imports de un showcase con nombres de componentes; no mide accesibilidad, cobertura funcional ni calidad visual. No se ejecutó. CLI requiere Node/PNPM y puede necesitar red; búsquedas/docs no equivalen a autorización para instalar. mcp.md describe un servidor shadcn, pero no se encontró configurado en .codex/config.toml; no inventar su disponibilidad.

vercel-composition-patterns. README, AGENTS compilado y rules/*.md; sin runtime ni ejecutables instalados. Se consultaron las reglas de evitar flags, interfaces de estado y cambios React 19. El README menciona metadata/generación upstream, pero eso no significa que estén los generadores o metadata.json en esta copia.

vercel-react-best-practices. README, AGENTS compilado y reglas individuales; sin scripts de build/validación instalados. Las instrucciones pnpm build/validate/extract-tests del README son del paquete upstream, no comandos que deban ejecutarse desde la raíz de Metis para preparar una skill. Se contrastaron estado derivado, importaciones dinámicas y deduplicación SWR.

ui-ux-pro-max. Tiene references/quick-reference.md, references/pro-rules.md, datos CSV/JSON y cinco módulos Python principales: search.py, core.py, design_system.py, reasoning_contract.py y validate_data.py, además de tests/fixtures. Se inspeccionaron búsqueda, imports, lectura de CSV y ramas de escritura. Python 3 y biblioteca estándar bastan para la búsqueda inspeccionada; no requiere pip ni dependencias de producción. --persist crea design-system/<slug>/MASTER.md y overrides; --force puede sobrescribirlos. No usar esas opciones en Metis para competir con DESIGN.md.

El catálogo local declara verificación a 26-08-2026; se contaron realmente 88 filas de estilos, 192 productos/paletas/perfiles de razonamiento, 74 pares tipográficos, 119 guías UX, 105 iconos curados, 17 presets de movimiento, 25 tipos de gráfico y 22 CSV de stacks. Los 79 estilos consultables y 50 activos están declarados en catalog-summary.json; no equivalen a 79 temas implementados en Metis. Las fechas/procedencias del dataset no son una versión del motor ni garantía de actualidad de cada API. Los presets GSAP, recomendaciones Phosphor/otras fuentes y ejemplos de librerías no constituyen nuevas dependencias autorizadas.

3.4. Compatibilidad con Codex y límites reales

Las 15 skills aparecen en el catálogo de la sesión y existen en disco. Sus instrucciones Markdown son legibles por Codex. shadcn incorpora descriptor agents/openai.yml; las demás no necesitan ese descriptor para estar expuestas aquí. La sintaxis ! de shell interpolado y allowed-tools: Bash(...) de shadcn no debe considerarse una ejecución ya realizada ni una herramienta Codex disponible por sí misma.

El ejemplo de Pro Max con ${CLAUDE_PLUGIN_ROOT}/.claude/... no corresponde a esta instalación. Resolver el script desde .agents/skills/ui-ux-pro-max/scripts/, con python3 en WSL y sin rutas personales embebidas en código del proyecto. Las menciones a «Claude» en el texto no impiden usar las guías; tampoco garantizan compatibilidad ejecutable sin esta adaptación.

La orquestación Uxcel remite a estas skills de auditoría no instaladas: ux-heuristics-audit, ux-microcopy-audit, ux-dark-patterns-audit, ux-accessibility-audit, ux-aesthetics-audit, ux-information-architecture-audit y ux-mobile-responsiveness-audit. También hay referencias a ux-color, ux-typography, ux-layout-spacing-grids, ux-contact-support, ux-login-signup, ux-menus, ux-modals-and-dialogs y ux-settings, ausentes. No son aliases de las guías generativas disponibles; por ejemplo, ux-microcopy no es ux-microcopy-audit.

No existe el docs/orchestration-policy.md referenciado ni en esos directorios de skill ni en la documentación del proyecto. No inventar su contenido ni escribirlo dentro de la distribución ajena. El orquestador dice que las ausencias no bloquean: continuar con comprobaciones propias y declararlas. Su sugerencia de listarlas como «available but not run» se corrige en el informe de Metis por «no instalada/no ejecutada», para no comunicar una capacidad inexistente.

No hay una skill dedicada de accesibilidad/auditoría WCAG en este núcleo, ni un runner de Playwright suministrado por estas skills. Hay criterios de accesibilidad repartidos entre ellas; la ejecución visual/interactiva corresponde al MCP y scripts propios existentes. No se certifica accesibilidad por leer checklists ni se presentan los tests del catálogo como pruebas de la aplicación.

4. Otras capacidades del entorno: fuera del núcleo Metis

Se revisaron metadatos y alcance inicial, sin invocarlas ni auditar todos sus recursos. Las rutas siguientes son del equipo de esta sesión, no dependencias portables del repositorio.

Skill / ubicación SKILL.md	Procedencia/referencia visible	Propósito y decisión de uso
imagegen · /home/david/.codex/skills/.system/imagegen/SKILL.md	Skill de sistema; sin versión declarada en frontmatter	Recursos bitmap, edición y mockups. Puede apoyar una tarea explícita de imágenes; no sustituye iconos Tabler, wireframes de estructura ni navegador. Herramienta de imagen por defecto; fallback CLI tiene otros requisitos y autorización, no ejecutado.
sites:sites · /home/david/.codex/plugins/cache/openai-curated-remote/sites/1.1.0/skills/sites/SKILL.md	Paquete de caché Sites 1.1.0, no versión declarada de SKILL	Construcción/publicación alojada mediante Sites. Fuera del flujo de mantenimiento de esta SPA local; no exportar ni publicar Metis por esta auditoría. Requiere herramientas/servicio del plugin, no comprobados aquí.
sites:sites-remix · misma raíz, skills/sites-remix/SKILL.md	Paquete Sites 1.1.0	Remix de un Site identificado. Sin consumidor para el repositorio Metis; no usar para rediseñar su shell.

La caché openai-templates/0.1.1/skills/ contiene artifact-template-simple-light-mode, artifact-template-simple-dark-mode, artifact-template-design-report, artifact-template-analytics-dashboard y artifact-template-system-design, cada una con su SKILL.md. Se inspeccionaron sus frontmatters: son plantillas de presentaciones, documentos o una hoja de cálculo, no skills de componentes frontend. No aparecen como skills disponibles en esta sesión; no atribuirles capacidad activa ni aplicar sus temas claro/oscuro a Metis. El resto de plantillas de esa caché son artefactos de negocio, fuera del alcance UI de la aplicación.

find-skills, skill-installer y skill-creator administran descubrimiento/instalación/autoría; openai-docs documenta productos OpenAI. review-agent está presente en la carpeta de sistema pero no expuesto en el catálogo de skills de esta sesión; no se ha delegado ninguna revisión. Skills de Pages, mascotas y administración de plugins tampoco aportan reglas al frontend de Metis. No se cuentan dentro de las 15 especializadas.

5. Matriz de responsabilidades y utilización

R = reglas/criterios; P = procedimiento; H = herramienta ejecutable; B = base de conocimiento. Una skill puede cubrir varias funciones, pero no todas ejecutan pruebas.

Área	Skills y naturaleza	Límite / responsable efectivo
Diseño visual	frontend-design R/P; Pro Max R/B/H	DESIGN.md decide tokens/identidad; consumidor y rdx-ui componen.
UX	ux-* R/P; Pro Max R/B/H	Requisitos/tareas del usuario y patrones especializados prevalecen.
Accesibilidad	Criterios de Pro Max, shadcn y ux-* R/B	Base UI aporta primitivas; integrador verifica uso y foco. Sin auditor dedicado instalado.
Arquitectura frontend	vercel-composition-patterns R; shadcn R/P	AGENTS/estructura web y fronteras módulo/rdx-ui/vendor.
React/rendimiento	vercel-react-best-practices R; Pro Max R/B/H	Evidencia de profiling/bundle y stack instalado; no nuevas librerías por receta.
Componentes/composición	shadcn R/P/H; vercel-composition-patterns R	API pública real, composición propia y responsabilidades acotadas.
Auditoría visual	ux-design-review P parcial; otras guías R	Capturas/navegación reales con Playwright MCP; skill no genera evidencia por sí sola.
Automatización/pruebas	Pro Max H sobre catálogo; shadcn H sobre showcase	No son tests UI. Infraestructura de aplicación: scripts propios, MCP y pruebas del proyecto.

Selección por tarea

Tarea	Skill principal	Complementarias cuando aporten valor	Resultado esperado
1. Diseñar pantalla nueva	frontend-design	Skill UX del tipo de tarea; Pro Max ante duda concreta; shadcn al componer	Esquema/jerarquía basado en DESIGN, estados y patrón reutilizable, sin generar otro sistema.
2. Mejorar visualmente pantalla	frontend-design	ux-tables/navigation/forms según problema; Pro Max para criterio observable	Cambio acotado y comparación visual, sin refactor ajeno.
3. Crear componente compartido	vercel-composition-patterns	shadcn; React best practices si hay hooks/estado	API semántica, consumidores reales, composición accesible y sin DTO en rdx-ui.
4. Formularios/diálogos	ux-inputs-and-forms	shadcn; ux-error-recovery o microcopy para el aspecto afectado	Patrón de diálogos, schemas/RHF existentes, estabilidad, ayuda y foco verificados.
5. Listados/tablas	ux-tables	shadcn; ux-search si cambian búsquedas/filtros	EntityTable y acciones/paginación de Metis, con datos representativos.
6. Navegación responsive	ux-navigation	shadcn para Sheet; Pro Max para foco; composición si cambia API	Contratos de V01 y prueba por capacidad; no nueva arquitectura por hábito.
7. Accesibilidad	ui-ux-pro-max, consulta puntual	shadcn y guía UX del componente	Criterio observable → API → prueba real. Declarar que no existe skill WCAG dedicada.
8. Refactorizar React	vercel-composition-patterns	vercel-react-best-practices si hay estado/efectos; shadcn si afecta composición	Simplificación justificada, sin mover código por preferencia.
9. Rendimiento frontend	vercel-react-best-practices	Pro Max solo para UX percibida, listas o layout	Medición antes/después; aplicar React/Vite, no recetas Next/SWR.
10. Auditoría UI/UX	ux-design-review, con alcance parcial declarado	Guías especializadas del flujo y Pro Max; navegador según AGENTS	Informe único priorizado; separar código, visual, funcional, no reproducido y pendiente.

Dashboard, vacíos, copy, recuperación y notificaciones tienen sus guías principales propias cuando ese sea el objeto de la tarea. No añadirlas por el simple hecho de que una pantalla contenga un texto o un contador.

6. Compatibilidad, solapamientos y resoluciones

Reglas de precedencia propuestas

Bajo las instrucciones vigentes del usuario y del entorno, aplicar el orden solicitado:

1. Restricciones obligatorias del proyecto y AGENTS aplicable: alcance, seguridad, vendor, i18n y arquitectura.
2. DESIGN.md y patrones especializados: en su ámbito, listados/diálogos prevalecen sobre el resumen general.
3. Contratos reales de componentes instalados: determinan cómo componer una pauta; una desviación de la implementación no deroga la norma y debe señalarse.
4. Skills pertinentes: criterios complementarios; recomendaciones no son autorización ni requisitos nuevos.

Ante conflicto: citar recomendación y norma, justificar adaptación, escoger la solución menor y registrar solo lo relevante en la entrega. No modificar una skill upstream para silenciar un conflicto ni bloquear una tarea ya autorizada para pedir de nuevo permiso que no necesita.

Conflictos y riesgos concretos

Recomendación localizada	Conflicto o riesgo en Metis	Resolución propuesta
shadcn SKILL/design-system: init, preset, add --all, editar variantes/vendor y tailwindCssFile	El alias apunta al CSS vendor, protegido por AGENTS; la app ya existe.	Consultar docs/API; extender desde rdx-ui/módulos y CSS propio autorizado. No ejecutar el bootstrap ni regenerar vendor.
shadcn: consultar registries/añadir componentes y providers	Tener una receta no demuestra que falte componente ni autoriza nuevas dependencias.	Buscar primero en rdx-ui/vendor; CLI informativa cuando corresponda; instalación solo con alcance y autorización aplicables.
shadcn: FieldGroup/Field, Empty y toast como recetas universales	Metis tiene FormDialog/FormLabel/FormSection/EmptyState y feedback propios.	Reutilizar wrappers; no migrar formularios o notificaciones completos solo para coincidir con la skill.
Pro Max: generar sistema para páginas nuevas y persistir MASTER/overrides	Crearía una segunda fuente normativa de color, tipo y espaciado.	Consulta dirigida --domain/--stack; sin --persist, --force ni redefinición de tokens por página.
Pro Max: 16 px base, max-width global, cero scroll horizontal y breakpoints de ejemplo	Metis usa texto base de 14 px, tablas anchas con scroll propio y distribución por contenedor.	No ensanchar ni restringir todo por receta. Distinguir documento de tabla; validar legibilidad/zoom y capacidad real.
Pro Max: virtualizar 50+ filas; stack React: listas de más de 100	Umbrales internos distintos, sin medición de consumidores; los listados ya paginan.	Medir volumen realmente renderizado/rendimiento antes de introducir virtualización.
Pro Max/ux-navigation: icono siempre con texto, no navegación modal	Choca literalmente con raíl y Sheet propuestos en V01.	Overlay es contenedor temporal de enlaces reales, no un formulario que sustituye una ruta. Raíl solo con etiquetas accesibles, ayuda y expansión; validar descubribilidad.
ux-navigation: 44×44, texto 16; forms: objetivos 38; Pro Max: 24 CSS px web frente a unidades nativas	Inconsistencia entre guías, densidad empresarial y plataformas.	Distinguir objetivo táctil, tamaño visual y criterio de accesibilidad. No redimensionar vendor globalmente; aprobar objetivo por contexto y verificar espacio/zoom.
ux-inputs-and-forms: una columna siempre, opcionales rotulados y asterisco antes	Patrón de Metis admite columnas por contenedor, opcionales sin sufijo y asterisco final.	Aplicar patrón de diálogos y FormLabel existentes; conservar orden DOM y agrupación accesibles.
forms/error/Pro Max: validación siempre onBlur, máscaras y autofill; autosave/confirmar todo cierre con cambios	Puede alterar validación Zod/RHF, cancelar y persistencia, además de campos legítimos.	Evaluar por campo/operación; no quitar campos funcionales ni cambiar contratos automáticamente. Preservar borrador ante fallo sin inventar autosave.
ux-tables: acciones ocultas hasta hover, controles de lista a la derecha	Acción principal visible y selection primera son normas de Metis.	Conservar icono principal, tres puntos y selección al inicio; controles siempre accesibles con teclado/táctil.
ux-search: lupa como submit y ~10 sugerencias/recentes, múltiples filtros	Búsqueda actual filtra en vivo; global solo busca compañías/destinos.	No crear botón inútil, historial ni servicio transversal. Mantener query/contexto; mejorar solo el problema real.
notifications: badges solo para no leídos, toast no descartable, éxito siempre verde	CountBadge cuenta entidades; UI y feedback no son una taxonomía móvil universal.	Contador de inventario no es notificación. Comprobar primitive/API y tokens antes de introducir colores, timers o controles.
ux-dashboard: todo eje parte de cero; microcopy: mañana mejor que fecha exacta	No todo gráfico o dato de historial tiene la misma semántica.	Evaluar comparación/trend y necesidad de fecha exacta; no convertir preferencias en mandatos universales.
Vercel React: Next/RSC, next/dynamic, SWR	SPA Vite y TanStack Query ya establecidos.	Aplicar principio de diferir/cachar sin copiar APIs ajenas. Importación dinámica/React.lazy si procede y se justifica.
Vercel composición: todos los estados en providers, use() reemplaza useContext	Puede añadir capas a componentes sencillos y provocar migraciones sin valor.	Estado local por defecto, elevar con necesidad real. No sustituir hooks válidos ni alterar vendor por una convención de la skill.
shadcn/Pro Max ejemplos Base UI abreviados	Ejemplo Pro Max de Button con enlace omite nativeButton={false}; ejemplo Sheet coloca side en Root, aunque vive en SheetContent.	Comprobar tipos y consumidor instalado. render frente a asChild, multiple y contratos Base UI según API concreta. No copiar snippets como contratos.
Uxcel: lentes opcionales ofrecidas antes de accesibilidad/mobile	AGENTS ya exige verificar accesibilidad y responsive cuando se modifica UI.	No usar la oferta como permiso para omitir controles obligatorios; no instalar auditores ni pedir aprobaciones repetidas para verificaciones autorizadas.
Skills: checklist de entrega o consejo «shadcn es accesible»	Lectura/uso de primitiva no prueba integración, contraste ni foco.	Navegador, mediciones y teclado; lector/zoom/tema según alcance y límites expresos.

Las guías coinciden en jerarquía, lenguaje claro, etiquetas, reutilización, estados y foco. Se deduplica el análisis: una incidencia puede tener apoyo de varias skills, pero se informa una sola vez. ux-microcopy concreta textos; ux-error-recovery decide recuperación; ux-empty-states diferencia causas. No repetir tres informes para el mismo «sin resultados».

7. Integración en el trabajo habitual

Antes de diseñar

Leer el requisito, AGENTS, DESIGN y patrón pertinente; reconocer consumidores equivalentes. Elegir una guía principal de §5 y declarar contexto conocido: soporte empresarial, web responsive, Base UI/Vega, sistema visual existente y tarea operativa. No volver a preguntar identidad/stack ya documentados.

Consultar frontend-design para composición visual nueva; para V01 comenzar con ux-navigation. Pro Max se utiliza para una duda verificable —por ejemplo foco oculto por sticky—, no para solicitar una paleta SaaS de sustitución. Registrar alternativas solo cuando exista una decisión real.

Durante implementación

Consultar shadcn para contratos/primitivas y tipos instalados, manteniendo wrappers existentes. Si el cambio tiene estado/hook, consultar las reglas React pertinentes; composición solo cuando se diseñe una API o cambien responsabilidades reales. La skill UX especializada dirige contenido/interacción; ninguna decide DTO, permisos, rutas o persistencia.

Convertir cada criterio aplicado en comportamiento observable: acción visible, foco al cerrar, error conservado, contador anunciado con contexto o ancho operativo. Evitar instalar herramientas de revisión, servidores MCP o librerías porque aparezcan en el texto de una skill.

Al auditar la interfaz terminada

Para cambio puntual, revisar el flujo afectado con la guía principal y MCP; para auditoría integral, usar la estructura de ux-design-review y declarar sus lentes ausentes. Mantener accesibilidad, responsive y estados exigidos por el proyecto aunque el orquestador los considere opcionales.

Reutilizar entorno sintético autenticado activo, conservar capturas fuera de Git y abrirlas antes de concluir. Separar evidencia visual, geométrica, funcional y de código; no afirmar WCAG, dark mode o zoom sin pruebas. Informar skills consultadas y efecto concreto, no una lista decorativa de nombres.

Integración formalizada en AGENTS.md

La sección UI/UX — Instrucciones obligatorias remite a esta matriz para seleccionar una skill principal y complementarias pertinentes. Establece precedencia, reutilización, límites sobre vendor/dependencias, verificación con Playwright y declaración de ausencias y pruebas pendientes. DESIGN.md incorpora únicamente una referencia a esta guía; no se han adoptado sus propuestas de tokens, layout o arquitectura V01. La matriz se mantiene aquí, sin duplicarla en AGENTS.md.

8. Posibles mejoras de DESIGN.md

No hace falta modificar paleta, fuentes o tokens para adoptar las skills. Las mejoras siguientes son propuestas editoriales/de proceso; requieren aprobación o una tarea posterior, sin convertirse aquí en normas vigentes.

Sección de DESIGN.md	Mejora concreta	Aportación / límite
§2 Fuentes y capas	Enlazar esta matriz y distinguir instrucción, API, ejemplo y evidencia.	Aclara conflictos; ya existe precedencia, no crear otra autoridad.
§3 Fundamentos	Documentar rol de pares semánticos y cómo verificar estados/temas; inventariar tokens de éxito/aviso solo si hay necesidad real.	Pro Max sistematiza búsquedas/checks; no adoptar paletas generadas ni editar vendor.
§4/§10 Navegación y responsive	Añadir criterios de orientación y pruebas de disponibilidad del contenido, remitiendo a V01 como propuesta pendiente.	ux-navigation aporta taxonomía/entrada profunda; no fija nuevos breakpoints.
§5 Listados	Aclarar alineación de cifras/formatos y visibilidad de acciones como criterios revisables por tarea.	ux-tables concreta escaneabilidad; no sustituye EntityTable ni fija 40/48 px para todas las filas.
§7 Formularios	Registrar momento de validación por contrato y criterios para resumen de errores si se aprueba.	forms/error-recovery, sin eliminar campos, automatizar defaults ni cambiar cancelación.
§8 Estados	Matriz primer uso/sin coincidencias/completado/error/permisos y acción permitida; distinguir contador, estado y notificación.	Mayor detalle de empty/error/notifications, buena parte ya cubierta por Metis.
§9 Accesibilidad	Distinguir criterio mínimo y objetivo más estricto, tamaño CSS/táctil, foco visible/no oculto y pruebas por componente.	Pro Max aporta índice consultable; no declarar cumplimiento por catálogo.
§11 Verificación	Elegir skills por tarea, declarar auditores ausentes y documentar evidencia/limitaciones sin duplicar checklists.	ux-design-review aporta estructura parcial; Playwright ya existía.
§12 Gobernanza	Referencias al lock, procedencia y revisión de scripts/actualizaciones.	Nueva disciplina de mantenimiento del conocimiento; no una dependencia runtime.

El catálogo de componentes puede incorporar, en futuras tareas, ejemplos de estados de uso y decisiones de foco por consumidor. No es necesario construir ahora un showcase completo para cumplir una receta de shadcn ni afirmar cobertura porque todos los componentes estén importados.

9. Revisión de impacto sobre V01

La propuesta sigue fundamentada por las geometrías observadas: menús apilados en móvil y competencia de tabla/panel en ventanas intermedias. Las skills nuevas no aportan mediciones nuevas ni justifican cambiar la arquitectura B híbrida, los 21 destinos o el modelo por capacidad. V01 permanece pendiente; no se repite su auditoría ni se actualiza su documento en esta tarea.

Criterio nuevo/revisado	Qué cubre ya V01	Mejora concreta justificada para su futura implementación
ux-navigation: visibles cuando quepan; orientación al entrar por enlace	Colapso/overlay por capacidad, compañía/sección persistentes, URLs y activo	Añadir a pruebas la identificación del destino sin abrir menú y acceso al último de los 21 destinos con teclado. Mantener el coste de dos activaciones declarado, sin inventar mejora de tiempos.
ux-navigation/Pro Max: iconos no deben sustituir reconocimiento	Raíl global con nombre accesible, tooltip/expansión; secundaria con etiquetas	Comprobar que la ayuda aparece también al foco y es alcanzable al tacto mediante expansión. No eliminar el raíl por una máxima genérica ni añadir una bottom nav sin necesidad demostrada.
Pro Max: foco no oculto, mínimo frente a enhanced	Sticky, scroll-padding y prueba de foco visible previstos	Separar en aceptación «foco al menos parcialmente visible» y objetivo de foco completamente visible, sin llamar AA al segundo. El motor devolvió ambas reglas por separado.
ux-navigation: títulos de documento describen ubicación	Franja y título en contenido; no contrato específico de document.title	Proponer como decisión menor un título Activos · Compañía · Metis Desk al entrar por URL. Requiere definir responsable de navegación; no modifica rutas ni es requisito aprobado.
Pro Max: etiquetas compactas y cadenas largas	V01 pide truncamiento con nombre accesible completo	Concretar una prueba de compañía con nombre largo/ID/URL: ningún overflow global y acceso al texto completo por teclado y puntero, no solo un atributo title o lector.
ux-tables: comparar sin perder acción	V01 propone tabla 800, panel mínimo 1144 y scroll interno	Validar ese presupuesto con varias filas, columnas opcionales y etiquetas inglesas. La skill no demuestra que 800 sea el mínimo correcto ni aporta otro umbral.
ux-search: búsqueda secundaria móvil expandible	Botón móvil propuesto con ámbito compañías/destinos preservado	Mantener activador fuera del Sheet y retorno al botón; no introducir resultados de activos o historial por usar ux-search.
Pro Max: no bloquear interacción por animaciones	Resize/foco/modalidad y una presentación de detalle previstos	Probar aperturas/cierres rápidos y resize durante transición, con movimiento reducido; el estado final no depende de animation-end. Complementa, no sustituye, las esperas estables de medición.

Las guías llaman «drawer» a un patrón, no a una obligación de importar otro componente o biblioteca. V01 puede usar el Sheet ya instalado basado en Dialog de Base UI. Su condición por contenedor sigue requiriendo coordinación semántica, no solo CSS que oculte un panel modal. El observer único y el modo discreto ya están justificados; no añadir un framework responsive ni observadores por enlace.

Hay criterios genéricos en tensión con V01 —«no ocultar navegación primaria», «sin modales para navegación», «siempre icono + texto»— que no constituyen evidencia técnica contra el diseño: el overlay presenta enlaces normales conservando URL/historial y evita la pérdida de contenido medida. Mantener sus ventajas en escritorio amplio y verificar descubribilidad en los tamaños donde se oculta. Si las pruebas con usuarios muestran dificultad, revisar acceso a destinos frecuentes; no anticipar otra arquitectura sin esa evidencia.

10. Gobernanza y mantenimiento propuestos

Incorporación de una skill

1. Identificar una carencia concreta y comprobar que normas, componentes o skills existentes no la resuelven. Preferir no añadir otra guía que repita cinco checklists.
2. Revisar procedencia, licencia declarada, revisión upstream, instrucciones, referencias y dependencias. Separar consejo, comando, ejemplo y acción externa. No ejecutar lo descargado antes de leerlo.
3. Revisar scripts e imports transitivos: red, lectura de archivos, ejecución de procesos, instalación, escrituras y flags de sobrescritura. No pasar datos de clientes, credenciales o fragmentos privados a búsquedas/servicios externos.
4. Comprobar compatibilidad React 19/TypeScript/Tailwind 4/Vite/Base UI y APIs reales. Registrar conflictos y referencias faltantes.
5. Tras autorización aplicable, instalar en .agents/skills/, actualizar lock y documentar su referencia efectiva y responsabilidades. No registrar un commit/tag que el instalador no proporcione. Si falta referencia inmutable, declarar esa limitación junto a la huella disponible.
6. Validar una tarea representativa acotada. Para guía textual, comprobar instrucciones; para herramienta, prueba reproducible sin persistencia y, cuando corresponda, tests propios inspeccionados. Ninguna prueba del catálogo certifica la aplicación.

Actualizaciones

Actualizar de forma explícita por necesidad, no descargar latest durante cada tarea de UI. Revisar diff de SKILL, referencias, scripts y datos; una misma versión 1.0.0 puede contener revisiones distintas. Registrar fecha, origen, huella anterior/nueva, comandos realmente ejecutados y cambios de compatibilidad. No modificar manualmente computedHash para hacer coincidir una copia ni asumir un algoritmo de hash que no se ha comprobado.

Si se necesita reproducibilidad más fuerte que el lock actual, conservar el commit/tag resuelto y el método de instalación en la revisión que lo introduzca. La huella no demuestra autenticidad remota y no se validó aquí su algoritmo. No ejecutar los comandos de build de README upstream como si fueran scripts del monorepo.

Pruebas mínimas tras cambios de herramientas: consultas de dominio/stack conocidas, salida vacía/fallback, ausencia de efectos de escritura en modo lectura y comprobación de rutas. Cambios en generación/persistencia se prueban únicamente en una salida desechable explícita. No ejecutar un --force contra el proyecto para validar.

Responsabilidades y registro

Responsable	Responsabilidad propuesta
Quien mantiene frontend/sistema visual	Selección por tarea, conflictos, tokens/patrones y revisión de cambios de API.
Quien ejecuta la tarea con Codex	Leer recursos, adaptar ejemplos, respetar alcance y declarar evidencia/limitaciones.
Revisión técnica del cambio	Comprobar fuente/huella/scripts y que no se han aplicado recetas incompatibles o añadido dependencias sin motivo.
Responsable funcional de Metis	Aprobar decisiones de producto y cambios de arquitectura visual, como V01; no las decide la skill.

En la entrega registrar únicamente las skills consultadas con influencia concreta y las comprobaciones realizadas. Mantener esta matriz como mapa, sin copiar todos los SKILL a AGENTS o DESIGN. Registrar «no instalada», «no pertinente» y «no ejecutada» por separado. Si falta una referencia, continuar con alcance declarado cuando sea posible; no afirmar haber leído un documento ausente.

11. Comprobaciones realmente ejecutadas y limitaciones

Entorno comprobado: bash/WSL en la raíz del proyecto, Node v24.20.0, PNPM 11.25.0 y Python 3.12.3.

Después de inspeccionar los módulos Python y sus ramas de lectura/escritura, se ejecutaron desde la raíz:

PYTHONDONTWRITEBYTECODE=1 python3 .agents/skills/ui-ux-pro-max/scripts/search.py \
  'focus not obscured' --domain ux -n 2 --json
PYTHONDONTWRITEBYTECODE=1 python3 .agents/skills/ui-ux-pro-max/scripts/search.py \
  'dialog render base' --stack shadcn -n 2 --json

Ambas terminaron con código 0 y devolvieron dos resultados. La primera distinguió Focus Not Obscured Enhanced/Minimum; la segunda devolvió composición render para Base UI y selección explícita de base. Se verificó pertinencia y se detectó que el ejemplo abreviado del enlace necesita completar el contrato real de Button. No fue necesario reintentar. No se generaron MASTER, overrides, paquetes ni cachés Python en la instalación de skills.

Se contaron archivos de catálogo con CSV/JSON de la biblioteca estándar y se inspeccionaron registros/referencias. No se ejecutó validate_data.py, la suite de tests de la skill, el showcase, shadcn CLI, herramientas de instalación ni scripts de generación. Es una prueba de búsqueda, no una validación exhaustiva del catálogo ni de la interfaz.

En la auditoría original no se abrió otra auditoría de navegador ni se iniciaron entornos. Las pruebas visuales de V01 citadas pertenecen a su documento y no se presentan como repetidas aquí. No se ejecutaron build/typecheck/lint/tests globales: los cambios de auditoría y formalización son documentales. Se comprobaron enlaces locales, concordancia de nombres/lock y diff; los archivos de skills/lock se conservan.

Capacidades nuevas frente a las ya cubiertas

Nuevas realmente disponibles: diez guías UX con decisiones por tipo de tarea, estructura de auditoría parcial y recuperación/microcopy más detalladas; buscador local de Pro Max con datos, criterios por stack y dos consultas comprobadas. Ya cubiertas: identidad visual, reutilización, contratos Base UI, composición React, estado mínimo, teclado/foco, responsive, estados y verificación de navegador, presentes en las cuatro skills anteriores y en normas/infraestructura de Metis.

No incorporadas por estas instalaciones: auditores *-audit, política de orquestación ausente, certificación WCAG, tests E2E, servidor shadcn MCP, nueva búsqueda global, sistema de notificaciones, bibliotecas de UI/animación o implementación V01. Tampoco implican que un script, snippet o recomendación esté validado para cada consumidor.

La adopción propuesta mejora la selección y profundidad de criterios; no cambia automáticamente ninguna pantalla ni convierte máximas generales en decisiones normativas.