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

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:

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 (python -m ui_clone.* / node bin/ui-clone, published: npx ui-clone-cli, 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

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. Neither host is pointed at the development checkout, so tmp/, scratch/, .venv, and other local artifacts are never copied into plugin caches. The two hosts need different sources: Codex reads its install in place, so it gets the symlink projection under ~/plugins/ui-clone-skills and stays live with the checkout; Claude Code copies its marketplace source into a per-version cache without following symlinks, so it gets a real-file source under ~/.local/share/ui-clone-skills-claude-src (override with UI_CLONE_CLAUDE_SRC_DIR; it must resolve outside the checkout, and the installer refuses it otherwise). For Claude Code, the installer also installs the plugin (ui-clone-skills@voidmatcha, user scope) — new Claude Code sessions load it automatically. The Codex plugin is globally skills-only; the ui-reverse-engineering skill automatically configures hooks only in the active clone workspace. Installation and updates remove legacy global ui-clone hook entries from older releases.

After installing, the installer runs one of the installed hooks out of Claude's plugin cache and fails if it does not execute. An install can otherwise report success while delivering an empty plugin — that failure is invisible to claude plugin list, which reports such a plugin as installed and enabled. If the probe itself misbehaves on your host, UI_CLONE_SKIP_HOOK_PROBE=1 skips it; do not use it to get past a genuine delivery failure, because the result is a plugin that silently enforces nothing.

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.

Pipeline hooks register through the Claude Code plugin source's hooks/hooks.json. Codex uses project-local .codex/hooks.json files configured automatically by ui-reverse-engineering, so unrelated sessions load no ui-clone hooks. For the full hook table, manual ui-clone hooks commands, 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. python -m ui_clone.pipeline ... status --json (or node bin/ui-clone ... status --json; published: npx ui-clone-cli) 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:

1. Reference capture → tmp/ref/payments-hero/{full,desktop,tablet,mobile}.png + scroll video
2. DOM/CSS/JS extraction → tmp/ref/payments-hero/{structure,styles,assets}.json + transition-spec.json
3. Component generation → ./out/PaymentsHero.tsx (CSS-first, original class names)
4. 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.

Claude Code hooks are registered on install. Codex hooks are configured automatically on first ui-reverse-engineering use in each workspace and route through the same hooks/shim.sh, so premature-write blocks and unverified-completion warnings stay shared without affecting unrelated sessions. The first Codex enable or a manifest change may require /hooks review and a fresh session. Manage the boundary directly with ui-clone hooks status|enable|disable [--project-root <path>].

Recovering a stalled run. Symptom: a session goes quiet for >15 min showing "N shells still running", but ps/pgrep find no live processes. Cause: a background-shell completion wake-up was lost at the runtime level — the completion event failed to re-invoke the agent and was not retried. Nothing is corrupted. Recovery: send any message — the pipeline resumes losslessly from pipeline-state.json and the on-disk artifacts. To shrink the exposure window, long verification sweeps are split into sub-8-minute, idempotent chunks with persisted intermediate state: the video-motion scroll sweep checkpoints each captured position to scroll-chunk-manifest.json (UI_CLONE_VMC_SCROLL_CHUNK bounds positions per invocation), so a resumed run re-captures at most one in-flight chunk instead of restarting the whole sweep, and the aggregated verdict is identical to a monolithic run.

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.