# One Shot Ui

> Deterministic screenshot diffing for AI coding agents. Extract design tokens, diff implementations vs reference, get CSS fix suggestions.

- **Type:** MCP server
- **Install:** `agentstack add mcp-tn0123-one-shot-ui`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TN0123](https://agentstack.voostack.com/s/tn0123)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.7.0
- **License:** MIT
- **Upstream author:** [TN0123](https://github.com/TN0123)
- **Source:** https://github.com/TN0123/one-shot-ui
- **Website:** https://www.npmjs.com/package/one-shot-ui

## Install

```sh
agentstack add mcp-tn0123-one-shot-ui
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# one-shot-ui

### Catch what the eye can't.

**Deterministic screenshot diffing for AI coding agents.**
Turn 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.

[](https://www.npmjs.com/package/one-shot-ui)
[](./LICENSE)
[](https://www.npmjs.com/package/one-shot-ui)

## The problem

AI 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.

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

```
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 */
```

> Copy-paste CSS, ranked by visual impact — every example above is real output from the run below.

## Watch it converge

The `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.

## Why one-shot-ui

- **Deterministic, not vibes.** Stable pixel + structural diff scores — same input, same numbers — so you can gate CI on "is this pixel-close enough?"
- **Exact fixes, not nudges.** It returns concrete CSS (`width: 616px`, `#303040`, `gap: 176px`), grouped by component and ranked by visual impact.
- **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.
- **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.
- **Local & private.** Pixel diffing, OCR, and layout extraction all run on your machine. No images leave your box, no API keys.

## Copy a UI's *style*, not just match it

Matching 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.

```sh
# 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
```

It 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.

## Install

```sh
npm install -g one-shot-ui
```

For commands that need a browser (`capture`, `run`):

```sh
npx playwright install chromium
```

## Quick start

```sh
# 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
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
```

Every command supports `--json` for structured, agent-friendly output.

## Use it with your coding agent

`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.

Install the skill in one line:

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

## Use it as an MCP server

`one-shot-ui` also runs as a local [MCP](https://modelcontextprotocol.io) server, so any
MCP-capable agent (Claude Code, Cursor, Cline, Windsurf, VS Code) can call `compare`,
`converge`, `suggest_fixes`, `extract`, `tokens`, `plan`, and `style_check` as tools — no shell
glue. It runs over stdio, makes no network calls, and needs no API keys.

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

Or add to any client's MCP config:

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

See [docs/MCP.md](./docs/MCP.md) for per-client setup and registry publishing.

## Commands

| Command | Purpose | Key Flags |
|---------|---------|-----------|
| `extract` | Analyze a screenshot into layout, color, and text data | `--json`, `--no-ocr`, `--overlay`, `--fine` |
| `compare` | Pixel + structural diff between two screenshots | `--json`, `--heatmap`, `--dom-diff` |
| `tokens` | Design tokens + a reusable style system (palette, spacing, type, radii) | `--json`, `--emit shadcn\|tailwind\|json` |
| `style-check` | Check a new UI conforms to a reference's design language | `--json` (new UI = URL / HTML / screenshot) |
| `plan` | Generate an implementation strategy | `--json` |
| `capture` | Screenshot a URL or local HTML file | `--url`, `--file`, `--output` |
| `suggest-fixes` | Tailwind/CSS fix suggestions from a diff | `--json`, `--top`, `--dom-diff`, `--framework` |
| `converge` | Closed-loop optimizer: pixel-verified CSS patch | `--impl`, `--out`, `--json`, `--budget-seconds` |
| `run` | Multi-pass extract→capture→compare→fix loop | `--impl`, `--max-passes`, `--threshold` |
| `benchmark` | Run benchmark suites | `--json`, `--output` |

## How it works

1. **extract** — segments the reference into layout regions, samples colors/tokens, and OCRs text.
2. **capture** — screenshots your implementation (URL or local HTML) at a matched viewport.
3. **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.
4. **suggest-fixes** — turns issues into concrete, ranked CSS edits.

`run` chains all four in a loop until the diff drops below `--threshold`.

## Development

Requires [Bun](https://bun.sh).

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

Dev scripts run directly from source:

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

Build for npm:

```sh
bun run build
```

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TN0123](https://github.com/TN0123)
- **Source:** [TN0123/one-shot-ui](https://github.com/TN0123/one-shot-ui)
- **License:** MIT
- **Homepage:** https://www.npmjs.com/package/one-shot-ui

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.7.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.7.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tn0123-one-shot-ui
- Seller: https://agentstack.voostack.com/s/tn0123
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.