MDVP

Análise de DOM para qualquer URL ativa, pontuada de 0 a 100 com correções concretas.

GitHub
6
Experimente este MCPPatrocinado

Documentação

@mdvp/cli

Linter de design para frontends gerados por IA. Audite qualquer URL ativa quanto à qualidade de HTML/CSS, desvios do design system, estrutura relevante para acessibilidade e padrões comuns de UI de IA. As auditorias padrão são executadas localmente pelo caminho exato do navegador renderizado, sem chave de API, sem conta e sem linha de base de capturas de tela; atalhos estáticos/de cache exigem MDVP_USE_CACHE=1.

CI npm npm downloads License: MIT

npx @mdvp/cli audit myapp.com

MDVP CLI audit output for mdvp.dev

O MDVP oferece a equipes e agentes um sinal determinístico de qualidade de design antes que uma página tenha usuários, capturas de tela ou uma linha de base. Ele lê o DOM renderizado com getComputedStyle(), mede a disciplina de cor/espaçamento/tipografia, verifica contraste APCA e estrutura semântica, e sinaliza padrões comuns de UI gerada, como paletas padrão do Tailwind, raio de pílula em tudo, chips genéricos de hero e tokens de design ausentes.

Use-o para:

  • Detectar desvios de UI "vibe-coded" antes do merge.
  • Bloquear URLs de preview na CI com audit --check.
  • Dar ao Cursor, Claude, OpenCode, Windsurf e Cline uma ferramenta MCP de qualidade de design.
  • Publicar um selo de pontuação após enviar um resultado público.

Pipeline

MDVP scoring pipeline

A auditoria exata inicia o crawler local do navegador → extrai métricas do DOM renderizado com getComputedStyle() → 12 categorias pontuam em 4 componentes → um registro de padrões destaca heurísticas comuns de design. Defina MDVP_USE_CACHE=1 somente quando você quiser intencionalmente o atalho aproximado estático/de cache; adicione --fast em scripts para tornar esse opt-in visível. Veja Como funciona abaixo para o passo a passo completo.

Prova de Desenvolvimento

O MDVP é útil quando dá ao desenvolvedor uma próxima mudança concreta, não apenas uma pontuação.

  • Descoberta dogfood: node cli.mjs audit mdvp.dev produziu B+ 75/100 e sinalizou um problema acionável: 5 famílias de fontes na página renderizada, onde o limite profissional é 2. A próxima tarefa de engenharia é clara: consolidar a pilha tipográfica do site e reexecutar a auditoria.
  • Fluxo antes/depois: o fixture reproduzível do design system começa em 95/A+; empilhar problemas de UI gerada o reduz para 60/B- com originalidade em 0. Isso se traduz diretamente em ações de desenvolvimento: reduzir famílias de fontes, substituir gradientes roxo-azul padrão do Tailwind, normalizar raios de pílula, adicionar tokens de design semânticos e adicionar conteúdo real.
  • Portão de PR: npx @mdvp/cli init --github-action transforma essas mesmas verificações em um portão de CI para URLs de preview, de modo que proliferação de cores, desvio de fontes, baixa aderência à grade de espaçamento e sinais proibidos de UI gerada falhem antes do merge.

Veja Prova de desenvolvimento para o fluxo de trabalho concreto e Benchmark para as ressalvas de validação.

Por quê

Ferramentas como v0, Bolt, Lovable e Cursor geram frontends rapidamente — mas a saída frequentemente compartilha padrões comuns: Inter como fonte primária, a paleta de gradiente roxo-azul-rosa padrão do Tailwind, todo botão é border-radius: 9999px, 40+ cores CSS únicas sem sistema. Ferramentas de regressão visual não ajudam quando não há captura de tela anterior para comparar; linters de código verificam sintaxe, não qualidade renderizada.

O MDVP fornece números sobre a estrutura da página e o design system. A auditoria padrão instrumenta a página renderizada, extrai valores CSS computados via getComputedStyle() e é o modo certo para resultados contestados ou evidências baseadas em capturas de tela. O analisador estático ainda está disponível como um atalho aproximado, mas somente quando você opta explicitamente com MDVP_USE_CACHE=1 --fast.

Início 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

Saída:

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

Como funciona

A auditoria padrão usa Puppeteer para o DOM renderizado e evidências de estilo computado, agrupa 12 categorias em quatro componentes nomeados e usa detectores heurísticos independentes para pontuar padrões comuns de UI gerada por IA. O analisador estático em Rust permanece disponível via MDVP_USE_CACHE=1 --fast para loops de baixo consumo de recursos, e sua saída JSON é marcada como source: "static" com limitações. Veja o artigo de metodologia para o algoritmo completo, a tabela de pesos e a comparação com trabalhos anteriores.

Documentação

  • Instalação — requisitos, instalação, primeira execução, solução de problemas
  • Comandos da CLI — todas as flags, todos os subcomandos, códigos de saída
  • Pontuação — o que os quatro componentes medem, o registro de sinais
  • Catálogo de sinais — cada detector de UI gerada, superfície de evidência e caminho de remediação
  • Conformidade com DESIGN.md — compare métricas de página auditadas com seu design system
  • Pontuação de páginas autenticadas — protótipo do conector de sessão Chrome local e modelo de privacidade
  • Aplicação na CI — .mdvprc, GitHub Action, códigos de saída, outros sistemas de CI
  • Containers — Alpine, distroless, Apple Container e orientação para imagens exatas/de navegador
  • Binários autônomos — decisão de artefato de release e restrições de binários somente estáticos
  • Nix — nix develop, apps reproduzíveis de verify/smoke e notas sobre NixOS
  • Servidor MCP — conecte-se ao Claude, OpenCode, Cursor, Windsurf, Cline
  • Arquitetura — componentes, protocolo de jobs, self-hosting
  • Metodologia — artigo completo de pontuação (4 pilares, tabela de pesos)
  • Benchmark — sensibilidade / ablação + painel de referência ao vivo
  • Playbook de adoção — exemplos, posicionamento e loops honestos de distribuição
  • Desenvolvimento — configuração, testes, adicionar um sinal, cortar um release

Adicione um selo de pontuação ao seu projeto

Mostre sua pontuação MDVP no README do seu projeto: docs/badge.md. Envie seu site e depois gere o markdown do shields.io:

npx @mdvp/cli badge myapp.com

Contribuindo

Relatórios de bugs e solicitações de recursos: GitHub Issues. Código e detectores de sinais: veja CONTRIBUTING.md. Novos detectores de UI gerada devem começar pelo catálogo de sinais e pelo guia de desenvolvimento.

Citação

Se você usar o MDVP em pesquisa, cite pelo botão "Cite this repository" (alimentado por CITATION.cff). Um rascunho preprint da metodologia está em docs/paper.md.

Licença

MIT. O mecanismo local de pontuação, a CLI, o servidor MCP e a GitHub Action estão neste repositório. A camada de coordenação hospedada e o conjunto de dados não fazem parte deste pacote de código aberto — veja docs/architecture.md para o limite.