{
  "markdown": "<div align=\"center\">\n\n# one-shot-ui\n\n### Catch what the eye can't.\n\n**Deterministic screenshot diffing for AI coding agents.**\nTurn a reference screenshot into structured data, diff any build against it — pixel, layout, color, and type — then get the exact CSS to fix. Or copy a UI's **design language** onto a brand-new screen.\n\n[![npm version](https://img.shields.io/npm/v/one-shot-ui?color=8b7cf6&label=npm)](https://www.npmjs.com/package/one-shot-ui)\n[![license](https://img.shields.io/npm/l/one-shot-ui?color=8b7cf6)](./LICENSE)\n[![node](https://img.shields.io/node/v/one-shot-ui?color=8b7cf6)](https://www.npmjs.com/package/one-shot-ui)\n\n<img src=\"https://raw.githubusercontent.com/TN0123/one-shot-ui/main/assets/hero.png\" alt=\"one-shot-ui diffs an agent's build against the reference screenshot and flags the exact deltas\" width=\"100%\">\n\n</div>\n\n## The problem\n\nAI agents get UI **~90% of the way there** — then stall. The layout looks right, but a card is 8px too tall, a panel is the wrong shade of gray, a shadow is flat, a gap is off by 24px. Asking the model to \"look at the screenshot again and fix it\" is slow, and you get a different answer every time.\n\n`one-shot-ui` closes that last 10% **deterministically**. It extracts structured data from a reference screenshot — layout regions, colors, typography, spacing, design tokens — diffs your implementation against it, and returns **specific, ranked fixes**, not \"make it look more like this.\"\n\n```\nSet width to 616px (currently 640px)\nChange the fill color to #303040.\nSet box-shadow to -3px 0px 24px 0px rgba(28, 29, 38, 0.32).\ngap: 176px; /* currently ~152px */\n```\n\n> Copy-paste CSS, ranked by visual impact — every example above is real output from the run below.\n\n## Watch it converge\n\n<div align=\"center\">\n<img src=\"https://raw.githubusercontent.com/TN0123/one-shot-ui/main/assets/converge.gif\" alt=\"The one-shot-ui run loop: the diff heatmap goes from ablaze to quiet across passes\" width=\"100%\">\n</div>\n\nThe `run` command loops **extract → capture → compare → fix** until the heatmap goes quiet. In the run above, the agent's first build looked identical to the eye — `one-shot-ui` flagged **15 concrete deltas** (position, size, color, shadow, spacing) and the loop drove the build to **~2.5% pixel mismatch**, within ~0.5% of the tool's own estimated *irreducible* floor (≈2%, sub-pixel font rendering) for this design.\n\n## Why one-shot-ui\n\n- **Deterministic, not vibes.** Stable pixel + structural diff scores — same input, same numbers — so you can gate CI on \"is this pixel-close enough?\"\n- **Exact fixes, not nudges.** It returns concrete CSS (`width: 616px`, `#303040`, `gap: 176px`), grouped by component and ranked by visual impact.\n- **Structural, not just pixels.** Detects missing/extra elements, position & size shifts, color, shadow, spacing, and typography — and labels which differences are *irreducible* (anti-aliasing, photographic content) so agents don't chase ghosts.\n- **Not gameable.** `converge` scores structural **fidelity** — is the reference's content present, placed, and legible? — not just pixel mismatch, and it refuses to win pixels by hiding, overlapping, or recoloring text into its background. It even flags reference text your build renders but **clips out of view** (a fixed-height `overflow:hidden` box) — the failure a pixel diff *rewards*, because cropped text lowers the mismatch.\n- **Agent-native.** Ships an `AGENTS.md` (auto-discovered by Claude Code, Cursor, Codex, …) plus a Claude Code skill, so your agent drives it without hand-holding.\n- **Local & private.** Pixel diffing, OCR, and layout extraction all run on your machine. No images leave your box, no API keys.\n\n## Copy a UI's *style*, not just match it\n\nMatching a screenshot pixel-for-pixel is one job. The other: building a **different** screen that feels like it belongs to the same design system. `one-shot-ui` extracts the *design language* from a reference and verifies a new UI conforms to it — deterministically, with no pixel oracle to lean on.\n\n```sh\n# Extract a reusable style system — palette, spacing scale, type ratio, radii, elevation\none-shot-ui tokens reference.png --emit shadcn      # or: tailwind | json\n\n# Build a different screen in that style, then check it conforms\none-shot-ui style-check reference.png ./pricing.html\n```\n\nIt reports measured facts and leaves the taste to the agent: it won't name your \"primary\" color or classify the mood — you decide those from the image (you're the vision model; the tool is your exact, hallucination-free eyes). Conformance is judged on what a screenshot grounds reliably — palette, spacing rhythm, type scale — while roundedness and elevation are flagged as advisories, since a raster can't pin them down.\n\n## Install\n\n```sh\nnpm install -g one-shot-ui\n```\n\nFor commands that need a browser (`capture`, `run`):\n\n```sh\nnpx playwright install chromium\n```\n\n## Quick start\n\n```sh\n# Diff your implementation against a reference and see exactly what's off\none-shot-ui compare reference.png build.png --json --heatmap heatmap.png\n\n# Get copy-paste CSS fixes, ranked by impact\none-shot-ui suggest-fixes reference.png build.png --json\n\n# The step that gets you pixel-perfect: trial fixes in a live browser and keep\n# only the ones that provably reduce pixel mismatch — outputs a verified patch,\n# a structural fidelity score, and any reference text your build hides or clips\none-shot-ui converge reference.png --impl ./index.html\n\n# Or run the full automated loop until it converges\none-shot-ui run reference.png --impl ./index.html --max-passes 5 --threshold 0.02\n```\n\nEvery command supports `--json` for structured, agent-friendly output.\n\n## Use it with your coding agent\n\n`one-shot-ui` ships an `AGENTS.md` (auto-discovered by Claude Code, Cursor, Codex, and other agent tools) plus a `skill/SKILL.md` for Claude Code.\n\nInstall the skill in one line:\n\n```sh\nmkdir -p .claude/skills/one-shot-ui && cp \"$(npm root -g)/one-shot-ui/skill/SKILL.md\" .claude/skills/one-shot-ui/\n```\n\n## Use it as an MCP server\n\n`one-shot-ui` also runs as a local [MCP](https://modelcontextprotocol.io) server, so any\nMCP-capable agent (Claude Code, Cursor, Cline, Windsurf, VS Code) can call `compare`,\n`converge`, `suggest_fixes`, `extract`, `tokens`, `plan`, and `style_check` as tools — no shell\nglue. It runs over stdio, makes no network calls, and needs no API keys.\n\n```sh\nclaude mcp add one-shot-ui -- npx -y one-shot-ui mcp\n```\n\nOr add to any client's MCP config:\n\n```json\n{\n  \"mcpServers\": {\n    \"one-shot-ui\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"one-shot-ui\", \"mcp\"]\n    }\n  }\n}\n```\n\nSee [docs/MCP.md](./docs/MCP.md) for per-client setup and registry publishing.\n\n## Commands\n\n| Command | Purpose | Key Flags |\n|---------|---------|-----------|\n| `extract` | Analyze a screenshot into layout, color, and text data | `--json`, `--no-ocr`, `--overlay`, `--fine` |\n| `compare` | Pixel + structural diff between two screenshots | `--json`, `--heatmap`, `--dom-diff` |\n| `tokens` | Design tokens + a reusable style system (palette, spacing, type, radii) | `--json`, `--emit shadcn\\|tailwind\\|json` |\n| `style-check` | Check a new UI conforms to a reference's design language | `--json` (new UI = URL / HTML / screenshot) |\n| `plan` | Generate an implementation strategy | `--json` |\n| `capture` | Screenshot a URL or local HTML file | `--url`, `--file`, `--output` |\n| `suggest-fixes` | Tailwind/CSS fix suggestions from a diff | `--json`, `--top`, `--dom-diff`, `--framework` |\n| `converge` | Closed-loop optimizer: pixel-verified CSS patch + structural fidelity score, flags hidden/clipped text | `--impl`, `--out`, `--json`, `--budget-seconds` |\n| `run` | Multi-pass extract→capture→compare→fix loop | `--impl`, `--max-passes`, `--threshold` |\n| `benchmark` | Run benchmark suites | `--json`, `--output` |\n\n## How it works\n\n1. **extract** — segments the reference into layout regions, samples colors/tokens, and OCRs text.\n2. **capture** — screenshots your implementation (URL or local HTML) at a matched viewport.\n3. **compare** — aligns the two, computes a pixel heatmap *and* a structural diff, and classifies each issue (layout / color / typography / spacing) plus whether it's actionable.\n4. **suggest-fixes** — turns issues into concrete, ranked CSS edits.\n\n`run` chains all four in a loop until the diff drops below `--threshold`.\n\n## Development\n\nRequires [Bun](https://bun.sh).\n\n```sh\nbun install\nbun run install:browsers   # Playwright Chromium\nbun run typecheck\n```\n\nDev scripts run directly from source:\n\n```sh\nbun run dev:extract -- ./reference.png --json\nbun run dev:compare -- ./reference.png ./build.png --json\n```\n\nBuild for npm:\n\n```sh\nbun run build\n```\n\n## License\n\nMIT\n",
  "bytes": 8725,
  "sha": "16eafa5fa521a707423736de8f1b4499da3d11ee4bdad9dd24d9f2564edf1680",
  "repo_slug": "tn0123/one-shot-ui",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tn0123_one_shot_ui_0105fb37/readme"
}