one-shot-ui

課題

AI エージェントは UI を約 90％まで仕上げますが、そこで行き詰まります。レイアウトは正しく見えても、カードの高さが 8px 高すぎる、パネルのグレーの色合いが違う、影が平坦、間隔が 24px ずれている、といった具合です。「もう一度スクリーンショットを見て修正して」とモデルに頼むのは時間がかかり、回答は毎回異なります。

one-shot-ui は残りの 10％を決定論的に仕上げます。参照スクリーンショットから、レイアウト領域、色、タイポグラフィ、間隔、デザイントークンなどの構造化データを抽出し、実装と比較して、「もっと似せて」ではなく、具体的で優先順位付けされた修正案を返します。

Set width to 616px (currently 640px)
Change the fill color to #303040.
Set box-shadow to -3px 0px 24px 0px rgba(28, 29, 38, 0.32).
gap: 176px; /* currently ~152px */

視覚的な影響度順に並んだ、コピーして貼り付けられる CSS です。上記の例はすべて、以下の実行から得られた実際の出力です。

収束の様子を見る

run コマンドは、ヒートマップが落ち着くまで抽出 → キャプチャ → 比較 → 修正を繰り返します。上の実行例では、エージェントの最初のビルドは見た目には同一でしたが、one-shot-ui は具体的な差分を 15 件（位置、サイズ、色、影、間隔）指摘し、ループによってビルドの**ピクセル不一致率は約 2.5％**まで低下しました。これは、このデザインにおけるツール自身が推定した解消不能な下限（約 2％、サブピクセルのフォントレンダリング）から約 0.5％以内です。

one-shot-ui を選ぶ理由

• 雰囲気ではなく、決定論的です。 ピクセルと構造の差分スコアが安定しており、同じ入力には同じ数値を返すため、「ピクセル単位で十分に近いか？」を基準に CI の実行を制御できます。
• 曖昧な指示ではなく、正確な修正案を提示します。 具体的な CSS（width: 616px、#303040、gap: 176px）を返し、コンポーネントごとにまとめ、視覚的な影響度順に並べます。
• ピクセルだけでなく、構造も比較します。 要素の欠落や余分な要素、位置やサイズのずれ、色、影、間隔、タイポグラフィを検出します。また、エージェントが存在しない差を追いかけないよう、どの差が解消不能（アンチエイリアス、写真コンテンツなど）かを示します。
• スコアを不正に操作できません。 converge は、ピクセルの不一致だけでなく、参照の内容が存在し、正しく配置され、読み取れるかという構造上の忠実度を評価します。さらに、テキストを隠したり、重ねたり、背景色で塗りつぶしたりしてピクセルスコアを上げることを許しません。参照画像内のテキストがビルドでも描画されているのに表示範囲から切れている場合（固定高さの overflow:hidden ボックスなど）も指摘します。これはピクセル差分では、切り取られたテキストによって不一致が減るため、むしろ報われてしまう失敗です。
• エージェントに最適化されています。 AGENTS.md（Claude Code、Cursor、Codex などが自動検出）と Claude Code スキルが含まれており、手取り足取りしなくてもエージェントが操作できます。
• ローカルでプライベートです。 ピクセル差分比較、OCR、レイアウト抽出はすべてお使いのマシン上で実行されます。画像が外部に送信されることも、API キーも必要ありません。

UI の「スタイル」をコピーする。単に一致させるだけではなく

スクリーンショットをピクセル単位で一致させるのも一つの作業です。もう一つは、同じデザインシステムに属しているように感じられる別の画面を作ることです。one-shot-ui は参照画像からデザイン言語を抽出し、新しい UI がそれに準拠しているかを、ピクセルの正解画像に頼らず決定論的に検証します。

# Extract a reusable style system — palette, spacing scale, type ratio, radii, elevation
one-shot-ui tokens reference.png --emit shadcn      # or: tailwind | json

# Build a different screen in that style, then check it conforms
one-shot-ui style-check reference.png ./pricing.html

測定した事実を報告し、好みの判断はエージェントに委ねます。「プライマリ」カラーを指定したり、雰囲気を分類したりはしません。画像からそれらを判断するのはあなたです（あなたはビジョンモデルであり、このツールは正確で幻覚のない目です）。準拠状況は、スクリーンショットから確実に把握できる要素（パレット、間隔のリズム、文字サイズのスケール）に基づいて判定します。一方、角の丸みや浮き上がりはラスター画像から特定できないため、参考情報として示します。

