# 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](../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](../AGENTS.md), [DESIGN.md](../DESIGN.md), los patrones de [listados](patron-de-listados-de-entidades.md) y [diálogos](patron-de-dialogos.md), la [estructura frontend](estructura-web-por-entidades-y-operaciones.md), la [auditoría visual](auditoria-ui-ux-visual.md), la [propuesta V01](propuesta-navegacion-responsive-v01.md) y el procedimiento de [Playwright MCP](playwright-mcp.md).

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](../.agents/skills/frontend-design/SKILL.md) | `anthropics/skills` · `skills/frontend-design/SKILL.md` | No declarada | `89496d5dd00f` |
| [shadcn](../.agents/skills/shadcn/SKILL.md) | `shadcn-ui/ui` · `skills/shadcn/SKILL.md` | No declarada | `b864a9587655` |
| [ui-ux-pro-max](../.agents/skills/ui-ux-pro-max/SKILL.md) | `nextlevelbuilder/ui-ux-pro-max-skill` · `.claude/skills/ui-ux-pro-max/SKILL.md` | No declarada | `27b1e8c953e2` |
| [ux-dashboard](../.agents/skills/ux-dashboard/SKILL.md) | `uxcel-lab/product-skills` · `ux/screens/dashboard/SKILL.md` | `1.0.0` | `4bf93a57b230` |
| [ux-design-review](../.agents/skills/ux-design-review/SKILL.md) | `uxcel-lab/product-skills` · `ux/workflows/design-review/SKILL.md` | `1.0.0` | `16b69fd0d31d` |
| [ux-empty-states](../.agents/skills/ux-empty-states/SKILL.md) | `uxcel-lab/product-skills` · `ux/screens/empty-states/SKILL.md` | `1.0.0` | `82c55ab7d5d7` |
| [ux-error-recovery](../.agents/skills/ux-error-recovery/SKILL.md) | `uxcel-lab/product-skills` · `ux/flows/error-recovery/SKILL.md` | `1.0.0` | `9f77a4a62216` |
| [ux-inputs-and-forms](../.agents/skills/ux-inputs-and-forms/SKILL.md) | `uxcel-lab/product-skills` · `ux/components/inputs-and-forms/SKILL.md` | `1.0.0` | `af498000a05f` |
| [ux-microcopy](../.agents/skills/ux-microcopy/SKILL.md) | `uxcel-lab/product-skills` · `ux/foundations/microcopy/SKILL.md` | `1.0.0` | `980c00cfa403` |
| [ux-navigation](../.agents/skills/ux-navigation/SKILL.md) | `uxcel-lab/product-skills` · `ux/components/navigation/SKILL.md` | `1.0.0` | `3d3442366144` |
| [ux-notifications-and-toasts](../.agents/skills/ux-notifications-and-toasts/SKILL.md) | `uxcel-lab/product-skills` · `ux/components/notifications-and-toasts/SKILL.md` | `1.0.0` | `86574eaa1d14` |
| [ux-search](../.agents/skills/ux-search/SKILL.md) | `uxcel-lab/product-skills` · `ux/components/search/SKILL.md` | `1.0.0` | `9918d81eaa3d` |
| [ux-tables](../.agents/skills/ux-tables/SKILL.md) | `uxcel-lab/product-skills` · `ux/components/tables/SKILL.md` | `1.0.0` | `92d4de539c6a` |
| [vercel-composition-patterns](../.agents/skills/vercel-composition-patterns/SKILL.md) | `vercel-labs/agent-skills` · `skills/composition-patterns/SKILL.md` | `1.0.0` | `f98931159fa9` |
| [vercel-react-best-practices](../.agents/skills/vercel-react-best-practices/SKILL.md) | `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](../AGENTS.md#uiux--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:

```bash
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.