MDVP

Análisis del DOM para cualquier URL en vivo, puntuado de 0 a 100 con correcciones concretas.

GitHub
6
Prueba este MCPPatrocinado

Documentación

@mdvp/cli

Linter de diseño para frontends generados por IA. Audita cualquier URL en vivo para verificar la calidad de HTML/CSS, la desviación del sistema de diseño, la estructura relevante para accesibilidad y los patrones comunes de UI generada por IA. Las auditorías predeterminadas se ejecutan localmente a través de la ruta exacta del navegador renderizado, sin clave de API, sin cuenta y sin línea base de capturas de pantalla; los atajos estáticos/de caché requieren MDVP_USE_CACHE=1.

CI npm npm downloads License: MIT

npx @mdvp/cli audit myapp.com

MDVP CLI audit output for mdvp.dev

MDVP ofrece a equipos y agentes una señal determinista de calidad de diseño antes de que una página tenga usuarios, capturas de pantalla o una línea base. Lee el DOM renderizado con getComputedStyle(), mide la disciplina de color/espaciado/tipografía, verifica el contraste APCA y la estructura semántica, y señala patrones comunes de UI generada, como paletas predeterminadas de Tailwind, todo con radio de píldora, chips de héroe genéricos y tokens de diseño faltantes.

Úsalo para:

  • Detectar la deriva de UI generada por vibes antes del merge.
  • Controlar las URLs de vista previa en CI con audit --check.
  • Proporcionar a Cursor, Claude, OpenCode, Windsurf y Cline una herramienta MCP de calidad de diseño.
  • Publicar una insignia de puntuación después de enviar un resultado público.

Pipeline

MDVP scoring pipeline

La auditoría exacta lanza el rastreador del navegador local → extrae métricas del DOM renderizado con getComputedStyle() → 12 categorías se puntúan en 4 componentes → un registro de patrones destaca heurísticas de diseño comunes. Establece MDVP_USE_CACHE=1 solo cuando quieras intencionalmente el atajo aproximado estático/de caché; añade --fast en los scripts para que esa opción sea visible. Consulta Cómo funciona a continuación para el recorrido completo.

Prueba de desarrollo

MDVP es útil cuando le da a un desarrollador un cambio concreto a continuación, no solo una puntuación.

  • Hallazgo dogfood: node cli.mjs audit mdvp.dev produjo B+ 75/100 y señaló un problema accionable: 5 familias de fuentes en la página renderizada donde el límite profesional es 2. La siguiente tarea de ingeniería es clara: consolidar la pila tipográfica del sitio y volver a ejecutar la auditoría.
  • Flujo de trabajo antes/después: el fixture reproducible del sistema de diseño comienza en 95/A+; acumular problemas de UI generada lo reduce a 60/B- con originalidad en 0. Eso se traduce directamente en acciones de desarrollo: reducir familias de fuentes, reemplazar los gradientes púrpura-azul predeterminados de Tailwind, normalizar los radios de píldora, añadir tokens de diseño semánticos y añadir contenido real.
  • Puerta de PR: npx @mdvp/cli init --github-action convierte esas mismas comprobaciones en una puerta de CI de URL de vista previa, de modo que la dispersión de color, la deriva de fuentes, la baja adherencia a la cuadrícula de espaciado y las señales de UI generada prohibidas fallen antes del merge.

Consulta Prueba de desarrollo para el flujo de trabajo concreto y Benchmark para las advertencias de validación.

Por qué

Herramientas como v0, Bolt, Lovable y Cursor generan frontends rápido, pero el resultado suele compartir patrones comunes: Inter como fuente principal, la paleta de gradientes púrpura-azul-rosa predeterminada de Tailwind, cada botón es border-radius: 9999px, más de 40 colores CSS únicos sin sistema. Las herramientas de regresión visual no pueden ayudar cuando no hay una captura de pantalla previa con la que comparar; los linters de código verifican la sintaxis, no la calidad renderizada.

MDVP te da números sobre la estructura de la página y el sistema de diseño. La auditoría predeterminada instrumenta la página renderizada, extrae valores CSS calculados mediante getComputedStyle(), y es el modo adecuado para resultados disputados o evidencia respaldada por capturas de pantalla. El analizador estático sigue disponible como atajo aproximado, pero solo cuando optas explícitamente con MDVP_USE_CACHE=1 --fast.

Inicio rápido

# Score any URL locally with rendered browser evidence
npx @mdvp/cli audit myapp.com

# Check local first-run prerequisites without crawling
npx @mdvp/cli doctor

