polish

polish は、UIコードをレビューするためのセルフホスト型CLIおよびMCPサーバーです。ユーザビリティ、デザインの完成度、アクセシビリティ、インターフェースの文章を0〜100点で採点し、ファイル単位の指摘事項と具体的な修正案を提示します。ローカルで実行し、独自のAPIキーを設定して、レビューループをワークフロー内に留めることができます。

実際のUIコードをレビューするデザイナーとエンジニアのために作られました。

実際の動作はこちら: https://tomiabe.github.io/polish/

なぜ作ったか

ホスト型のデザインレビューツールは便利ですが、クォータや月間制限に縛られます。polish は、独自のAPIキーと小さなNode CLIを使ってレビューループをローカルに保ちます。UIファイルを指定すると、ルーブリックとともにLLMに送信し、スコアと、重大度・カテゴリ・ファイル:行・具体的な修正案を含む指摘事項を返します。

Related MCP server: @gridwork/siteaudit

特徴

• 階層化されたルーブリックに基づいてレビューします: ユーザビリティヒューリスティクス、デザインの完成度、インターフェースの文章、アクセシビリティ。見出し、説明文、ラベル、ヘルパーテキストを、ビジュアルおよびインタラクションコードとともにチェックします。ルーブリックはプレーンなデータなので、任意のデザイン思想に置き換えられます。

• polish の重み付けスコアリング。重大な指摘は22点減点、深刻な指摘は9点減点、中程度の指摘は3点減点です。重大度に上限はありません。

• Groq、OpenAI、Anthropic、Gemini、OpenRouter のプロバイダーに対応し、baseUrl による OpenAI 互換エンドポイントにも対応しています。

• オプションのプロバイダーフォールバックチェーンにより、複数のAPIを順番に試せます。

• 1つのエンジンがCLIとMCPサーバーの両方を駆動するため、ターミナルユーザーとAIエージェントは同一の結果を得られます。

• polish init-agent は、リポジトリローカルな安全な AGENTS.md を書き出し、コーディングエージェントにUI変更をいつレビューすべきか、レシートの認識方法、修正の検証方法を教えます。

• 検証モードは、以前の指摘事項を更新されたファイルに対して再チェックし、フルレビューの数分の一のコストで、残存問題の新しいスコアを返します。

• 重大な指摘がある場合は終了コード1で終了するため、pre-commit や CI ゲートとして機能します。

インストール

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

シェルプロファイルにAPIキーを1つ設定します:

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

使い方

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

設定

プロジェクトルートに .polish.json を作成します。すべてオプションです:

{
  "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、gemini のいずれか。存在する環境変数キーから自動検出されます。

• providers - 順序付きフォールバックリスト。設定すると、polish は各プロバイダーを順番に、成功するまで試します。

• model - デフォルトは gpt-4o-mini、claude-sonnet-4-20250514、openai/gpt-4o-mini（OpenRouter）、llama-3.3-70b-versatile（Groq）、gemini-2.5-flash です。

• baseUrl - プロキシやセルフホスト型ゲートウェイ用にAPIエンドポイントを上書きします。

• include / exclude - **、*、?、{a,b} を使用したグロブパターン。node_modules と .git は常にスキップされます。

• rubric - 使用するルーブリックレイヤー。usability（コアヒューリスティクス）、craft（タイポグラフィ、色、スペーシング、モーション、コンポーネント、文章）、accessibility（コントラスト、キーボード、セマンティクス、フォーム、タッチターゲット、モーション削減）。3つすべてがデフォルトでオンです。大規模なレビューでトークンコストを削減するには、サブセットを選択します。

• maxFiles / maxFileBytes - 大きなファイルがトークン予算を超えないようにする安全上限。実行のたびに推定トークン数が表示されます。

ルーブリックとその調整

デフォルトのルーブリックは3つのレイヤーで構成されています:

• usability - 10のコアヒューリスティクス: システム状態の可視性、実世界との一致、ユーザーの制御と自由、一貫性と標準、エラー防止、認識よりも想起、柔軟性と効率性、美的でミニマルなデザイン、エラーの診断と回復、ヘルプとドキュメント。

• craft - デザインシステムの規律: ビジュアルクラフト（同心円状の半径、光学的整列、マジックナンバーなし、一般的なAIデフォルトスタイルなし）、色とトークン、タイポグラフィ、スペーシングとレイアウト、モーション、コンポーネント構成、文章。

• accessibility - 検証可能な要件: コントラスト、キーボードサポート、セマンティック要素、フォーム、タッチターゲット、モーション削減。

ルーブリックはデータ構造です。独自の思想に置き換えるには、.polish.json に principles 配列を置きます:

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

ルールは、「ボタンはローディング状態を表示する」のようにモデルがチェックできる文言にするのが最も効果的で、「美的な雰囲気」のような表現は避けるべきです。

スコアリング

• 100点から開始します。各指摘は polish の重みに従って減点されます: 重大 -22、深刻 -9、中程度 -3。

• スコアは0を下回ることはありません。

すべてのレビュー実行は、polishApplied: true、実行ID、スコア、レビュー対象ファイルを含むレシートも出力します。人間向けモードでは、polish はスコアの前にそのレシートを表示します。--json モードでは、エージェントはプレーンテキスト出力を解析せずに同じレシートを読めます。

検証モード

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

検証モードは、フラグが立てられた指摘事項のみを現在のファイル内容に対して再実行し、それぞれについて FIXED または STILL PRESENT を報告します。 また、残存する指摘事項に基づく新しいスコアと、フルレビューと同じ形式のレシートも出力します。 --json を追加すると、検証スコア、レシート、ステータスを機械可読なJSONとして取得できます。

MCPサーバー

polish は stdio 上のMCPサーバーとしても動作するため、AIエージェントがツールとして呼び出せます。公開するツール:

• polish_review_files - コンテンツでUIファイルをレビューし、スコア、レシート、指摘事項を返します

• polish_verify_fixes - 更新されたコンテンツに対して指摘事項を再チェックし、新しいスコア、レシート、ステータスを返します

• polish_usage - 使用状況。常に無制限でセルフホスト型です

MCP対応クライアントに登録します。opencode の場合、~/.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 は ~/Library/Application Support/Claude/claude_desktop_config.json を読み、Codex は ~/.codex/config.toml を読みます。3つすべてで、node の絶対パス（例: /usr/local/bin/node）を使用してください。GUIアプリはシェルのPATHを継承しないためです。また、GUIアプリはシェルプロファイルを読み込まないため、サーバーの環境変数でAPIキーを渡してください。

エージェント向け手順

MCPサーバーを登録したら、プロジェクトルートで polish init-agent を実行します。UI変更のレビューループを含む AGENTS.md を作成します。このコマンドは、--force を渡さない限り既存ファイルの置き換えを拒否します。

開発

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

デモ

node scripts/demo.mjs は、モックのOpenAI互換サーバーに対して完全なパイプライン（設定、プロンプト、LLM呼び出し、スコアリング、検証）を実行するため、APIキーは不要です。アクセシビリティのブロッカーとデザインシステムの漏れがあるコンポーネント demo/ProfileCard.before.jsx をレビューし、次にその修正版 demo/ProfileCard.after.jsx（およびそのスタイルシート demo/profile.css）をレビューし、最後に before の指摘事項が after のコードで解決されていることを検証します。モックは決定的です: 39/100 から 97/100 へのスコアと 8/8 件の指摘が修正済み を期待できます。

APIキーを設定すると、同じコマンドがライブモデルに対して実行され、判定は本物になります。Groq（llama-3.3-70b-versatile）での記録済みライブランでは、カードデモは before が 62/100、after が 78/100、フォームデモは before が 43/100、after が 66/100 でした。判定はモデルと実行ごとに異なるため、自分のコードを判断するにはライブランを使用してください:

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

ファイル

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

トークンコストに関する注意

polish は行番号付きの完全なファイル内容をモデルに送信します。推定トークン数は各実行前に表示されます。maxFiles と maxFileBytes は厳しめに設定し、リポジトリ全体ではなく、変更で触れる画面を監査対象にしてください。