polish

polish — это self-hosted CLI и MCP-сервер для ревью UI-кода. Он оценивает юзабилити, качество дизайна, доступность и тексты интерфейса по шкале от 0 до 100, с находками на уровне файлов и конкретными исправлениями. Запускайте его локально, подключайте свои API-ключи и держите цикл ревью внутри своего рабочего процесса.

Создан для дизайнеров и инженеров, которые ревьюят реальный UI-код.

Посмотреть вживую: https://tomiabe.github.io/polish/

Зачем

Хостинговые инструменты дизайн-ревью полезны, но они работают по квотам и месячным лимитам. polish держит цикл ревью локальным, используя ваш собственный API-ключ и небольшой Node CLI. Укажите ему ваши UI-файлы — он отправит их в LLM с рубрикой и вернёт оценку плюс находки с серьёзностью, категорией, file:line и конкретным исправлением.

Related MCP server: @gridwork/siteaudit

Возможности

• Ревью по многослойной рубрике: эвристики юзабилити, качество дизайна, тексты интерфейса и доступность. Он проверяет заголовки, описания, подписи и вспомогательный текст наряду с визуальным кодом и кодом взаимодействий. Рубрика — это обычные данные, поэтому её можно заменить на любую дизайн-философию.

• Взвешенная оценка polish. Критические находки вычитают 22, серьёзные — 9, умеренные — 3. Потолка по серьёзности нет.

• Поддержка провайдеров Groq, OpenAI, Anthropic, Gemini и OpenRouter, плюс любой OpenAI-совместимый endpoint через baseUrl.

• Опциональные цепочки фолбэка провайдеров, чтобы перебирать несколько API по порядку.

• Один движок управляет и CLI, и MCP-сервером, поэтому пользователи терминала и AI-агенты получают идентичные результаты.

• polish init-agent создаёт безопасный, локальный для репозитория AGENTS.md, который учит кодинг-агентов, когда ревьюить изменения UI, как распознавать receipt и как проверять исправления.

• Режим verify повторно проверяет предыдущие находки по обновлённым файлам за долю стоимости полного ревью и возвращает новый балл оставшихся проблем.

• Завершается с кодом 1 при наличии критических находок, поэтому работает как pre-commit или CI-гейт.

Установка

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

Задайте один API-ключ в профиле вашей оболочки:

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. Автоопределяется по присутствующему env-ключу.

• 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-эндпоинта для прокси или self-hosted шлюза.

• include / exclude — glob-паттерны с **, *, ? и {a,b}. node_modules и .git пропускаются всегда.

• rubric — какие слои рубрики использовать. usability (базовые эвристики), craft (типографика, цвет, отступы, анимация, компоненты, тексты), accessibility (контраст, клавиатура, семантика, формы, тач-таргеты, reduced motion). Все три включены по умолчанию; выберите подмножество, чтобы сократить расход токенов на больших ревью.

• maxFiles / maxFileBytes — предохранительные лимиты, чтобы большой файл не взорвал бюджет токенов. Каждый запуск печатает оценочное число токенов.

Рубрика и её настройка

Рубрика по умолчанию состоит из трёх слоёв:

• usability — 10 базовых эвристик: видимость статуса системы, соответствие реальному миру, контроль и свобода пользователя, согласованность и стандарты, предотвращение ошибок, узнавание вместо припоминания, гибкость и эффективность, эстетичный и минималистичный дизайн, диагностика и восстановление после ошибок, справка и документация.

• craft — дисциплина дизайн-системы: визуальное мастерство (концентрические радиусы, оптическое выравнивание, никаких магических чисел, никакого типового AI-стиля), цвет и токены, типографика, отступы и раскладка, анимация, композиция компонентов и тексты.

• accessibility — проверяемые требования: контраст, поддержка клавиатуры, семантические элементы, формы, тач-таргеты и reduced motion.

Рубрика — это структура данных. Чтобы заменить её своей философией, поместите массив principles в .polish.json:

{
  "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.

Каждый запуск ревью также выдаёт receipt с polishApplied: true, id запуска, оценкой и просмотренными файлами. В человеческом режиме polish печатает этот receipt перед оценкой. В режиме --json агенты могут читать тот же receipt без парсинга plain-text вывода.

Режим verify

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

Режим verify повторно прогоняет только отмеченные находки по текущему содержимому файлов и сообщает FIXED или STILL PRESENT для каждой. Он также выдаёт свежую оценку на основе оставшихся находок, плюс ту же форму receipt, что и полное ревью. Добавьте --json, чтобы получить оценку verify, receipt и статусы в виде машиночитаемого JSON.

MCP-сервер

polish также работает как MCP-сервер через stdio, так что AI-агенты могут вызывать его как инструменты. Он предоставляет:

• polish_review_files — ревью UI-файлов по содержимому, возвращает оценку, receipt и находки

• polish_verify_fixes — повторная проверка находок по обновлённому содержимому, возвращает новую оценку, receipt и статусы

• polish_usage — статус использования, всегда безлимитный и self-hosted

Зарегистрируйте его в любом 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. Во всех трёх используйте абсолютный путь к node (например /usr/local/bin/node), потому что GUI-приложения не наследуют PATH вашей оболочки, и передавайте API-ключ в окружении сервера, потому что GUI-приложения не загружают профиль вашей оболочки.

Инструкции для агента

После регистрации MCP-сервера запустите polish init-agent из корня проекта. Он создаёт AGENTS.md с циклом ревью для изменений UI. Команда отказывается заменять существующий файл, если не передать --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 прогоняет весь конвейер (конфиг, промпты, вызов LLM, оценку, verify) против мокового OpenAI-совместимого сервера, так что 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) оценили карточное демо 62/100 до и 78/100 после, а демо формы 43/100 до и 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 плотными и аудируйте экраны, которых касается изменение, а не целые репозитории.