ui-clone-cli

ui-clone-skills — Motion forensics for the animated web

ui-clone-skills is motion forensics for the animated web: an agent skill for Claude Code and Codex by @voidmatcha that investigates a live URL the way a forensic analyst investigates a binary — extracts real CSS and real animation parameters from JS bundles (GSAP, Framer Motion, Lenis, anime.js), then either explains them, emits production React + Tailwind code, or scores an existing impl against the original via AE/SSIM pixel diff. No screenshot input, no vision tokens for routine verification.

Four jobs against a live URL

Command	Job
decode <url>	Analyse motion + build: which animation library, which scroll engine, what timings. Educational — no code emitted.
clone <url>	Generate React + Tailwind components against the captured DOM + extracted animation params.
verify <url> <impl>	Score an existing impl against the ref with AE/SSIM + motion-parity. Third-party clone audit.
extract <url>	Raw JSON dump (structure, styles, animations, bundles) for downstream tooling.

Screenshot-to-code and prompt-driven UI tools generate components that look like the original at a glance but ship the wrong transitions, wrong scroll behavior, and broken responsive breakpoints — visible parity, hidden divergence. Input is a live URL, not a screenshot or design file. Supports Next.js, Tailwind v4, Webflow IX2, and scroll-driven animations.

• Uses the original CSS directly — downloads stylesheets, keeps original class names. No re-implementing from extracted values.
• Near-zero vision tokens for verification — AE/SSIM image diff instead of reading screenshots with the LLM. Vision tokens only used in Phase E (final LLM review) when automated checks pass but semantic verification is needed.
• Extracts real values from JS bundles — GSAP timelines, Framer Motion springs, anime.js timelines, Lenis scroll params, scroll-driven keyframes. No guessing.
• Falls back to getComputedStyle when CSS is obfuscated (Tailwind, CSS-in-JS). Auto-detects site type.

Contents

• When to use this · Design principles · Skills · Install · Requirements · Quickstart
• Deep dives: ui-reverse-engineering · ui-capture · visual-debug
• Operations: Pipeline hooks, goal card, gates · Token management · Security · Responsible use · FAQ · Changelog

When to use this — decision tree

Different inputs need different tools. Pick by what you have:

What you have	Use
A live URL and want pixel-faithful React + Tailwind (real CSS, real animation params, scroll/hover behavior)	ui-clone-skills ← you are here
A Figma file	Builder.io / Anima / Plasmic
A screenshot (no source available)	screenshot-to-code / v0
A text description (no reference)	Claude Code / v0 / Lovable / Bolt.new
A live URL and just want static HTML mirror (no React)	wget --mirror / HTTrack

Why this exists: prompt-/screenshot-driven tools approximate what's visible. ui-clone-skills downloads the actual stylesheet, runs getComputedStyle against the rendered DOM, greps the JS bundle for GSAP/Framer Motion/anime.js/Lenis parameters, and verifies the result against the original via AE/SSIM — so the output matches transitions and responsive behavior, not just the static layout.

When NOT to use: general "build me a UI from scratch" tasks (use v0/Lovable or Claude Design), Figma-driven workflows (use Builder/Anima), one-off CSS help (just ask Claude directly).

Design principles

These are the decisions that shape how the plugin is structured. They aim to keep agent sessions focused and bounded.

• Real values, not guesses. Every number — font-size, easing curve, scroll offset, stagger delay — comes from getComputedStyle, raw CSS, or a JS bundle grep. The plugin refuses to ship approximations.
• Near-zero vision tokens for comparison. AE and SSIM CLI tools handle pixel diff — the LLM never reads ref vs impl screenshots side-by-side. Vision tokens are only used when: (1) reading a single diff image on AE/SSIM failure, (2) Phase E final semantic review (~44K tokens, mandatory).
• Progressive-disclosure sub-docs. Each SKILL.md contains only the pipeline and core rules (~5.9K tokens total across 3 skills). Detailed procedures live in 51 focused sub-docs loaded only when that step runs. Common paths stay lean; specialized paths expand on demand.
• Single source of truth for transitions. transition-spec.json is produced once from bundle analysis. Implementation reads the spec, never re-greps the bundle — avoiding wasted work and the risk of picking the wrong conditional branch.
• Automation over introspection. CLI gates (npx ui-clone-cli, compatibility: python -m ui_clone.*, plus scripts/verify/auto-verify.sh) decide whether a step is complete. Agents don't self-certify "looks good enough."
• No judgment, data only. Every decision must be backed by extracted data, captured screenshots, or script output. "Probably", "close enough", and "just a content difference" are forbidden — each has a documented failure case.

Skills

User intent	Skill	Owned responsibility	Non-goal	Handoff/next action
Build/route	ui-reverse-engineering	Run the website-to-React pipeline and route the next phase from pipeline status.	Not a standalone capture utility or mismatch diagnosis tool.	Calls ui-capture for reference artifacts; uses visual-debug for visual verification.
Capture/reference	ui-capture	Capture reference screenshots, scroll/transition evidence, and optional implementation clips for the caller.	Not the primary post-implementation mismatch diagnosis tool.	Handoff failing diffs or mismatch investigation to visual-debug.
Diagnose mismatch	visual-debug	Compare original vs implementation, run AE/SSIM/computed-style diagnosis, and identify fixes.	Not the build pipeline or baseline capture owner.	Return concrete findings/fixes to ui-reverse-engineering or the caller.

