Show HN: Motion Debugger – A browser critic for AI slop

A developer publishing as ShadowKingYT444 released Motion Debugger, an open-source tool that pairs a `premium-motion` agent skill with a `motion-debugger critique` command to rebuild and visually check AI-generated landing pages. The critique command opens the local page in Chromium via Playwright, records the entrance, scrolls the full page, hovers every control, checks the phone layout and reduced motion, then returns ranked fixes and screenshots to the coding agent. The tool requires Node.js 22 or later and works with agents including Claude Code, Cursor, Codex, VS Code and OpenCode.

Upgrade a vibe-coded site to premium with your coding agent. Motion first, then taste, checked in a real browser. Install install · Upgrade a site upgrade-a-site · Commands commands · The critic the-critic · Demos four-upgrades · FAQ faq · Contribute https://github.com/ShadowKingYT444/motion-debugger/blob/main/CONTRIBUTING.md <sub Left: a site an agent built from a one-paragraph brief. Right: the same site after a fresh agent Opus 5.5 ran premium-motion upgrade on it. Nothing edited by hand. All four upgrades four-upgrades .</sub Every agent-built landing page looks the same: near-black with one neon accent, a headline with an italic word, pill buttons, a bento grid, a logo marquee, and every section fading up the same way. It is not ugly. It just tells everyone a model made it, and nobody looked at it before it shipped. Motion Debugger gives your agent two things it doesn't have: - 🎬 A workflow that rebuilds the look and keeps the truth. The premium-motion skill runs an upgrade pipeline: it records a baseline, keeps every fact, link and form, picks a direction from the product's own world, then rebuilds the page around choreographed motion and one cinematic scroll scene. It uses a tested GSAP, ScrollTrigger, SplitText and Lenis stack, or Motion in React projects. - 👀 Eyes. motion-debugger critique opens the local page in Chromium, records the entrance, scrolls the whole page, hovers every control, checks the phone layout and reduced motion, and hands the agent ranked fixes plus screenshots of the real frames. The agent looks, fixes and looks again, then compares against the baseline. Every line below is one command. They work with any model and any coding agent, and the same commands run on macOS, Linux and Windows bash, zsh or PowerShell . The CLI and npx lines need Node.js 22 or later; the git line needs only git. The full setup critic, skill and agent configuration . Install, then run init in your project: npm install -g https://github.com/ShadowKingYT444/motion-debugger/releases/latest/download/motion-debugger.tgz motion-debugger init init detects your agent Claude Code, Cursor, Codex, VS Code, OpenCode , installs the skill, offers to download a matching Chromium, and shows every file it would change before asking you to type yes . Nothing is written without that, and your existing settings are kept. Just the skill, or just the critic: | You want | One line | |---|---| | The skill, for the agent you use | npx skills add ShadowKingYT444/motion-debugger --skill premium-motion -a cursor | | The skill, in the shared .agents/skills folder many agents read | npx skills add ShadowKingYT444/motion-debugger --skill premium-motion -a universal -y | | The skill without Node bash, zsh | mkdir -p .agents/skills && git clone --depth 1 https://github.com/ShadowKingYT444/motion-debugger.git /tmp/motion-debugger && cp -r /tmp/motion-debugger/plugin/motion-debugger/skills/premium-motion .agents/skills/ | | The skill without Node PowerShell | git clone --depth 1 https://github.com/ShadowKingYT444/motion-debugger.git $env:TEMP\motion-debugger; $null = New-Item -ItemType Directory -Force .agents\skills; Copy-Item -Recurse $env:TEMP\motion-debugger\plugin\motion-debugger\skills\premium-motion .agents\skills\ | | The critic, with nothing installed | npx -y -p https://github.com/ShadowKingYT444/motion-debugger/releases/latest/download/motion-debugger.tgz motion-debugger critique http://localhost:3000 | | A browser for the critic | motion-debugger setup --browser | For -a , use your agent's name: claude-code , cursor , codex , gemini-cli , github-copilot , windsurf , cline , roo , zed , opencode , goose , kiro-cli , amp , junie and about 70 more skills CLI https://github.com/vercel-labs/skills . An agent that can't run shell commands can still follow the skill; it just can't look at the page. The critic uses Playwright's Chromium if you downloaded it, then CHROMIUM PATH , then an installed Chrome, Chromium or Edge in the usual place on macOS, Windows or Linux. CI installs the packed CLI on all three and critiques a real page. Start your dev server, then tell your agent: Use premium-motion upgrade on this site. What the agent does, from commands/upgrade.md https://github.com/ShadowKingYT444/motion-debugger/blob/main/plugin/motion-debugger/skills/premium-motion/commands/upgrade.md : 1. Baseline. Critiques the page as it is and lists its AI tells. 2. Inventory. Writes down what to keep facts, numbers, CTAs, forms, your logo and colours and what to replace. 3. Direction. Writes PREMIUM.md : audience, facts, the product's world, type, colour, imagery and one motion personality. 4. First viewport. Rebuilds the hero alone and critiques it until it holds up. 5. Rebuild. Works section by section, each laid out from its content instead of eyebrow, bento and marquee. 6. Signature scene. Builds one scroll-scrubbed scene that tells the product's story and is finished at every scroll position. 7. Polish and harden. Fixes every outlined defect, then the phone layout, reduced motion, accessibility and scroll performance. 8. Verify. Critiques again and compares with the baseline side by side. Narrow targets work too: upgrade the pricing section , signature the how-it-works section , polish the footer . | Command | What it does | |---|---| | upgrade target | The full pipeline above: vibe-coded to premium, verified before and after | | audit target | Records the page and ranks every AI tell and motion or finish defect. No edits | | direction | Writes PREMIUM.md , the design context every other command reads | | motion target | Choreographs the hero, reveals, hover, press and transitions in one personality | | signature target | Designs and builds one cinematic scroll scene | | typeset target | Replaces default type with a system that has character, scale and finish | | palette target | Colour, light and depth from the product's world, with a chapter rhythm | | imagery target | Rich visuals without stock photos: product renders, generative scenes, live product UI | | compose target | Layout, hierarchy and rhythm: one dominant element per frame | | polish target | The finish pass: everything the critic outlines, every state, every edge | | harden target | Phone layout, reduced motion, accessibility and scroll performance | The motion code agents copy from the skill is extracted from its Markdown and run in Chromium in CI at desktop, phone and reduced-motion sizes, so the documented snippet is the tested snippet. Run it yourself on anything local: motion-debugger critique http://localhost:3000 your dev server Next.js, Vite, … motion-debugger critique ./site a folder with index.html, or one .html file It prints findings with fixes, writes contact sheets to .motion-critique/ , and says what changed since the last run: fixed, new and remaining. | | Finding | What it means | |---|---|---| | 🎞️ | Motion checks | No entrance, unstaggered entrance, linear easing, motion that stops after the hero, dead hover, invisible focus, no reduced-motion support, scroll jank, layout shift | | 🚫 | stuck-invisible | Content that never appears, even after a full scroll the most common agent bug | | 🧱 | text-collision , copy-under-sticky | Copy painted over other copy, or scrolling under a sticky header | | 🕳️ | hollow-containers , dead-space | Cards with an empty band inside; screens that are mostly blank | | 📐 | near-miss-alignment , edge-crowding | Items a few pixels off their column; copy jammed against the screen edge | | 📱 | mobile-overflow , tap targets, clipped text | A phone layout that is really a squeezed desktop | | 🤖 | default-template | How many of nine default AI-landing-page traits the first screen shares | Findings come from real Chromium frames, never from reading the source. Every check and its limits https://github.com/ShadowKingYT444/motion-debugger/blob/main/docs/PREMIUM-MOTION.md . Four landing pages that Sonnet 5.5 built from one-paragraph briefs with no plugin, the controls from the A/B study below. A fresh Opus 5.5 agent ran upgrade on each, with the same prompt. These are single runs to show the workflow, not a blinded comparison, and nobody edited the results. The prompt, the skill version and every recording are in demos/upgrades.json https://github.com/ShadowKingYT444/motion-debugger/blob/main/demos/upgrades.json . | | Critic score before → after | Blocker and major findings | Template traits | |---|---|---|---| | Ledgerline: payments API | 30 → 100 | 2 → 0 | 6 → 1 of 9 | | Atelier Norr: architecture studio | 8 → 98 | 4 → 0 | 7 → 0 of 9 | | Halo: wireless speaker launch | 38 → 100 | 3 → 0 | 5 → 0 of 9 | | Drift: AI sleep coach | 24 → 100 | 3 → 0 | 8 → 0 of 9 | One critic run per site, made after the agents finished. The agents were working against this critic, so read the score as "the defects it can see are gone", not as a measure of taste. Judge the films. Atelier Norr: architecture studio · film https://github.com/ShadowKingYT444/motion-debugger/blob/main/demos/norr/upgrade.mp4 Halo: wireless speaker launch · film https://github.com/ShadowKingYT444/motion-debugger/blob/main/demos/halo/upgrade.mp4 Drift: AI sleep coach · film https://github.com/ShadowKingYT444/motion-debugger/blob/main/demos/drift/upgrade.mp4 Ledgerline: payments API · film https://github.com/ShadowKingYT444/motion-debugger/blob/main/demos/ledgerline/upgrade.mp4 Each upgraded/ folder also holds the PREMIUM.md direction file the agent wrote. Open any site live from demos/ https://github.com/ShadowKingYT444/motion-debugger/blob/main/demos/README.md . Separately from the upgrades, we ran a blinded A/B test of building from scratch: same brief, same builder model Sonnet 5.5 , one fresh agent per site. One agent worked in an empty project; the other had the skill and the critic. In the latest batch four matched pairs, plugin v4 , blinded Opus 5.5 judges preferred the plugin's site in all four pairs 8 of 8 judgments . Distinctiveness rose from 6.4 to 8.8 and overall premium from 6.9 to 8.0. The control sites shared 6.5 of 9 default-template traits on average; the plugin's sites shared none. Visual design moved least 7.8 to 8.1 . Four pairs are too few for statistical significance. The earlier 16-pair study reached it for overall premium +1.0, p = 0.005 and motion quality +1.34, p = 0.0004 , but found no gain in visual design, which later versions were rebuilt to address. The study predates the upgrade workflow. Method, every verdict and threats to validity https://github.com/ShadowKingYT444/motion-debugger/blob/main/studies/premium-ab/README.md . How is this different from Impeccable or other design skills? The skill's shape one skill, a command vocabulary, a context file and a playbook per command is borrowed from Impeccable https://github.com/pbakaus/impeccable , with thanks. The differences are the focus and the loop. Motion is the core: a tested GSAP and Lenis stack, signature scroll scenes, choreography and reduced-motion handling. And every command ends by recording the page in a real browser: the critic measures what actually moved and finds finish defects in the captured frames, so the agent works from evidence instead of reading its own CSS. Will it change my content? upgrade keeps the product's facts, numbers, links, forms and anything you already own logo, brand colours, fonts, photos . It replaces the generic look. Run audit first if you only want a report. Does it work with my stack? Plain HTML, React, Next.js, Vite, Motion framer-motion and GSAP. The skill uses the animation library you already have and never adds a second one. Does it need Claude, or a particular model? No. Nothing here calls a model API: the critic is a plain CLI with Markdown or --json output, and the skill is a standard Agent Skill in Markdown. Use it with any model your agent runs. The demos were made with Claude models because that's what we had; the workflow doesn't depend on them. init sets up Claude Code, Cursor, Codex, VS Code and OpenCode, and the skills CLI covers about 80 more agents see Install . Does it work on my machine? Yes on macOS, Linux and Windows with Node.js 22 or later. CI installs the packed CLI on all three and critiques a real page. Does anything leave my machine? No. The critic only opens credential-free local pages localhost , 127.0.0.1 , files , never imports your browser profile, and keeps recordings in your project folder. Security model https://github.com/ShadowKingYT444/motion-debugger/blob/main/SECURITY.md . motion-debugger init sets these up for you; this is what it writes. | Agent | --client | MCP configuration | Skills | |---|---|---|---| | Claude Code | claude-code | .mcp.json | .claude/skills/ | | Cursor | cursor | .cursor/mcp.json | .cursor/skills/ | | Codex | codex | .codex/config.toml | .agents/skills/ | | VS Code / Copilot | vscode | .vscode/mcp.json | .github/skills/ | | OpenCode 1.x | opencode | opencode.json | .opencode/skills/ | Any other agent Gemini CLI, Aider, Windsurf, a CI job : copy the skill folder into your project and add the block printed by motion-debugger agents-md --skills-dir <folder to the agent's instructions file AGENTS.md , GEMINI.md , .cursorrules , … . MCP hosts also get motion critique , which returns the findings and screenshots as image content. Client setup details https://github.com/ShadowKingYT444/motion-debugger/blob/main/docs/CLIENTS.md · Native plugin packages https://github.com/ShadowKingYT444/motion-debugger/blob/main/docs/PLUGIN-PACKAGES.md . Debugging one specific transition? The evidence tools. For a single interaction, the MCP evidence tools record bounded journeys and compare repairs: | Tool | Purpose | |---|---| | motion critique | Critique a whole page: findings, fixes and contact sheets | | motion recipe | Get runnable animation patterns and integration guidance | | motion review | Review transitions with actor observations and native images | | motion probe | Try interruption offsets and retain failure evidence | | motion capture | Record a local interaction with explicit expectations | | motion inspect | Inspect events and measurements around a moment | | motion frames | Extract images from the actual recording | | motion compare | Compare equivalent before/after journeys | | motion list | Find saved captures | See Agent workflow https://github.com/ShadowKingYT444/motion-debugger/blob/main/docs/AGENT-WORKFLOW.md . Bug reports, false positives the critic flags, and new checks are all welcome. Browse the open issues https://github.com/ShadowKingYT444/motion-debugger/issues or say hi in Discussions https://github.com/ShadowKingYT444/motion-debugger/discussions . Contributing guide https://github.com/ShadowKingYT444/motion-debugger/blob/main/CONTRIBUTING.md .