polish

polish ist ein selbst gehosteter Review-CLI und MCP-Server für UI-Code. Er bewertet Usability, Design-Handwerk, Barrierefreiheit und Interface-Texte von 0-100, mit Befunden auf Dateiebene und konkreten Korrekturen. Führen Sie ihn lokal aus, binden Sie Ihre eigenen API-Schlüssel ein und halten Sie den Review-Zyklus in Ihrem Workflow.

Entwickelt für Designer und Ingenieure, die echten UI-Code überprüfen.

Live ansehen: https://tomiabe.github.io/polish/

Warum

Gehostete Design-Review-Tools sind nützlich, aber sie laufen auf Kontingenten und monatlichen Limits. polish hält den Review-Zyklus lokal, mit Ihrem eigenen API-Schlüssel und einer kleinen Node-CLI. Richten Sie ihn auf Ihre UI-Dateien, er sendet sie an ein LLM mit einer Rubrik und gibt eine Punktzahl plus Befunde mit Schweregrad, Kategorie, Datei:Zeile und einer konkreten Korrektur zurück.

Related MCP server: @gridwork/siteaudit

Funktionen

• Bewertet anhand einer mehrschichtigen Rubrik: Usability-Heuristiken, Design-Handwerk, Interface-Texte und Barrierefreiheit. Es prüft Überschriften, Beschreibungen, Labels und Hilfetexte neben visuellem und Interaktionscode. Die Rubrik ist reine Daten und kann daher gegen jede Designphilosophie ausgetauscht werden.

• Polish-gewichtete Bewertung. Kritische Befunde ziehen 22 Punkte ab, schwerwiegende 9 und moderate 3. Es gibt keine Obergrenze für den Schweregrad.

• Unterstützung für Groq, OpenAI, Anthropic, Gemini und OpenRouter sowie jeden OpenAI-kompatiblen Endpunkt über baseUrl.

• Optionale Provider-Fallback-Ketten, sodass Sie mehrere APIs der Reihe nach ausprobieren können.

• Eine Engine treibt sowohl eine CLI als auch einen MCP-Server an, sodass Terminalnutzer und KI-Agenten identische Ergebnisse erhalten.

• polish init-agent schreibt eine sichere, repo-lokale AGENTS.md, die Codierungsagenten beibringt, wann sie UI-Änderungen überprüfen, wie sie eine Quittung erkennen und wie sie Korrekturen verifizieren.

• Der Verify-Modus prüft frühere Befunde gegen aktualisierte Dateien zu einem Bruchteil der Kosten einer vollständigen Überprüfung und liefert eine neue Punktzahl für verbleibende Probleme.

• Beendet mit Code 1, wenn kritische Befunde vorliegen, und funktioniert so als Pre-Commit- oder CI-Gate.

Installation

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

Legen Sie einen API-Schlüssel in Ihrem Shell-Profil fest:

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

Verwendung

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

Konfiguration

Erstellen Sie .polish.json im Projektstamm. Alles ist optional:

