one-shot-ui

Deterministic UI extraction, diffing, and scaffolding from screenshots.

Turn a reference screenshot into structured JSON — layout regions, colors, typography, spacing, components, design tokens — then compare implementations against the reference and get actionable fix suggestions.

Installation

npm install -g one-shot-ui

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

npx playwright install chromium

Commands

| Command | Purpose | Key Flags | |---------|---------|-----------| | extract | Analyze screenshot into layout, color, and text data | --json, --no-ocr, --overlay, --fine | | compare | Pixel + structural diff between two screenshots | --json, --heatmap, --dom-diff | | scaffold | Generate React+Tailwind (default) or HTML/CSS from a screenshot | --framework, --styling, --output | | tokens | Extract design tokens (colors, spacing, radii) | --json | | 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 | | run | Multi-pass extract→capture→compare→fix loop | --impl, --max-passes, --threshold | | benchmark | Run benchmark suites | --json, --output |

Quick Start

# Extract structured data from a screenshot
one-shot-ui extract reference.png --json

# Generate a React + Tailwind component (default)
one-shot-ui scaffold reference.png --output ./src

# Or generate vanilla HTML/CSS instead
one-shot-ui scaffold reference.png --output ./src --framework vanilla --styling css

# Capture your implementation
one-shot-ui capture --url http://localhost:3000 --output impl.png

# Compare against the reference
one-shot-ui compare reference.png impl.png --json --heatmap heatmap.png

# Get CSS fix suggestions
one-shot-ui suggest-fixes reference.png impl.png --json

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

All commands support --json for structured output.

Agent Integration

one-shot-ui ships with an AGENTS.md for automatic discovery by Claude Code, Cursor, Codex, and other agent tools, plus a skill/SKILL.md for Claude Code skill installation:

mkdir -p .claude/skills/one-shot-ui
cp node_modules/one-shot-ui/skill/SKILL.md .claude/skills/one-shot-ui/SKILL.md

Development

Requires Bun.

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

Dev scripts run directly from source:

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

Build for npm:

bun run build

License

MIT