polish

polish es una CLI de revisión autoalojada y un servidor MCP para código de UI. Puntúa usabilidad, oficio de diseño, accesibilidad y redacción de interfaz de 0 a 100, con hallazgos a nivel de archivo y correcciones concretas. Ejecútalo localmente, conecta tus propias claves de API y mantén el bucle de revisión dentro de tu flujo de trabajo.

Diseñado para diseñadores e ingenieros que revisan código de UI real.

Vívelo en: https://tomiabe.github.io/polish/

Por qué

Las herramientas de revisión de diseño alojadas son útiles, pero funcionan con cuotas y límites mensuales. polish mantiene el bucle de revisión local, usando tu propia clave de API y una pequeña CLI de Node. Apúntalo a tus archivos de UI, los envía a un LLM con una rúbrica, y devuelve una puntuación más hallazgos con severidad, categoría, archivo:línea y una corrección concreta.

Related MCP server: @gridwork/siteaudit

Características

• Revisa con una rúbrica en capas: heurísticas de usabilidad, oficio de diseño, redacción de interfaz y accesibilidad. Comprueba encabezados, descripciones, etiquetas y texto de ayuda junto con el código visual y de interacción. La rúbrica son datos simples, por lo que se puede intercambiar por cualquier filosofía de diseño.

• Puntuación ponderada de Polish. Los hallazgos críticos restan 22, los graves restan 9 y los moderados restan 3. No hay límite de gravedad.

• Soporte de proveedores para Groq, OpenAI, Anthropic, Gemini y OpenRouter, además de cualquier endpoint compatible con OpenAI mediante baseUrl.

• Cadenas de respaldo de proveedores opcionales, para que puedas probar varias API en orden.

• Un solo motor impulsa tanto una CLI como un servidor MCP, por lo que los usuarios de terminal y los agentes de IA obtienen resultados idénticos.

• polish init-agent escribe un AGENTS.md seguro y local al repositorio que enseña a los agentes de codificación cuándo revisar cambios de UI, cómo reconocer un recibo y cómo verificar correcciones.

• El modo de verificación vuelve a comprobar los hallazgos anteriores contra los archivos actualizados a una fracción del costo de una revisión completa y devuelve una nueva puntuación de problemas restantes.

• Sale con código 1 cuando existen hallazgos críticos, por lo que funciona como puerta de pre-commit o CI.

Instalación

git clone https://github.com/tomiabe/polish.git
cd polish
npm link          # makes `polish` available in every project

Configura una clave de API en tu perfil de shell:

export GROQ_API_KEY=...        # or:
export OPENAI_API_KEY=...      # or:
export ANTHROPIC_API_KEY=...   # or:
export GEMINI_API_KEY=...      # or:
export OPENROUTER_API_KEY=...

Uso

polish                                   # audit files matched by config globs
polish src/components src/pages/*.tsx    # audit specific files or directories
polish --verify findings.json           # re-check that previous findings are fixed
polish --dry-run                        # preview what would be sent, no API call
polish --json                           # machine-readable receipt + findings, for CI or agents
polish init-agent                       # add the Polish workflow to AGENTS.md

Configuración

Crea .polish.json en la raíz de un proyecto. Todo es opcional:

{
  "provider": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "providers": ["gemini", "groq"],
  "include": ["src/**/*.{ts,tsx,css}"],
  "exclude": ["src/generated/**"],
  "rubric": ["usability", "craft", "accessibility"],
  "maxFiles": 20,
  "maxFileBytes": 100000
}

• provider - openai, anthropic, openrouter, groq o gemini. Se detecta automáticamente a partir de la clave de entorno presente.

• providers - lista de respaldo ordenada. Si se establece, polish prueba cada proveedor en orden hasta que uno tenga éxito.

• model - los valores predeterminados son gpt-4o-mini, claude-sonnet-4-20250514, openai/gpt-4o-mini (OpenRouter), llama-3.3-70b-versatile (Groq) y gemini-2.5-flash.

• baseUrl - anula el endpoint de la API, para un proxy o una puerta de enlace autoalojada.

• include / exclude - patrones glob que usan **, *, ? y {a,b}. node_modules y .git siempre se omiten.

• rubric - qué capas de rúbrica usar. usability (heurísticas principales), craft (tipografía, color, espaciado, movimiento, componentes, redacción), accessibility (contraste, teclado, semántica, formularios, objetivos táctiles, movimiento reducido). Las tres están activadas por defecto; elige un subconjunto para reducir el costo de tokens en revisiones grandes.

• maxFiles / maxFileBytes - límites de seguridad para que un archivo grande no reviente el presupuesto de tokens. Cada ejecución imprime su recuento estimado de tokens.

La rúbrica y cómo adaptarla

La rúbrica predeterminada tiene tres capas:

• usability - 10 heurísticas principales: visibilidad del estado del sistema, coincidencia con el mundo real, control y libertad del usuario, consistencia y estándares, prevención de errores, reconocimiento en lugar de recuerdo, flexibilidad y eficiencia, diseño estético y minimalista, diagnóstico y recuperación de errores, ayuda y documentación.

• craft - disciplina del sistema de diseño: oficio visual (radio concéntrico, alineación óptica, sin números mágicos, sin estilo genérico por defecto de IA), color y tokens, tipografía, espaciado y maquetación, movimiento, composición de componentes y redacción.