# Make the default rendered browser path explicit in scripts
npx @mdvp/cli audit myapp.com --exact

# Use the approximate static/cache shortcut only after opting in
MDVP_USE_CACHE=1 npx @mdvp/cli audit myapp.com --fast

# Enforce thresholds in CI — exits 1 on violation
npx @mdvp/cli audit myapp.com --check

# Score a logged-in local or staging page through your own Chrome session
MDVP_BROWSER_URL=http://127.0.0.1:9222 npx @mdvp/cli audit http://localhost:3000/dashboard --json

# Create starter .mdvprc and GitHub Actions workflow
npx @mdvp/cli init --github-action

# Look up a known site from the public dataset (no local crawl)
npx @mdvp/cli audit myapp.com --cloud

# Contribute your local result to the public dataset
npx @mdvp/cli audit myapp.com --swarm

# JSON output for scripting
npx @mdvp/cli audit myapp.com --json | jq .components.css_health

# Compare two saved JSON snapshots
npx @mdvp/cli diff before.json after.json

# Print a README badge for your site
npx @mdvp/cli badge myapp.com

Salida:

myapp.com  C+  58/100  local audit

  css_health      ████████░░░░  48   32 colors · 4 fonts · 61% on grid
  visual_quality  ██████████░░  67
  structure       ████████████  81
  originality     ████░░░░░░░░  38

entropy 0.82 · apca 94.2 · grid 61%
Lowest: originality (38) · color (44) · spacing (51)
  · 32 unique colors. Professional limit: 8–12
  · 4 font families. Professional limit: 2
  · Inter + Tailwind purple-blue palette — common design pattern

Cómo funciona

La auditoría predeterminada usa Puppeteer para el DOM renderizado y la evidencia de estilos calculados, agrupa 12 categorías en cuatro componentes nombrados y usa detectores heurísticos independientes para puntuar patrones comunes de UI generada por IA. El analizador estático en Rust sigue disponible a través de MDVP_USE_CACHE=1 --fast para bucles de bajos recursos, y su salida JSON está marcada como source: "static" con limitaciones. Consulta el artículo de metodología para el algoritmo completo, la tabla de pesos y la comparación con trabajos previos.

Documentación

  • Instalación — requisitos, instalación, primera ejecución, solución de problemas
  • Comandos CLI — cada bandera, cada subcomando, códigos de salida
  • Puntuación — qué miden los cuatro componentes, el registro de señales
  • Catálogo de señales — cada detector de UI generada, superficie de evidencia y ruta de remediación
  • Cumplimiento de DESIGN.md — compara las métricas de la página auditada con tu sistema de diseño
  • Puntuación de páginas autenticadas — prototipo de conector de sesión local de Chrome y modelo de privacidad
  • Aplicación en CI — .mdvprc, GitHub Action, códigos de salida, otros sistemas de CI
  • Contenedores — Alpine, distroless, Apple Container y guía de imágenes exactas/de navegador
  • Binarios independientes — decisión de artefactos de lanzamiento y restricciones de binarios solo estáticos
  • Nix — nix develop, aplicaciones reproducibles de verificación/smoke y notas de NixOS
  • Servidor MCP — conéctalo a Claude, OpenCode, Cursor, Windsurf, Cline
  • Arquitectura — componentes, protocolo de trabajos, autoalojamiento
  • Metodología — artículo completo de puntuación (4 pilares, tabla de pesos)
  • Benchmark — sensibilidad / ablación + panel de referencia en vivo
  • Manual de adopción — ejemplos, posicionamiento y bucles de distribución honestos
  • Desarrollo — configuración, pruebas, añadir una señal, publicar una versión

Añade una insignia de puntuación a tu proyecto

Muestra tu puntuación MDVP en el README de tu proyecto: docs/badge.md. Envía tu sitio y luego genera el markdown de shields.io:

npx @mdvp/cli badge myapp.com

Contribuciones

Informes de errores y solicitudes de funciones: GitHub Issues. Código y detectores de señales: consulta CONTRIBUTING.md. Los nuevos detectores de UI generada deberían comenzar con el catálogo de señales y la guía de desarrollo.

Cómo citar

Si usas MDVP en investigación, cita mediante el botón "Cite this repository" (impulsado por CITATION.cff). Un borrador preliminar de la metodología está en docs/paper.md.

Licencia

MIT. El motor de puntuación local, la CLI, el servidor MCP y la GitHub Action están en este repositorio. La capa de coordinación alojada y el conjunto de datos no forman parte de este paquete de código abierto — consulta docs/architecture.md para el límite.