{
  "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 oder gemini. Wird automatisch aus dem vorhandenen Umgebungsschlüssel erkannt.

• providers – geordnete Fallback-Liste. Wenn gesetzt, versucht polish jeden Provider der Reihe nach, bis einer erfolgreich ist.

• model – Standardwerte sind gpt-4o-mini, claude-sonnet-4-20250514, openai/gpt-4o-mini (OpenRouter), llama-3.3-70b-versatile (Groq) und gemini-2.5-flash.

• baseUrl – überschreibt den API-Endpunkt für einen Proxy oder ein selbst gehostetes Gateway.

• include / exclude – Glob-Muster mit **, *, ? und {a,b}. node_modules und .git werden immer übersprungen.

• rubric – welche Rubrik-Ebenen verwendet werden sollen. usability (Kernheuristiken), craft (Typografie, Farbe, Abstände, Bewegung, Komponenten, Texte), accessibility (Kontrast, Tastatur, Semantik, Formulare, Touch-Ziele, reduzierte Bewegung). Alle drei sind standardmäßig aktiviert; wählen Sie eine Teilmenge, um Token-Kosten bei großen Überprüfungen zu senken.

• maxFiles / maxFileBytes – Sicherheitsgrenzen, damit eine große Datei das Token-Budget nicht sprengt. Jeder Lauf gibt die geschätzte Token-Anzahl aus.

Die Rubrik und ihre Anpassung

Die Standard-Rubrik besteht aus drei Ebenen:

• usability – 10 Kernheuristiken: Sichtbarkeit des Systemstatus, Übereinstimmung mit der realen Welt, Benutzerkontrolle und Freiheit, Konsistenz und Standards, Fehlervermeidung, Wiedererkennen statt Erinnern, Flexibilität und Effizienz, ästhetisches und minimalistisches Design, Fehlerdiagnose und -behebung, Hilfe und Dokumentation.

• craft – Designsystem-Disziplin: visuelles Handwerk (konzentrischer Radius, optische Ausrichtung, keine magischen Zahlen, kein generisches KI-Standard-Styling), Farbe und Tokens, Typografie, Abstände und Layout, Bewegung, Komponentenzusammensetzung und Texte.

• accessibility – überprüfbare Anforderungen: Kontrast, Tastaturunterstützung, semantische Elemente, Formulare, Touch-Ziele und reduzierte Bewegung.

Die Rubrik ist eine Datenstruktur. Um sie durch Ihre eigene Philosophie zu ersetzen, fügen Sie ein principles-Array in .polish.json ein:

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

Regeln funktionieren am besten, wenn sie als Dinge formuliert sind, die ein Modell überprüfen kann („Schaltflächen zeigen einen Ladezustand“), nicht als ästhetische Stimmungen.

Bewertung

• Start bei 100. Jeder Befund zieht gemäß den Polish-Gewichten ab: kritisch -22, schwerwiegend -9, moderat -3.

• Die Punktzahl fällt nie unter 0.

Jeder Überprüfungslauf gibt außerdem eine Quittung mit polishApplied: true, einer Lauf-ID, der Punktzahl und den überprüften Dateien aus. Im menschlichen Modus druckt polish diese Quittung vor der Punktzahl. Im --json-Modus können Agenten dieselbe Quittung lesen, ohne die Klartextausgabe zu parsen.

Verify-Modus

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

Der Verify-Modus führt nur die markierten Befunde gegen den aktuellen Dateiinhalt erneut aus und meldet für jeden FIXED oder STILL PRESENT. Er gibt außerdem eine neue Punktzahl basierend auf den verbleibenden Befunden aus, plus dieselbe Quittungsform wie bei einer vollständigen Überprüfung. Fügen Sie --json hinzu, um die Verify-Punktzahl, Quittung und Status als maschinenlesbares JSON zu erhalten.

MCP-Server

polish läuft auch als MCP-Server über stdio, sodass KI-Agenten ihn als Werkzeug aufrufen können. Er stellt bereit:

• polish_review_files – überprüft UI-Dateien anhand des Inhalts, gibt eine Punktzahl, Quittung und Befunde zurück

• polish_verify_fixes – prüft Befunde gegen aktualisierten Inhalt erneut und gibt eine neue Punktzahl, Quittung und Status zurück

• polish_usage – Nutzungsstatus, immer unbegrenzt und selbst gehostet

Registrieren Sie ihn in jedem MCP-fähigen Client. Für opencode in ~/.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 liest ~/Library/Application Support/Claude/claude_desktop_config.json, und Codex liest ~/.codex/config.toml. Verwenden Sie in allen drei den absoluten Pfad zu node (z. B. /usr/local/bin/node), da GUI-Apps Ihre Shell-PATH nicht erben, und übergeben Sie den API-Schlüssel in der Umgebung des Servers, da GUI-Apps Ihr Shell-Profil nicht laden.

Agentenanweisungen

Nach der Registrierung des MCP-Servers führen Sie polish init-agent aus dem Projektstamm aus. Es erstellt AGENTS.md mit einem Überprüfungszyklus für UI-Änderungen. Der Befehl weigert sich, eine vorhandene Datei zu ersetzen, es sei denn, Sie übergeben --force.

Entwicklung

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 führt die vollständige Pipeline (Konfiguration, Prompts, LLM-Aufruf, Bewertung, Verify) gegen einen Mock-OpenAI-kompatiblen Server aus, sodass kein API-Schlüssel erforderlich ist. Es überprüft demo/ProfileCard.before.jsx, eine Komponente mit Barrierefreiheitsblockern und Designsystem-Lecks, dann ihr korrigiertes Gegenstück demo/ProfileCard.after.jsx (plus ihr Stylesheet demo/profile.css) und verifiziert schließlich, dass die Vorher-Befunde im Nachher-Code aufgelöst sind. Der Mock ist deterministisch: Erwarten Sie 39/100 bis 97/100 und 8/8 Befunde behoben.

Mit einem gesetzten API-Schlüssel laufen dieselben Befehle gegen ein Live-Modell, und die Urteile sind real. Aufgezeichnete Live-Läufe auf Groq (llama-3.3-70b-versatile) bewerteten die Karten-Demo mit 62/100 vorher und 78/100 nachher, und die Formular-Demo mit 43/100 vorher und 66/100 nachher. Die Urteile variieren je nach Modell und Lauf, verwenden Sie also einen Live-Lauf, um Ihren eigenen Code zu beurteilen:

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

Dateien

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

Hinweise zu Token-Kosten

polish sendet vollständige, zeilennummerierte Dateiinhalte an das Modell. Die geschätzte Token-Anzahl wird vor jedem Lauf ausgegeben. Halten Sie maxFiles und maxFileBytes eng und prüfen Sie die Bildschirme, die Sie in einer Änderung berühren, anstatt ganze Repositorys.