インストール

npm install -g one-shot-ui

ブラウザーが必要なコマンド（capture、run）の場合：

npx playwright install chromium

クイックスタート

# Diff your implementation against a reference and see exactly what's off
one-shot-ui compare reference.png build.png --json --heatmap heatmap.png

# Get copy-paste CSS fixes, ranked by impact
one-shot-ui suggest-fixes reference.png build.png --json

# The step that gets you pixel-perfect: trial fixes in a live browser and keep
# only the ones that provably reduce pixel mismatch — outputs a verified patch,
# a structural fidelity score, and any reference text your build hides or clips
one-shot-ui converge reference.png --impl ./index.html

# Or run the full automated loop until it converges
one-shot-ui run reference.png --impl ./index.html --max-passes 5 --threshold 0.02

すべてのコマンドで、構造化されたエージェント向けの出力を得るために --json を使用できます。

コーディングエージェントで使う

one-shot-ui には、Claude Code、Cursor、Codex などのエージェントツールが自動検出する AGENTS.md と、Claude Code 用の skill/SKILL.md が含まれています。

次のワンライナーでスキルをインストールします。

mkdir -p .claude/skills/one-shot-ui && cp "$(npm root -g)/one-shot-ui/skill/SKILL.md" .claude/skills/one-shot-ui/

MCP サーバーとして使う

one-shot-ui はローカルの MCP サーバーとしても動作するため、MCP 対応のエージェント（Claude Code、Cursor、Cline、Windsurf、VS Code）なら、シェルの連携処理なしで compare、converge、suggest_fixes、extract、tokens、plan、style_check をツールとして呼び出せます。stdio 経由で動作し、ネットワーク呼び出しは行わず、API キーも必要ありません。

claude mcp add one-shot-ui -- npx -y one-shot-ui mcp

または、任意のクライアントの MCP 設定に追加します。

{
  "mcpServers": {
    "one-shot-ui": {
      "command": "npx",
      "args": ["-y", "one-shot-ui", "mcp"]
    }
  }
}

クライアントごとの設定方法とレジストリへの公開については、docs/MCP.md をご覧ください。

コマンド

コマンド	目的	主なフラグ
extract	スクリーンショットをレイアウト、色、テキストのデータに分析します	--json、--no-ocr、--overlay、--fine
compare	2 枚のスクリーンショットのピクセル差分と構造差分を比較します	--json、--heatmap、--dom-diff
tokens	デザイントークンと再利用可能なスタイルシステム（パレット、間隔、文字、角丸）を生成します	--json、--emit shadcn|tailwind|json
style-check	新しい UI が参照画像のデザイン言語に準拠しているか確認します	--json（新しい UI は URL／HTML／スクリーンショット）
plan	実装方針を生成します	--json
capture	URL またはローカル HTML ファイルのスクリーンショットを撮影します	--url、--file、--output
suggest-fixes	差分から Tailwind／CSS の修正案を提案します	--json、--top、--dom-diff、--framework
converge	クローズドループオプティマイザー：ピクセル検証済みの CSS パッチと構造的忠実度スコアを生成し、非表示／クリップされたテキストにフラグを付けます	--impl、--out、--json、--budget-seconds
run	extract→capture→compare→fix の複数パスのループを実行します	--impl、--max-passes、--threshold
benchmark	ベンチマークスイートを実行します	--json、--output

動作の仕組み

1. extract — 参照画像をレイアウト領域に分割し、色とトークンをサンプリングして、テキストを OCR で認識します。
2. capture — 実装（URL またはローカル HTML）のスクリーンショットを、参照画像と一致するビューポートで撮影します。
3. compare — 2 つの画像の位置を合わせ、ピクセルヒートマップと構造差分を計算し、各問題を分類（レイアウト／色／タイポグラフィ／間隔）したうえで、修正可能かどうかを判定します。
4. suggest-fixes — 問題を具体的な優先順位付き CSS 編集案に変換します。

run はこの 4 つすべてをループで連結し、差分が --threshold を下回るまで実行します。

開発

Bun が必要です。

bun install
bun run install:browsers   # Playwright Chromium
bun run typecheck

開発用スクリプトはソースから直接実行できます。

bun run dev:extract -- ./reference.png --json
bun run dev:compare -- ./reference.png ./build.png --json

npm 向けにビルドします。

bun run build

ライセンス

MIT