What DESIGN.md can't tell your coding agent - and how to extract it anyway.
Every AI coding agent today can read a DESIGN.md. Colors, spacing tokens, typography scale, component variants - drop that file into a repo and Claude Code, Codex, Cursor, or Gemini CLI will follow it faithfully. It's become the standard way to hand a coding agent a design system and expect consistent output.
But open the sites that actually make people stop scrolling, and the thing you notice first is never in that file.
It's the way a hero canvas breathes when nothing is happening. The way a row of elements tilts toward your cursor before you've consciously registered it moved. The pacing of a scroll-triggered reveal - not just that it animates, but how it accelerates and settles. None of that lives in a token file. It lives in the running page, and it disappears the moment you only read the
markup.
That gap is what web-reverse-engineer is for.
The current AI-coding stack has gotten good at two things:
What's missing is the step before any of that: actually studying a reference site's runtime behavior - its motion, its interaction logic, its animation timing, and turning that observation into something an agent can build from. Screenshots don't capture motion. A design token file doesn't capture how an SVG eye rotates to track a cursor using real pointer math. That knowledge only exists while the page is running, and most workflows never bother to extract it before code gets written.
web-reverse-engineer is a portable SKILL.md workflow that does exactly that: inspect a public reference, extract the design and motion principles behind it, and hand a coding agent enough structured observation to rebuild an original implementation - not a copy of what it saw.
That distinction matters enough that it's the first rule of the project, not a footnote.
The workflow never touches proprietary source code, minified bundles, shader strings, stylesheets, or media assets from the reference site. It doesn't reproduce exact layout or exact animation timing. What it does extract is the principle - the class of motion, the interaction pattern, the structural idea - and every line of code in the rebuild is written fresh, in a different brand, different palette, different copy, re-tuned animation velocity.
In short:
Three small demos made this concrete:
Each one started as observation - measuring the running page, writing down what it was actually doing - before a single line of the rebuild got written. Look first, build second.
Here's the honest part: even with good extraction, there's a step no agent gets to skip past on its own.
The bar for whether a rebuilt animation actually works is simple to state and hard to automate: if a normal person watching for three seconds doesn't notice the motion, the demo failed, regardless of whether the build compiled, lint passed, and the code looked right. "Build passing" and "demo passing" turned out to be two different claims, and only a human can actually confirm the second one. The workflow leans into that instead of pretending otherwise: it captures evidence - screenshots, frame sequences - precisely so a person can make that call, rather than letting an agent self-certify something it fundamentally can't perceive.
That's a small detail, but it's the kind of thing that only shows up once you've actually tried to automate this instead of just writing a spec for it.
web-reverse-engineer installs as a standard package and drops a portable SKILL.md into your project for your coding agent to use on the next site you want to learn from:
npm install web-reverse-engineer
Live demos, the clean-room notes behind each one, and the skill itself are all in the repo, or see it running live.
If you're already handing your coding agent a DESIGN.md, screenshots, Cursor rules, or a custom skill to carry design context, I'd genuinely like to know what that setup looks like for you. What's the layer you built to cover the gap DESIGN.md leaves open?