• accessibility - requisitos comprobables: contraste, soporte de teclado, elementos semánticos, formularios, objetivos táctiles y movimiento reducido.

La rúbrica es una estructura de datos. Para reemplazarla con tu propia filosofía, pon un array principles en .polish.json:

{
  "principles": [
    {
      "id": "D1",
      "name": "Your design principles",
      "rules": [
        "A concrete rule the model can verify in code",
        "Another concrete rule"
      ]
    }
  ]
}

Las reglas funcionan mejor cuando están redactadas como cosas que un modelo puede comprobar ("los botones muestran un estado de carga"), no como vibraciones estéticas.

Puntuación

• Comienza en 100. Cada hallazgo resta según los pesos de Polish: crítico -22, grave -9, moderado -3.

• La puntuación nunca baja de 0.

Cada ejecución de revisión también emite un recibo con polishApplied: true, un id de ejecución, la puntuación y los archivos revisados. En modo humano, polish imprime ese recibo antes de la puntuación. En modo --json, los agentes pueden leer el mismo recibo sin analizar la salida de texto plano.

Modo de verificación

polish > findings.json
# fix the issues
polish --verify findings.json

El modo de verificación vuelve a ejecutar solo los hallazgos marcados contra el contenido actual de los archivos e informa FIXED o STILL PRESENT para cada uno. También emite una puntuación nueva basada en los hallazgos que quedan, además de la misma forma de recibo que una revisión completa. Añade --json para obtener la puntuación de verificación, el recibo y los estados como JSON legible por máquina.

Servidor MCP

polish también se ejecuta como servidor MCP sobre stdio, para que los agentes de IA puedan llamarlo como herramientas. Expone:

• polish_review_files - revisa archivos de UI por contenido, devuelve una puntuación, recibo y hallazgos

• polish_verify_fixes - vuelve a comprobar los hallazgos contra el contenido actualizado, devolviendo una nueva puntuación, recibo y estados

• polish_usage - estado de uso, siempre ilimitado y autoalojado

Regístralo en cualquier cliente compatible con MCP. Para opencode, en ~/.config/opencode/opencode.json:

{
  "mcp": {
    "polish": {
      "type": "local",
      "command": ["node", "/absolute/path/to/polish/mcp-server.js"],
      "enabled": true,
      "environment": {
        "GROQ_API_KEY": "your-key"
      }
    }
  }
}

Claude Desktop lee ~/Library/Application Support/Claude/claude_desktop_config.json, y Codex lee ~/.codex/config.toml. En los tres, usa la ruta absoluta a node (por ejemplo /usr/local/bin/node) porque las aplicaciones GUI no heredan tu PATH de shell, y pasa la clave de API en el entorno del servidor porque las aplicaciones GUI no cargan tu perfil de shell.

Instrucciones para agentes

Después de registrar el servidor MCP, ejecuta polish init-agent desde la raíz del proyecto. Crea AGENTS.md con un bucle de revisión para cambios de UI. El comando se niega a reemplazar un archivo existente a menos que pases --force.

Desarrollo

npm test          # node --test: unit tests plus a mock-server end-to-end test
node scripts/demo.mjs            # before/after demo, no API key needed
node scripts/mcp-handshake.mjs   # manual MCP handshake test

Demo

node scripts/demo.mjs ejecuta el pipeline completo (config, prompts, llamada LLM, puntuación, verificación) contra un servidor simulado compatible con OpenAI, por lo que no se necesita clave de API. Revisa demo/ProfileCard.before.jsx, un componente con bloqueadores de accesibilidad y fugas del sistema de diseño, luego su gemelo corregido demo/ProfileCard.after.jsx (más su hoja de estilos demo/profile.css), y finalmente verifica que los hallazgos anteriores están resueltos en el código posterior. El simulacro es determinista: espera 39/100 a 97/100 y 8/8 hallazgos corregidos.

Con una clave de API configurada, los mismos comandos se ejecutan contra un modelo en vivo, y los veredictos son reales. Ejecuciones en vivo registradas en Groq (llama-3.3-70b-versatile) puntuaron la demo de tarjeta 62/100 antes y 78/100 después, y la demo de formulario 43/100 antes y 66/100 después. Los veredictos varían según el modelo y la ejecución, así que usa una ejecución en vivo para juzgar tu propio código:

polish demo/ProfileCard.before.jsx
polish demo/ProfileCard.after.jsx demo/profile.css
polish demo/SettingsForm.before.jsx
polish demo/SettingsForm.after.jsx demo/settings-form.css

Archivos

bin/polish.js        CLI entry, output rendering, exit codes
mcp-server.js        MCP server (stdio) wrapping the review engine
lib/rubric.js        default rubric layers (usability, craft, accessibility), swap for your own
lib/config.js        config loading, glob expansion, defaults
lib/llm.js           LLM provider callers and JSON extraction
lib/prompt.js        review and verify prompt builders
lib/review.js        shared review and verify engine, used by CLI and MCP
lib/agent.js         repo-local instructions for coding agents
lib/scoring.js       weighted scoring and summaries
demo/                before/after demo components (ProfileCard, SettingsForm)
test/                unit and integration tests
scripts/             manual test scripts

Notas sobre el costo de tokens

polish envía el contenido completo de los archivos con números de línea al modelo. El recuento estimado de tokens se imprime antes de cada ejecución. Mantén maxFiles y maxFileBytes ajustados, y audita las pantallas que tocas en un cambio en lugar de repositorios completos.