Generador y Auditor Estructural de UX.md (v1)
Resumen
Mientras que DESIGN.md especifica tokens visuales (colores, tipografía, radios, sombras, escala de espaciado), UX.md especifica el esqueleto estructural y las reglas de interacción de una aplicación.
Sin UX.md, los agentes de IA de codificación derivan entre sesiones: mezclan anchos de contenedor, mueven CTAs principales, alternan arbitrariamente entre modales y paneles laterales, omiten estados vacíos o de error, pierden el estado del filtro al recargar con F5 e introducen rutas sin salida.
Este skill opera en cuatro modos usando un pipeline de tres fases respaldado por seis scripts Node.js sin dependencias en scripts/.
Scripts CLI incluidos
| Script | Propósito | Ejemplo de uso |
|---|---|---|
scripts/extract-ux.mjs | Escanea package.json, AGENTS.md, DESIGN.md y las rutas fuente (src/app, src/pages) para producir JSON estructurado | node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json |
scripts/generate-ux.mjs | Crea un UX.md de 12 secciones a partir de un arquetipo, un preset de producto (--preset linear) o ux-scan.json | node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md |
scripts/validate-ux.mjs | Ejecuta 16 reglas estructurales deterministas y reglas de linter --check-code (paridad de rutas, primitivas, handlers muertos, z-index fuera de control) | node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code |
scripts/scaffold-ux.mjs | Genera propiedades personalizadas CSS ux-contract.css y primitivas de layout React/TypeScript (AppShell.tsx, PageHeader.tsx, PageSection.tsx, DataStateBoundary.tsx) a partir de UX.md | node .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux |
scripts/preview-ux.mjs | Genera un simulador de wireframe interactivo, responsive e independiente ux-preview.html | node .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html |
scripts/diff-ux.mjs | Compara dos archivos UX.md en busca de regresiones de ruta, arquetipo, presupuesto o umbrales | node .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json |
Modos de operación
- Sintetizar (greenfield /
init): Ejecutaextract-ux.mjs+generate-ux.mjspara crear elUX.mdinicial a partir del contexto del proyecto yDESIGN.md, luego personaliza las rutas, arquetipos y reglas de dominio. - Extraer de referencia (producto de referencia o URL): Extrae el shell espacial, las reglas de interacción, los atajos de teclado y los arquetipos de página de un producto de referencia conocido (por ejemplo Linear, ChatGPT Canvas, Stripe Dashboard, Shopify o Supabase).
- Auditar e ingeniería inversa (base de código existente):
Ejecuta
extract-ux.mjspara descubrir rutas existentes (src/app/**,src/pages/**,src/routes/**), detecta desviaciones estructurales y genera unUX.mdunificado. - Evolucionar (adición de funcionalidades / sincronización de rutas):
Actualiza la Sección 3 (Arquetipos de página) y la Sección 4 (Navegación, Grafo de rutas y Persistencia de URL) cada vez que se añadan nuevas páginas o flujos de trabajo, verificando la paridad con
validate-ux.mjs UX.md --check-code.
Pipeline de generación en tres fases
Fase 1: Extracción determinista y clasificación de arquetipos
- Ejecuta
node .agents/skills/ux-md-generator/scripts/extract-ux.mjs .(o inspecciona directamentepackage.json,AGENTS.mdyDESIGN.md) para detectar el runtime objetivo, el límite de autenticación, las rutas existentes y los puntos de corte deDESIGN.md. - Carga resources/archetype-taxonomy.md y confirma:
platform_profile:web-app|mobile-native|desktop-app|terminal-tuiarchetype:b2b-saas-workspace|ai-chat-canvas|analytics-dashboard|ecommerce-storefront|developer-tool
- Opcionalmente, siembra
UX.mdmediante:node .agents/skills/ux-md-generator/scripts/generate-ux.mjs --archetype <archetype> --project "<Nombre del Proyecto>" --output UX.md
Fase 2: Síntesis de 12 secciones específicas del dominio
Carga resources/ux-md-format.md, resources/layout-primitives.md y resources/writing-style-guide.md. Personaliza UX.md en la raíz del repositorio con:
- Frontmatter YAML: Configuración completa (
spec_version: "1.0",shell_budget,z_index_scale,thresholds,layout_primitives). - Secciones
0a11en orden secuencial:## 0. Topología de producto y dominio## 1. Arquitectura espacial y shell de la app(wireframe ASCII y tabla de presupuesto de viewport)## 2. Contrato de scroll, viewport y z-index## 3. Arquetipos de página principales (Planos)(usando encabezados### Archetype: <ID de arquetipo>)## 4. Navegación, grafo de rutas y persistencia en URL(Diagrama Mermaidflowchart LR, tabla de alcanzabilidad de rutas y matriz de persistencia de estado)## 5. Matriz de decisión de superposiciones y feedback(umbrales de número de campos ypx)## 6. Estados de vista obligatorios (Matriz de 4 estados)(Cargando,Vacío,Error,Poblado)## 7. Ergonomía de mutaciones, formularios y permisos(guardiaisDirty, reglas destructivas de 2 niveles, compuertas de permisos de 3 vías)## 8. Estrés de datos reales, densidad y truncamiento(modo único de escalado de listas,min-w-0 truncate, token de celda vacía-,tabular-nums)## 9. Reflujo responsive y coreografía de entrada(orden de colapso, objetivos táctiles>= 44x44pxcon espacio>= 8px, equivalentes táctiles para interacciones hover, padding de scroll en área segura)## 10. Primitivas de layout obligatorias (Contrato de código)(<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>)## 11. Qué hacer, qué no hacer y guía de prompt para el agente
Restricciones de redacción:
- Cero adjetivos vagos: No escribir "formulario pequeño", "diseño limpio", "solicitud lenta" o "navegación intuitiva" sin números explícitos (
<= 4 campos,1280px,>= 150ms). Consulta resources/anti-patterns.md. - Cero callejones sin salida: Cada ruta en la Sección 4 referencia un
<ID de arquetipo>válido de la Sección 3 y define tanto unDisparador de entradacomo unaSalida / Cancelación de respaldo. - Aplicar primitivas de layout: Asegurar que todas las rutas componen las 4 primitivas de layout obligatorias (
<AppShell>,<PageHeader>,<PageSection>,<DataStateBoundary>) definidas en la Sección 10.
Fase 3: Auditoría cruzada y validación automática
- Audita el
UX.mdgenerado contra resources/quality-checklist.md ([UX-01]a[UX-16]). - Ejecuta el script de linter automatizado:
node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code - Resuelve cualquier hallazgo reportado como
errorowarningy vuelve a ejecutar hasta que el validador salga con0 errors.