Communitygithub.com

ux-md-generator

Genera, extrae, audita, previsualiza, compara y valida especificaciones UX.md v1 de estructura UI/UX. Define el esqueleto de la aplicación (shell de la app, presupuesto espacial, propiedad del scroll y z-index, arquetipos de página, grafo de alcanzabilidad de rutas, persistencia de estado en URL, matriz de decisión de superposiciones, contrato de 4 estados de vista, ergonomía de formularios y mutaciones, y primitivas de diseño obligatorias) como compañero estructural de DESIGN.md y AGENTS.md. Úsalo al inicializar un proyecto frontend/UI, extraer patrones UX de un producto de referencia, auditar una base de código existente por desviación de diseño, o añadir nuevas rutas y vistas.

¿Qué es ux-md-generator?

El skill **ux-md-generator** es una herramienta profesional para ingenieros de UI y agentes de IA (como Claude Code, Cursor, Codex) que centraliza y estandariza la especificación estructural de una aplicación frontend en un único archivo `UX.md` v1. A diferencia de `DESIGN.md` (que define tokens visuales), `UX.md` captura el esqueleto de la interfaz: el shell de la app, el presupuesto espacial (anchos, altos), la propiedad del scroll y z-index, los arquetipos de página, el grafo de navegación con persistencia de estado en URL, la matriz de decisión de overlays (modal vs drawer), el contrato de 4 estados obligatorios (carga, vacío, error, poblado), y las primitivas de layout (`AppShell`, `PageHeader`, `PageSection`, `DataStateBoundary`). Soporta cuatro modos de operación: síntesis desde cero (greenfield), extracción desde un producto de referencia, auditoría inversa de una base de código existente, y evolución incremental al añadir rutas y vistas. El skill viene con seis scripts Node.js sin dependencias externas que realizan extracción, generación, validación (16 reglas), scaffolding de componentes React/TypeScript, previsualización interactiva en HTML, y diff entre versiones. Está diseñado para eliminar la deriva entre sesiones de agentes de IA, asegurando consistencia en layouts, estados, rutas y comportamientos mediante un pipeline de tres fases y una taxonomía de arquetipos predefinida.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/SolidStateNetwork/ux.md/tree/main/skills/ux-md-generator

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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

ScriptPropósitoEjemplo de uso
scripts/extract-ux.mjsEscanea package.json, AGENTS.md, DESIGN.md y las rutas fuente (src/app, src/pages) para producir JSON estructuradonode .agents/skills/ux-md-generator/scripts/extract-ux.mjs . --output ux-scan.json
scripts/generate-ux.mjsCrea un UX.md de 12 secciones a partir de un arquetipo, un preset de producto (--preset linear) o ux-scan.jsonnode .agents/skills/ux-md-generator/scripts/generate-ux.mjs --preset linear --project "Acme" --output UX.md
scripts/validate-ux.mjsEjecuta 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.mjsGenera propiedades personalizadas CSS ux-contract.css y primitivas de layout React/TypeScript (AppShell.tsx, PageHeader.tsx, PageSection.tsx, DataStateBoundary.tsx) a partir de UX.mdnode .agents/skills/ux-md-generator/scripts/scaffold-ux.mjs UX.md --out-dir src/components/ux
scripts/preview-ux.mjsGenera un simulador de wireframe interactivo, responsive e independiente ux-preview.htmlnode .agents/skills/ux-md-generator/scripts/preview-ux.mjs UX.md --output ux-preview.html
scripts/diff-ux.mjsCompara dos archivos UX.md en busca de regresiones de ruta, arquetipo, presupuesto o umbralesnode .agents/skills/ux-md-generator/scripts/diff-ux.mjs UX.old.md UX.md --json

Modos de operación

  1. Sintetizar (greenfield / init): Ejecuta extract-ux.mjs + generate-ux.mjs para crear el UX.md inicial a partir del contexto del proyecto y DESIGN.md, luego personaliza las rutas, arquetipos y reglas de dominio.
  2. 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).
  3. Auditar e ingeniería inversa (base de código existente): Ejecuta extract-ux.mjs para descubrir rutas existentes (src/app/**, src/pages/**, src/routes/**), detecta desviaciones estructurales y genera un UX.md unificado.
  4. 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

  1. Ejecuta node .agents/skills/ux-md-generator/scripts/extract-ux.mjs . (o inspecciona directamente package.json, AGENTS.md y DESIGN.md) para detectar el runtime objetivo, el límite de autenticación, las rutas existentes y los puntos de corte de DESIGN.md.
  2. Carga resources/archetype-taxonomy.md y confirma:
    • platform_profile: web-app | mobile-native | desktop-app | terminal-tui
    • archetype: b2b-saas-workspace | ai-chat-canvas | analytics-dashboard | ecommerce-storefront | developer-tool
  3. Opcionalmente, siembra UX.md mediante:
    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 0 a 11 en 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 Mermaid flowchart 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 y px)
    • ## 6. Estados de vista obligatorios (Matriz de 4 estados) (Cargando, Vacío, Error, Poblado)
    • ## 7. Ergonomía de mutaciones, formularios y permisos (guardia isDirty, 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 >= 44x44px con 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 un Disparador de entrada como una Salida / 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

  1. Audita el UX.md generado contra resources/quality-checklist.md ([UX-01] a [UX-16]).
  2. Ejecuta el script de linter automatizado:
    node .agents/skills/ux-md-generator/scripts/validate-ux.mjs UX.md --strict --check-code
    
  3. Resuelve cualquier hallazgo reportado como error o warning y vuelve a ejecutar hasta que el validador salga con 0 errors.

Skills relacionados