Start with ui-reverse-engineering when the request begins with a live URL, when you're unsure which skill fits, or when a run is partial, failed, or already complete. It checks the current state first, then routes to capture, generation, verification, or mismatch diagnosis without discarding usable artifacts.

Call ui-capture directly only when you need fresh reference evidence. Call visual-debug directly only when reference and implementation evidence already exist and the task is to diagnose a mismatch.

The public surface stays small: Claude Code and Codex expose the same three skills from shared skills/; each host adapter points back to the same core scripts, gates, and hooks.

Install

tmp=$(mktemp) && curl -LsSf -o "$tmp" https://raw.githubusercontent.com/voidmatcha/ui-clone-skills/main/install.sh && bash "$tmp" && rm -f "$tmp"

The default install registers both Claude Code and Codex marketplaces in one pass; each registration is skipped silently if that host's CLI is not on PATH. Both hosts are pointed at the same lightweight local projection under ~/plugins/ui-clone-skills, not at the development checkout, so tmp/, scratch/, .venv, and other local artifacts are never copied into plugin caches. For Claude Code, the installer also installs the plugin (ui-clone-skills@voidmatcha, user scope) — new Claude Code sessions load it automatically. For Codex, the installer also merges the gate hooks into ~/.codex/hooks.json (codex-cli 0.137 removed the plugin_hooks feature, so plugin-manifest hooks no longer load) — accept the one-time hook-trust prompt on the next Codex session.

For one-host installs, using a local development checkout as the plugin source, the manual git-clone path, the SKILL.md-only no-hooks copy, and the manual system-deps recipe, see README_detail/install.md.

Requirements

Tested on: macOS 14+ (primary), Ubuntu 22.04+ via WSL2 or native Linux. Windows native is not supported — use WSL2.

Dep	Why
agent-browser	Browser automation for extraction + comparison
imagemagick	AE pixel comparison
dssim	Structural visual similarity (perceptual diff)
ffmpeg	Video capture + frame extraction
uv + Python 3.11+	Gate / hook system (ui_clone/)

Pipeline hooks register through the Claude Code plugin source's hooks/hooks.json and, for Codex, via install.sh merging hooks/codex-hooks.json into ~/.codex/hooks.json (codex-cli 0.137 removed the plugin_hooks manifest path). For the full hook table, the goal-driven continuation pattern, and the gate-system CLI, see README_detail/pipeline.md.

Quickstart

After installing, give the agent a URL and a target. Use ui-reverse-engineering as the default entrypoint for live URL work, uncertain routing, partial runs, failed verification, or completed-state follow-up:

Clone the hero section from https://stripe.com/payments into React + Tailwind. Output to ./out/

The pipeline runs automatically. npx ui-clone-cli ... status --json (compatibility: python -m ui_clone.pipeline) detects the current phase and prints the next action; you don't invoke phases manually. See docs/agent-cli.md for the agent-readable CLI contract.

What happens:

• Reference capture → tmp/ref/payments-hero/{full,desktop,tablet,mobile}.png + scroll video
• DOM/CSS/JS extraction → tmp/ref/payments-hero/{structure,styles,assets}.json + transition-spec.json
• Component generation → ./out/PaymentsHero.tsx (CSS-first, original class names)
• Visual verification → scripts/verify/auto-verify.sh → D0 layout health + AE/SSIM diff

If verification fails, the pipeline iterates up to 3 rounds (Phase H self-healing loop) before asking for human review.

Hooks are registered on install and both Claude Code and Codex route through hooks/shim.sh, so premature write blocks and unverified-completion warnings stay shared. Claude Code loads them from the installed plugin source's hooks/hooks.json. Codex loads them from ~/.codex/hooks.json, into which install.sh merges the gate entries (idempotently) — plugin_hooks was removed in codex-cli 0.137 and is no longer used. Re-run install.sh after pulling hook-registration changes; plain script-logic edits are picked up live via the install marker on the next session.

Skill deep dives

Each skill ships with a dedicated detail page documenting its pipeline phases, automation scripts, and input modes:

• ui-reverse-engineering — full website-to-React pipeline (Phase 0 → 9), repo automation scripts, visual-debug script reference, input modes
• ui-capture — baseline screenshots, per-trigger transition capture, optional implementation evidence handoff
• visual-debug — quick comparison vs full verification, Phase E semantic review

Operations

• Pipeline hooks, goal card, gates — what every hook does, how the goal card drives continuation, gate CLI reference
• Token management — built-in mitigations, ENABLE_PROMPT_CACHING_1H=1 setup per shell + plan, rtk integration
• Security — prompt-injection defense, post-extraction sanitization, content-boundary enforcement
• Responsible use — copyright, ToS, font licensing, trademarks; intended vs disallowed use cases
• FAQ — comparisons with v0/Lovable/screenshot-to-code/Anima, framework support, vision-token policy, error/abort behavior

Evals

All skills include eval suites following skill-creator conventions, at skills/*/evals/.

Changelog

See CHANGELOG.md.

License

Apache-2.0. See LICENSE.txt.